## Helix™ DNA Producer 10.0 Job File Reference |

This document describes Helix DNA Producer job files. Job files are XML formatted text files that specify all settings needed for an encoding session. The job file is composed of XML elements organized in a hierarchal tree structure as shown below:

- <job>
  - <clipInfo>
    - <entry>
  - <parInputs>
    - <input>
      - <prefilters>
        - <prefilter>
  - <parOutputs>
    - <output>
      - <clipInfo>
      - <mediaProfile>
      - <destinations>
        - <destination>
          - <postfilters>
            - <postfilter>
  - <audiences>
    - <audience>
    - <streams>
      - <stream>

The above hierarchy represents all the major sections in a job file. Each of the sections are documented below. In some cases, a section may appear in more than one place within the job file (e.g clipInfo appears in both the job element as well as the output element). In these cases, the section is documented only once below.

XML documents are composed of elements and attributes. Elements may contain a simple value or other elements. Elements that contain simple values are referred to as properties. An example of a property is <enableTwoPass>true</enableTwoPass>. Elements that contain other elements are referred to as sections. Examples of a section is the clipInfo section above which includes the entry subsection.

Job files may be read, created or modified through Helix DNA Producer applications or SDK as well as any text or XML document editor. Information on how to edit Helix DNA Producer XML settings files is available in the Editing XML Files Reference. The remainder of this document provides information on the properties in the outline above.

Helix DNA Producer Job files are given a special file extension by convention. The file extension for a server file is ".rpjf" which stands for RealNetworks Producer Job File.

# Document Root | [ job ]

An XML document contains one and only one root. The document root for job files is job. Nested within the job element is the enableTwoPass property and a number of subsections (clipInfo, input, outputs, and audiences). Each of these sections may contain subsections as well. The job element also contains one attribute, xmlns.

The outline below shows the structure of the job element and its immediate children.

- <job>
  - <enableTwoPass>
  - <clipInfo>
  - <parInputs>
  - <outputs>
  - <audiences>

The job element may contain either an outputs element or an single output element but not both (as indicated by the vertical bar between the two). The clipInfo, input, outputs, and audiences sub sections are described in subsequent sections of this document.

The attributes and properties of the job element are described below.

## Attributes

The job tag contains three attributes:

- xmlns
- xmlns:xsi
- xsi:schemaLocation

These attributes are described below.

xmlns | [ job ]

XML Namespace attribute. The xmlns attribute stands for XML Namespace. This setting is used to store the type and version of an XML file for purposes of validation.

Default:
http://ns.real.com/tools/job.2.0

Values:
Helix DNA Producer 10 job files are given a version of 2.0. If a newer version is encountered, the Helix DNA Producer SDK or command line application will refuse to open the job.

Example:
<job xmlns="http://ns.real.com/tools/job.2.0">

xmlns:xsi | [ job ]

XML Schema Instance Namespace Attribute. The xsi:schemaLocation attribute provided information on where to locate the XML Schema file used to validate the server file. The value of the xsi:schemaLocation is a space separated list of namespace/URI pairs.

Default:
http://www.w3.org/2001/XMLSchema-instance

Values:
A string containing the XML Schema Instance namespace. The XML Schema Instance namespace provides functionality for handling XML schema validation. The definitions of xsi:type and xsi:schemaLocation used in Heilx Produer settings files are provided by this namespace. More information on the xmlns:xsi namespace and the definitions it provides can be found in the document, Extending and Validating Helix DNA Producer Settings Files with XML Schemas.

Example:
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation | [ job ]

Location of the XML Schema File used to validate the file. The xsi:schemaLocation attribute provided information on where to locate the XML Schema file used to validate the job file. The value of the xsi:schemaLocation is a space separated list of namespace/URI pairs.

Default:
http://ns.real.com/tools/job.2.0 http://ns.real.com/tools/job.2.0.xsd

Values:
A string containing the namespace on the left (http://ns.real.com/tools/job.2.0) and the location of the XML Schema file in the form of a URI. The default is http://ns.real.com/tools/job.2.0.xsd which works for most XML Schema validators as long as there is network connectivity to the Internet. The URI can also be any valid filename including path.

More information on the xsi:schemaLocation attribute can be found in the document, Validating Helix DNA Producer Settings Files with XML Schemas.

Example:
xsi:schemaLocation="http://ns.real.com/tools/job.2.0 job.2.0.xsd" (relative path)
xsi:schemaLocation="http://ns.real.com/tools/job.2.0 C:\job.2.0.xsd" (absolute path)

## Properties

The job section contains two attributes:

- enableTwoPass
- disableLoadManagement

These properties are described below.

enableTwoPass | [ job ]

Enables or disables 2-pass encoding.

2-pass is an encoding technique where the file is read in two passes. The first pass analyzes the file to determine where the most bits are required in the file. The second pass encodes the file using hints provided by the first pass. By disabling this option, the resulting file will be of lower quality but the encoding time is reduced by about one half. This option is applied to all outputs. 2-pass encoding only applies for encoding file to file so this option is ignored if input is a device or output is a server.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means 2-pass encoding is enabled (file is analyzed in 1 pass and encoded in a 2nd pass)
- A value of 'false' means 2-pass encoding is disabled (file is encoded in 1 pass)

Type:
bool

Example:
<enableTwoPass type="bool">false</enableTwoPass>

disableLoadManagement | [ job ]

Disables load management/CPU scalability functionality.

Load management occurs during real-time operation and enables codecs to reduce the complexity, and hence CPU requirements, in order to maintain steady state operation. This option should generally only be used for testing or in cases where there is a strong reason to disable automatic load management. Disabling load management may result undesirable behavior in cases where encoding load requirements exceeds available system resources.

Default:
false

Values:
Any valid Boolean Value where:

- A value of 'true' means 2-pass encoding is enabled (file is analyzed in 1 pass and encoded in a 2nd pass)
- A value of 'false' means 2-pass encoding is disabled (file is encoded in 1 pass)

Type:
bool

Example:
<disableLoadManagement type="bool">false</disableLoadManagement>

# Clip Info Section | [ job ]

The clipInfo section is where clip information (a.k.a. metadata) properties for the output media files are defined. The clip Info section supports any custom clip information entry, each containing a name and a value. The outline below shows the structure for the clipInfo section with one clip information entry populated.

- <clipInfo>
  - <entry>
    - <name> (See Standard Clip Information for a list of standard names)
    - <value>

The clip Info section may contain one or more entry sections. Each entry section defines a name/value clip information pair.

The clip Info section is optional. It may be included as a child to either the document root (job) or the output section.

The following rules define the behavior when clip information is included as a child to the document root (job) and/or the output section.

- When a clipInfo section is included as a child to the output section, each property applies to only that output.
- When a clipInfo section is included as a child to the document root (job), each property applies to all outputs.
- When a clipInfo section is included as a child to the document root (job) and the output section, properties in the output override properties in the job in the event that a property is duplicated in both places.

The properties of the clipInfo section are described below.

name | [ job > clipInfo ]

Clip info entry name. A string used as the name of a metadata field.

Default:
No Default

Values:
Any string up to 255 characters in length. Within each entry section a valid name must be provided or an error will result at encode time.

Type:
No type attribute.

Example:
<name>Title</name>

value | [ job > clipInfo ]

Clip info entry value. A string or unsigned integer used as the value of a metadata field.

Default:
Empty String

Values:
Any string up to 64k-1 characters in length or any valid unsigned integer depending on the type attribute.

Type:
string or uint

Example:
<value type="string">This is a string value</value>
<value type="uint">5</value>

## Standard Clip Information | [ job > clipInfo ]

Helix DNA Producer provides a fixed set of clip information from the command line user interface. Helix DNA Producer exposes the following metadata fields in the command line application:

- Title
- Author
- Copyright
- Keywords
- Description
- Content Rating

The standard properties of the clipInfo section are described below.

Title | [ job > clipInfo ( standard clip info ) ]

A metadata field to enter a clip title.

Default:
Empty String

Values:
Any string up to 255 bytes (i.e. 255 single-byte characters).

Type:
string

Example:
<entry>
<name>Title</name>
<value type="string">This is a Title</value>
</entry>

Author | [ job > clipInfo ( standard clip info ) ]

A metadata field to enter a clip author.

Default:
Empty String

Values:
Any string up to 255 bytes (i.e. 255 single-byte characters).

Type:
string

Example:
<entry>
<name>Author</name>
<value type="string">Your Name</value>
</entry>

Copyright | [ job > clipInfo ( standard clip info ) ]

A metadata field to enter a clip copyright.

Default:
Empty String

Values:
Any string up to 255 bytes (i.e. 255 single-byte characters).

Type:
string

Example:
<entry>
<name>Copyright</name>
<value type="string">Your Company (c) 2003</value>
</entry>

Keywords | [ job > clipInfo ( standard clip info ) ]

A metadata field to enter clip keywords.

Default:
Empty String

Values:
Any string up to 255 bytes (i.e. 255 single-byte characters).

Type:
string

Example:
<entry>
<name>Keywords</name>
<value type="string">keyword1 keyword2 keyword3</value>
</entry>

Description | [ job > clipInfo ( standard clip info ) ]

A metadata field to enter a clip description.

Default:
Empty String

Values:
Any string up to 1023 bytes (i.e. 1023 single-byte characters).

Type:
string

Example:
<entry>
<name>Description</name>
<value type="string">This is the description.</value>
</entry>

Content Rating | [ job > clipInfo ( standard clip info ) ]

Defines an age range category rating system. If this element is not included in the job file or the "No Rating" option is selected, then the Content Rating field is not added to the output RealMedia file.

Default:
0

Values:
Any integer from 0 to 6. 0 Means not rated.

The following values are valid:

- 0 - No Rating

- 1 - All Ages

- 2 - Older Children

- 3 - Younger Teens

- 4 - Older Teens (15 & up)

- 5 - Adult Supervision Recommended

- 6 - Adults Only

Type:
uint

Example:
<entry>
<name>Content Rating</name>
<value type="uint">1</value>
</entry>

# Parallel Inputs Section | [ job ]

The parInputs section entities that are to be executed in parallel. The parInputs section may be nested as a child of the job element or as a child of the seqInputs element. When included as a child to the job element, the parInputs section can contain or more input and seqInputs sections. When included as a child of a seqInputs section, the parInputs section can contain an input section only.

Below is an outline of the parInputs section when included as a child to the job element.

- <parInputs>
  - <input>
  - <seqInputs> (Not supported in this release)

Below is an outline of the parInputs section when included as a child to the seqInputs section.

- <parInputs>
  - <input>

One or more input sections or seqInputs sections may occur within a parInputs section. All input and seqInputs under the parInputs section are read in parallel. An input may be an a capture or file as described in the Input Section of this document. A seqInputs section groups one or more inputs to be read sequentially as described in the Sequential Inputs Section of this document. Inputs are required in order to perform encoding but valid job files may be created without any inputs to facilitate sharing of job files. Thus, a top level parInputs section is not required but must be included to perform encoding.

Note: seqInputs is not supported in this release. It is included for future compatibility purposes.

# Sequential Inputs Section | [ job > parInputs ]

The seqInputs section groups one or more input and parInputs sections. Below is an outline of the seqInputs section.

- <seqInputs>
  - <parInputs>
  - <input>

One or more input sections or parInputs sections may occur within a seqInputs section. All input and parInputs under the seqInputs section are read in parallel. An input may be an a capture or file as described in the Input Section of this document. A parInputs section groups one or more inputs to be read in parallel as described in the Parallel Inputs Section of this document. The seqInputs section is optional.

Note: seqInputs is not supported in this release. It is included for future compatibility purposes.

# Input Section | [ job > parInputs ]

The input section contains input media settings and one or more prefilters grouped within the prefilters section. Inputs specify where to read input source media from and what prefilters to apply to that input media before encoding.

An input can be one of several types depending on the value of the xsi:type attribute. The xsi:type attribute is a special XML entity that allows a single parent tag name to contain different sets of properties and subsections. The value of xsi:type identifies which set of properties and subsections may be contained within the parent tag.

An input element can contain any value of xsi:type as long as there is a plug-in defined to handle that input type. If XML Schema validation is being performed, there must also be a type defined matching the value of xsi:type as described in Validating and Extending Helix DNA Producer Settings Files with XML Schemas. Following is a list of known input types.

- <input xsi:type="avFileInput">
- <input xsi:type="captureInput">

Each of these input types are described below following the definition of the xsi:type attribute.

xsi:type | [ job > parInputs > input ]

XML Schema Instance Type Attribute. The xsi:type attribute stands for XML Schema Instance. This setting is used to identify the type of input that is defined within the section. Each instance of a input section may be one of several types and each type may contain a different group of properties and subsections. There are four known input types but new types can be defined as documented in Validating and Extending Helix DNA Producer Settings Files with XML Schemas.

Default:
No Default

Values:
The list of values below for xsi:type are known. Other types can be added.

- avFileInput
- captureInput

Example:
xsi:type="avFileInput"
xsi:type="acmeSpecialMediaSourceInput"

## AV File Input Section | [ job > parInputs > input ]

The input section of xsi:type avFileInput contains settings for file type inputs. This is an optional section. The outline below shows the structure for the input section of type avFileInput.

- <input xsi:type="avFileInput">
  - <prefilters>
  - <pluginName>
  - <name>
  - <filename>
  - <disableAudio>
  - <disableVideo>

The input section of xsi:type avFileInput may contain a prefilters subsection where one or more prefilter sections are defined. Prefilters allow the audio or video to be enhanced or modified in some way prior to encoding. For example, a prefilter might remove noise from audio or add a watermark to video. Prefilters defined in an input apply to all outputs in a job.

The properties of the input section of xsi:type avFileInput are described below.

pluginName | [ job > parInputs > input (avFileInput) ]

A string that defines the name of the plug-in to load. The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax for plug-in names as described in the Plug-in Names section.

Default:
No default. If not provided then all readers are scanned.

Values:
rn-avfile-aviuncompressed, rn-avfile-directshow, rn-avfile-movuncompressed, rn-avfile-qt, rn-avfile-wavuncompressed or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-avfile-aviuncompressed</pluginName>
<pluginName type="string">acme-avfile-myinputfiletype</pluginName>

name | [ job > parInputs > input (avFileInput) ]

The name assigned to an input. This name is used to identify an input. This is not a required field and typically used in graphical user interfaces only.

Default:
source<i> where i is the input number starting from 1. e.g. source1, source2, etc.

Values:
Any valid name.

Type:
string

Example:
<name type="string">My Input</name>

filename | [ job > parInputs > input (avFileInput) ]

A filename pointing to a file to be encoded.

Filename can be a relative or absolute path on a network or local drive. If relative paths provided, the location is relative to the current working directory (the directory you executed producer from). See File and Directory Paths below for valid cross platform file paths.

Ignored if Audio Capture Device or Audio Capture Device properties specified. May be left blank to allow job files to be shared between different systems.

Supported Input File Formats:
File type support varies by platform. The following list describes the input file types supported and the platforms they are supported on:

- Linux & Mac OSX
  - Uncompressed AVI
  - Uncompressed MOV
  - Uncompressed WAV
- Windows
  - All uncompressed file formats listed above
  - Any compressed and uncompressed file types supported by DirectShow
  - Any compressed and uncompressed file types supported by QuickTime

The later two items under Windows include compressed AVI, compressed QT, MPEG1, MPEG2, MP3 and many other compressed and uncompressed file formats. For MPEG2 you need to have an MPEG2 DirectShow filter which is installed by many software DVD players.

Supported Input Color Formats:

- YUV12 (a.k.a. I420)

- RGB 15, 16, 24, 322

- BGR 15, 16, 24, 32 (Macintosh versions of RGB)

- Windows YUV Formats: YUY2, YV12, YVU9, YVYU, CYUV, IYUV, UYNV, UYVY, V422, YUNV,

- Mac YUV Formats: 2VUY, YUVS, YVYU, YUVU, YVU9, YUV2, V210

Note: I420 is the native color format required by RealVideo codecs. Using I420 as input will improve performance by removing the need to convert the color format prior to encoding.

Default:
Blank

Values:
Any valid filename including path.

Type:
string

Example:
<filename type="string">c:\media\myfile.wav</filename>
<filename type="string">media/myfile.wav</filename>

disableAudio | [ job > parInputs > input (avFileInput) ]

Option to strip out audio from the input media file. Affects all output files.

Default:
false

Values:
Any valid Boolean Value where:

- A value of 'true' means audio output is disabled (i.e. stripped from the input)
- A value of 'false' means audio output is enabled

Type:
bool

Example:
<disableAudio type="bool">true</disableAudio>
<disableAudio type="bool">1</disableAudio>

disableVideo | [ job > parInputs > input (avFileInput) ]

Option to strip out video from the input media file. Affects all output files.

Default:
false

Values:
Any valid Boolean Value where:

- A value of 'true' means video output is disabled (i.e. stripped from the input)
- A value of 'false' means video output is enabled

Type:
bool

Example:
<disableVideo type="bool">true</disableVideo>
<disableVideo type="bool">1</disableVideo>

## Capture Input Section | [ job > parInputs > input ]

The input section of xsi:type captureInput contains settings for audio and video capture device type inputs. This is an optional section. The outline below shows the structure for the input section of type captureInput.

- <captureInput>
  - <prefilters>
  - <pluginName>
  - <name>
  - <duration>
  - <audioDeviceID>
  - <audioDevicePort>
  - <audioCaptureMono>
  - <videoDeviceID>
  - <videoDevicePort>
  - <videoFrameWidth>
  - <videoFrameHeight>

The input section of xsi:type captureInput may contain a prefilters subsection where one or more prefilter sections are defined. Prefilters allow the audio or video to be enhanced or modified in some way prior to encoding. For example, a prefilter might remove noise from audio or add a watermark to video. Prefilters defined in an input apply to all outputs in a job.

The properties of the input section of xsi:type captureInput are described below.

pluginName | [ job > parInputs > input (captureInput) ]

A string that defines the name of the plug-in to load. The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax for plug-in names as described in the Plug-in Names section.

Default:
rn-capture-av

Values:

rn-capture-av or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-capture-av</pluginName>
<pluginName type="string">acme-capture-mycapturetype</pluginName>

name | [ job > parInputs > input (captureInput) ]

Name to assign this input. Uniqueness of names is not required but strongly recommended.

Default:
input<i> where i is the input number starting from 1. e.g. input1, input2, etc.

Values:
Any valid name.

Type:
string

Example:
<name type="string">My Input</name>

duration | [ job > parInputs > input (captureInput) ]

The length of time for which the given capture device will apply. By definition, the encoder is designed to stop when all inputs stop. Thus, this setting essentially sets the duration of the encoding session. If not set, the default duration is infinite. The string 'infinite' or the number 0 is used to explicitly set the duration as infinite.

Default:
infinite

Values:
Any valid Duration.

Type:
duration

Example:
<duration type="duration">1:30:00</duration> (1 hour and 30 minutes)
<duration type="duration">60.0</duration> (60 seconds)
<duration type="duration">2:00:00:00</duration> (2 days)

Note: While fractions of a second can be specified, exact accuracy may not be achieved depending on the bit rate, CPU, capture device and other factors.

audioDeviceID | [ job > parInputs > input (captureInput) ]

Specifies the audio capture device ID for the input audio capture.

The audio capture device ID may obtained from the command line application option (-pd). Overrides the Input option (-i).

Note: On Linux, if an audio device is in use when opened by the command line application, the OSS audio driver will load the next available audio device instead of failing. 4Front Technologies has indicated that this behavior is scheduled to change in OSS version 3.99 scheduled to be released the 4th quarter of 2002. The new drivers will fail when attempting to access any device except for /dev/dsp which will retain the behavior of finding the next available device.

Default:
No Default

Values:

Audio Device name or number. Allowable values can be any of:

- Any integer 0 and higher identifying a specific device number (e.g. "0")
- A string matching an existing device name (e.g. "Sound Blaster Live!").
- A string with wildcard (*) matching an existing device name (e.g. "Sound Blaster*")
- A UNIX device name (e.g. /dev/audio)

Type:
string

Example:
<audioDeviceID type="string">VIA Audio (WAVE)</audioDeviceID>
<audioDeviceID type="string">0</audioDeviceID>
<audioDeviceID type="string">/dev/dsp1</audioDeviceID> (Linux only)

audioDevicePort | [ job > parInputs > input (captureInput) ]

Specifies the audio port for the input audio capture device.

The port may be obtained from the command line application option (-pd). Audio port may be omitted in which case the current mixer settings are used. If used, must be accompanied by the audioDeviceID property.

This option is not available under Windows or under Linux when using the free OSS audio drivers. In these cases, set audio capture port using the Windows Recording Control Panel or Linux distribution specific mixer software instead.

Default:
No Default

Values:

Audio Port name or number. Allowable values can be any of:

- Any integer 0 and higher identifying a specific port number (e.g. "0")
- A string matching an existing port name (e.g. "Line in").
- A string with wildcard (*) matching an existing port name (e.g. "Mic*")

Type:
string

Example:
<audioDevicePort type="string">0</audioDevicePort>
<audioDevicePort type="string">Line-in</audioDevicePort>
<audioDevicePort type="string">Mic*</audioDevicePort>

videoDeviceID | [ job > parInputs > input (captureInput) ]

Specifies the video capture device ID (i.e. video capture card) for input video capture.

The video capture device ID may be obtained from the command line application option (-pd).

Video Frame rate for input capture is determined by the maxFrameRate property in the audiences defined for the current encoding session. The largest frame rate among all audiences is selected.

Default:
No Default

Values:

Video Device name or number. Allowable values can be any of:

- Any integer 0 and higher identifying a specific device number (e.g. "0")
- A string matching an existing device name (e.g. "Osprey Capture Card 1").
- A string with wildcard (*) matching an existing device name (e.g. "Osprey*")
- A UNIX device name (e.g. /dev/video)

Type:
string

Example:
<videoDeviceID type="string">0</videoDeviceID>
<videoDeviceID type="string">Osprey Capture Card 1</videoDeviceID>
<videoDeviceID type="string">Osprey*</videoDeviceID>
<videoDeviceID type="string">/dev/video3</videoDeviceID>

videoDevicePort | [ job > parInputs > input (captureInput) ]

Specifies the device port (e.g. Composite 1, S-Video) for the input video device.

The video capture port may be obtained from the command line application option -pd. Video port may be omitted in which case the current device settings are used. If used, must be accompanied by the videoDeviceID property.

Not available for Video for Windows (VFW) devices (video capture port is set via the device driver dialog instead).

Default:
No Defalut

Values:

Video Port name or number. Allowable values can be any of:

- Any integer 0 and higher identifying a specific port number (e.g. "0")
- A string matching an existing port name (e.g. "Composite 1").
- A string with wildcard (*) matching an existing port name (e.g. "Composite*")

Type:
string

Example:
<videoDevicePort type="string">0</videoDevicePort>
<videoDevicePort type="string">Composite 1</videoDevicePort>

videoFrameWidth | [ job > parInputs > input (captureInput) ]

Width in pixels of the video image size that the capture cards is configured to provide.

Ignored for audio only inputs or input is a file.

Width of the final encoded output must be divisible by the number of pixels suitable for the output codec. For RealVideo, the width and height must be divisible by 4 pixels (e.g. 32, 36, 40, ... 2048). If videoFrameWidth is not an even increment of that supported by the codec, the video is cropped down to the nearest multiple that is supported as input to the codec just prior to encoding but after all prefiltering and resizing have occurred.

If the device does not support the requested capture size, Producer attempts to negotiate a capture by dropping the capture frame width and height to the next lower increment allowed by card. If Producer is able to negotiate a capture frame size different from the requested capture frame width or height, a warning is logged and encoding proceeds. If a capture frame width or height cannot be negotiated, encoding fails and an error is logged.

Default:
0

Values:
Any positive integer divisible by 4, not to exceed 2048. A value of 0 means that the width should be defined by the last device setting or by the device default.

Type:
uint

Example:
<videoFrameWidth type="uint">320</videoFrameWidth>

videoFrameHeight | [ job > parInputs > input (captureInput) ]

Height in pixels of the video image size that the capture card is configured to provide.

Ignored for audio only inputs or input is a file.

Height of the final encoded output must be divisible by the number of pixels suitable for the output codec. For RealVideo, the width and height must be divisible by 4 pixels (e.g. 32, 36, 40, ... 2048). If videoFrameHeight is not an even increment of that supported by the codec, the video is cropped down to the nearest multiple that is supported as input to the codec just prior to encoding but after all prefiltering and resizing have occurred.

If the device does not support the requested capture size, Producer attempts to negotiate a capture by dropping the capture frame width and height to the next lower increment allowed by card. If Producer is able to negotiate a capture frame size different from the requested capture frame width or height, a warning is logged and encoding proceeds. If a capture frame width or height cannot be negotiated, encoding fails and an error is logged.

Default:
0

Values:
Any positive unsigned integer divisible by 4. Not to exceed 2048. A value of 0 means that the width should be defined by the last device setting or the device default.

Type:
uint

Example:
<videoFrameHeight type="uint">240</videoFrameHeight>

# Prefilters Section | [ job > parInputs > input ]

The prefilters section groups one or more prefilter sections. Below is an outline of the prefilters section.

- <prefilters>
  - <prefilter>

One or more prefilter sections may occur within a prefilters section. A prefilter may be an audio or video prefilter as described in the Prefilter section of this document. Prefilters are not required in order to perform encoding.

The prefilters section is optional. A prefilters section may be included as a child to the input section. Prefilters included in the input element apply to all outputs.

# Prefilter Section | [ job > parInputs > input > prefilters ]

A prefilter section contains settings for a single prefilter. Prefilters allow the audio or video to be enhanced or modified in some way prior to encoding. For example, a prefilter might remove noise from audio or add a watermark to video.

A prefilter can be one of several types depending on the value of the xsi:type attribute. The xsi:type attribute is a special XML entity that allows a single parent tag name to contain different sets of properties and subsections. The value of xsi:type identifies which set of properties and subsections may be contained within the parent tag.

A prefilter section can contain any value of xsi:type as long as there is a plug-in defined to handle that prefilter type. If XML Schema validation is being performed, there must also be a type defined matching the value of xsi:type as described in Validating and Extending Helix DNA Producer Settings Files with XML Schemas. Following is a list of known prefilter types.

- <prefilter xsi:type="inputCroppingPrefilter">
- <prefilter xsi:type="deinterlacePrefilter">
- <prefilter xsi:type="videoNoiseReductionPrefilter">
- <prefilter xsi:type="videoResizePrefilter">
- <prefilter xsi:type="blackLevelPrefilter">
- <prefilter xsi:type="audioGainPrefilter">
- <prefilter xsi:type="audioMeterPrefilter">
- <prefilter xsi:type="audioDelayCompPrefilter">

Each of these prefilter types are described below following the definition of the xsi:type attribute.

Note: The order of prefilters in a job file can affect the resulting quality of the video or audio. See the Prefilter Order section below for more information on the proper order for prefiltering.

xsi:type | [ job > parInputs > input > prefilters > prefilter ]

XML Schema Instance Type Attribute. The xsi:type attribute stands for XML Schema Instance. This setting is used to identify the type of prefilter that is defined within the section. Each instance of a prefilter section may be one of several types and each type may contain a different group of properties and subsections. There are four known prefilter types but new types can be defined as documented in Validating and Extending Helix DNA Producer Settings Files with XML Schemas.

Default:
No Default

Values:
The list of values below for xsi:type are known. Other types can be added.

- inputCroppingPrefilter
- deinterlacePrefilter
- videoNoiseReductionPrefilter
- blackLevelPrefilter
- videoReiszePrefilter
- audioGainPrefilter
- audioMeterPrefilter
- audioDelayCompPrefilter

Example:
xsi:type="inputCroppingPrefilter"
xsi:type="acmePrefilter"

## Video Cropping Prefilter | [ job > parInputs > input > prefilters > prefilter ]

The prefilter section of xsi:type inputCroppingPrefilter contains settings for input video cropping. This is an optional section. The outline below shows the structure for the prefilter section of type inputCroppingPrefilter.

- <prefilter xsi:type="inputCroppingPrefilter">
  - <pluginName>
  - <enabled>
  - <left>
  - <top>
  - <width>
  - <height>

The properties of the inputCroppingPrefilter section are described below.

pluginName | [ job > parInputs > input > prefilters > prefilter (videoCroppingPrefilter) ]

A string that defines the name of the plug-in to load. The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax for plug-in names as described in the Plug-in Names section.

Default:
rn-prefilter-inputcropping

Values:
rn-prefilter-inputcropping or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-prefilter-videocropping</pluginName>
<pluginName type="string">acme-prefilter-myprefilter</pluginName>

enabled | [ job > parInputs > input > prefilters > prefilter (videoCroppingPrefilter) ]

Property to enable or disable the video cropping prefilter. Enabling the prefilter means that video cropping is applied.

From the SDK, this prefilter must be enabled before encoding has started. The filter can not be enabled or disabled in during encoding.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means the prefilter is turned on and cropping is performed.
- A value of 'false' means the prefilter is loaded but disabled during the encode so no cropping occurs.

Type:
bool

Example:
<enabled type="bool">false</enabled>

left | [ job > parInputs > input > prefilters > prefilter (videoCroppingPrefilter) ]

An integer value representing the left side of the cropping region.

Default:
0

Values:
Any unsigned integer from 0 thru 32 less than the input width

Type:
uint

Example:
<left type="uint">2</left>

top | [ job > parInputs > input > prefilters > prefilter (videoCroppingPrefilter) ]

The value representing the top side of the cropping region.

Default:
0

Values:
Any unsigned integer from 0 thru 32 less than the input height

Type:
uint

Example:
<top type="uint">2</top>

width | [ job > parInputs > input > prefilters > prefilter (videoCroppingPrefilter) ]

The value representing the right side or width of the cropping region.

Default:
Width of the input video

Values:
Any unsigned integer from 32 to width of input video in increments of 4 pixels. If the frame size provided is not an increment of 4 pixels, it is truncated to the next lower valid value.

Type:
uint

Example:
<width type="uint">316</width>

height | [ job > parInputs > input > prefilters > prefilter (videoCroppingPrefilter) ]

The value representing the bottom or height of the cropping region.

Default:
Height of the input video

Values:
Any integer from 32 to height of input video in increments of 4 pixels. If the frame size provided is not an increment of 4 pixels, it is truncated to the next lower valid value.

Type:
uint

Example:
<height type="uint">236</height>

## Deinterlace/Inverse Telecine Prefilter | [ job > parInputs > input > prefilters > prefilter]

The prefilter section of xsi:type deinterlacePrefilter containing settings for De-interlace and Inverse Telecine filtering. This is an optional section. The outline below shows the structure for the prefilter section of type deinterlacePrefilter.

- <prefilter xsi:type="deinterlacePrefilter">
  - <pluginName>
  - <enabled>
  - <manual>
  - <deinterlace>
  - <inverseTelecine>

The properties of the deinterlacePrefilter section are described below.

pluginName | [ job > parInputs > input > prefilters > prefilter (deinterlacePrefilter) ]

A string that defines the name of the plug-in to load. The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax for plug-in names as described in the Plug-in Names section.

Default:
rn-prefilter-deinterlace

Values:
rn-prefilter-deinterlace or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-prefilter-deinterlace</pluginName>
<pluginName type="string">acme-prefilter-myprefilter</pluginName>

enabled | [ job > parInputs > input > prefilters > prefilter (deinterlacePrefilter) ]

Property to enable or disable the video de-interlace/inverse telecine prefilter. Enabling the prefilter means that de-interlace and inverse telecine is performed as specified below.

From the SDK, this prefilter may be enabled or disabled after encoding has started.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means the prefilter is turned on and de-interlace and inverse telecine is performed as specified below.
- A value of 'false' means the prefilter is loaded but disabled during the encode so that no deinterlace or inverse telecine are performed.

Type:
bool

Example:
<enabled type="bool">false</enabled>

manual | [ job > parInputs > input > prefilters > prefilter (deinterlacePrefilter) ]

Enable/Disable manual/auto mode. If false, and the filter is enabled, this option to cause the filter will examine the video to determine if it is needed, then apply what it considers the appropriate filtering (either deinterlace, inverse telecine, or both). This is an optional parameter. If it is not included, it is assumed to be false, and the filter will default to automatic behavior.

Default:
false

Values:
Any valid Boolean Value

Type:
bool

Example:
<manual type="bool">true</manual>

deinterlace | [ job > parInputs > input > prefilters > prefilter (deinterlacePrefilter) ]

Force De-interlace. If manual is false, this value is ignored. If manual is true, then is value determines if deinterlace will be applied to the video. This parameter is ignored and is optional if manual is not defined.

Default:
true

Values:
Any valid Boolean Value

Type:
bool

Example:
<deinterlace type="bool">true</deinterlace>

inverseTelecine | [ job > parInputs > input > prefilters > prefilter (deinterlacePrefilter) ]

Force inverse telecine. If manual is false, this value is ignored. If manual is true, then is value determines if inverse telecine will be applied to the video. This parameter is ignored and is optional if manual is not defined.

Default:
true

Values:
Any valid Boolean Value

Type:
bool

Example:
<inverseTelecine type="bool">true</inverseTelecine>

## Video Noise Reduction Prefilter | [ job > parInputs > input > prefilters > prefilter ]

The prefilter section of xsi:type videoNoiseReductionPrefilter containing settings for video noise reduction. This is an optional section. The outline below shows the structure for the prefilter section of type videoNoiseReductionPrefilter.

- <prefilter xsi:type="videoNoiseReductionPrefilter">
  - <pluginName>
  - <enabled>
  - <level>

The properties of the videoNoiseReductionPrefilter section are described below.

pluginName | [ job > parInputs > input > prefilters > prefilter (videoNoiseReductionPrefilter) ]

A string that defines the name of the plug-in to load. The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax for plug-in names as described in the Plug-in Names section.

Default:
rn-prefilter-videonoisereduction

Values:
rn-prefilter-videonoisereduction or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-prefilter-videonoisereduction</pluginName>
<pluginName type="string">acme-prefilter-myprefilter</pluginName>

enabled | [ job > parInputs > input > prefilters > prefilter (videoNoiseReductionPrefilter) ]

Property to enable or disable the video noise reduction prefilter. Enabling the prefilter means that video noise reduction is performed.

From the SDK, this prefilter may be enabled or disabled after encoding has started.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means the prefilter is turned on and video noise reduction is performed.
- A value of 'false' means the prefilter is loaded but disabled during the encode so that no video noise reduction is performed.

Type:
bool

Example:
<enabled type="bool">false</enabled>

level | [ job > parInputs > input > prefilters > prefilter (videoNoiseReductionPrefilter) ]

This filter removes small distortions or static in the video image. This filter is applied to all inputs.

Default:
low

Values:
low/high

Type:
string

Example:
<level type="string">high</level>

## Video Resize Prefilter | [ job > parInputs > input > prefilters > prefilter ]

The prefilter section of xsi:type videoResizePrefilter containing settings for video resizing. This is an optional section. The outline below shows the structure for the prefilter section of type videoResizePrefilter.

- <prefilter xsi:type="videoResizePrefilter">
  - <pluginName>
  - <enabled>
  - <videoResizeWidth>
  - <videoResizeHeight>
  - <videoResizeQuality>

The properties of the videoResizePrefilter section are described below.

This prefilter is provided in the event that resizing must occur in a specific sequence in the prefilter chain. Unless required, consider using the Output Width and Output Height to enable the codec to perform more optimal resizing (see Output Width and Output Height for details).

pluginName | [ job > parInputs > input > prefilters > prefilter (videoResizePrefilter) ]

A string that defines the name of the plug-in to load. The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax for plug-in names as described in the Plug-in Names section.

Default:
rn-prefilter-videoresize

Values:
rn-prefilter-videoresize or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-prefilter-videoresize</pluginName>
<pluginName type="string">acme-prefilter-myprefilter</pluginName>

enabled | [ job > parInputs > input > prefilters > prefilter (videoResizePrefilter) ]

Property to enable or disable the video resize prefilter. Enabling the prefilter means that video resize is performed.

From the SDK, this prefilter may be enabled or disabled after encoding has started.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means the prefilter is turned on and video resize is performed.
- A value of 'false' means the prefilter is loaded but disabled during the encode so that no video resize is performed.

Type:
bool

Example:
<enabled type="bool">false</enabled>

videoResizeWidth | [ job > parInputs > input > prefilters > prefilter (videoResizePrefilter) ]

Resizes the video width in pixels. This prefilter is provided in the event that resizing must occur in a specific sequence in the prefilter chain. Unless required, consider using the Output Width and Output Height to enable the codec to perform more optimal resizing (see Output Width and Output Height for details).

Both videoResizeWidth and videoResizeHeight are related as follows:

- If only videoResizeWidth = 0 then videoResizeWidth is computed from the videoResizeHeight and input aspect ratio.

- If only videoResizeHeight = 0 then videoResizeHeight is computed from the videoResizeWidth and input aspect ratio.

- If videoResizeHeight = 0 and videoResizeWidth = 0 then no resizing occurs.

- If videoResizeHeight and videoResizeWidth are omitted then no resizing occurs.

Width and height values of the final encoded output must be divisible by the number of pixels suitable for the output codec. It is recommended that the width and height values used in resize be even increments of that supported by the codec. For RealVideo, the width and height must be divisible by 4 pixels (e.g. 32, 36, 40, ... 2048). If width or height are not an even increment of that supported by the codec, the video is cropped down to the nearest multiple that is supported as input to the codec just prior to encoding but after all prefiltering and resizing have occurred.

Resize should be avoided if possible for live video capture due to the significant load that resizing incurs. Instead, perform any necessary video scaling operations in hardware by choosing the input video capture size (videoFrameWidth and videoFrameHeight). Note, while most capture devices perform resizing of video in hardware, some capture devices such as USB cameras do not. If you observe very high loads for live capture, consult your hardware documentation for the default capture size and try performing fast quality resize (videoResizeQuality). If you are using a DV capture device, capture size settings are defined in the DV Decoder available through the capture settings dialog.

Ignored for audio-only inputs.

Default:
0 (same width as input)

Values:
An integer 0 or 32 to 2048 in multiples supported by the output codec (see above)

Type:
uint

Example:
<videoResizeWidth type="uint">320</videoResizeWidth>
<videoResizeWidth type="uint">0</videoResizeWidth> (No resize or maintain aspect ratio)

videoResizeHeight | [ job > parInputs > input > prefilters > prefilter (videoResizePrefilter) ]

Sets the output video height in pixels. This prefilter is provided in the event that resizing must occur in a specific sequence in the prefilter chain. Unless required, consider using the Output Width and Output Height to enable the codec to perform more optimal resizing (see Output Width and Output Height for details).

Both videoResizeWidth and videoResizeHeight are related as follows:

- If only videoResizeWidth = 0 then videoResizeWidth is computed from the videoResizeHeight and input aspect ratio.

- If only videoResizeHeight = 0 then videoResizeHeight is computed from the videoResizeWidth and input aspect ratio.

- If videoResizeHeight = 0 and videoResizeWidth = 0 then no resizing occurs.

- If videoResizeHeight and videoResizeWidth are omitted then no resizing occurs.

Width and height values of the final encoded output must be divisible by the number of pixels suitable for the output codec. It is recommended that the width and height values used in resize be even increments of that supported by the codec. For RealVideo, the width and height must be divisible by 4 pixels (e.g. 32, 36, 40, ... 2048). If width or height are not an even increment of that supported by the codec, the video is cropped down to the nearest multiple that is supported as input to the codec just prior to encoding but after all prefiltering and resizing have occurred.

Resize should be avoided if possible for live video capture due to the significant load that resizing incurs. Instead, perform any necessary video scaling operations in hardware by choosing the input video capture size (videoFrameWidth and videoFrameHeight). Note, while most capture devices perform resizing of video in hardware, some capture devices such as USB cameras do not. If you observe very high loads for live capture, consult your hardware documentation for the default capture size and try performing fast quality resize (videoResizeQuality). If you are using a DV capture device, capture size settings are defined in the DV Decoder available through the capture settings dialog.

Ignored for audio-only inputs.

Default:
0 (same height as input)

Values:
An integer 0 or 32 to 2048 in multiples of 4 (e.g. 0, 32, 36, 40, ... 2048)

Type:
uint

Example:
<videoResizeHeight type="uint">240</videoResizeHeight>
<videoResizeHeight type="uint">0</videoResizeHeight> (No resize or maintain aspect ratio)

videoResizeQuality | [ job > parInputs > input > prefilters > prefilter (videoResizePrefilter) ]

Affects the resulting quality of an output video when resize is applied. Choosing high results in a better quality resize but uses considerably more CPU.

Default:
high

Values:
fast or high

Type:
string

Example:
<videoResizeQuality type="string">fast</videoResizeQuality>

## Black Level Prefilter | [ job > parInputs > input > prefilters > prefilter ]

The prefilter section of xsi:type blackLevelPrefilter containing settings for black level filtering. This is an optional section. The outline below shows the structure for the prefilter section of type blackLevelPrefilter.

- <prefilter xsi:type="blackLevelPrefilter">
  - <pluginName>
  - <enabled>

The properties of the blackLevelPrefilter section are described below.

pluginName | [ job > parInputs > input > prefilters > prefilter (blackLevelPrefilter) ]

A string that defines the name of the plug-in to load. The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax for plug-in names as described in the Plug-in Names section.

Default:
rn-prefilter-blacklevel

Values:
rn-prefilter-blacklevel or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-prefilter-blacklevel</pluginName>
<pluginName type="string">acme-prefilter-myprefilter</pluginName>

enabled | [ job > parInputs > input > prefilters > prefilter (blackLevelPrefilter) ]

Property to enable or disable the black level prefilter. Enabling the prefilter means that black level adjustments are performed.

From the SDK, this prefilter may be enabled or disabled after encoding has started.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means the prefilter is turned on and black level prefiltering is performed
- A value of 'false' means the prefilter is loaded but disabled during the encode so that no black level prefiltering is performed.

Type:
bool

Example:
<enabled type="bool">true</enabled>

## Audio Gain Prefilter | [ job > parInputs > input > prefilters > prefilter ]

The prefilter section of xsi:type audioGainPrefilter containing settings for audio gain control. This is an optional section. The outline below shows the structure for the prefilter section of type audioGainPrefilter.

- <prefilter xsi:type="audioGainPrefilter">
  - <pluginName>
  - <enabled>
  - <gain>

The properties of the audioGainPrefilter section are described below.

pluginName | [ job > parInputs > input > prefilters > prefilter (audioGainPrefilter) ]

Unique name assigned to prefilter plug-in. This is a way to uniquely identify a prefilter plug-in.

Default:
rn-prefilter-audiogain

Values:
rn-prefilter-audiogain or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-prefilter-audiogain</pluginName>
<pluginName type="string">acme-prefilter-myprefilter</pluginName>

enabled | [ job > parInputs > input > prefilters > prefilter (audioGainPrefilter) ]

Property to enable or disable the audio gain prefilter. Enabling the prefilter means that audio gain is applied.

From the SDK, this prefilter may be enabled or disabled after encoding has started. However, setting the enabled property to false simply set the gain to 0; it will not disable processing altogether.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means the prefilter is turned on and audio gain as defined in gain setting is applied.
- A value of 'false' means the prefilter is loaded but disabled during the encode so that no audio gain is applied.

Type:
bool

Example:
<enabled type="bool">true</enabled>

gain | [ job > parInputs > input > prefilters > prefilter (audioGainPrefilter) ]

Provides audio gain control to lower or increase the audio levels. The value of gain is set in units of dB and can range from +12 dB gain (amplification) to -12 dB gain (attenuation). Where the gain-modified signal would otherwise clip, dynamic range compression is applied. Thus, this filter will never introduce clipping, even at the maximum gain level. This filter is applied to all inputs. If option is omitted, the audio levels are not modified.

It is extremely important that you avoid clipping at your sound card by adjusting mixer levels too high or at any point where audio is processed. This means you should adjust the analog gains leading up to your sound card input such that the input VU meter never goes to the 0 dB level. If needed, perform audio gain in an external mixer board to avoid adding too much gain using the sound card's audio mixer.

With certain material and input sources, this may lead to sound levels which are too low on average. In this case, use the gain tool to bring the signal up to acceptable levels. This is safe to do, as the gain tool will not introduce clipping (as an analog gain would).

Default:
0

Values:
Any number from -12 to +12

Type:
double

Example:
<gain type="double">6.5</gain>
<gain type="double">-6</gain> (lowering audio level)

## Audio Meter Prefilter | [ job > parInputs > input > prefilters > prefilter ]

The prefilter section of xsi:type audioMeterPrefilter containing settings for audio VU Metering. This is an optional section. This section is not required because the VU Meter prefilter is automatically added by the command line and GUI applications in order to display audio levels. The outline below shows the structure for the prefilter section of type audioMeterPrefilter.

- <prefilter xsi:type="audioMeterPrefilter">
  - <pluginName>
  - <enabled>

The properties of the audioMeterPrefilter section are described below.

pluginName | [ job > parInputs > input > prefilters > prefilter (audioMeterPrefilter) ]

Unique name assigned to prefilter plug-in. This is a way to uniquely identify a prefilter plug-in.

Default:
rn-prefilter-audiometer

Values:
rn-prefilter-audiometer or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-prefilter-audiometer</pluginName>
<pluginName type="string">acme-prefilter-myprefilter</pluginName>

enabled | [ job > parInputs > input > prefilters > prefilter (audioMeterPrefilter) ]

Property to enable or disable the audio meter prefilter. Enabling the prefilter means that audio metering is performed.

This filter must be enabled in order for an application to display audio levels. If the audio meter prefilter is omitted from a job, it is automatically added by the command line and GUI applications in order to display audio levels.

From the SDK, this prefilter may be enabled or disabled after encoding has started.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means the prefilter is turned on and audio metering is performed.
- A value of 'false' means the prefilter is loaded but disabled during the encode so that no audio metering is performed.

Type:
bool

Example:
<enabled type="bool">true</enabled>

## Audio Delay Compensation Prefilter | [ job > parInputs > input > prefilters > prefilter ]

The prefilter section of xsi:type audioDelayCompPrefilter contains settings for correcting audio shift when audio input is out of synch with video. This filter takes a delay in seconds (fractions of a second supported) and shifts the audio in time (negative or positive) by the indicated amount. This filter is useful if there is delay in the audio or video input. Some video editing tools, such as DVD ripping software, provide information on how much delay exists between audio an video in the files they create. Using this filter, that delay can be corrected at encode time without additional pre-processing steps.

The filter works by adjusting time stamps of the audio. If necessary, audio samples are dropped at the beginning of the audio stream to make sure that timestamps never go negative or silence added at the beginning.

This filter has essentially no impact on the CPU and adds latency equivalent to the value of delay.

This is an optional section. The outline below shows the structure for the audioDelayCompPrefilter section.

- <audioDelayCompPrefilter>
  - <pluginName>
  - <enabled>
  - <delay>
  - <advance>

The properties of the audioDelayCompPrefilter section are described below.

pluginName | [ job > parInputs > input > prefilters > prefilter (audioDelayCompPrefilter) ]

Unique name assigned to prefilter plug-in. This is a way to uniquely identify a prefilter plug-in.

Default:
rn-prefilter-audiodelaycomp

Values:
rn-prefilter-audiodelaycomp or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-prefilter-audiodelaycomp</pluginName>

enabled | [ job > parInputs > input > prefilters > prefilter (audioDelayCompPrefilter) ]

Property to enable or disable the audio delay compensation prefilter. Enabling the prefilter means that audio delay compensation as defined by the delay property is applied.

From the SDK, this prefilter must be enabled before encoding has started. The filter can not be enabled or disabled in during encoding.

Default:
true

Values:
Any valid Boolean Value where:

- A value of 'true' means the prefilter is turned on and audio delay as defined in the delay property is applied.
- A value of 'false' means the prefilter is loaded but disabled during the encode and audio delay is not applied.

Type:
bool

Example:
<enabled type="bool">true</enabled>

delay | [ job > parInputs > input > prefilters > prefilter (audioDelayCompPrefilter) ]

The value by which timestamps are delayed. Audio timestamps can be adjusted using either the delay and/or the advance properties as follows:

- If the delay property is set, the audio signal is delayed by that amount of time. This is done by padding delay seconds of silence at the beginning of the audio stream and adjusting the timestamp on all other audio samples so they occur delay seconds earlier.
- If the advance property is set the audio signal is advanced by that amount of time by removing advance seconds of audio samples at the beginning of the audio stream and adjusting the timestamp on all other audio samples so they occur advance seconds later in time.
- If both the delay and advance properties are set, then they are summed such the two are essentially subtracted from one another and the remainder is applied as delay or advance, whichever is applicable..

This filter is applied to all inputs. If option is omitted, the audio delay is not modified.

Default:
0

Values:
Any valid Duration.

Type:
duration

Example:
<delay type="duration">0.200</delay> (delaying audio in time relative to other streams by .2 seconds)
<delay type="duration">-0.255</delay>

advance | [ job > parInputs > input > prefilters > prefilter (audioDelayCompPrefilter) ]

The value by which timestamps are advanced. Audio timestamps can be adjusted using either the delay and/or the advance properties as follows:

- If the delay property is set, the audio signal is delayed by that amount of time. This is done by padding delay seconds of silence at the beginning of the audio stream and adjusting the timestamp on all other audio samples so they occur delay seconds earlier.
- If the advance property is set the audio signal is advanced by that amount of time by removing advance seconds of audio samples at the beginning of the audio stream and adjusting the timestamp on all other audio samples so they occur advance seconds later in time.
- If both the delay and advance properties are set, then they are summed such the two are essentially subtracted from one another and the remainder is applied as delay or advance, whichever is applicable..

This filter is applied to all inputs. If option is omitted, the audio delay is not modified.

Default:
0

Values:
Any valid Duration.

Type:
duration

Example:
<advance type="duration">0.200</advance> (advancing audio in time relative to other streams by .2 seconds)
<advance type="duration">-0.255</advance>

## Prefilter Order

Because a prefilters change the audio or video data before passing it on, the order in which a prefilter section appears in the prefilters section file can affect the resulting output. The wrong order can degrade the output by changing the input and preventing subsequent prefilters from doing their intended task. For example, resizing height or performing noise reduction on an input video stream before performing a de-interlace operation can change the input video signal enough to make it impossible to detect interlacing artifacts and remove them.

Prefilter order is determined by their position in the prefilters section. Prefilters in a job file are ordered from top to bottom where the topmost prefilter section in the prefilters section is loaded earliest in the prefilter chain.

The ideal order for video prefilters included in a Job File is:

1. Horizontal Resize
2. Cropping
3. Inverse Telecine
4. De-interlace
5. Video Noise Reduction
6. Black Level
7. Vertical Resize

### Video Resize

For quality reasons, vertical resize of the video should always be performed after most video pre-processing operations. Most importantly, vertical resize should be performed after inverse telecine and de-interlace due to the probability that resizing vertically will modify the video signal such that removing interlace or telecine becomes impossible.

There are two places to specify resize settings. They are:

- Video Resize Filter Section - Inserts a video resize filter in the position specified in the job file
- Media Profile Section - Performs video resize after all other prefiltering operations.

Defining resize settings in the mediaProfile section allows the codec to apply an optimization when encoding to RealVideo. When resize is defined in the mediaProfile section, video resize is performed by the codec. This allows the codec to perform the following optimization:

- If the video is resized up, the codec does not actually resize the video but instead adds information to the stream header that instructs the player to render the video at the larger frame size. This avoids having to "invent" pixels and saves system resources.

While defining video resize settings in the mediaProfile section allows optimal performance, the video resize prefilter is useful for correcting for non-square pixel aspect ratios. If the input video, such as DV, has non-square pixel aspect ratio, the video can be resized down horizontally to convert non-square pixels to square pixels.

### Droped-frames Sensitive Prefilters

The De-interlace and duplicate video frame dropper prefilter expose a property that tell the SDK not to drop frames before these prefilters. These prefilters, as well as any other prefilter exposing the "Drop frames after me" property, will always be loaded in the filter chain such that the prefilter plug-in responsible for dropping video frames in response to system load will be loaded after these. This property, if implemented by a prefilter, is used to prevents the SDK from dropping frames before that prefilter. This property should be used only on prefilters that require access to every frame in sequence in order to perform its work properly.

# Postfilters Section | [ job > parOutputs > output > destinations > destination ]

The postfilters section groups one or more postfilter sections. Below is an outline of the postfilters section.

- <postfilters>
  - <postfilter>

One or more postfilter sections may occur within a postfilters section. Postfilters are not required in order to perform encoding.

The postfilters section is optional. A postfilters section may be included as a child to the destination section. Postfilters included in the destination section apply to only to that destination.

# Postfilter Section | [ job > parOutputs > output > destinations > destination > postfilters ]

A postfilter section contains settings for a single postfilter. Postfilters allow the audio or video to be transformed in some way after encoding has taken place. For example, a postfilter might encrypt the audio and video for a digital rights management solution.

A postfilter can be one of several types depending on the value of the xsi:type attribute. The xsi:type attribute is a special XML entity that allows a single parent tag name to contain different sets of properties and subsections. The value of xsi:type identifies which set of properties and subsections may be contained within the parent tag.

A postfilter section can contain any value of xsi:type as long as there is a plug-in defined to handle that postfilter type. If XML Schema validation is being performed, there must also be a type defined matching the value of xsi:type as described in Validating and Extending Helix DNA Producer Settings Files with XML Schemas. There are no known postfilter types for Helix DNA Producer at this time.

The xsi:type attribute is described below.

xsi:type | [ job > parOutputs > output > destinations > destination > postfilters > postfilter ]

XML Schema Instance Type Attribute. The xsi:type attribute stands for XML Schema Instance. This setting is used to identify the type of postfilter that is defined within the section. Each instance of a postfilter section may be one of several types and each type may contain a different group of properties and subsections. There are no known postfilter types but new types can be defined as documented in Validating and Extending Helix DNA Producer Settings Files with XML Schemas.

Default:
No Default

Values:
No known types for xsi:type are known at this time. Types can be added as noted above.

Example:
<postfilter xsi:type="acmePostfilter">

# Parallel Outputs Section | [ job ]

The parOutputs section contains one or more output sections. An output is a collection of encoding settings and one or more file or server destinations. See the output section below for more information on the output section. All outputs within the parOutputs section are run in parallel.

# Output Section | [ job > parOutputs ]

The output section contains encoding settings grouped within the mediaProfile section and one or more destinations grouped within the destinations section. Below is an outline the output section.

- <output>
  - <destinations>
  - <mediaProfile>
  - <clipInfo>

The destinations, mediaProfile and clipInfo sections are optional.

The mediaProfile section holds one or more encoding settings for how the output should be encoded.

The destinations section holds one or more file or server destinations that the encoded media is written to. All destination sections within the destinations section are written in parallel.

The clipInfo section allows one or more clip information name/value pairs to be defined which are added to the media file. Standard clip information, like title, author and copyright, are displayed in the player upon playback. Other clip information may be used in search engines or displayed in custom players. The contents of the clipInfo section and rules defining behavior when clip information is included in both an output section and as a child to the root element job are explained above in the Clip Info section of this document.

# Destinations Section | [ job > parOutputs > output ]

The destinations section groups one or more destination sections. Below is an outline of the destinations section.

- <destinations>
  - <destination>

One or more destination sections may occur within a destinations section. A destination may be a file or server destination as described in the Destination section of this document. At least one destination must exist in order to perform encoding.

# Destination Section | [ job > parOutputs > output > destinations ]

A destination section contains settings for a single destination. A destination can be one of several types depending on the value of the xsi:type attribute. The xsi:type attribute is a special XML entity that allows a single parent tag name to contain different sets of properties and subsections. The value of xsi:type identifies which set of properties and subsections may be contained within the parent tag.

A destination can contain any value of xsi:type as long as there is a plug-in defined to handle that destination type. If XML Schema validation is being performed, there must also be a type defined matching the value of xsi:type as described in Validating and Extending Helix DNA Producer Settings Files with XML Schemas. Following is a list of known destination types.

- <destination xsi:type="fileDestination">
- <destination xsi:type="pushServer">
- <destination xsi:type="pullServer">
- <destination xsi:type="g2PushServer">

Each of these four destination types are described below following the definition of the xsi:type attribute.

xsi:type | [ job > parOutputs > output > destinations > destination ]

XML Schema Instance Type Attribute. The xsi:type attribute stands for XML Schema Instance. This setting is used to identify the type of destination that is defined within the section. Each instance of a destination section may be one of several types and each type may contain a different group of properties and subsections. There are four known destination types but new types can be defined as documented in Validating and Extending Helix DNA Producer Settings Files with XML Schemas.

Default:
No Default

Values:
The list of values below for xsi:type are known. Other types can be added.

- fileDestination
- pushServer
- pullServer
- g2PushServer

Example:
xsi:type="fileDestination"
xsi:type="acmePublishDestination"

## File Destination | [ job > parOutputs > output > destinations > destination ]

A destination section of xsi:type fileDestination contains settings required to write an output to file on a local or network drive. File formats supported by the standard fileDestination section are the RealMedia file writer plug-in. A destination section of type fileDestination section may be included one or more times within the destinations section. The outline below shows the structure for the fileDestination section.

- <destination type="fileDestination">
  - <postfilters>
  - <pluginName>
  - <name>
  - <filename>
  - <destinationRollTime>
  - <destinationRollSize>

The postfilters section is a containers for one or more postfilters. Postfilters allow the audio or video to be transformed in some way after encoding has taken place. For example, a postfilter might encrypt the audio and video for a digital rights management solution. When included in the mediaProfile section, the postfilter is applied to all destinations in the respective output section. See the Postfilters section of this document for more information on available postfilters

The properties of the fileDestination section are described below.

pluginName | [ job > parOutputs > output > destinations > destination (fileDestination) ]

A string that defines the name of the plug-in to load. The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax for plug-in names as described in the Plug-in Names section.

Default:
rn-file-realmedia

Values:
rn-file-realmedia, rn-file-ogg or a valid plug-in name.

Type:
string

Example:
<pluginName type="string">rn-file-realmedia</pluginName>
<pluginName type="string">acme-file-myfiletype</pluginName>

name | [ job > parOutputs > output > destinations > destination (fileDestination) ]

The name assigned to an output. This name is used to identify an output. This is not a required field and typically used in graphical user interfaces only.

Default:
outputfile<i> where i is the input number starting from 1. e.g. outputfile1, outputfile2, etc.

Values:
Any valid name.

Type:
string

Example:
<name type="string">High Bitrate Archive</name>

filename | [ job > parOutputs > output > destinations > destination (fileDestination) ]

File name to use for the output file. This property is required to run the job, but should not be required to load a job in a GUI application.

Archiving - If a file exists with the requested output filename, the existing file is backed up immediately following the merge process to a filename based on the input filename with "_archNNN" inserted before the file extension where NNN is the next available integer (e.g. movie_arch001.rm).

File size limits - If the output file size reaches 4 GB (limit of RealMedia file format) the output file is automatically rolled and a new file is started. The new file is appended with a number (e.g. movie1.rm). On Linux the output file is rolled at 2 GB.

Note: If the input file is ".rm" and the encoding type is VBR the file extension is renamed to ".rmvb" automatically. For any other file extension, no automatic redefining of the file extension is applied.

Default:
Required if input device used.

Values:
Any valid filename and path.

Type:
string

Example:
<filename type="string">C:\output\myfile.rm</filename>
<filename type="string">output/myfile.rm</filename>

destinationRollTime | [ job > parOutputs > output > destinations > destination (fileDestination) ]

The time interval at which to roll the destination RealMedia file measured in minutes. The new file is appended with a number (e.g. movie1.rm). Only works with RealMedia file types - using this property with other types results in an error.

Destination file rolling will occur at the next available point where the file can be broken after the roll time passes. This is often pretty close to the time requested but may differ at higher bit rates. Destination file rolling is only available for RealMedia file destinations; attempting to use destination file rolling properties with other output data types will result in an error. If both -drt and -drs are set, the first to occur in time takes precedence.

File size limits - The maximum allowable value for RealMedia files is 4 GB (limit of RealMedia file format). Setting destinationRollTime such that the corresponding size is larger than this value will result in an unreadable file being created. The new file is appended with a number (e.g. movie1.rm). On Linux the destination file limit is 2 GB. On Macintosh OS X the file file limit is 1.45 GB.

Due to the nature of file rolling, files that are rolled may not paste end to end seamlessly and may contain audio gaps or video gaps.

Default:
No Default

Values:
A duration with the syntax "dd:hh:mm:ss" where seconds are ignored. Days and hours may be omitted if they are 0.

Example:
<destinationRollTime type="duration">60:00</destinationRollTime>

destinationRollSize | [ job > parOutputs > output > destinations > destination (fileDestination) ]

The size interval at which to roll the destination RealMedia file measured in Megabytes. The new file is appended with a number (e.g. movie1.rm). Only works with RealMedia file types - using this property with other types results in an error.

Destination file rolling will occur at the next available point where the file can be broken after the roll time passes. This is often pretty close to the time requested but may differ at higher bit rates. Destination file rolling is only available for RealMedia file destinations; attempting to use file rolling properties with other output data types will result in an error. If both -drt and -drs are set, the first to occur in time takes precedence.

File size limits - The maximum allowable value for RealMedia files is 4 GB (limit of RealMedia file format). Setting destinationRollSize larger than this value will result in an unreadable file being created. The new file is appended with a number (e.g. movie1.rm). On Linux the destination file limit is 2 GB. On Macintosh OS X the file file limit is 1.45 GB.

Due to the nature of file rolling, files that are rolled may not paste end to end seamlessly and may contain audio gaps or video gaps.

Default:
No Default

Values:
Any valid integer

Example:
<destinationRollSize type="uint">25</destinationRollSize>

## Push Server Destination | [ job > parOutputs > output > destinations > destination (pushServer) ]

A destination section of xsi:type pushServer contains settings required to broadcast an output to a version 9 or later Helix Server. A destination section of type pushServer section may be included one or more times within the destinations section. The outline below shows the structure for the pushServer section.

- <destination xsi:type="pushServer">
  - <postfilters>
  - <name>
  - <pluginName>
  - <authType>
  - <streamname>
  - <path>
  - <address>
  - <port>
  - <endPort>
  - <username>
  - <password>
  - <savePassword>
  - <transport>
  - <listenAddress>
  - <multicastAddress>
  - <multicastTTL>
  - <fecPercent>
  - <fecOffset>
  - <metadataResendInterval>
  - <allowResends>
  - <enableTCPReconnect>
  - <TCPReconnectInterval>
  - <statisticsUpdateInterval>

The postfilters section is a containers for one or more postfilters. Postfilters allow the audio or video to be transformed in some way after encoding has taken place. For example, a postfilter might encrypt the audio and video for a digital rights management solution. When included in the mediaProfile section, the postfilter is applied to all destinations in the respective output section. See the Postfilters section of this document for more information on available postfilters

All properties above are defined in the Server File Reference except the ' name' property which is defined below.

For information about configuring Push Broadcasting, refer to Performing Push Broadcasting in the Server File Reference.

## Pull Server Destination | [ job > parOutputs > output > destinations > destination (pullServer) ]

A destination section of xsi:type pullServer contains settings required to broadcast an output to a version 9 or later Helix Server. A destination section of type pullServer section may be included one or more times within the destinations section. The outline below shows the structure for the pullServer section.

- <destination xsi:type="pullServer">
  - <postfilters>
  - <name>
  - <pluginName>
  - <streamname>
  - <path>
  - <listenAddress>
  - <listenPort>
  - <password>
  - <savePassword>
  - <serverTimeout>

The postfilters section is a containers for one or more postfilters. Postfilters allow the audio or video to be transformed in some way after encoding has taken place. For example, a postfilter might encrypt the audio and video for a digital rights management solution. When included in the mediaProfile section, the postfilter is applied to all destinations in the respective output section. See the Postfilters section of this document for more information on available postfilters

All properties above are defined in the Server File Reference except the 'name' property which is defined below.

For information about configuring Pull Broadcasting, refer to Performing Pull Broadcasting in the Server File Reference.

## G2 Push Server Destination | [ job > parOutputs > output > destinations > destination (g2PushServer) ]

A destination section of xsi:type g2PushServer contains settings required to broadcast an output to a version G2 or later RealServer. A destination section of type g2PushServer section may be included one or more times within the destinations section. The outline below shows the structure for the g2PushServer section.

- <destination xsi:type="g2PushServer">
  - <postfilters>
  - <name>
  - <pluginName>
  - <streamname>
  - <path>
  - <address>
  - <port>
  - <username>
  - <password>
  - <savePassword>
  - <transport>

The postfilters section is a containers for one or more postfilters. Postfilters allow the audio or video to be transformed in some way after encoding has taken place. For example, a postfilter might encrypt the audio and video for a digital rights management solution. When included in the mediaProfile section, the postfilter is applied to all destinations in the respective output section. See the Postfilters section of this document for more information on available postfilters

All properties above are defined in the Server File Reference except the 'name' property which is defined below.

For information about configuring G2 Push Broadcasting, refer to Performing G2 Push Broadcasting in the Server File Reference.

Server Name name | [ job > parOutputs > output > destinations > destination (pushServer) ]

The name assigned to a server. This name is used to identify a server. This is not a required field and typically used in graphical user interfaces only.

Default:
No Default

Values:
Any string

Type:
string

Example:
<name type="string">My Server</name>

# Media Profile Section | [ job > parOutputs > output ]

The mediaProfile section defines encoding settings used to compress the media. One mediaProfile section is defined for each output in a job. The outline below shows the structure for the mediaProfile section.

- <mediaProfile>
  - <audienceRefs>
    - <audienceRef>
  - <audioMode>
  - <videoMode>
  - <disableAudio>
  - <disableVideo>
  - <outputWidth>
  - <outputHeight>
  - <resizeQuality>
  - <audioResamplingQuality>

The audienceRefs section is required for encoding.

The audienceRefs section is a container that holds zero or more audienceRef sections. Each audienceRef section is a reference to an audience defined in the audiences section of the root job element. Each audienceRef section in the audienceRef must identify a valid audience defined in the audiences section of the job element.

The properties of the mediaProfile section are described below.

audioMode | [ job > parOutputs > output > mediaProfile ]

Describes the type of audio content.

Certain codecs are tuned to encode voice frequency responses and others are turned to encode music. Audiences are defined with different choices for audio codec based on the type of input. This setting determines which audio codec to be assigned from an audience.

The audience is defined with a Stream Context section for each stream which defines two variables:

- presentation type (audio-only or audio-video)
- audio mode (voice or music)

Thus, up to 4 audio streams may be defined within a single audience, each using a different combination of presentation type and audio mode. This setting is used in combination with presentation type to define which of the 4 streams definitions that is used for encoding. Presentation type is determined by whether the input contains audio-only or audio & video and the use of the disable audio/disable video options.

If an audience has only 1 stream defined that does not contain stream context settings, this setting has no effect.

Default:
music

Values:
voice, music

Type:
string

Example:
<audioMode type="string">voice</audioMode>

videoMode | [ job > parOutputs > output > mediaProfile ]

Setting to control the picture quality of the encoded video.

This setting is provided as a suggestion to the codec to indicate how it should adjust frame rate to reach the best possible quality. Normally the codec attempts to encode at the frame rate requested but in challenging scenes, the codec may reduce frame rate to maintain a minimum quality level. This setting affects how strongly the codec tries to reach the requested frame rate.

Default:
normal

Values:
sharp, normal, smooth, slideshow

Type:
string

Example:
<videoMode type="string">smooth</videoMode>

disableAudio | [ job > parOutputs > output > mediaProfile ]

Option to strip out audio from the input media file.

Affects all destinations within the respective output. Do not use this option for capture since it will take more resources to capture audio and then strip it out of the output. Instead, omit the audio capture device property in the input.

Default:
false

Values:
Any valid Boolean Value where:

- A value of 'true' means audio output is disabled (i.e. stripped from the input)
- A value of 'false' means audio output is enabled

Type:
bool

Example:
<disableAudio type="bool">true</disableAudio>
<disableAudio type="bool">1</disableAudio>

disableVideo | [ job > parOutputs > output > mediaProfile ]

Option to strip out video from the input media file or device.

Affects all destinations within the respective output. Do not use this option for capture since it will take more resources to capture video and then strip it out of the output. Instead, omit the video capture property in the input.

Default:
false

Values:
Any valid Boolean Value where:

- A value of 'true' means video output is disabled (i.e. stripped from the input)
- A value of 'false' means video output is enabled

Type:
bool

Example:
<disableVideo type="bool">true</disableVideo>
<disableVideo type="bool">1</disableVideo>

outputWidth | [ job > parOutputs > output > mediaProfile ]

Sets the output video width in pixels.

Both outputWidth and outputHeight are related as follows:

- If only outputWidth = 0 then outputWidth is computed from the outputHeight and input aspect ratio.

- If only outputHeight = 0 then outputHeight is computed from the outputWidth and input aspect ratio.

- If outputHeight = 0 and outputWidth = 0 then no resizing occurs.

- If outputHeight and outputWidth are omitted then no resizing occurs.

Width and height values of the final encoded output must be divisible by the number of pixels suitable for the output codec. For RealVideo, the width and height must be divisible by 4 pixels (e.g. 32, 36, 40, ... 2048). If width or height are not an even increment of that supported by the codec, the video is cropped down to the nearest multiple that is supported as input to the codec just prior to encoding but after all prefiltering and resizing have occurred.

If the requested outputWidth is larger than the input video width, the image is not actually resized. Instead, information is embedded into the stream to tell the player to stretch the video on playback.

Resize should be avoided if possible for live video capture due to the significant load that resizing incurs. Instead, perform any necessary video scaling operations in hardware by choosing the input video capture size (videoFrameWidth and videoFrameHeight). Note, while most capture devices perform resizing of video in hardware, some capture devices such as USB cameras do not. If you observe very high loads for live capture, consult your hardware documentation for the default capture size and try performing fast quality resize (resizeQuality). If you are using a DV capture device, capture size settings are defined in the DV Decoder available through the capture settings dialog.

Ignored for audio-only inputs.

Default:
0 (same width as input)

Values:
An integer 0 or 32 to 2048 in multiples supported by the output codec (see above)

Type:
uint

Example:
<outputWidth type="uint">320</outputWidth>
<outputWidth type="uint">0</outputWidth> (No resize or maintain aspect ratio)

outputHeight | [ job > parOutputs > output > mediaProfile ]

Sets the output video height in pixels.

Both outputWidth and outputHeight are related as follows:

- If only outputWidth = 0 then outputWidth is computed from the outputHeight and input aspect ratio.

- If only outputHeight = 0 then outputHeight is computed from the outputWidth and input aspect ratio.

- If outputHeight = 0 and outputWidth = 0 then no resizing occurs.

- If outputHeight and outputWidth are omitted then no resizing occurs.

Width and height values of the final encoded output must be divisible by the number of pixels suitable for the output codec. For RealVideo, the width and height must be divisible by 4 pixels (e.g. 32, 36, 40, ... 2048). If width or height are not an even increment of that supported by the codec, the video is cropped down to the nearest multiple that is supported as input to the codec just prior to encoding but after all prefiltering and resizing have occurred.

If the requested outputHeight is larger than the input video height, the image is not actually resized. Instead, information is embedded into the stream to tell the player to stretch the video on playback.

Resize should be avoided if possible for live video capture due to the significant load that resizing incurs. Instead, perform any necessary video scaling operations in hardware by choosing the input video capture size (videoFrameWidth and videoFrameHeight). Note, while most capture devices perform resizing of video in hardware, some capture devices such as USB cameras do not. If you observe very high loads for live capture, consult your hardware documentation for the default capture size and try performing fast quality resize (resizeQuality). If you are using a DV capture device, capture size settings are defined in the DV Decoder available through the capture settings dialog.

Ignored for audio-only inputs.

Default:
0 (same height as input)

Values:
An integer 0 or 32 to 2048 in multiples of 4 (e.g. 0, 32, 36, 40, ... 2048)

Type:
uint

Example:
<outputHeight type="uint">240</outputHeight>
<outputHeight type="uint">0</outputHeight> (No resize or maintain aspect ratio)

resizeQuality | [ job > parOutputs > output > mediaProfile ]

Affects the resulting quality of an output video when resize is applied. Choosing high results in a better quality resize but uses considerably more CPU.

Default:
high

Values:
fast or high

Type:
string

Example:
<resizeQuality type="string">fast</resizeQuality>

audioResamplingQuality | [ job > parOutputs > output > mediaProfile ]

Affects the resulting quality of audio resampling operations.

Resampling must be done if the sample rate required by the target audio codec is different from the input file or device sample rate. The resampler is automatically invoked for each audio codec as needed. Choosing 'high' results in an audio-only encode using up to 2 times as much CPU for live or taking twice as long to encode for file to file encodes. The fast audio resampling algorithm does not incur additional CPU but results in the encoded output having a slightly lower quality. In all cases, there is no pitch shift incurred by the audio resampler.

Default:
high

Values:
fast or high

Type:
string

Example:
<audioResamplingQuality type="string">fast</audioResamplingQuality>

audienceRefs | [ job > parOutputs > output > mediaProfile ]

This tag holds one or more audienceRef elements, each defining a single audience to be added to the output media file. Each audienceRef element should contain one and only one audience. All audiences defined in this section are output to a single file. If more than 1 audience is specified, the output is a multi-rate file (e.g. RealMedia SureStream files). The output media file specified must support the number and type of audiences selected or an error will result.

Default:
No Default

Values:
One or more audienceRef elements are nested within this element.

Type:
No type attribute in this element

Example:
<audienceRefs>
<audienceRef type="string">28k</audienceRef>
<audienceRef type="string">56k</audienceRef>
<audienceRef type="string">256k</audienceRef>
</audienceRefs>

audienceRef | [ job > parOutputs > output > mediaProfile > audienceRefs ]

This tag holds a reference to the name of an audience defined in the audiences section of the job file. This tag may appear one or more times. Each occurrence represents one audience that is to be added to the mediaProfile. Each audienceRef element should contain one and only one audience though the tag may be included multiple times for output file types that support multi-rate files.

Default:
No Default

Values:
Any valid audience name defined within the job file audiences section.

Type:
string

Example:
<audienceRef type="string">28k</audienceRef>
<audienceRef type="string">256k</audienceRef>
<audienceRef type="string">28k Dial-up Modem</audienceRef>

# Audiences Section | [ job ]

The audiences section is a container for one or more audience sections. An audience defines settings used by the codecs to compress media for a particular target bit rate. For example, an audience called "28 kbps Dial-up Modem" may define encoding settings suitable for streaming over a 28 kbps modem.

A job file may contain one or more audience sections. Audiences defined in the audiences section are referenced in each output section in the job file. A single audience section may be referenced from one or more output sections by using the audience name property. Its perfectly acceptable to have an audience defined in the audience section that is not referenced in any output but that audience will not be used.

The outline below shows the structure for the audiences section.

- <audiences>
  - <audience>
  - <name>
  - <avgBitrate>
  - <maxBitrate>
  - <streams>
  - <stream type="audioStream">
  - <pluginName>
  - <codecName>
  - <codecFlavor>
  - <streamContext>
  - <presentationType>
  - <audioMode>
  - <stream type="videoStream">
  - <pluginName>
  - <codecName>
  - <encodingType>
  - <encodingComplexity>
  - <quality>
  - <maxStartupLatency>
  - <maxFrameRate>
  - <maxKeyFrameInterval>
  - <enableLossProtection>
  - <stream type="eventStream">
  - <pluginName>
  - <avgBitrate>
  - <stream type="imageMapStream">
  - <pluginName>
  - <avgBitrate>

All properties above are defined in the Audience File Reference except the name property which is defined below.

name | [ job > audience ]

The name assigned to an audience. This name is used to identify an audience. This audience name is used to match an audience with the list of audienceRefs defined in the mediaProfile section. A one and only audience matching the value of the name property must exist in the audienceRefs section in the mediaProfile section. If a Job contains two audiences with the same name property based on a case-sensitive string match, an error is logged and the Job File is not run.

Default:
No Default

Values:
Any string

Type:
string

Example:
<name type="string">28k Dial-up Modem</name>

# Data Types | [Back to Top]

## White Space

White space is always preserved in all elements that contain just attributes and data. White space includes new lines, spaces and tabs. For example, the following will be rejected because the extra spaces surrounding the string "sharp" will be used when making a comparison to the allowed values for videoMode.

>     <videoMode type="string"> sharp </videoMode>

The above should be re-written as:

>     <videoMode type="string">sharp</videoMode>

White space is still allowed between elements or within complex elements containing only other elements to improve readability of the XML settings files. For example, the following is allowed:

    <mediaProfile>
       <videoMode type="string">sharp</videoMode>
    </mediaProfile>

Note: Because the default is to preserve white space, use of the xml:space attribute will not affect handling white space. That is, white space will always be preserved.

## Tag Names

1. XML tag names are case sensitive.
   e.g. <input> is NOT the same as <Input>
2. All XML tag values are case-insensitive unless otherwise noted.
   e.g. <codecName>rv9</codecName> IS the same as <codecName>RV9</codecName>
3. Each XML section may only be included once unless otherwise noted.

## Boolean Values

Valid boolean values are defined as follows:

- true or false (preferred format)
- 1 (true) or 0 (false)
- t or f

Note: Using t and f will result in XML files that, when opened in an XML editor, will generate errors because t and f are not standard XML Schema values for the Boolean data type. Thus, if you wish to edit files in XML editors, it is best avoid using t and f as boolean values.

The default used by the GUI and command line applications is 'true' and 'false'.

## String Values

Valid string value is any sequence of characters. The characters must be from the character set identified in the encoding attribute specified in the XML processing instructoin (the tag that starts with ?xml at the added to top of ever XML file). By default the encoding type is set to UTF-8 which supports a double byte character set.

## Unsigned Integer Values

Unsigned integer values are any positive 32 bit integer value from 0 to 2 raised to the power of 32 (4,294,967,296). The data type is specified as uint.

## Double Values

Double values are any floating point 32 bit number value. The data type is specified as double.

## File and Directory Paths

To minimize cross-platform differences, file paths are interpreted in a cross-platform manner. This means that a job file written on one platform can be easily transferred and run on another platform with no modifications.

1. Relative and absolute paths are supported in all file paths. Relative paths are relative to the current working directory.
   - Working directory is the directory from which the command line application was invoked from or the application installation directory for the GUI application when started from the Start Menu shortcut. If Producer is started by double clicking a job file, the working directory is the same directory as the job file.
2. On Windows, when reading a path, forward slashes are interpreted as backslashes. (e.g. interpret "/" as "\")
3. On Linux, when reading a path, backslashes are interpreted as forward slashes. (e.g. interpret "\" as "/")
4. On Windows, when reading an absolute path that starts with a single forward slash "/" or backslash "\" the path will be assumed to be absolute on the default drive for that system.
5. On Linux, when reading an absolute path that starts with a drive letter designation (e.g. C:\), no translation is attempted and an error is logged since there is no logical translation in this case.

## Duration Syntax

Duration format is [D:][h:][m:]s[.xyz]
Where:

- D is Number of Days - Optional. If omitted then D=0 is assumed.
- h is Number of Hours - Optional. If D and h omitted then D=0 and h=0 assumed.
- m is Number of Minutes - Optional. If omitted then D=0, h=0 and m=0 is assumed.
- s is Number of seconds - Required.
- f is Fractions of a second with 3 digits max - Optional. 0, 1 or 2 digits are acceptable. A decimal separates the seconds and the fractions of a second. If f is omitted no fractions of a second are assumed. Accurate only to an audio or video packet size in final encode. For audio this is about 200 milliseconds. For video the size depends on bit rate.

Note: Duration is always a positive value. Negative values of duration are not allowed.

Examples:

- 1:4:34:0 - 1 day, 4 hourse, 34 minutes and 0 seconds.
- 2:23.0 - 2 minutes, 23 seconds
- 60 - 60 seconds

## Plug-in Name

The pluginName property is used to identify the formal plug-in name advertised by a given Helix DNA Producer plug-in. A plug-in name can be any string as long as it matches the string advertised by the intended plug-in but should comply with the recommended syntax as defined below.

pluginName syntax is <company>-<plugin type>-<plugin name>

Where:

- company is a short string representing the author.
- plugin type is a string defining the general type of plug-in (see below).
- plugin name is a descriptive string identifying the plug-in functionality.

Example: xyz-prefilter-audionoisereduction

The different plug-in types are:

- avfile - AV file input plug-in
- capture - AV capture input plug-in
- prefilter - Prefilter plug-in
- audiocodec - Audio codec plug-in
- videocodec - Video codec plug-in
- transform - Codec plug-ins which done actually compress (e.g. event and imagemap)
- postfilter - Postfilter plug-in
- file - Output file (e.g. rmfile, ogg, etc)

## Stream Path

A streamname may include the path and filename portion of a RealMedia URL. Following are valid characters for a streamname

- may contain any ASCII character except for: # $ % & ? + \ < > @ : *
- The forward slash (/) is reserved for path separators
- While any other ASCII character may be used, it is safest to use only letters, numbers, underscore (_) and dash (-)

## IP Addresses

Valid IP address values have four fields containing integer numbers separated by a period delimiter. Each of the four fields may assume a value of 1 to 254. There must be no spaces or other characters in the IP address other than the period separating each number field.

## Domain Names

Any string is allowed as a valid domain name value. Because on some network, even netbios names may result in a valid DNS lookup, it is not required to have a dot separated domain name (e.g. it is not required to have a .com suffix or a machine prefix). Domain names have the following general syntax:

> <label> [.<label>] ...

Where:

Label is a string that contains any one of the 52 alphabetic characters A through Z in upper case and a through z in lower case or any one of the ten digits 0 through 9.

Examples of valid domain names are:

- domino.dev.prognet.com
- domino

# Deprecated Properties | [Back to Top]

Capture Mono Audio audioCaptureMono | [ job > parInputs > input (captureInput) ]

Forces the audio card to record a single mono audio channel only when true. Linux only.

This is only required for audio devices that are configured as single mono channels instead of stereo pairs. When this property is true, mono audio capture is enabled. When this property is omitted or false, stereo audio capture is enabled. Linux only option, ignored on Windows platforms.

This property is replaced by the audioChannels property. Use audioChannels with a value of 1 instead. If this property is present along with audioChannels in the same job file, the number of channels provided by audioChannels will override and audioCaptureMono is ignored.

Default:
false

Values:
Any valid Boolean Value where true and false are interpreted as follows:.

- false - Request stereo input (2 channels) from the capture device (default)
- true - Request mono input (1 channel) from the capture device.

Type:
bool

Example:
<audioCaptureMono type="bool">true</audioCaptureMono>
<audioCaptureMono type="bool">1</audioCaptureMono>

# Other Topics | [Back to Top]

## File Extension

Job files are given a special file extension. The file extension is ".rpjf". This extension is not required but is useful for associating the job file with GUI applications on Windows.

## Sample Jobs

Sample jobs are installed into the samples directory in the application installation directory. Sample jobs can be used as starting points for creating jobs.

## XML Schema

A Schema is a document that describes the format of an XML document. It specifies almost everything about an XML document structure. The syntax of the document itself is defined by simple XML rules. Schemas are useful in identifying syntax and structure errors in an XML document. XML Schema Part 0 Primer <http://www.w3.org/TR/xmlschema-0/> from WC3's website is an excellent introduction to XML Schemas provided by the W3C. There are also many good books on the subject.

Schemas are defined by the WC3. More information about the XML Schemas can be found at http://www.w3.org/XML/Schema. At this site you will find a list of tools that support both XML document validation based on Schemas as well as tools that allow one to edit XML documents based on an XML Schema.

While Helix DNA Producer itself does not perform XML Schema validation, Helix DNA Producer ships with an XML 1.0 compliant XML Schema for the job file. This Schema file can be used to validate job files and ensure their accuracy before putting into production. There are even tools that allow editing of XML documents based on XML Schemas. Products like XML Spy can enable a job file to be edited and provide interactive information on the structure of the file as you build it.

Information on how to edit XML files is available in the Editing XML Files Reference. The job file XML Schema can be found in the samples directory in the application installation directory.

# 21 Glossary | [Back to Top]

Following terms are useful in referring to XML documents.
Tag
  A name surrounded by angle brackets. e.g. <input>.
Tag Name
  An XML tag name is a series of characters consisting of letters, numbers, the underscore (_), dash (-), colon (:) or periods (.). XML tag names are case sensitive. e.g. input
Element
  Everything from the opening tag to corresponding close tag. e.g. <input>...</input>.
Attribute
  Name/value pair that contain information about the tag. e.g. <input type="device">...</input> where type is the attribute name and device is the attribute value.
Value
  Actual data that is contained between the opening and closing tags.
Empty Element
  An element that contains no data. Typically empty elements contain attributes.
  e.g. </input type="capture">.
Simple Element
  An element that contains only a value. Simple XML elements are referred to as "properties" below.
  e.g. <filename>C:\Myfile.avi</filename>
Complex Element
  An element that contains other elements and/or values within it. Complex XML elements are referred to as "sections" below.
  e.g. <input>
  <filename>C:\Myfile.avi</filename>
  </input>

Copyright © 2004, RealNetworks Inc. All rights reserved.

Helix, RealAudio, RealNetworks, RealSystem, RealVideo, and SureStream are trademarks or registered trademarks of RealNetworks, Inc. All other companies or products listed herein are trademarks or registered trademarks of their respective owners. All rights reserved.