Appendix C: Audience File Syntax

This appendix describes the RealProducer audience syntax. Each audience file or job file records settings about how clips and broadcasts are encoded. The information in this appendix allows you to edit audience information to modify encoding settings without using 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 Audiences

Each audience section within an audience file or job file defines a single audience for which a clip or broadcast is encoded. RealProducer predefines a number of audiences that appear within the graphical user interface when you click the Audiences button. For example, one audience is for 56 Kbps dial-up modems while another is for 256 Kbps DSL and cable modem users. Each audience specifies the streaming rates at which audio and video clips are encoded, along with other settings.

Audience Files

The audience files are stored in the audiences subdirectory under the main RealProducer installation directory, although you can change this location through the RealProducer preferences. Audience files use the file extension .rpad, and their file names correspond directly to the audience name in the graphical application. For example, the 56k Dial-up audience in the graphical user interface stores its information in the file named 56k Dial-up.rpad.

If you edit an audience through the graphical application—a process described in "Creating and Editing Audiences"—RealProducer updates the corresponding audience file to record the changes. You can also edit audience files manually. This allows you to change audience information used by the graphical application or command-line application using a text editor or any automated process that can modify text files.

Tip: When creating a new audience file, RealNetworks recommends that you start with an existing audience file that you have renamed.

Audiences in Job Files

A job file, which Appendix B explains, can also hold information about audiences. For example, if you use the RealProducer graphical application to create a new job and add the 56k Dial-up audience to this job, RealProducer copies the audience information from the 56k Dial-up.rpad audience file into the job file. Unlike an audience file, which defines just a single audience, a job file can define multiple audiences. This is necessary for using SureStream technology, which encodes a single clip with multiple streams targeting different audiences.

When you encode a clip using a job file, RealProducer gathers the audience information from the job file, rather than the original audience file. This allows you to change the audience settings for the job without affecting the audience default settings. For instance, you might change an audio codec used for your 56 Kbps dial-up audience within a job. That change affects only the clips encoded using that job file.

The syntax for defining an audience within an audience file and a job file is the same, except for the following differences:

• The main <audience> tag in an audience file requires a namespace, whereas an <audience> tag within a job file does not use a namespace.
• Within a job file, an audience definition requires a name value. A job allows multiple outputs, such as encoding to two separate files. Using the name values, you can specify which audiences each output uses. One output might use a high-bandwidth audience, for example, while another output encodes for a low-bandwidth audience.
• Because a job file supports multiple audiences, each <audience> section falls within a list that begins with an <audiences> tag and ends with </audiences>. The audience file, which defines only one audience, does not use the <audiences> container list.

For More Information: Refer to "Audiences Section" for an explanation of how audiences appear within a job file.

Audience Section

The <audience> and </audience> tags encapsulate an audience section within an audience file or job file. The audience section then uses separate <streams> sections to define the video stream, the audio stream, and so on. For a standalone audience file that defines a single audience, the <audience> 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"?>
<audience xmlns="http://ns.real.com/tools/audience.2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://ns.real.com/tools/audience.2.0
  http://ns.real.com/tools/audience.2.0.xsd">
    ...all audience parameters...
</audience>

For More Information: For information about defining an audience within a job file, refer to "Audiences Section".

Audience Properties

The following table describes the properties of an <audience> element.

Audience Properties Example

The following example shows a template for an audience using 256 Kbps DSL or cable modem connections. The average bit rate is set to 225 Kbps, which allows approximately 10 percent of the total bandwidth for network overhead. If variable bit rate encoding is used, bandwidth spikes can reach 450 Kbps:

<audience>
    <avgBitrate type="uint">225000</avgBitrate>
    <maxBitrate type="uint">450000</maxBitrate>
    <name type="string">256k DSL or cable</name>
    <streams>
        ...streams defined here...
     </streams>
</audience>

Streams Section

Each audience template has a streams section that defines the encoded streams. This section starts and ends with <streams> and </streams> tags (note the plural "streams"). Within this list, one or more sublists defined between <stream> and </stream> tags (note the singular "stream") define each stream setting.

Each <stream> section can define an audio or video stream. All stream types are optional. You can omit the video stream from audio-only encodings, for example. You define each video stream once within the audience section. For audio, however, you can define up to four streams for four separate audio contexts:

• music in an audio-only clip
• voice in an audio-only clip
• music in a video clip
• voice in a video clip

The various <stream> sections use an xsi:type attribute to indicate the type of the stream. The following example shows the five possible streams defined within an audience section:

<audience>
    ...other audience properties...
    <streams>
        <stream xsi:type="audioStream">
            ...audio stream for music in an audio-only clip...
        </stream>
        <stream xsi:type="audioStream">
            ...audio stream for voice in an audio-only clip...
        </stream>
        <stream xsi:type="audioStream">
            ...audio stream for music in a video clip...
        </stream>
        <stream xsi:type="audioStream">
            ...audio stream for voice in a video clip...
        </stream>
        <stream xsi:type="videoStream">
            ...video stream...
        </stream>
    </streams>
</audience>

Audio Stream Properties

The following table describes the properties that the various audio streams can contain. Each audio stream section begins with a <stream xsi:type="audioStream"> tag and ends with a </stream> tag. The codecName and codecFlavor properties are required.

Audio Stream Context

Each audience can have up to four audio streams that define which audio codec is used based on the presentation type (audio-only or audio-video) and audio mode (voice or music). This creates four possible audio stream contexts:

• voice in an audio-only clip
• music in an audio-only clip
• voice in a video clip
• music in a video clip

These contexts exist because you should use different codecs when encoding music or voice. As well, the audio typically receives more bandwidth in an audio-only clip than in a video clip. When RealProducer encodes a clip using the audience information, it selects just one of the audio contexts, based on other audio settings you have defined in the job file, graphical application, or command line.

For More Information: For background on audio contexts, refer to the section "Audio Encoding for Audiences".

Stream Context Element

Each audio stream uses the streamContext sublist to define one of the four possible audio contexts. For example, the following markup instructs RealProducer to use this audio stream when encoding voice audio for a video clip or broadcast:

<stream xsi:type="audioStream">
    ...audio codec information...
    <streamContext type="bag">
        <audioMode type="string">voice</audioMode>
        <presentationType type="string">audio-video</presentationType>
    </streamContext>
</stream>

Stream Context Properties

The following table describes the stream context properties.

For More Information: The section "Setting Audio Parameters" explains how to set the audio mode through the graphical application. For the command line, see the section "Audio Mode (-am)". See "Media Profile" for information about how the stream context is set in a job file.

Using Fewer than Four Audio Stream Contexts

Unless you are an advanced user, RealNetworks recommends that you always define four separate audio streams for the four possible stream contexts. This ensures that the audience information is valid for all possible audio contexts. However, you can define fewer than four audience contexts depending on your encoding needs. Improperly defining these audio contexts, however, may cause errors.

If you encode only music videos, for example, you can define just one audio stream that uses the appropriate music codec for your audience streaming speed. In this case, you do not need to include a <streamContext> list. RealProducer uses the single, defined stream for any audio encoded for the audience.

If you define a single audio stream, though, you may inadvertently create unstreamable clips, or clips that do not use available bandwidth effectively. Suppose that you create a 56 Kbps modem audience and use a 32 Kbps music codec as the only audio stream. The total streaming speed for this audience is approximately 34 Kbps. As long as you encode audio-only files, you are using bandwidth effectively. But if you encode a video with this audience setting, the visual track gets only 2 Kbps of bandwidth, rendering the video useless.

Conversely, you might define a 6 Kbps music clip for your 56 Kbps modem audience. This leaves about 28 Kbps of usable bandwidth for a video's visual track, which is a good division. However, if you encode an audio-only clip with this audience, it still uses just 6 Kbps of the bandwidth for the audio, letting the other 28 Kbps of bandwidth go unused. For an audio-only clip, you want to select a higher-bandwidth codec that uses bandwidth more effectively and improves the sound quality.

When you define multiple audio streams for different stream contexts, you need to ensure that a context fits your audio encoding settings. Suppose that you set RealProducer to encode a video sound track with music, and your audience file specifies just two streams:

• a stream for audio-only music
• a stream for audio-only voice

In this case, RealProducer does not encode the clip because no context for audio-video with music exists.

Audio Context Examples

The following sections explain the codec choices and show the markup used for defining audio streams for a 56 Kbps dial-up modem audience. Because this type of modem connection rarely achieves a sustained throughput of 56 Kbps, the avgBitrate value for the audience is set at 34 Kbps. The audio (or audio and video together) cannot use more than this amount of bandwidth.

For More Information: The section "RealAudio Codecs" lists the audio codecs along with the values you use for codecName and codecFlavor.

Voice for Audio-Only Clips

For audio-only with voice, choose a voice codec that uses as much of the available bandwidth as possible. For a 34 Kbps target speed, for example, the best choice is 32 Kbps voice, which has a codec name of cook and a flavor of 7:

<stream xsi:type="audioStream">
    <pluginName type="string">rn-audiocodec-realaudio</pluginName>
    <codecName type="string">cook</codecName>
    <codecFlavor type="uint">7</codecFlavor>
    <encodingComplexity type="string">high</encodingComplexity>
    <streamContext type="bag">
        <presentationType type="string">audio-only</presentationType>
        <audioMode type="string">voice</audioMode>
    </streamContext>
</stream>

Music for Audio-Only Clips

For audio-only music, choose a music codec that has a bit rate as close to the available bit rate without going over. For a 34 Kbps target speed, for example, a good choice is 32 Kbps Stereo Music High Response - RealAudio. This codec has a name of cook and a flavor of 21:

<stream xsi:type="audioStream">
    <pluginName type="string">rn-audiocodec-realaudio</pluginName>
    <codecName type="string">cook</codecName>
    <codecFlavor type="uint">21</codecFlavor>
    <encodingComplexity type="string">high</encodingComplexity>
    <streamContext type="bag">
        <presentationType type="string">audio-only</presentationType>
        <audioMode type="string">music</audioMode>
    </streamContext>
</stream>

Voice Audio for Video Clips

For audio with video, it's generally advisable to allocate only 20 percent of a video's bandwidth for audio. A good choice when streaming at 34 Kbps is 6.5 Kbps voice. This codec has a name of sipr and a flavor of 0:

<stream xsi:type="audioStream">
    <pluginName type="string">rn-audiocodec-realaudio</pluginName>
    <codecName type="string">sipr</codecName>
    <codecFlavor type="uint">0</codecFlavor>
    <encodingComplexity type="string">high</encodingComplexity>
    <streamContext type="bag">
        <presentationType type="string">audio-video</presentationType>
        <audioMode type="string">voice</audioMode>
    </streamContext>
</stream>

Music Audio for Video Clips

As with voice, a music codec for a video stream should consume only about 20 percent of the total bit rate. A good choice is either 6 Kbps Music - RealAudio, or 8 Kbps Music - RealAudio if you want better sound quality. The following illustrates the 8 Kbps codec, which has a name of cook and a flavor of 0:

<stream xsi:type="audioStream">
    <pluginName type="string">rn-audiocodec-realaudio</pluginName>
    <codecName type="string">cook</codecName>
    <codecFlavor type="uint">0</codecFlavor>
    <encodingComplexity type="string">high</encodingComplexity>
    <streamContext type="bag">
        <presentationType type="string">audio-video</presentationType>
        <audioMode type="string">music</audioMode>
    </streamContext>
</stream>

Video Stream Properties

The following table describes the properties that a video stream can contain. Each video stream section begins with a <stream xsi:type="videoStream"> tag and ends with a </stream> tag.

Stream Encoding Types

The encodingType attribute for an audio or video stream uses one of the values described in the following table. The value you select determines whether RealProducer ignores or adheres to other audience settings. This attribute primarily affects video streams, but can be used with audio as well. If you do not define it for an audio stream, RealProducer uses vbrUnconstrainedQuality for the RealAudio lossless codec and cbr for all other audio codecs.

For More Information: For background on variable bit rate encoding, see "Variable Bit Rate Video".

Video Stream Bit Rate

When you define a video stream, you do not set its bit rate directly. To determine the rate, take the audience's avgBitrate value and subtract the rates for the selected audio stream.

For a 256 Kbps audience, for example, the average bit rate may be 225 Kbps. If a 44 Kbps music audio codec is used for the sound track, the video's visual track has an average bit rate of 181 Kbps (225 minus 44). If the video uses a voice sound track that consumes 32 Kbps, the visual track has an average bit rate of 193 Kbps (225 minus 32).

For a variable bit rate clip, the same calculation using the audience's maxBitrate value reveals the video's maximum rate. If the maximum rate is 450 Kbps, for instance, the video's visual track can use a maximum bandwidth of 406 Kbps (450 minus 44) when a music codec is used, or a maximum bandwidth of 418 Kbps (450 minus 32) if a voice codec is used.

For More Information: The section "Audience Properties" describes the audience values. For background on the division between the sound track and the visual track in a video clip, refer to "Soundtrack Bandwidth".

Video Stream Example

The following example shows a video stream defined for a relatively low bandwidth, such as a dial-up modem. Because of the slow streaming speed, constant bit rate encoding is used with a maximum frame rate of 15 frames per second:

<stream xsi:type="videoStream">
    <codecName type="string">rv10</codecName>
    <enableLossProtection type="bool">false</enableLossProtection>
    <encodingComplexity type="string">high</encodingComplexity>
    <encodingType type="string">cbr</encodingType>
    <maxFrameRate type="double">15.000000</maxFrameRate>
    <maxKeyFrameInterval type="double">10.000000</maxKeyFrameInterval>
    <maxStartupLatency type="double">4.000000</maxStartupLatency>
    <pluginName type="string">rn-videocodec-realvideo</pluginName>
    <quality type="uint">30</quality>
</stream>

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