XML File Format Used By LOR2 to Save Sequences

1. XML File Format Used By LOR2 to Save Sequences • The XML format used by LOR2 makes it easier for users to view and edit a sequence file outside of LOR with some level of success. • Editing of sequence files outside of the LOR editor is not recommended by LOR and may result in a corrupt file which is unusable. • ! ! ! BACK UP YOUR FILES BEFORE ATTEMPTING TO EDIT THEM ! ! ! • Note: This information is valid for LOR 2.9.4 (saveFileVersion 8)

2. LOR1 used a binary data file to store sequences etc. • Binary format could be opened using other applications (like Notepad) but most of the data was not understandable and could not be edited. • Binary format was compact to achieve smaller files sizes. • I’m not sure where goopblip37 came from, but it was used throughout the sequence file to divide sections of the file.

3. LOR2 uses a XML file format to store sequences etc. • XML is a text-based format which can be viewed and understood using simple text readers (like Notepad). • XML can be edited and saved using simple text readers (if the correct syntax is used).

4. XML - Extensible Markup Language • XML is similar to the HTML format used to save web pages. • XML defines a basic syntax that is used to save and share information. • Along with using the XML syntax, LOR2 uses a specific structure to store the data (referred to as a schema). • The LOR2 schema is not published, but it can be learned by studying the files. • XML format basics • XML data is stored in a tree type structure. • The XML file has one root element. • The root element can contain any number of child elements. • Each element is designated with a start-tag (<_>) and a corresponding end-tag (</_>). • Each element can contain additional child elements, values, and attributes. • Additional info on XML can be found by searching the web for XML format.

5. Example of XML data in LOR2 sequence file (viewed using Notepad)

6. XML Notepad is a great tool for understanding the content of an XML file • XML Notepad opens any XML file into tree view. • The elements of the tree can be expanded or collapsed to navigate the file. • You can learn a lot about how a sequence functions by viewing it in XML Notepad. • XML Notepad 2007 is available free from Microsoft.

7. The XML declaration element • <?xml version="1.0" encoding="UTF-8" standalone="no"?> • This should not be edited. • The start-tag of the root element and its attributes • (sequence start-tag and sequence attributes) • <sequence saveFileVersion=“6" author="RW" createdAt="2/1/2009 7:30:48 AM" musicFilename="C:\1wertz\Lights\LorInfo\testsnd.wav"> • This marks the beginning of all the information contained in the sequence. • It also defines sequence specific settings (file version, music file etc.) • <sequence is the beginning of the start-tag of the sequence. • saveFileVersion, author, createdAt, and musicFilename are all attributes of the sequence. • > is the end of the start-tag (and also encloses the attributes of the sequence). • The corresponding end-tag (</sequence>) occurs at the end of the file. • The saveFileVersion denotes different versions of the structure of the file. • Most updates to the saveFileVersionsimply indicate new features that are not backward compatible. • The official release of LOR2 (2.3.4) changed the saveFileVersion from 5 to 6. • This change was significant because they moved the timings from within each track to a separate holding area called timingGrids.

8. The channels element and individual channel elements contained for each channel • <channels> • <channel name="Unit 01.1" color="12615744" centiseconds="87" deviceType="LOR" unit="1" circuit="1" savedIndex="0"> • <effect type="intensity" startCentisecond="0" endCentisecond="10" intensity="100"/> • <effect type="intensity" startCentisecond="50" endCentisecond="60" intensity="100"/> • </channel> • <channel name="Unit 01.2" color="12615744" centiseconds="87" deviceType="LOR" unit="1" circuit="2" savedIndex="1"> • <effect type="intensity" startCentisecond="0" endCentisecond="10" intensity="100"/> • <effect type="intensity" startCentisecond="20" endCentisecond="30" intensity="100"/> • <effect type="intensity" startCentisecond="60" endCentisecond="80" intensity="100"/> • </channel> • </channels> • This defines the channel settings (name, color etc.) and the lighting effects. • <channels> is the start-tag for the element that contains the group of channel elements. • <channel is the beginning of the start-tag for a individual channel. • channel name, color, centiseconds, deviceType, unit, circuit, and savedIndex are all attributes of the channel. • > is the end of the start-tag for the channel (and also encloses the attributes of the channel). • The savedIndex is how LOR references the channel. It does not control the order they are displayed. • The lighting effects for the channel are listed next. • <effect type="intensity" startCentisecond="0" endCentisecond="10" intensity="100"/> • /> is the end-tag for the effect. effect is not needed because / occurs before the closing angle bracket. • This is an empty-element. It contains no other elements, just attributes • * Cool Trick - To reduce the intensities in a sequence, do a replace of intensity="100" with intensity="50"

9. The tracks element and individual track elements contained for each track • This defines which channels are displayed in each track. • <tracks> • <track totalCentiseconds ="87" timingGrid="0"> • <channels> • <channel savedIndex="0"/> • <channel savedIndex="1"/> • <channel savedIndex="2"/> • <channel savedIndex="3"/> • </channels> • <loopLevels/> • </track> • </tracks>

10. The animation element • This defines the animation picture, the dimensions of the animation grid, and which cells are assigned to which channels • <animation rows="40" columns="60" image="" hideControls="false"> • <row index="14"> • <column index="24" channel="0"/> • <column index="25" channel="0"/> • </row> • <row index="16"> • <column index="24" channel="1"/> • <column index="25" channel="1"/> • </row> • </animation> • The end-tag of the root element (sequence) • </sequence>

11. Editing the LOR2 sequence file using Notepad - Part 1 • Make a backup copy of the sequence file in case your changes mess up the sequence file. • Open Notepad program • Open the LOR2 sequence file (File / Open / Files of type: All Files) • Make any necessary changes to the file • Save the file • Find and Replace are the simplest and safest changes • Be sure you are replacing only the data you are looking for and you put valid data in its place. • Intensity change would be a common change. But notice that the attribute intensity is capitalized differently than the word “Intensity” in the attributes startIntensity and endIntensity. • Changing this capitalization could cause LOR to crash when it opens the file. • Find and Replace can be done on a specific section of the sequence. • Place the cursor at the beginning of the area to be effected and replace until the end of the area is reached.

12. Editing the LOR2 sequence file using Notepad - Part 2 • Adding channels is significantly more complicated. • A channel element must be added to both the channels element and one of the track elements. • The savedIndex must be in line with the existing savedIndexes. • (The savedIndex does not correlate with the displayed order in the program) • If you are modifying multiple sequence files, the savedIndexes will likely be different in each file. • Fixing missing musicFilename • LOR used to have an issue that made it possible for a music sequence to act like an animation sequence and disable the ability to assign a music file. • If a music sequence was saved without the music file set to a valid file, LOR would remove the musicFilename attribute in the sequence element. • Once this happened the only way to recover the file was to edit the musicFilename attribute back into the sequence file.

13. Using Excel to extract a sortable copy of the channel configuration – Part 1 • (This is how it works in Excel 2003) • To avoid affecting any LOR files, export a new copy of your channel configuration. • In Excel choose File / Open. • Change Files of type to All Files. • Open the configuration (.lcc) file.

14. Using Excel to extract a sortable copy of the channel configuration – Part 2 • You may have to choose Open XML As an XML list. • You may have to choose OK when told Excel will create a schema.

15. Using Excel to extract a sortable copy of the channel configuration – Part 3 • Look for the columns labeled “unit” (or possibly “/channels/channel/@unit”) and “circuit” (or possibly “/channels/channel/@circuit”). • Scroll down till you see info in theses columns. • Copy the info to a fresh Excel workbook. Then you can sort, save, etc.

16. Using Excel to extract a sortable copy of the channel configuration – Part 4 • Notes: • Any channel that is copied to another track will appear multiple times. To avoid confusion, you can remove any entries from your sort list that do not belong to track 1. • Unit numbers are saved as a decimal value in the configuration file. This value has to be converted to Hexadecimal in order to compare it with the settings in the sequence and on the controller.