Appendix B: Job File Syntax

A RealProducer job file records a range of encoding settings so that you can quickly re-encode clips or broadcasts using the same properties. This appendix describes the job file syntax. Using this information, you can edit a job file without relying on the RealProducer graphical application.

Note: If you are not familiar with XML syntax, refer to Appendix A for information about XML namespaces, tags, attributes, and values.

Understanding Job Files

A job file records the full range of RealProducer settings used to encode a clip or broadcast. It defines the audio and video codecs used, for example, and specifies the use of filters and other options. When you save a job through the graphical application—a process described in Chapter 6—RealProducer updates the file automatically to record your encoding changes. You can also create job files, which use the file extension .rpjf, through the command-line application and edit them manually. This allows you to change job information using a text editor or any automated process that can modify XML files.

For More Information: The section "Job File Options" explains how to create a job file through the command-line application.

Features Exclusive to the Job File

You can set up a few RealProducer encoding features only through a job file or command line. The following features are not available through the graphical user interface. If your job file includes them, you must encode the jobs using the command-line application:

• RealAudio Lossless Codec

To encode audio using the lossless codec, you need to specify the lossless codec in an audience definition. The section "Audiences Section" illustrates the audience section in the job file. Appendix C covers the audience syntax.

• Multiple Outputs

A job file can define multiple outputs that are encoded in parallel. Multiple outputs might be two separate clips, one of which is encoded for a lower bandwidth and resized smaller. For more information, see "File and Server Outputs".

• Parallel Inputs

Using a job file, you can merge parallel inputs into a single output. For example, you might merge a video stream from a digitized file with audio that you capture live. For more information, see "Single and Multiple Inputs".

• Audio Delay Compensation Prefilter

This prefilter allows you to resynchronize an audio soundtrack with video. This is useful if you are capturing audio and video separately as parallel inputs. Refer to "Audio Delay Compensation Prefilter".

• Prefilter Resizing

Through the job file, you can resize the video input before or during the encoding. See "Video Resizing Methods" for an explanation of the available resizing options.

• File Rolling

File rolling normally occurs when an encoded clip reaches the file size limit set by the operating system. With the file rolling parameters, you can specify other sizes or time limits for file rolling. See "File Rolling".

Tips for Creating Job Files

The following are some tips to keep in mind when using job files:

• When creating a new job file, RealNetworks recommends that you start with an existing job file that you have renamed. RealProducer provides a number of predefined job files that are stored in the samples/jobs subdirectory under the RealProducer main directory. You can use these files as templates for your own jobs.
• You can override most job file settings through the RealProducer graphical application, then save or discard your changes after encoding. If a certain clip could benefit from noise filtering, for instance, you can apply that filter during the encoding, even though the job file does not specify the use of that filter. This gives you the ability to create job files with general settings that you change on a case-by-case basis.
• When encoding through the command-line application, you cannot override or add to the settings in the job file, except in the specific cases described in "Job File Options".
• Prefilters, which are described in "Prefilters", have parameters that enable or disable them. This allows you to define a prefilter within a job without activating it. If you think that you may want to use a certain prefilter with a job, it's a good idea to add the prefilter syntax to the job file and leave the filter disabled until you need to use it.
• A job can define specific input and output files. You can override a specific input and output during encoding. Or, you can create a job file that has blank input and output values. If you do this, include the appropriate syntax, but leave the value blank, as in the following example:

<filename type="string"></filename>

• A job file defines encoding audiences, as described in "Audiences Section". An output's media profile, described in "Media Profile", determines which audiences the output uses, though. This allows you to define all the audiences you think that you might use within the audiences section, then apply those audiences to various outputs through their the media profiles.
• RealProducer Plus supports the full range of job file capabilities. If you use RealProducer Basic, however, you are limited by the following restrictions:

• no cropping, resize, or audio gain filter
• RealVideo 10 codec only
• maximum of three audiences in a SureStream CBR clip
• one customized audience
• one file and one server destination
• no multicast broadcasting

Job Section

The <job> and </job> tags encapsulate all job information within a job file. The <job> tag follows directly after the XML declaration tag. Be sure to include the namespaces shown in the following example, and add any namespaces required by customized RealProducer components:

<?xml version="1.0" encoding="UTF-8"?>
<job xmlns="http://ns.real.com/tools/job.2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://ns.real.com/tools/job.2.0
  http://ns.real.com/tools/job.2.0.xsd">
    ...all job parameters...
</job>

Job Properties

The following table describes the main properties within the <job> list.

Job File Example

The following abstract example shows the major structure of a job file. The order of the lists within the <job> section does not matter. For example, the <audiences> list can precede the <clipInfo> list. The hierarchy does matter, however. The <audiences> list cannot fall within the <clipInfo> list, for instance:

<?xml version="1.0" encoding="UTF-8"?>
<job xmlns="http://ns.real.com/tools/job.2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://ns.real.com/tools/job.2.0
  http://ns.real.com/tools/job.2.0.xsd">
    <enableTwoPass type="bool">true</enableTwoPass>
    <clipInfo>
        ...clip information such as title, author, and copyright...
    </clipInfo>
    <inputs>
        ...inputs used to encode the clip or broadcast contents...
    </inputs>
    <parOutputs>
        ...outputs for the encoded content, such as a clip or broadcast server...
    </parOutputs>
    <audiences>
        ...audiences for the content, defining bandwidths and the codecs used...
    </audiences>
</job>

Clip Information

The optional clip information section defines metadata properties that are encoded into static clips and live broadcasts. The values are typically provided for the benefit of the viewer, and do not affect the encoded content. For example, a metadata value can provide a clip title that displays in the media player's title bar. The following abstract example demonstrates clip information within the job file structure:

<clipInfo>
    <entry>
        <name>Metadata Name</name>
        <value type="type">Metadata Value</value>
    </entry>
         ...additional metadata entries...
</clipInfo>

Clip Information Values

Each metadata entry falls between <entry> and </entry> tags. A <name> element and <value> element define each metadata property.

Metadata Values for RealPlayer

RealPlayer supports a number of metadata values. If you do not specifically add metadata values, no metadata is encoded into the stream.

For More Information: The section "Adding Clip Information" explains the values you should use for the clip metadata properties.

Separate Clip Information for Outputs

If you define information within a single <clipInfo> list at the start of the job file, that information is used for all clips or broadcasts created with the job file. As described in the section "File and Server Outputs", you can also define clip information within each output section. This allows you to define separate information for each output when encoding multiple outputs. You can also mix the two methods. In this case, clip information defined for an output overrides the corresponding information defined for the job.

Tip: You can define the same basic information, such and title, author, and copyright for all outputs by setting these values for the job. You can then add specific information, such as unique descriptions, for each output.

Clip Information Examples

The following example defines several metadata properties used for all outputs created through the job file:

<job...>
    <clipInfo>
        <entry>
            <name>Title</name>
            <value type="string">2003 Football Highlights</value>
        </entry>
        <entry>
            <name>Copyright</name>
            <value type="string">(C) 2004</value>
        </entry>
        <entry>
            <name>Keywords</name>
            <value type="string">sports, football</value>
        </entry>
        <entry>
            <name>Description</name>
            <value type="string">A year-end review of the highlights in the 2003 
                 fall football season.</value>
        </entry>
        <entry>
            <name>Content Rating</name>
            <value type="uint">1</value>
        </entry>
    </clipInfo>
    ...all other job file information...
</job>

The next example defines basic clip information such as title, author, and copyright for all outputs, but a separate description for each output. In this example, one output is a live broadcast and another output is an archive clip that will be available on-demand after the broadcast ends:

<job...>
    <clipInfo>
        <entry>
            <name>Title</name>
            <value type="string">2003 Football Highlights</value>
        </entry>
        ...other clip info such as author and copyright...
    </clipInfo>
    ...other job file information...
    <parOutputs>
        <output>
            ...output information for the live broadcast...
            <clipInfo>
                <entry>
                    <name>Description</name>
                    <value type="string">A live, year-end review of the highlights in
                        the 2003 fall football season.</value>
                </entry>
            </clipInfo>
        </output>
        <output>
            ...output information for the archive clip...
            <clipInfo>
                <entry>
                    <name>Description</name>
                    <value type="string">Archived highlights of the 2003 fall 
                        football season.</value>
                </entry>
            </clipInfo>
        </output>
    </parOutputs>
    ...additional job file information...
</job>

Audio and Video Inputs

The inputs section defines the audio or video input for the job. Inputs can be either digitized files or output from capture devices such as cameras attached to a video capture card. The <inputs> and </inputs> tags encapsulate the inputs section. Within this list, you can define a single input or multiple inputs.

For More Information: The section "Audio and Video Input Formats" lists acceptable file and color formats for encoding.

Single and Multiple Inputs

To define a single input, you add <input> and </input> tags within the <inputs> element:

<inputs>
    <input ...>
        ...single input defined here...
    </input>
</inputs>

To define multiple inputs, you add <parInputs> and </parInputs> tags within the <inputs> element. Then, you define each input between <input> and </input> tags:

<inputs>
    <parInputs>
        <input ...>
            ...audio input defined here...
        </input>
        <input ...>
            ...video input defined here...
        </input>
    </parInputs>
</inputs>

Using parallel inputs, you can encode one audio and one video stream simultaneously, using any combination of sources. For example, you might encode into a single clip the audio from one file and the video from a different file. Or, you might combine the audio from a file with video images captured live.

Tip: To encode audio and video from the same live event, you capture the audio and video as a single input. You use parallel inputs only when the audio and video come from different sources.

Note: When a job includes parallel inputs, you must encode the job through the command-line application rather than the graphical application.

For More Information: With parallel inputs, you can use the audio delay compensation prefilter to synchronize the audio and video inputs. See "Audio Delay Compensation Prefilter".

Input Tag

The <input> tag defines each input. It uses an xsi:type attribute with a value of avFileInput or captureInput, respectively, to indicate whether the input comes from a digitized file or a capture device. The following example shows a single input for a digitized file:

<inputs>
    <input xsi:type="avFileInput">
        ...input values for the digitized file...
    </input>
</inputs>

The next example defines the single input as live or prerecorded material coming from an audio or video capture device:

<inputs>
    <input xsi:type="captureInput">
        ...input values for the capture...
    </input>
</inputs>

Digitized File Input

When the input is a digitized file, the input type is avFileInput. You can then specify the following properties. You can leave the file name value blank if you want to specify the file name through the graphical application, as described in "Using a File as the Input". The file name value is required when you process the job file through the command-line application, however.

File and Directory Paths

For an input's filename value, you list the path and file name when encoding through the command-line interface. When using the graphical application, you can specify the name, or leave the value blank and provide the file name when encoding. The file name and path should use the standard conventions for your operating system. However, RealProducer observes the following conventions to help keep the job file portable across platforms:

• You can specify a relative or absolute path to a file. Relative paths are relative to the current working directory, which is the directory from which the command-line application is run or the graphical application was started. If you start RealProducer by double-clicking a job file, the working directory is the directory that holds the job file.
• On Windows, forward slashes in paths are interpreted as backslashes, so "/" is read as "\".
• On Linux, backslashes are interpreted as forward slashes, so "\" is read as "/".
• If an absolute path starts with a single slash, RealProducer on Windows assumes that the path occurs on the system's default drive. For example, if C:\ is the default drive, the path /home/media/video.mpeg is interpreted as C:\home\media\video.mpeg.
• On Linux, absolute paths that start with a drive letter such as C:\ cause an error because no logical translation is possible.

Capture Input

When the input comes from a capture device, such as a camera, microphone, or CD player, the input type is captureInput. You can then specify the following properties. Only the capture device ID is required.

Devices and Ports

The required audioDeviceID and videoDeviceID parameters select the capture card or cards used for the input. The optional audioDevicePort and videoDevicePort parameters set the ports used for audio and video capture, respectively. You can use any of the following values:

• Integer of value 0 or higher identifying a specific device or port number. A value of 0 always selects the first device or port. Here is an example:

<audioDeviceID type="uint">1</audioDeviceID>

• String matching an existing device or port name. The following are examples:

<audioDeviceID type="string">Sound Blaster Live!</audioDeviceID> <audioDevicePort type="string">Line In</audioDevicePort>

<videoDeviceID type="string">Osprey Capture Card 1</videoDeviceID> <videoDevicePort type="string">S-Video</videoDevicePort>

• String with a wildcard (*) matching an existing device or port name, such as:

<audioDeviceID type="string">Sound Blaster *</audioDeviceID> <audioDevicePort type="string">Mic*</audioDevicePort>

<videoDeviceID type="string">Osprey Capture Card *</videoDeviceID> <videoDevicePort type="string">Composite*</videoDevicePort>

• UNIX device name, such as one of the following:

/dev/audio

/dev/video

The following are tips for setting the audio and video device IDs and ports:

• If you use a single video card to capture both video and audio, you must specify both the audioDeviceID and videoDeviceID parameters.
• Using numbers for the device IDs maximizes the portability of the job file so that you can transfer it to another machine.
• The pull-down lists in the Devices section of the graphical application supply the names of audio and video devices on your RealProducer computer. For more information, see "Using Live Audio or Video as the Input".
• The command-line application's -pd option displays audio and video device information. See "Print Device Information (-pd)".
• The video card's settings define the captured frame rate. During encoding, RealProducer uses the largest frame rate among all selected audiences as the maximum frame rate target. See "Video Stream Properties".

Input File and Capture Examples

The following examples illustrate the syntax for encoding input from files and live captures.

Single Input File

The following example defines a single input for a digitized file. A single prefilter is used with the input. For more on prefilters, refer to "Prefilters".

<inputs>
    <input xsi:type="avFileInput">
        <filename type="string">C:\media\videos\video1.avi</filename>
        <prefilters>
            <prefilter xsi:type="audioGainPrefilter">
                <enabled type="bool">true</enabled>
                <gain type="double">-5</gain>
                <pluginName type="string">rn-prefilter-audiogain</pluginName>
            </prefilter>
        </prefilters>
    </input>
</inputs>

Single Capture Input

The following example captures audio and video input for 15 minutes. A single prefilter is used to attenuate the audio input. For more on prefilters, refer to "Prefilters".

<inputs>
    <input xsi:type="captureInput">
        <audioDeviceID type="string">Sound Blaster *1</videoDeviceID>
        <audioDevicePort type="string">Mic*</videoDevicePort>
        <videoDeviceID type="string">Osprey Capture Card 1</videoDeviceID>
        <videoDevicePort type="string">S-Video</videoDevicePort>
        <pluginName type="string">rn-capture-av</pluginName>
        <duration type="duration">15:00.000</duration>
        <prefilters>
            <prefilter xsi:type="audioGainPrefilter">
                <enabled type="bool">true</enabled>
                <gain type="double">-5</gain>
                <pluginName type="string">rn-prefilter-audiogain</pluginName>
            </prefilter>
        </prefilters>
    </input>
</inputs>

Parallel Inputs

Using parallel inputs, you can encode one audio stream and one video stream from separate sources. The following example captures the visual track from a digitized video file. It combines this stream with five minutes of audio from the audio capture device. The black-level filter increases the video contrast. The audio delay compensation prefilter advances the audio one-half second to synchronize it with the video. For more on prefilters, refer to "Prefilters".

<inputs>
    <parInputs>
        <input xsi:type="avFileInput">
            <name type="string">VideoInput</name>
            <filename type="string">c:\media\promo.avi</filename>
            <disableAudio type="bool">true</disableAudio>
            <prefilters>
                <prefilter xsi:type="blackLevelPrefilter">
                    <pluginName type="string">rn-prefilter-blacklevel</pluginName>
                    <enabled type="bool">true</enabled>
                </prefilter>
            </prefilters>
        </input>
        <input xsi:type="captureInput">
            <name type="string">AudioInput</name>
            <audioDeviceID type="string">Sound Blaster *1</videoDeviceID>
            <audioDevicePort type="string">Mic*</videoDevicePort>
            <pluginName type="string">rn-capture-av</pluginName>
            <duration type="duration">5:00.000</duration>
            <prefilters>
                <prefilter xsi:type="audioDelayCompPrefilter">
                    <pluginName type="string">
                        rn-prefilter-audiodelaycomp</pluginName>
                    <enabled type="bool">true</enabled>
                    <advance type="double">0.5</advance>
                </prefilter>
            </prefilters>
        </input>
    </parInputs>
</inputs>

Prefilters

An optional prefilters section can appear within each <input> list to define the audio and video filters that are applied to the input before it is encoded. The prefilters appear within a list defined by <prefilters> and </prefilters> tags (note the plural "prefilters"). Each prefilter uses <prefilter.../> and </prefilter> tags (note the singular "prefilter") to enclose the prefilter properties. An xsi:type attribute within a <prefilter> tag determines the type of prefilter used. The following example shows the audio gain prefilter defined within an input section:

<input xsi:type="avFileInput">
    ...additional input information...
    <prefilters>
        <prefilter xsi:type="audioGainPrefilter">
            <enabled type="bool">true</enabled>
            <gain type="double">0.000000</gain>
            <pluginName type="string">rn-prefilter-audiogain</pluginName>
        </prefilter>
    </prefilters>
</input>

The following table summarizes the available prefilters.

Note: You can also define prefilters within the media profile section, which is described in "Media Profile". This is recommended if you are defining multiple outputs and want to use different filters for each output.

Prefilter Order

RealProducer applies prefilters in the order they are specified within the job file. Because a prefilter alters video data before the data is passed to the next filter, specifying prefilters in the wrong order can degrade the output. For example, reducing noise can make a video impossible to de-interlace. The following is the recommended order for using prefilters on video input:

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

Note: You can apply audio prefilters at any point in the filtering chain.

Video Resizing Methods

The following sections describe the two methods for resizing a video. In either case, video resizing during encoding is processor-intensive and should be avoided for a live broadcast. If you need to resize a live broadcast, the best method is to perform resizing in hardware on the video capture device before sending the input to RealProducer.

Tip: You can also crop an input video to remove unnecessary portions. This is done through the cropping prefilter, as described in "Input Cropping Prefilter".

Prefilter Resizing

The video resize prefilter, which is described in "Video Resizing Prefilter", alters the size of the video before it is encoded. This prefilter is useful for correcting non-square pixel aspect ratios. If the input video has a non-square pixel aspect ratio (such as DV), you can shorten the video horizontally to convert non-square pixels to square pixels. Resizing the video before the actual encoding may also speed the rest of the encoding process because less source material needs to be encoded. All outputs use the resized input.

Codec Resizing

Through an output's media profile, which is described in "Media Profile", you can also specify a new video height and width. In this resizing method, the RealVideo codec resizes the content during the encoding. Because codec resizing is more efficient, it is generally preferable to prefilter resizing unless you need to correct for non-square pixels. This is the mode used when you resize content through the graphical application or command-line application.

Tip: Always use codec resizing when making a video larger. Expanding the video through the resizing prefilter adds extra pixels, which makes the clip larger and harder to compress. In contrast, resizing the output larger through the codec encodes instructions that tell RealPlayer how to increase the video dimensions during playback. This keeps the clip size smaller.

Width and Height Values for Resizing

For the video resize prefilter, the videoResizeWidth and videoResizeHeight properties set the video's new size. When you resize through the codec, the media profile's outputWidth and outputHeight properties resize the video. Both sets of properties work the same way.

For any resize property, the value must be at least 32, and be a multiple of 4, such as 120, 240, 360, and so on. Values not divisible by 4 are rounded down. For example, a value of 123 is rounded down to 120. If both height and width are set to 0, no resizing occurs. The maximum height or width is 2048 pixels.

To preserve an input video's aspect ratio, set the height or width to the desired size, then set the other value to 0. If the input video is 640 pixels wide by 480 high, for example, you can set the width to 320 and the height to 0. This automatically scales the height to 240. If you do not preserve the input video's height-to-width ratio when resizing, the output video will appear distorted.

Input Cropping Prefilter

The input cropping filter contains several settings for cropping the video source. You can use it to cut out unnecessary parts of a video, such as the black bars at the top and bottom of a letterboxed, widescreen clip. The prefilter uses the type value of xsi:type="inputCroppingPrefilter".

Note: The cropping prefilter does not scale the video larger or smaller. For information about resizing, see "Video Resizing Methods".

Input Cropping Properties

The following table describes the cropping properties.

Tip: If you perform a horizontal or vertical resizing on the video first, the cropping offsets are measured from the video's new size, not its original size.

Input Cropping Example

The following example demonstrates the cropping prefilter syntax. Applying this prefilter creates a video that is 320 pixels wide by 240 pixels high. The output video's top border begins 12 pixels down from the top border of the input video. As well, its left border begins 24 pixels in from the left border of the input video.

<prefilter xsi:type="inputCroppingPrefilter">
    <pluginName type="string">rn-prefilter-inputcropping</pluginName>
    <enabled type="bool">true</enabled>
    <left type="uint">24</top>
    <width type="uint">320</top>
    <top type="uint">12</top>
    <height type="uint">240</top>
</prefilter>

De-Interlace and Inverse-Telecine Prefilter

The optional de-interlace filter is useful for videos larger than 240 pixels high. The inverse-telecine filter is for NTSC videos that have been transferred from film. For an explanation of these filters, refer to "Inverse-Telecine Filter" and "De-interlace Filter". The prefilter uses the type value of xsi:type="deinterlacePrefilter".

De-Interlace and Inverse-Telecine Properties

The following table describes the de-interlace and inverse-telecine properties.

De-Interlace and Inverse-Telecine Example

The following syntax provides an example of the de-interlace and inverse telecine filters:

<prefilter xsi:type="deinterlacePrefilter">
    <pluginName type="string">rn-prefilter-deinterlace</pluginName>
    <enabled type="bool">true</enabled>
    <manual type="bool">false</manual>
    <deinterlace type="bool">true</deinterlace>
    <inverseTelecine type="bool">true</inverseTelecine>
</prefilter>

Video Noise Reduction Prefilter

This filter can reduce video noise. It has high and low settings, which are described in the section "Noise Filters". The prefilter uses the type value of xsi:type="videoNoiseReductionPrefilter".

Noise Reduction Properties

The following table describes the noise reduction filter properties.

Noise Reduction Example

The following is sample syntax for the low noise reduction prefilter:

<prefilter xsi:type="videoNoiseReductionPrefilter">
    <pluginName type="string">rn-prefilter-videonoisereduction</pluginName>
    <enabled type="bool">true</enabled>
    <level type="string">low</level>
</prefilter>

Black-Level Prefilter

This filter increases the video contrast and improves the RealVideo codec efficiency. For more information, refer to "Black-Level Correction Filter". The prefilter uses the type value of xsi:type=blackLevelPrefilter".

Black-Level Properties

The following table describes the black level properties.

Black-Level Example

The following is sample syntax for the low noise reduction prefilter:

<prefilter xsi:type="blackLevelPrefilter">
    <pluginName type="string">rn-prefilter-blacklevel</pluginName>
    <enabled type="bool">true</enabled>
</prefilter>

Video Resizing Prefilter

The video resize prefilter resizes the video input before encoding. You should generally run it last, as noted in "Prefilter Order", because vertical resizing can adversely affect the use of other prefilters. The prefilter uses the type value of xsi:type="videoResizePrefilter".

Tip: Refer to "Video Resizing Methods" to determine if the resize prefilter or codec resizing is the better method to use for your content.

Video Resizing Properties

The following table describes the video resizing filter properties.

Video Resizing Examples

The following example demonstrates the video resize filter syntax reducing the video size to 176 pixels wide by 132 pixels high:

<prefilter xsi:type="videoResizePrefilter">
    <pluginName type="string">rn-prefilter-videoresize</pluginName>
    <enabled type="bool">true</enabled>
    <videoResizeWidth type="uint">176</videoResizeWidth>
    <videoResizeHeight type="uint">132</videoResizeHeight>
    <videoResizeQuality type="string">high</videoResizeQuality>
</prefilter>

If you are running the de-interlace filter on a large video, you may be able to decrease the encoding time by first resizing the video's width, running the other prefilters, then resizing the video's height. The initial, horizontal resize decreases the amount of video data that other prefilters must process. Only vertical resizing needs to be performed after other prefilter operations because it can affect de-interlacing.

The following example resizes a video from 320-by-240 pixels to 176-by-132 pixels in two steps. Note that in the first resizing, the height is reduced. Here, the original width is specified because leaving the videoResizeHeight set to its default value automatically reduces the height to keep it in the same aspect ratio with the video. In the second resizing, the height is reduced:

<prefilters>
    <prefilter xsi:type="videoResizePrefilter">
        <pluginName type="string">rn-prefilter-videoresize</pluginName>
        <enabled type="bool">true</enabled>
        <videoResizeWidth type="uint">176</videoResizeWidth>
        <videoResizeHeight type="uint">240</videoResizeHeight>
        <videoResizeQuality type="string">high</videoResizeQuality>
    </prefilter>
    ...other prefilters, such as de-interlacing...
    <prefilter xsi:type="videoResizePrefilter">
        <pluginName type="string">rn-prefilter-videoresize</pluginName>
        <enabled type="bool">true</enabled>
        <videoResizeWidth type="uint">176</videoResizeWidth>
        <videoResizeHeight type="uint">132</videoResizeHeight>
        <videoResizeQuality type="string">high</videoResizeQuality>
    </prefilter>
</prefilters>

Audio Gain Prefilter

The audio gain prefilter amplifies or attenuates audio. When the prefilter is enabled in the job file, it applies to all audio inputs. The audio gain prefilter does not support multichannel audio and should not be used when encoding multichannel input. This prefilter uses the type value of xsi:type="audioGainPrefilter".

Audio Gain Properties

The following table describes the audio gain filter properties.

Audio Gain Example

The following example demonstrates the audio gain filter syntax:

<prefilter xsi:type="audioGainPrefilter">
    <pluginName type="string">rn-prefilter-audiogain</pluginName>
    <enabled type="bool">true</enabled>
    <gain type="double">5.000000</gain>
</prefilter>

Audio Delay Compensation Prefilter

The audio delay compensation prefilter corrects audio shift when audio input is out of synchronization with a video's visual track. It shifts the audio by the number of specified seconds, eliminating the need to correct the delay through video preprocessing. This is useful when you encode audio and video from separate, parallel inputs.

You can specify this filter only through the job file. It is not available through the graphical user interface or command-line application.When the prefilter is included in the job file, it applies to all audio inputs. Using this filter, which has a type value of xsi:type="audioDelayCompPrefilter", does not increase the encoding time.

Tip: Some video editing tools, such as DVD ripping software, provide information about how much delay exists between audio and video.

For More Information: For more on separate, parallel inputs used to encode audio and video, refer to "Single and Multiple Inputs".

Audio Delay Compensation Properties

The following table describes the audio delay compensation filter properties.

Note: You typically specify either advance or delay. If you specify both, the applied delay value is the difference between the two values. For example, if you set advance to 0.2 seconds and delay to 0.5 seconds, the applied audio compensation is a delay of 0.3 seconds.

Audio Delay Compensation Example

The following example demonstrates the audio gain filter syntax:

<prefilter xsi:type="audioDelayCompPrefilter">
    <pluginName type="string">rn-prefilter-audiodelaycomp</pluginName>
    <enabled type="bool">true</enabled>
    <delay type="duration">0.1</delay>
</prefilter>

File and Server Outputs

The outputs section defines the output for the job, which is either an encoded clip or a broadcast stream sent to Helix Server. The <parOutputs> and </parOutputs> tags encapsulate the outputs section. Within this list you can define one or more outputs between <output> and </output> tags. All outputs defined in this section are encoded simultaneously when the job file runs.

The <output> tag defines each output within the <parOutputs> list. An <output> section is itself a container for separate sublists that define the output's destination, media profile, and optional clip information. The following example shows the structure for defining a single output for a digitized file:

<parOutputs>
    <output>
        <destinations>
            ...output destinations for the clip or broadcast...
        </destinations>
        <mediaProfile>
            ...profile for the output, such as the audiences it uses...
        </mediaProfile>
        <clipInfo>
            ...optional clip information for the output...
        </clipInfo>
    </output>
    ...additional outputs...
</parOutputs>

Note: When you define more than one output, the output streams are encoded simultaneously. You must use the command-line application to process a job file that includes multiple outputs, however. For live captures, it is important that your RealProducer machine has sufficient processing power for parallel outputs.

For More Information: For instructions about defining clip information for each output, refer to "Clip Information". For background on broadcast requirements, refer to Chapter 10.

Destinations Section

The destinations section defines the destination for each output, which can either be a clip or a broadcast stream sent to a server. The <destinations> and </destinations> tags encapsulate the destinations section within an <output> list. Within this list you can define one or more destinations between <destination> and </destination> tags. All destinations defined for the output are encoded simultaneously when the job file runs.

Destination Tag

A <destination> tag defines each destination within the <destinations> list. It uses a type attribute with one of the following values to encode the output as a file or a broadcast stream:

File Destinations

When the output destination is a digitized file, the destination type is xsi:type="fileDestination". You can then specify the properties described in the following table. A file name parameter is required, but you can leave the value blank if you want to specify the name through the graphical application, as described in "Creating a Destination Clip". When you use the command-line application, you must include the file name. If you specify more than one output file, you must run the job through the command-line application.

File Destination Example

The following example shows a single input for a digitized file:

<destination xsi:type="fileDestination">
    <filename type="string">C:\media\movie.rm</filename>
</destination>

Output File Names

An output file name is required when encoding through the command-line application. It is optional when using the graphical application, however, and you can add the name through the graphical application before you encode, as described in "Creating a Destination Clip".

Whether you use the command-line application or graphical application, you can omit the file name value as long as you encode from an input file. The output then uses the same base file name as the input, along with the appropriate extension (.rm or .rmvb). For example, a constant bit rate clip encoded from movie.avi becomes movie.rm. A variable bit rate version becomes movie.rmvb.

If you specify the name of clip that exists already in the output directory, RealProducer archives the existing clip by appending _archNNN to the base file name. Hence, movie.rm becomes movie_arch001.rm before the new movie.rm clip is saved. If you encode the output again, the existing movie.rm becomes movie_arch002.rm. Higher numbers therefore represent newer archives.

File Rolling

File rolling allows you to create multiple RealMedia files for a single output clip. Each new file is appended with a number. The output clip movie.rm might be saved as movie.rm, movie1.rm, movie2.rm, and so on. Rolling happens automatically when the clip reaches the RealMedia file format limit (4 GB), or the maximum size allowed by the operating system:

• 2 or 4 Gigabytes on Windows
• 2 Gigabytes on Linux

You can also specify limits to the file size using the destinationRollSize property. A value of 30, for example, creates a new output clip from the file or live input when the current clip reaches 30 Megabytes in size.

Rolling Files By Time

The destinationRollTime property rolls new files based on the amount of time that RealProducer has encoded the output. For example, if you set a file destination time of 15 minutes when encoding a broadcast named live.rm, the first 15 minutes is encoded as live.rm, the second 15 minutes is saved as live1.rm, and so on.

Because this time-rolling method is based on encoding time rather than the input media's timeline, it can produce clips of various lengths when you encode an input file. With a roll time of 15 minutes, each rolled clip may play for 20 minutes, for example, if RealProducer was able to encode the input faster than real-time.

Time values are accurate to the minute, but should include a seconds designation using the syntax described in "Duration Syntax". For example, the following sets a roll time of 10 minutes:

<destinationRollTime type="duration">10:00</destinationRollTime>

Tip: You can specify both a file rolling time and a file rolling size. In this case, the new file is created when the first specified limit is reached.

Combining Archives

Using the RealMedia Editor described in Chapter 12, you can combine rolled files into a single output, up to the file size limit of your operating system. You can also play the individual clips in sequence through a Ram file or a SMIL file. With either method, though, that file transitions may not be seamless, and may contain audio and video gaps. If you stream the clips in sequence, each new clip may require buffering that temporary pauses playback on RealPlayer.

Tip: Refer to Introduction to Streaming Media or RealNetworks Production Guide for information about combining rolled clips into a single sequence using a Ram file or a SMIL file.

Server Destinations

When the output destination is a server, the destination type is one of the following, depending on the server type and the broadcast method:

If you plan to encode using the graphical application, you can include the server destinations in the job file. Or, you can leave the server destination section empty, and define server destinations through the graphical application as described in Chapter 11. When you broadcast using the command-line application and a job file, your job file must define the server destination.

Tip: The easiest way to define a server destination is to create a a server file as described in Appendix D. Then, incorporate the server file syntax into the job file.

Incorporating a Server File into a Job File

You can add server destination information from a server file into a job file manually, as described in the following procedure.

To create a job file server destination from a server file:

1. Create a <destinations>...</destinations> section for the output if one does not exist already.
2. Copy everything from the selected server file between its <destination> and </destination> tags, and paste this markup into the <destinations> element. This is everything in the server file, except for the XML declaration tag on the first line.
3. Delete the namespaces from the <destination> tag. The job file requires only the namespaces defined in the <job> tag.
4. If you wish to use the job file in the graphical application, include the server's name property.
5. If you set up multiple broadcast outputs sent to the same server, ensure that each stream name, as defined by the streamname property, is unique.

Media Profile

Within an output section, a media profile section defines the output settings, such as which audiences are used. Because you define the media profile separately for each output, you can create multiple outputs that have different properties, such as two clips encoded at different dimensions. A list created by the <mediaProfile> and </mediaProfile> tags defines these settings between each output's <output> and </output> tags, as shown in the following example:

<parOutputs>
    <output>
        ...output information...
        <mediaProfile>
            ...media profile settings for this output...
        </mediaProfile>
    </outputs>
<parOutputs>

Media Profile Properties

The following table describes the properties defined in an output's media profile section. The audience references section is required. All other elements are optional.

Media Profile Audience References

The <audienceRefs> list contains one or more <audienceRef> elements that select which audiences are used with the output. The audience defines the audio and video codecs used, and sets the output's streaming bandwidth. The audiences are defined elsewhere in the job file, as described in "Audiences Section". The value enclosed by the <audienceRef> element must correspond to an audience name, which is described in "Audience Properties".

Multiple Audience References Example

The following example shows four audiences used when encoding an output:

<parOutputs>
    <output>
        ...output information...
        <mediaProfile>
            ...media profile information...
            <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>
    </output>
</parOutputs>

Combining Multiple Audiences

As shown in the preceding example, you can encode multiple streams into a single output using SureStream. When you do this, you must choose audiences appropriately for the encoding to work:

• Using more than one audience requires that all audiences use constant bit rate encoding. Attempting to include a variable bit rate stream in the output causes the encoding to fail. In each audience definition, the encodingType value should be cbr. For more information, refer to "Video Stream Properties".
• All video streams must use the same video codec. You cannot encode some streams as RealVideo 10 and some streams as RealVideo 8, for example. If audiences specify different RealVideo codecs, the newer codec is used. For information on selecting the video codec, see "Video Stream Properties".
• To make good use of SureStream, streams should use significantly different bandwidths, as determined by the audience's avgBitrate element:

• If two video streams have average bit rates within five percent of each other, RealProducer encodes both streams but logs a warning.
• If two or more audio streams use different audio codecs that differ in bit rate by 1 Kbps or less, RealProducer logs an error and stops the encoding. Difference audiences can specify the same audio codec, however. To conserve file size and processing time, RealProducer encodes the audio stream only once.

For More Information: For more on avgBitrate, see "Audience Properties".

Media Profile Example

The following example shows media profile settings defined for two output clips. The first clip is meant for dial-up modem connections, so it specifies dial-up modem audiences, and resizes the input to make it smaller. This helps to increase the frame rate and clarity when streaming over slow connections. The second output is for broadband connections. It specifies several DSL and cable modem audiences, keeping the encoded video the same size as the input:

<parOutputs>
    <output>
        ...output information for the first file...
        <mediaProfile>
            <audioMode type="string">voice</audioMode>
            <disableAudio type="bool">false</disableAudio>
            <disableVideo type="bool">false</disableVideo>
            <outputHeight type="uint">132</outputHeight>
            <outputWidth type="uint">176</outputWidth>
            <resizeQuality type="string">high</resizeQuality>
            <audienceRefs>
                <audienceRef>16k Substream for 28k Dial-up</audienceRef>
                <audienceRef>28k Dial-up</audienceRef>
                <audienceRef>56k Dial-up</audienceRef>
            </audienceRefs>
        </mediaProfile>
    </output>
    <output>
        ...output information for the second file...
        <mediaProfile>
            <audioMode type="string">voice</audioMode>
            <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>
            <audienceRefs>
                <audienceRef>256k DSL or Cable</audienceRef>
                <audienceRef>512k DSL or Cable</audienceRef>
                <audienceRef>768k DSL or Cable</audienceRef>
            </audienceRefs>
        </mediaProfile>
    </output>
</parOutput>

For More Information: For information about the relationship between video dimensions, bandwidth, and output quality, see "Factors for Creating a Good Streaming Video".

Audiences Section

The audiences section defines one or more audiences that are used within the job file. Because a job file can define multiple audiences, the audience section starts and ends with <audiences> and </audiences> tags (note the plural "audiences"). Within this section, one or more sublists defined between <audience> and </audience> tags (note the singular "audience") create each audience setting. The following example shows the structure of the audience section within a job file:

<job...>
    ...additional job file information...
    <audiences>
        <audience>
                ...first audience definition...
        </audience>
        <audience>
                ...second audience definition...
        </audience>
        ...additional audience definitions...
    </audiences>
</job>

For More Information: Refer to Appendix C for an explanation of the audience syntax.

Working with Audiences

Each job file should have an audiences section defined between <audiences> and </audiences> tags. If you plan to encode using the graphical application, you can include the audiences in the job file. Or, you can leave the audiences section empty, and select your audiences through the graphical application as described in "Choosing Audiences".

When you use a job file with the command-line application, your job file must define the audiences. The easiest way to create the audience definitions is to import the syntax from an audience file, as described in "Incorporating an Audience File into a Job File".

It's important to keep in mind that not every audience listed in the job file must be used when encoding. The audience definitions within the <audiences> list provide the reference information necessary to encode for a particular audience. An output's media profile section determines which audiences are used for that output, however, as described in "Media Profile".

Incorporating an Audience File into a Job File

You can add audience information from an audience file into a job file manually, as described in the following procedure.

To create a job file audience section from an audience file:

1. Create an <audiences>...</audiences> section within the job file if one does not exist already. This list falls within the <job>...</job> list, and typically appears at the end of the job file. Note the plural "audiences" in the tag names.
2. Copy everything from the selected audience file between the <audience> and </audience> tags. This is everything in the file, except for the XML declaration tag on the first line.
3. Delete the namespaces from the <audience> tag. The job file requires only the namespaces defined in the <job> tag.
4. Ensure that the audience definition includes a name attribute, which is described in "Audience Properties".
5. For each output in the job file that uses these audience settings, modify the output's media profile to refer to the audience by way of the audience name value. For more information, refer to "Media Profile Audience References".

©2004 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.