XML Edit List
Similar to the traditional Excel type Edit list file, an XML edit list file can be employed. The XML file format offers a bi-directional method to push and pull data though SportsCode. We recommend using the XML import over the Edit List because it is offers more options and is easily extended. Plus, this is the only format that SportsCode can import live during capture. When using the SportsCode capture window a time code track based from the computer’s clock will be added to the movie.
The XML file can handle labels, label groups, instance notes, row colors, row sorting and time synchronisation where the traditional edit list does not offer this.
Note! Our XML file breaks strict XML standards, however the format follows the nested hierarchical nature (1 root element, elements and sub-elements) of standard XML structure. But, does not include special character handling in the element’s contents. Some characters such ampersand should be represented as ampersand if used as content in code, label, label group, and instance note elements. Do not use the special XML character handling routines. We admit to a loose interruption to the standard and apologise for any inconveniences. It is likely in the future we will tighten this up like we have done in the Matrix web exports.
Here is a short example of an XML edit list to get you started. We have added indenting and styling to better display the nesting of the tags and make it more readable. Often XML files will not have this nice indentation making them a little more intimidating. Just know this is not a necessity.
You can try copying and pasting this example into TextEdit or some other text editor like Text Wrangler, then changing some of the content between the elements and importing it into SportsCode. For those not familiar with XML, remember, all open tags must also be closed, i.e. </TAGNAME>. If the file is not formatted perfectly in this way, it will not import.
Reading down the above example from top to bottom, below is a description for each element found in the file. For interest of saving space and paper, not all descriptions will include excerpts from this example. Please refer to the example above for elements that embody many sub-elements.
The XML must start with <file> and end with </file>. This is the root element. This sets the block of data for SportsCode to read.
This is time stamp that indicates when the coding session commenced. The time stamp is used to calculate the offset between a SportsCode capture session and the incoming XML data session start time. This offset allows for seamless time synchronisation between the two separate systems. System time should be synchronised on any machines in the workflow. All instances must relate back to this time.
There are two supported date strings:
- yyyy-MM-dd HH:mm:ss.SS Z This is the preferred format.
- yyyy-MM-dd HH:mm:ss Z
<start_time>2010-03-10 21:21:39.63 +1100</start_time>
Sorting order can be included in order for the timeline rows to be automatically sorted when
they are imported. This is rather important for a better end user experience. So it should be highly considered especially when importing live XML data during captures.
The <SORT_INFO> element has a sub-element called <sort_type>. This element tells the timeline how it should sort the rows.
The options for sorting are:
- <sort_type>sort order</sort_type> – sort order indicates that a specific order must be followed during the import. The import routine will look in the <row> element to find a value to assign a priority for the sort.
- <sort_order>1<sort_order> – <sort_order> is set in the <row> element. Its contents should be represented by an integer or float: 1,2,3 or 1.1, 1.2, 1.3. The smaller the number, the higher priority the sort will be. The highest priority will be the first (top) row in the timeline. We recommend using integers, but floats can be handy if you need to insert something at a later date.
- <sort_type>color</sort_type> – color sorts the rows automatically by color using SportsCode’s standard color sorting method.
- <sort_type>name</sort_type> – name sorts the rows by name alphabetically
- <sort_type>color then name</sort_type> – color then name sorts the rows by color then name alphabetically
- <sort_type>instance count</sort_type> – instance count sorts the rows according to the number of instances, greatest being first row.Example:<SORT_INFO>
<sort_type>sort order</sort_type> </SORT_INFO>
The sorting methods are similar to those found under the Rows menu in the Main menu. Try opening an existing timeline and use the various sorting options to find out what will work best. We recommend experimenting using color and name. Color is a really good way to achieve nicely sorted and presentable timelines.
This declares the parent element for all the <instance> sub-elements. This is where the real work begins, this element contains all the instances that appear in your timeline. See this in the short example at the beginning of this section of the manual. It follows the <SORT_INFO> element.
The <instance> element represents a single instance in the timeline and all the sub-elements contained within will describe the instance to be represented in the timeline until closed with </ instance>. It is a sub-element of <ALL_INSTANCES>.
<start>4.9984074982</start> <end>10.0046128241</end> <code>Alexis Proctor</code> <label>
<text>First Step</text> </label>
<free_text>This is a great example of a fast first step.</free_text>
<ID> is a unique identifier for the instance. Each instance must have a unique identifier, no two can be the same and there can only be one of these elements per <instance> element. This is a sub- element of <instance> and its content must be represented as an integer.
This sets the start time for the instance in the timeline. It’s contents represent seconds. The contents can be an integer or float with precision up to 10 decimal places. This is a sub-element of <instance> and there can only be one of these elements per <instance> element.
Like <start>, <end> sets the end time for the instance in the timeline. It’s contents represent seconds. The contents can be an integer or float with precision up to 10 decimal places. This is a sub-element of <instance> and there can only be one of these elements per <instance> element.
The contents of the <code> element sets the row name in the timeline where the instance will be created. This is a sub-element of <instance> and there can only be one of these elements per
<instance> element. Example:
The next part describes the labels that will be contained in the instance. In the example, the first <label> element does not have a <group> sub-element , the second does. To learn more about label groups, see this section of the manual at page 35. We recommend using label grouping as it has great benefits in the Matrix and without them the Sorter loses most of sorting power.
This element indicates that a label is contained in the instance. This is a sub-element of <instance> and there can be as many <label> elements as required.
This is a sub-element of <label>. Its content is the label that will appear in the contents of the instance in the timeline. There can be only one <text> sub-element per <label> element. See page 31 of this manual for more description of a label and how and where it is used in SportsCode.
<text>First Step</text> </label>
Here is the second example with the <group> sub-element used within a <label> element.
<label> <group>Speed</group> <text>Fast</text> </label>
The <group> sub-element indicates that the label described in its sibling <text> sub-element belongs to its contents (label group). There can be only one <group> sub-element per <instance> element.
The <free_text> sub-element’s contents are the instances notes contained in an instance in the timeline. There can be only one <free_text> sub-element per <instance> element. To learn more about instance notes, see page 162 in this manual.
<free_text>This is a great example of a fast first step.</free_text>
The last section of the example describes each rows color and sorting in the timeline.
The <ROWS> element starts the section that tells SportsCode how to represent the code rows in the timeline. It is an element of the root element <file>. It contains sub-elements that indicate color for specific <code> sub-elements and provides sorting order information when the <sort_order> sub- element is used.
<sort_order>1</sort_order> <code>Alexis Proctor</code> <R>65535</R> <G>4139</G>
The <row> sub-element represents information about a specific row’s representation in the timeline. There can as many <row> sub-elements as required.
As described above, the <sort_order> sub-element sets the sort priority when the <sort_type> sub-element contents of the <SORT_INFO> element are set to “sort order”. There can be only one
<sort_order> sub-element per <row> sub_element and it is a sub-element of <row>.
The <code> sub-element’s contents tells the timeline which row it’s data is referring to. This where the relationship between the <instance> sub-elements and the <row> sub-elements is made. There can be only one <code> sub-element per <row> sub_element and it is a sub-element of <row>.
The <R> sub-element’s contents represent the color red in 16 bit RGB. It’s contents must be an integer from 0 to 65535. It is a sub-element of <row> and there can only be one per <row> sub- element.
The <G> sub-element’s contents represent the color green in 16 bit RGB. It’s contents must be an integer from 0 to 65535. It is a sub-element of <row> and there can only be one per <row> sub- element.
The <B> sub-element’s contents represent the color blue in 16 bit RGB. It’s contents must be an integer from 0 to 65535. It is a sub-element of <row> and there can only be one per <row> sub- element.
A helpful tool for finding color values on your Mac, is to use DigitalColor Meter. It can be found in the /Applications/Utilities folder. Set it to display RGB As Actual Value, 16-bit.