Appendix B: Job File Reference

This appendix provides a reference for job files created with Helix Producer. It shows you the basic structure of a job file and gives you details about the different sections within a job file.

Overview: Job Files

Job files are XML-based files that you edit using any text editor. These files can be used with either the main Helix Producer interface or the command line application to customize the settings that you will use for encoding.

Job File Structure

The following is an overview of the structure of the elements within the job file and how they are nested.

job 
          enableTwoPass 
          clipInfo 
               entry > 
          input 
               avFileInput | captureInput 
                    prefilters > 
          output 
               mediaProfile 
                    postfilters > 
                    prefilters > 
               destinations 
                    fileDestination > 
                    pushServer > 
                    pullServer > 
                    g2PushServer > 
          audiences
               audience 
                    streams 
                         audioStream > 
                              streamContext > 
                         videoStream > 
                         eventStream > 
                         imageMapStream >

A job file's structure can be divided into five main sections: job section, clip information section, input section, output section, and audiences section. Each section and their sub-elements are documented separately below.

Job Section

The top level of the job file is the job section. This section contains all tags within the job file.

enableTwoPass

This setting determines whether 2-Pass encoding is used for the job. Value can be True or False.

Clip Information Section

In this section, the metadata information about the encoded clip is stored. For each entry included, a name/value pair exists. This section is optional.

Structure:

clipInfo
     entry
          name
          value

entry

Each entry element contains one metadata information as a name/value pair. A number of standard metadata name/value pairs are supported by Helix Producer, but you may add your own.

The following table shows the standard metadata name/value pairs:

Standard Metadata
Name	Value	Description
Title	Any string up to 255 characters in length.	The name of the encoded clip.
Author	Any string up to 255 characters in length.	The author of the encoded clip.
Copyright	Any string up to 255 characters in length.	The owner and date of the copyright.
Keywords	Any string up to 1024 characters in length.	Keywords that enable a user to find the clip.
Description	Any string up to 4095 characters in length.	A brief description about the content of the clip.
Content Rating	Any integer from 0 to 6.	A rating system, where the following values equal the following ratings: 0 = no rating 1 = all ages 2 = older children 3 = younger teens 4 = older teens (15 and up) 5 = adult supervision recommended 6 = adults only

Example:

<clipInfo>
     <entry>
          <name>Title</name>
          <value type="string">My Title</value>
     </entry>
     <entry>
          <name>Copyright</name>
          <value type="string">(c) 2002 XYZ Media Corp.</value>
     </entry>
</clipInfo>

Input Section

This section contains information about the input for the encoding job. Only one of two elements can be contained in this section, an AV file input section or a capture section.

Structure:

input 
     avFileInput | captureInput >

avFileInput

This sub-section contains properties that define the audio or video file used as the source for the input.

Structure:

avFileInput
     pluginName
     filename
     prefilters>

The following are the avFileInput properties:

pluginName: Allows you to specify the file reader used to scan the input file. If not specified, all readers are scanned. Use one of:; rn-avfile-aviuncompressed rn-avfile-directshow rn-avfile-pcm rn-avfile-qtcompressed rn-avfile-qtuncompressedor a 3rd party AV file reader
filename: The file used as the source for the input. Use any valid filename, including the path.
prefilters: For more information, see "prefilters".

Example:

<avFileInput> <filename type="string">C:\\media\video1.mpg</filename> </avFileInput>

captureInput

This sub-section contains properties that define the audio or video capture device used as the source for the input.

Structure:

captureInput 
     prefilters > 
     pluginName (rn-capture-av) 
     duration (infinite) 
     audioDeviceID 
     audioDevicePort 
     videoDeviceID 
     videoDevicePort 
     videoFormat 
     videoFrameWidth 
     videoFrameHeight

The following are the captureInput properties:

prefilters: For more information, see "prefilters".
pluginName: Allows you to specify the capture driver used. Use rn-capture-av or a 3rd party plug-in.
duration: The length of time that the capture device will be used as the input source. Use the format: [D:][h:][m:]s[.xyz]. Default is infinite.
audioDeviceID: Sets the audio capture device that will be used as the source for the input.
audioDevicePort: Sets the audio port that will be recorded from.
videoDeviceID: Sets the video capture device that will be used as the source for the input.
videoDevicePort: Sets the video port that will be recorded from.
videoFormat: The video transmission format for the source video. Default is NTSC.
videoFrameWidth: The width (in pixels) of the video image that will be captured by the video capture device. Default is 0; the last device setting or default will be used.
videoFrameHeight: The height (in pixels) of the video image that will be captured by the video capture device. Default is 0; the last device setting or default will be used.

Example:

<captureInput>
     <duration type="duration">01:20:00.000</duration>
     <pluginName type="string">rn-capture-av</pluginName>
     <videoDeviceID type="string">MSVIDEO: XYZ Capture Driver</videoDeviceID>
</captureInput>

prefilters

Prefilters can be used nested within either the avFileInput sub-section or the captureInput sub-section. Using prefilters adjusts the input video or audio data before encoding. They are optional.

Structure:

prefilters 
     inputCroppingPrefilter 
          enabled (true) 
          left (0) 
          top (0) 
          width (input width) 
          height (input height) 
     deinterlacePrefilter 
          enabled (true) 
          manual (false) 
          deinterlace (true) 
          inverseTelecine (true) 
     videoNoiseReductionPrefilter 
          enabled (true) 
          level (low) 
     blackLevelPrefilter 
          enabled (true) 
     audioGainPrefilter 
          enabled (true) 
          gain (0)

inputCroppingPrefilter

Contains settings for cropping the size (in pixels) of the video input. Properties:

enabled: The state of the filter. Value can be True or False.
left: The left side of the cropping region.
top: The top side of the cropping region.
width: The width of the cropping region.
height: The height of the cropping region.

deinterlacePrefilter

Contains settings for De-interlace and Inverse Telecine filters that adjust the input video. Properties:

enabled: The state of the filter. Value can be True or False.
manual: Value can be True or False. If False (default), the filter will apply the De-interlace and Inverse Telecine filter if appropriate. If True, the filters you specify to be used will be used.
deinterlace: Determines if the De-interlace filter is used. Value can be True or False.
inverseTelecine: Determines if the Inverse Telecine filter is used. Value can be True or False.

videoNoiseReductionPrefilter

Contains settings for the reducing video noise from the input video. Properties:

enabled: The state of the filter. Value can be True or False.
level: Specifies the type of noise reduction used. Value can be low or high.

blackLevelPrefilter

Contains settings for filtering the black level of the input video. Properties:

enabled: The state of the filter. Value can be True or False.

audioGainPrefilter

Contains settings for changing the audio level from the input audio. Properties:

enabled: The state of the filter. Value can be True or False.
gain: The amount of audio gain increased or decreased. Value can be from -12 to 12.

Example:

<prefilters>
     <deinterlacePrefilter>
          <deinterlace type="bool">true</deinterlace>
          <enabled type="bool">true</enabled>
          <inverseTelecine type="bool">true</inverseTelecine>
          <manual type="bool">false</manual>
     </deinterlacePrefilter>
     <audioGainPrefilter>
          <enabled type="bool">true</enabled>
          <gain type="double">0.000000</gain>
     </audioGainPrefilter>
</prefilters>

Output Section

This section contains information about the output for the encoding job. It includes information about the destinations for the encoded output and how the media is encoded.

Structure:

output 
     destinations 
          fileDestination 
               pushServer 
               pullServer
               g2PushServer 
          mediaProfile 
               audienceRef
               audioMode (music) 
               videoMode (normal) 
               disableAudio (false) 
               disableVideo (false) 
               outputWidth (Input Width)
               outputHeight (Input Height) 
               resizeQuality (high)
               audioResamplingQuality (high)

destinations

This sub-section contains information about one or more file or server destinations.

fileDestination

Contains settings for the output file—the encoded RealMedia file. Properties:

pluginName: The name of the file destination plug-in that is used to create the file. Use one of rn-file-realmedia, rn-file-mp3, or a 3rd party plug-in.
name: Name of the output.
filename: The file name and path were the encoded output will be saved.

pushServer

A Push Server destination contains information required for a live server output using the Push broadcast method available in Helix Universal Server 9 and greater. There are three types of Push broadcasts: account-based, single- password, and multicast. The properties you use depends on which type of broadcast are using. For a detailed description of these types of Push broadcasting and the settings you need, see "Broadcasting Live to a Server" .

Properties:

name: The name of the server destination.
authType: The type of authentication used for the Push broadcast. Depending on which type you use, you need to use different properties. Use either account-based or single-password.
streamname: The name of the live stream used to identify the live broadcast. Use any valid file name and path. For example: live.rm.
path: Used if you want to use additional path information to define your stream, such as for archiving purposes.
address: The address of the Helix Universal Server being broadcast to. Use any valid IP address.
port: For account-based authType, this is the authentication/monitoring port on Helix Universal Server. For single-password authType, this is the starting port for sending packets, and it must match the receiver configuration defined on the Helix Universal Server.
endPort: The ending port used for sending packets. Used with single-password authType only.
username: The user name of a valid Helix Universal Server account. Used with account-based authType only.
password: For account-based authType, this is the valid password on the Helix Universal Server used in conjunction with the user name. For single-password authType, this is the password used to encrypt and decrypt packets before transmission to the Helix Universal Server.
savePassword: Allows you to save the password if value is True. Value can be True or False.
transport: The transport protocol used to connect to the Helix Universal Server. Value can be udp/unicast, udp/multicast, or tcp. See "Transport Protocols" for more information about protocols.
listenAddress: The address that Helix Producer uses to listen for resend requests from the broadcasting Helix Universal Server. Use any valid IP address.
multicastAddress: The multicast address used for the broadcast if transport is set to udp/multicast. Use a valid multicast address.
multicastTTL: The number of router hops that a multicast stream will cross before being blocked by the router. Limits the spread of a multicast. Value can be any integer from 1-255.
fecPercent: The percentage of stream allocated to forward error correction packets. If value is 100, a redundant stream is created. Value can be from 1-100.
fecOffset: The number of seconds used to offset FEC packets when fecPercent is set to 100. Value can be any integer from 1-9999.
metadataResendInterval: The number of seconds that Helix Producer will wait between sending header packets (packets that contain information about the broadcast) to theHelix Universal Server.
allowResends: Whether or not to accept/reject requests from the Helix Universal Server to resent packets. Value can be True or False.
enableTCPReconnect: Whether or not to enable TCP reconnects when the broadcast is dropped by the Helix Universal Server. Value can be True or False.
TCPReconnectInterval: If enableTCPReconnect is True, determines how long to wait in between reconnect attempts. Value can be any integer from 1-3600.
statisticsUpdateInterval: The number of seconds in between updates of statistics sent from the Helix Universal Server.

pullServer

A Pull Server destination contains information required for a live server output using the Pull broadcast method available in Helix Universal Server 9 and greater. For a detailed description of Pull broadcasting and the settings you need, see "Setting Up a Pull Broadcast" on page 48.

Properties:

name: The name of the server destination.
streamname: The name of the live stream used to identify the live broadcast. Use any valid file name and path. For example: live.rm.
path: Used if you want to use additional path information to define your stream, such as for archiving purposes.
listenAddress: The address used by Helix Producer to listen for Pull broadcast connection requests from a Helix Universal Server. Use only a valid IP address.
listenPort: The port used by Helix Producer to listen for Pull broadcast connection requests from a Helix Universal Server. Value can be any integer from 1-65535.
password: The password used by Helix Producer to initiate Pull broadcast requests. Must match the Broadcast Distribution Pull Receiver Password set in Helix Universal Server.
savePassword: Allows you to save the password if value is True. Value can be True or False.
serverTimeout: The number of seconds Helix Producer will wait for a ping from the Helix Universal Server before assuming that no clients are connected to the stream, and then close the broadcast connection. Value can be any integer from 0-86400.

g2PushServer

A G2 Push Server destination contains information required for a live server output using the Legacy broadcast method available with older versions of Helix Universal Server. For a detailed description of Pull broadcasting and the settings you need, see "Setting up a Legacy Push Broadcast" .

Properties:

name: The name of the server destination.
streamname: The name of the live stream used to identify the live broadcast. Use any valid file name and path. For example: live.rm.
path: Used if you want to use additional path information to define your stream, such as for archiving purposes.
address: The address of the Helix Universal Server being broadcast to. Use any valid IP address.
port: The port on Helix Universal Server being broadcast to. It should match the encoder port setting on Helix Universal Server.
username: The user name of a valid Helix Universal Server account.
password: This is the valid password on the Helix Universal Server used in conjunction with the user name.
savePassword: Allows you to save the password if value is True. Value can be True or False.
transport: The transport protocol used to connect to the Helix Universal Server. Value can be udp/unicast or tcp. See "Transport Protocols" for more information about protocols.

mediaProfile

This sub-section defines settings for how the output is encoded, plus it defines the audiences used for encoding.

Structure:

mediaProfile 
          audioMode (music) 
          videoMode (normal) 
          disableAudio (false) 
          disableVideo (false) 
          outputWidth (InputWidth) 
          outputHeight (InputHeight) 
          resizeQuality (high) 
          audioResamplingQuality (high) 
          audienceRefs 
               audienceRef

Properties:

audioMode: Describes the type of audio included in the encoded clip. The choice here affects the type of audio codec used to encode the output. Value can be either voice or music.
videoMode: Describes the type of video content included in the encoded clip. This setting controls the target quality of the encoded video, based on your choice. Value can be sharp, normal, smooth, or slideshow.
disableAudio: If False then audio is disabled for the output. Value can be True or False
disableVideo: If False then video is disabled for the output. Value can be True or False
outputWidth: The width of the output video image in pixels. A value between 32 and 2048 results in the output being scaled to fit. If value is 0 and outputHeight is 0, then no resizing occurs. If value is 0 and height is between 32 and 2048 then width is computed such that the aspect ratio of the input video is maintained.
outputHeight: The height of the output video image in pixels. A value between 32 and 2048 results in the output being scaled to fit. If value is 0 and outputWidth is 0, then no resizing occurs. If value is 0 and width is between 32 and 2048 then height is computed such that the aspect ratio of the input video is maintained.
resizeQuality: Affects the resulting video quality of an output file when resize is applied. Choosing High results in a better quality video but uses considerably more CPU. Value can be High or Fast.
audioResamplingQuality: 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. Value can be High or Fast.
audienceRefs: This property holds a reference to the name of an audience defined in the audiences section of the job file. One or more of this tag may appear. Each occurrence represents one audience that is to be added to the mediaProfile.

Example:

<mediaProfile>
     <audioMode type="string">music</audioMode>
     <audioResamplingQuality type="string">high</audioResamplingQuality>
     <disableAudio type="bool">false</disableAudio>
     <disableVideo type="bool">false</disableVideo>
     <outputHeight type="uint">0</outputHeight>
     <outputWidth type="uint">0</outputWidth>
     <resizeQuality type="string">high</resizeQuality>
     <videoMode type="string">normal</videoMode>
     <audienceRefs>
        <audienceRef>16k Substream for 28k Dial-up</audienceRef>
        <audienceRef>28k Dial-up</audienceRef>
        <audienceRef>56k Dial-up</audienceRef>
        <audienceRef>256k DSL or Cable</audienceRef>
     </audienceRefs>
</mediaProfile>

Audiences Section

This section defines one or more audiences that are used to encode the output media. For more detailed information on audiences, see Chapter 7: "Choosing Audiences for an Encoding Job".

Structure:

audiences

          audience 
               name (only within job file) 
               avgBitrate   
               maxBitrate   
               streams   
                    audioStream >
                    videoStream >
                    eventStream >
                    imageMapStream >

name

The name assigned to an audience. This name must match one of the audiences listed in the audienceRef property of the mediaProfile section.

avgBitrate

Bit rate in bps (bits per second) of the entire audience. Ignored if encodingType is quality.

maxBitrate

Limits total bit rate for the audience from going above the specified value in bps (bits per second). Set to 50000000 or more if no limit is desired.

streams

This sub-section is a container for the video stream and the audio stream(s) included with the audience.

Structure:

streams   
      audioStream 
          codecName 
          codecFlavor 
          streamContext 
               presentationType (audio-video) 
               audioMode (music) 
      videoStream 
          codecName (rv9) 
          encodingType (cbr) 
          quality 
          maxStartupLatency (4 s) 
          maxFrameRate (30 fps)
          maxKeyFrameInterval (10 s) 
          enableLossProtection (false) 
      eventStream 
          avgBitrate (200 bps) 
      imageMapStream 
          avgBitrate (400 bps)

audioStream

Defines settings for an audio stream. Properties:

codecName: The name of the audio codec to be used. See "Music RealAudio Codecs" and "Voice RealAudio Codecs" for a list of values.
codecFlavor: The flavor of the audio codec to be used. See "Music RealAudio Codecs" and "Voice RealAudio Codecs" for a list of values.
streamContext: Defines a unique set of properties to allow the application to select only one audio stream among several choices. The following are sub-properties:

Example:

<audioStream>
    <pluginName type="string">rn-audiocodec-realaudio</pluginName> 
    <codecName type="string">cook</codecName>
    <codecFlavor type="uint">4</codecFlavor> 
    <streamContext> 
        <presentationType type="string">audio-video</presentationType> 
         <audioMode type="string">music</audioMode> 
     </streamContext> 
</audioStream>

videoStream

Defines settings for a video stream. Properties:

codecName

The RealVideo codec name used to encode the video. Below is a table that lists codec names and the corresponding RealVideo codec.

Table 4: RealVideo Codecs
Name	RealAudio Codec Used
rv9	RealVideo 9
rv8	RealVideo 8
rvg2svt	RealVideo G2 with SVT

encodingType

The type of encoding used can be Constant Bit Rate (cbr), Variable Bit Rate using quality of video as a goal (vbrQuality), or Variable Bit Rate using an average bit rate as a goal (vbrBitrate). If you use Variable Bit Rate, you can only use one audience and the output file name must use a .rmvb extension.

quality

The target quality percentage that the video codec will attempt to encode the video at. Used if you specify the encodingType to be vbrQuality.

maxStartupLatency

The maximum time that the clip will buffer before playing begins. Value can be an integer from 4 to 25.

maxFrameRate

The ideal, maximum frame rate (in frames per second) that the video codec will attempt to encode the output video at. Value can be an integer from 0 to 60.

maxKeyFrameInterval

The number of seconds in between key frames of encoded video. Value can be an integer from 0 to 60.

enableLossProtection

Whether or not to add error correction information to the encoded file. Value can be True or False.

Example:

<videoStream> 
    <pluginName type="string">rn-videocodec-realvideo</pluginName>
    <codecName type="string">rv8</codecName>
    <encodingType type="string">cbr</encodingType>

    <maxStartupLatency type="double">4.0</maxStartupLatency>
    <maxFrameRate type="double">15.0</maxFrameRate> 
    <maxKeyFrameInterval type="double">10</maxKeyFrameInterval>
    <enableLossProtection type="bool">false</enableLossProtection>
</videoStream>

eventStream

Defines settings for an event stream. Properties:

avgBitrate: Bit rate for event stream in bits per second. Value can be from 1-1000.

imageMapStream

Defines settings for an image map stream. Properties:

avgBitrate: Bit rate for image map stream in bits per second. Value can be from 1-1000.

©2002 RealNetworks, Inc.
For more information, visit RealNetworks
Click here if the Table of Contents frame is not visible at the left side of your screen.