Rhozet Carbon API allows Etere to request tasks through an XML file; said file is formed by various sections called elements. For example:
sample.xml
<?xml version="1.0" encoding="utf-8" ?>
<cnpsXML TaskType="JobQueue" CarbonAPIVer="1.2" JobName="my_lowres_job">
<Sources>
<Module_0 Filename="\\michaelw7\mtxdb\Video\%0:s" />
</Sources>
<Destinations>
<Module_0 ModuleGUID="{A0FA1A78-58DF-4F38-952D-CC51B1CD1599}"
PresetGUID="{A0FA1A78-58DF-4F38-952D-CC51B1CD1599}">
<ModuleData CML_P_BaseFileName="%1:s" CML_P_Path="\\michaelw7\mtxdb\Proxy\"/>
</Module_0>
</Destinations>
<ProjectSettings Stitching.DWD="0" TargetOverWrite.DWD="1">
</ProjectSettings>
</cnpsXML>
Custom elements can be set for the Rhozet RZCP Transcoding action, for either the source or destination; the parameters supported in both cases (as well as other common elements) are explained in this chapter through the following sections:
<CnpsXML> - <SOURCES> - <WatchSource> - <DESTINATIONS> - <ProjectSettings> - <PostconversionTasks>
<CnpsXML>
The <cnpsXML> element encapsulates the entire job. You must specify the nature of the job (basically the "command" to the Carbon Engine) here. In addition, the XML API version is declared, and a name for the job can be given in an attribute. You can then use this name, for example, in email notifiers.
Element: CarbonAPIVer
Type: String
Description: Major and Minor version (string formated as fmajorg. fminorg where both are integers).
This element ensures compatibility between XML structures. Only the major part of the minor number is considered. For example, this document would require XML structures marked as "1. x".
Element: TaskType
Type: String
Description: The name of the task:
•JobEvaluate: Conversion Job Evaluation. Evaluate an XML structure, gather information about source files used, etc.
•JobQueue: Conversion Job Queuing. Submit a Job for execution or queuing.
•JobList: Conversion Job List. This task will return a list of currently running or queued jobs.
•JobCommand: Conversion Job Administration. The Conversion Job Administration tasks allow a caller to query for information and start, stop, delete, etc., a queued, running, or completed conversion job.
•WatchCreate: Watch Folder Creation. Establish and activate a watch folder.
•WatchList: Watch Folder List. This task will return a list of currently active watch folders.
•WatchCommand: Watch Folder Administration. The Watch Folder Administration allows the querying for Watch Folder information and to remove/-modify/etc. WatchFolders.
Element: JobName
Type: String (optional)
Description: Name of the job or task. This can be used in notifiers, etc.
Element: GUID
Type: GUID (String)
Description: In some cases, a TaskType only requires a GUID.
Element: AgentIP
Type: String (optional)
Description: The IP Address of the agent in case the command is meant for an agent in a Carbon Server Farm.
<Sources>
The <Sources> element encapsulates all the sources of a project. Multiple Sources can be handled in 2 different ways controlled in the <ProjectSettings> element (either stitched together to one logical source or processed separately as a batch process).
Each file source listed is described by the element <Module n>, which describes one file source, specified by its attributes:
Element: Filename
Type: String (optional)
Description: Full path to a Source File. If enabled, the RemoteFilename and RemoteFTPFilename are disabled.
Element: RemoteFilename
Type: String (optional)
Description: Full UNC path to a Source File located on a network share. The source file will be copied to a local folder before attempting conversion.
If enabled, the Filename and RemoteFTPFilename are disabled.
Element: RemoteFTPFilename
Type: String (optional)
Description: Full path to a Source File located on an FTP site. The source file will be copied to a local folder before attempting conversion.
If enabled, the Filename and RemoteFilename are disabled.
If specified, an <FTPSettings> element may be added as a sub-element of <Module n>.
Element: MultiSource.DWD
Type: Integer (optional)
Description: If the value is set to 1, this is a logical source with multiple source files for different data types.
If the MultiSource.DWD attribute is set to 1; only "Filename" is allowed
Element: ComplexSource.DWD
Type: Integer (optional)
Description: If the value is set to 1, this is a complex source with one video and multiple audios.
Element: TransitionSource.DWD
Type: Integer (optional)
Description: If the value is set to 1, this is a transition source
NB: This element is valid for JobQueue and WatchCreate (with command="SubmitSources") task types.
<WatchSource>
The <WatchSource> element describes the properties of a Watch to be created.
Element: WatchPath
Type: String
Description: Path of the Watches. It is heavily advised to use UNC path naming.
Element: LeadingSource
Type: String (optional)
Description: Path to a file that should be used as a leading clip. It is heavily advised to use UNC path naming.
Element: TrailingSource
Type: String (optional)
Description: Path to a file that should be used as a leading clip. It is heavily advised to use UNC path naming.
Element: Name
Type: String
Description: A pretty name to show in lists, etc.
Element: Description
Type: String
Description: A short description of the watch.
Element: WatchSubFolder.DWD
Type: Integer
Description: Enables/disables the monitoring of sub-folders.
•0 do not also monitor sub-folders of the WatchPath
•1 monitor also sub-folders of the WatchPath
Element: AppendSubFolder.DWD
Type: Integer
Description: Enables/disabled the appending of sub-folders names.
•0 do not append the watched sub-folder to the target file name
•1 append the watched sub-folder to the target file name
Element: OverWrite.DWD
Type: Integer
Description: Enables/disables the overwrite of existing target files.
•0 (default) delivery will fail if the target exists.
•1 delivery will overwrite the file if the target exists.
Element: Priority.DWD
Type: Integer
Description: 0 through 9, 255, Defines the Job priority when it will be established.
Element: WatchDeleteProcessedSource.DWD
Type: Integer
Description: Enables/disables the deletion of source files.
•0 Keep the source file when finished
•1 Delete the source file when finished
Element: Enabled.DWD
Type: Integer
Description: Specifies the current state of the watch folder:
•-1 Watch folder incomplete
•0 Watch folder disabled
•1 Watch folder enabled
Element: GUID
Type: GUID String(optional)
Description: When set, uses this GUID. If another watch with this GUID exists, it will be replaced. It can be used to update watches.
NB: This element is valid for WatchCreate (with command="SubmitSources") task types.
<Destinations>
The <Destinations> element encapsulates all the destinations of a project. Each destination is described in detail by the child element <Module n>.
Element: PresetGUID
Type: GUID (String)
Description: GUID of destination preset. The specification of this parameter is risky since it relies on a previously generated preset which may not exist (e.g. on a freshly installed system).
Element: ModuleGUID
Type: GUID (String)
Description: GUID of destination module
Element: DestinationName
Type: String
Description: User-assigned name serves identification when destination-specific notifiers are to be sent.
Element: AssignedAgentIPs
Type: String (optional)
Description: If set, assignable to these agents only. Multiple Agents are separated by ";."
Element: AssignedTags
Type: String (optional)
Description: If set, assignable only to an agent who exposes all of the property tags listed. Multiple Tags are separated by ";".
NB: The <Destinations> element is valid for JobQueue and WatchCreate task types.
Moreover, the <ModuleData> tag allows including some key parameters such as:
Parameter: CML_P_BaseFileName
Description: Filename to save files. If this parameter differs from the "destination metafile" (set in the Basic Settings of the T-workflow action), no metafile will be linked to the asset.
Sample value: "%1:s"
Parameter: CML_P_Path
Description: Path to save files. Etere variables (i.e. %0:s, %1:s, etc) are not supported.
Sample value: "\\michaelw7\mtxdb\Proxy\"
Please provide detailed technical information on implementing a custom <Destinations> element and the supported parameters (e.g. aspect_ratio_code.DWD, audio_channels.DWD, video_standard.DWD, etc.) to the Rhozet Carbon API documentation.
<ProjectSettings>
The <ProjectSettings> element defines parameters only for the current project:
Element: Stitching.DWD
Type: Integer
Description: Species whether to stitch the sources or not.
•0 batch encode source-by-source
•1 combine all sources into one logical source
Element: TempDir
Type: String
Description: Define temporary storage for this project
Element: Priority.DWD
Type: Integer
Description: Priority of the job to be submitted.
Scale: 0 through 9, where the lower the value, the lower the priority.
The default value is 5. The special value 255 executes the job immediately, disregarding the number of simultaneous jobs allowed.
Element: AssignedAgentIPs
Type: String (optional)
Description: If set, assign to this agent only (required, for example, if a certain agent has hardware or codecs installed. Multiple Agents are separated by ";."
Element: AssignedTags
Type: String (optional)
Description: If set, assign only to an agent who exposes all of the property tags listed. Multiple Tags are separated by ";". This can be used for a more dynamic control mechanism than fixed Agent names/IPs.
Element: MultiTargetSplitting.DWD
Type: Integer (optional)
Description: Specifies how the job(s) is created.
•0 Only one job is created with all the destinations
•1 One job per destination is created, each with one destination. Useful for lower latency in multi-node setups
Element: RenderMacroGrid.DWD
Type: Integer (optional)
Description: Enables/Disables segmented grid transcoding.
•0 A job is not segmented for transcoding
•1 A job is segmented to be transcoded in the macrogrid. Useful for improved speed in multiprocessor/-multinode setups. (Note that this option will be executed only if the job is suitable for it)
Element: MacroGridSegments.DWD
Type: Integer
Description: Maximum number of segments a job will be segmented in to be rendered in macrogrid.
This parameter is mandatory if RenderMacro-Grid.DWD = "1"
Element: TargetOverWrite.DWD
Type: Integer
Description: Enables/disables the overwrite of existing target files.
•0 (default) delivery will fail if the target exists.
•1 delivery will overwrite the file if the target exists.
NB: This parameter works with version 3.18.x or higher of Carbon coder.
NB: The <ProjectSettings> element is valid only for JobQueue and WatchCreate task types.
For instance, the project settings can be added as follows:
<ProjectSettings Stitching.DWD="0" TargetOverWrite.DWD="1"> </ProjectSettings>
<PostconversionTasks>
The <PostconversionTasks> element allows performing additional tasks before and after conversion.
Element: RemoteFTPFolder
Type: String
Description: Remote FTP folder
Element: RemoteFTPFile
Type: String (optional)
Description: Remote Filename. If not specified, the local file name will be taken.
Element: FTPSourceFile
Type: String (optional)
Description: Local file. If specified, the "real" source is ignored. Allows for the upload of arbitrary files.
Element: OverWrite.DWD
Type: Integer
Description: Enables/disables the overwrite of existing target files.
•0 (default) delivery will fail if the target exists.
•1 delivery will overwrite the file if the target exists.
NB: The <PostconversionTasks> element is valid for JobQueue and WatchCreate task types.