Editing XML Files

This document describes the process for editing XML files created with the Helix DNA Producer 10.0.   

The purpose of this document is to provide information on how to edit the settings files used by Helix DNA Producer: Job files, Audience files and Server files.

Complete references for each of the settings files are available in Helix DNA Producer Job File Reference, Helix DNA Producer Audience File Reference and Helix DNA Producer Server File Reference.


Table of Contents

     What is XML
     Editing XML with Text Editors
     GUI XML Editors
     XML Schemas

What is XML

XML is a text markup language defined by the World Wide Web Consortium (WC3, www.w3c.org) that provides a means of organizing data in a text formatted file.  Because XML is a WC3 recommendation, many applications support reading and writing of XML files.  Thus, tools are available to read, write and validate XML files on a wide variety of platforms.  This document discusses some of those tools.

Glossary

The following terms are useful in referring to XML documents:

Tag
A name surrounded by angle brackets.  
e.g. <input>
Tag Name
An XML tag name is a series of characters consisting of letters, numbers, the underscore (_), dash (-), colon (:) or period (.).   XML tag names are case sensitive.
e.g.  input
Element
Everything from an opening tag to its corresponding close tag.  
e.g. <input>...</input>
Attribute
Name/value pair that contains information about the tag.  
e.g. <input type="device">...</input> where type is the attribute name and device is the attribute value.
Value
Actual data that is contained between the opening and closing tags.
Empty Element
An element that contains no text between the opening and closing tags. Empty elements can be written with just the open tag as long as the tag has a forward slash before the close bracket (i.e. />).  Typically empty elements contain attributes.  
e.g. <input type="capture" />
Simple Element
An element that contains only a value.  Simple XML elements are referred to as "properties" below.
e.g. <filename>C:\Myfile.avi</filename>
Complex Element
An element that contains other elements and/or values within it.  Complex XML elements are referred to as "sections" below.
e.g.   <input>
             <filename>C:\Myfile.avi</filename>
        </input>

Editing XML with Text Editors

Helix DNA Producer settings files are text files written in XML format.  Thus, these files may be edited with any simple text editor such as Notepad on Windows or emacs on Linux.

For editing an audience file in Notepad, start Notepad and open the desired audience file.  You will find standard audiences in the audiences directory within the application installation folder.  When you open an audience file you will see something like this:

As you can see above, the format of the file is an XML document.  Be careful about what you change.  You should only modify values which are not nested between open and close angle brackets (e.g. <dont_edit_this or="this">ok_to_edit_this</and_dont_edit_this>).  If you are unsure about editing raw XML content, you should refer to the section below which discusses GUI XML editors.  

Simple Elements (Properties)

A simple element is the combination of a tag name and its value.

For example:

<avgBitrate type="uint">20000</avgBitrate>
Example 1  Simple Element

 

Where:

Note: Attributes are used to identify the data type.  Attributes are required on all properties that define a type attribute.  Information on attribute values can be found in the settings file reference for each of the settings files.

Complex Elements (Sections)

A complex element is an element that has one or more elements nested within it.

For example:

<stream xsi:type="videoStream">
   <pluginName type="string">rn-videocodec-realvideo</pluginName>
   <codecName type="string">rv9</codecName>
   <encodingType type="string">cbr</encodingType>
   <quality type="uint">30</quality>
   <maxStartupLatency type="double">4</maxStartupLatency>
   <maxFrameRate type="double">15</maxFrameRate>
   <maxKeyFrameInterval type="double">10</maxKeyFrameInterval>
   <enableLossProtection type="bool">false</enableLossProtection>
</stream>
Example 2  Complex Element

Where:

Common Editing Operations

There are a few common operations when editing an XML file such as:

Changing the value of a simple element means you edit the value located between the opening and closing XML tags.  For example, to change the average bit rate for an audience from 20kbps to 22 kbps, you modify the value 20000 to 22000 in the Example 1 as shown in Example 3 below.

<avgBitrate type="uint">20000</avgBitrate>
Example 3  Modified Property

Adding new sections is easiest if you can copy and paste the XML from another document or repeat a section in the existing document.  For example, in a job file, clip information is stored in a section called clipInfo.  The clipInfo section stores one or more entry sections which in turn hold 2 properties.  The following demonstrates a sample clipInfo section. 

 

<clipInfo>
   <entry>
      <name>Title</name>
      <value type="string">Your title here</value>
   </entry>
</clipInfo>
Example 4a  Unmodified Complex Element 

To add a new name/value pair, you copy the entire entry element and paste it below the existing one but before the close of the clipInfo complex element as shown below:

<clipInfo>
   <entry>
      <name>Title</name>
      <value type="string">Your title here</value>
   </entry>
   <entry>
      <name>Title</name>
      <value type="string">Your title here</value>
   </entry>
</clipInfo>
Example 4b  Duplicated Complex Element 

You now modify the values of the simple elements to the new name/value pair as shown below.

<clipInfo>
   <entry>
      <name>Title</name>
      <value type="string">Your title here</value>
   </entry>
   <entry>
      <name>Author</name>
      <value type="string">Your name here</value>
   </entry>
</clipInfo>
Example 4c  Modified Complex Element 

While this information describes how to edit an XML document in very generic terms, specific information about Helix DNA Producer XML documents can be found in the references files Helix DNA Producer Job File Reference, Helix DNA Producer Audience File Reference and Helix DNA Producer Server File Reference.

GUI XML Editors

Because the audience files are based on XML formatting, you can use any XML editor to edit these documents.  A simple XML editor available for free is Microsoft XML Notepad available at <http://msdn.microsoft.com/downloads>.   Following is an audience file opened in XML Notepad.

As you can see, there is much less chance of making an error by removing vital formatting when you use a GUI XML Editor.

There are many different applications to Edit XML files.  This application provides just one possible way to view and edit XML documents.  For a good listing of XML editors, please see the list of XML Software <http://www.w3.org/XML/#software> on W3C's XML website and Validating XML Software <http://www.w3.org/XML/Schema> on W3C's XML Schema website.

XML Schemas

XML Schemas are data definitions for XML documents.  XML Schemas are used to define the structure, content and semantics of XML documents.  The document Validating XML Files with Schemas describes XML Schemas and how they can be used to validate the contents of Helix DNA Producer settings files.

Copyright © 2003, RealNetworks Inc. All rights reserved.