Appendix A: XML File Basics

The text files that RealProducer uses when encoding streams—job file, audience file, and server file—use XML (eXtensible Markup Language) syntax. This appendix covers the basics of editing these files, explaining tags, lists, and namespaces. Subsequent appendixes cover the specific syntax for each file type in detail.

XML File Rules

This section explains the basics of XML markup, introducing you to the rules you need to follow when editing an XML file. If you are familiar with other Web-based markup languages, such as HTML, you will pick up XML quickly. You need to be careful, though, because XML is less forgiving than HTML. Lapses that may not matter in HTML markup, such as missing quotation marks or end tags, will prevent an XML file from working properly.

Tip: You can edit an XML file with any text, HTML, or XML editor that can save the file as plain text with the proper extension. On Windows, some text editors may automatically include .txt as the extension. Disable this feature when saving by choosing All Files for Save as type, or change the saved file's .txt extension through the operating system.

The XML Tag and Namespaces

XML files begin with an <?xml> version tag:

<?xml version="1.0" encoding="UTF-8"?>

Following the version tag, markup consists of one or more elements. An audience file, for example, uses an <audience> element that contains all additional markup:

<?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">
    ...audience information...
</audience>

Each xmlns attribute shown above defines an XML namespace. This namespace tells RealProducer how to handle the markup contained within the file. The namespace identifier is in the form of a URL only to ensure uniqueness. RealProducer does not contact the URL.

Note: If you edit an XML file, do not change the namespaces. When creating a new XML file, be sure to use the appropriate namespaces for the file type.

Tags, Attributes, and Values

Elements within an XML file take the following form:

<tag type="type">value</tag>

The following are the basic parts to an XML element:

Lowercase or Camel Case for Tags and Attributes

In RealProducer markup, single-word tags and attributes are lowercase. When a tag, attribute, or predefined value consists of a compound word, the first letter of all words after the first word is generally capitalized, as in encodingComplexity. This is referred to as "camel case."

Attribute Values Enclosed in Double Quotation Marks

Attribute values, such as string in type="string", must be enclosed in double quotation marks. Do not add any blank spaces between the quotation marks and the value they enclose.

Data Type Values

Most XML elements within the RealProducer files must include a type attribute that indicates the type of value.

Value Type Examples

The following examples illustrate the use of the type attribute in RealProducer XML files:

<outputWidth type="uint">360</outputWidth>

<maxFrameRate type="double">15.000000</maxFrameRate>

<streamContext type="bag">
    ...stream context elements...
</streamContext>

<stream xsi:type="audioStream">
    ...audio stream elements...
</stream>

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

<pluginName type="string">rn-prefilter-deinterlace</pluginName>

Duration Syntax

The format for the value of a parameter that specifies a duration is the following:

[d:][h:][m:]s[.xyz]

Only the seconds value is required. If a value is omitted, it is assumed to be zero. You must specify intermediate values. To indicate hours, for example, you must include the minutes and seconds field. Here are some sample values:

File Names and Paths Observe Letter Cases

In tags that specify files or other input, paths and file names can be uppercase, lowercase, or mixed case, corresponding to their actual names on the operating system. All of the following path and file name examples are allowable, for example:

<filename type="string">C:\media\video\video1.rm</filename>
<filename type="string">C:\media\video\Video1.rm</filename>
<filename type="string">C:\media\video\VIDEO1.rm</filename>

Note: On operating systems that are not case-sensitive, such as Windows, these tags all specify the same file. On a case- sensitive operating system such as Linux, these tags indicate different files.

XML Recommendations

Although not strict rules, the following recommendations will help you keep your XML markup organized and understandable.

XML Comments

As in HTML, XML has a comment tag that starts with these characters:

<!--

and ends with these characters:

-->

There is no corresponding end tag:

<!-- This is a comment -->

A comment can be any number of lines long. It can start and end anywhere in a XML file. Multiple comments cannot be nested, though. Use comments to describe what various sections of your XML file are meant to do. This helps other people understand your file more easily.

Indentation Between Elements

Although indenting XML markup is not required, it helps you to keep track of the XML file's structure. You typically indent markup by pressing the Tab key once for each level of indentation. In a stream section, for example, the element tags are indented one level from the <stream> tag. The two tags that make up the stream context are indented one level from the <streamContext> tag:

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