Custom XML Files for ANC Packets

Transcription

1 IMAGE PROCESSING TECHNIQUES Custom XML Files for ANC Packets The Extended Dataview feature offered in OmniTek video monitoring products enhances the standard pixel value display through the addition of pixel colour data and descriptions of identifiable structures such as ANC packets in the video signal. The information displayed about any ANC packet is generated with the aid of dedicated XMLformat descriptor files which identify data fields within particular ANC packets and specify how that data should be displayed in the Extended Dataview. A range of such XML files are delivered with each OmniTek application that offers the Extended Dataview feature. These files are located in the ANCParser\XMLDefs subdirectory of the application and enable the identification of a range of AES controls, SMPTE time codes and RP188 control codes. However, they don t cover all possible ANC packets. In particular, they don t cover any custom ANC packets that users may define. If an ANC packet is found for which no XML file is available, the message No Definition Found will be displayed together with the embedded Data ID to allow separate identification. This document describes how to set up XML-format descriptor files for decoding these ANC packets. Note: (i) The facility described in this document is limited to single ANC packets. It is not able to handle information spread across multiple packets such as those used to deliver Dolby-E metadata. (ii) Setting up these descriptor files is not a quick process as they effectively define each bit of the packet is to be handled, so before embarking on this process for an industry-standard ANC packet, it is a good idea to check that you are not simply seeing this message because something has happened to make the supplied XML files unavailable to the application. The application directory within your program files should include an ANCParser\XMLDefs subdirectory and this subdirectory should include a range of.xml files. June 2008

2 1. Overview The format of ANC packets is defined by SMPTE 291. The format of the packet header is rigidly defined by this standard. What is different between one packet type and another is the format of the UDW block, so it is the structure of this block that the XML file principally defines, together with a few items of header information such as the packet identifier. The detailed structure of the packet header, EAVs and SAVs are of no concern here. The format of the XML descriptor files is defined by the.xsd schema file included in the ANCParser\XMLDefs subdirectory. A single file can cover more than one type of packet, but for maintenance purposes, it is advisable to limit the packets detailed in any XML file to ones allied to same task or defined in the same specification. The top level of the hierarchy in these XML files is a Protocol statement, which records the name of the XML schema file that is used and gives an overall name to the set of packets described by XML file. Nested within the Protocol element are one or more PacketType elements. Each PacketType element describes an individual packet among the ones defined for the selected protocol. The PacketType statement itself is principally used to specify the Data ID of the ANC packets being described and to set the name that will be displayed on the Extended Dataview screen where this packet is identified within the video being analysed. The detailed description of the block of UDWs within the packet is given by a series of BitField elements, where necessary interspersed with Switch elements and/or BREAK statements. Each BitField statement defines how an individual bit field within the UDW area of the packet is to be displayed. These statements mainly lead on to a sequence of Bit statements that map the individual bits within the bit field into data to be displayed. BitField elements may also include Determinant statements that determine whether data is displayed or hidden depending on the value of a bit field within the UDW. Switch elements allow different display structures to be used depending on the value of a particular bit field. Each Switch statement is therefore followed by a BitField element as described above, together with one or more Case elements (also with associated BitField elements) that define the required action in each of the different conditions covered by the Switch. The BREAK statements that may be included within a packet description are concerned purely with the layout of the data when displayed in the Dataview. They allow subheadings to be inserted in the data. All of the different statements include a number of attributes that define the necessary details. Some of these attributes are required within a particular type of statement, some are optional. Details are given below, together with examples. Attributes that must be given are marked (required). While the nesting of these statements obviously has to be correct, there is no requirement on the ordering of information within any particular level or on the ordering of the attributes. However, adopting a logical order is recommended for both ease of maintenance and ease of debugging. It is similarly a good idea to give different items appropriate names. Page 2 of 16

3 Note: A number of the attributes associated with the different statements are purely concerned with the presentation of the information. Together, they offer a high degree of flexibility with regards to the layout of information. However, it is generally good idea to just worry about getting the information you want out correctly to start with and leave worrying about the presentation of this information as a secondary task. Issues of layout are dealt with in a separate section below. It is however worth thinking about the length of any labels you define because these aren t wrapped, so it is generally best to keep labels short. Resources supplied The following resources are supplied as part of appropriate OmniTek applications: XML Schema file (currently ANCV3.xsd) A range of XML descriptor files, providing interpretation of a range of AES controls, SMPTE time codes and RP188 control codes. These files are all located in ANCParser\XMLDefs subdirectory and can be viewed using a range of tools. Neither the Schema file nor the supplied XML should be changed but the supplied XML files may be used as examples on which to base your own XML files. Note, however, that these files can t be edited in Microsoft Excel. Resources required In order to create your own XML descriptor files, you will need: An XML file creation tool Detailed specification of each ANC packet that you want to create a descriptor file for Video sequences that include one or more examples of these packets for testing purposes. If you don t have a dedicated XML file creation tool, we recommend downloading the free XML Notepad application from the Microsoft web-site. While it is possible to use a text editor to create the descriptor file, using a dedicated XML creation tool will usually be very much easier. Creation Procedure The details of the procedure to follow to create a file depend on the tool used but in essence you need to create a file that: 1. First identifies the version of XML that is being used (must be compatible with the supplied schema, which is XML version 1.0). 2. Then selects the supplied schema (currently ANCV3.vsd). 3. Below that adds, for each of the required packet type(s), the appropriate statements needed to define first the packet identifier (and give the packet a suitably descriptive name), then the location of the required data within UDW block. The file then simply needs to be saved as a.xml file to the ANCParser\XMLDefs subdirectory, replacing any existing.xml file that describes any of the same packet types. The OmniTek application automatically checks the Packet Identifier in ANC packets in the video against the.xml Page 3 of 16

4 files it finds in its ANCParser\XMLDefs directory. If there are duplicate definitions, there is no guarantee that it will pick out the one you require. Various approaches are possible but the easiest may be to copy the different elements you require from the supplied XML files (taking care not to save any changes you accidentally make to the supplied file), paste the required element into the new XML file and make any adjustments that are needed and just continue doing this until you have defined how to handle each bit of information that you want to extract from the UDW region of the packet. Ultimately, the XML file is essentially a text file containing a sequence of XML-format statements. The syntax of the various statement types is given in Section 2 below, together with examples. However, your XML Editor may well present it in a more user-friendly form, for example with each component of any description shown as a user-editable sequence of associated attributes and values. The statements that are valid are ultimately defined by the schema, and depending on the XML Editor that you use, it may be possible to make this pick up and work with the supplied schema in such a way that it only offers / accepts valid constructs and valid information. Testing To test the XML description that you have created at any stage, save the file to the ANCParser\XMLDefs directory. Then reload the OmniTek application and use your test video (see above) to see whether the packets you know it contains are both correctly identified and the required information displayed. Page 4 of 16

5 2. The Elements The sections below give the syntax of the different statements that may appear in descriptor files used with the supplied schema file, together with examples of valid statements. The examples given are taken from the supplied XML files. Protocol Statement The Protocol is the top-level element. To be compliant, the XML document must specify exactly one Protocol element. <Protocol Attributes> </Protocol> Attributes: xmlns=" (required) where schema-file is the name of the.xsd file (assumed to be located within the ANCParser\XMLDefs directory). e.g. xmlns=" ProtocolName="protocol-name" (required) where protocol-name is a string that gives a suitable overall name to the set of packets described by XML file, for example one that identifies the specification defining the packets. This string does not have to be unique to this XML document. e.g. ProtocolName="AES" Example: <Protocol xmlns=" ProtocolName="AES"> Nested within the Protocol element are one or more PacketType elements (see below). PacketType Statements The PacketType is the second-level element within the file. It is nested within the Protocol element. There must be at least one PacketType element within the file but there is no maximum number. Each PacketType element describes an individual packet among the ones defined for the selected protocol. Only those packets that are of interest need be defined: for any other packets, the Extended Dataview will simply display the message No Definition Found together with the packet s Data ID. <PacketType Attributes> </PacketType> Attributes: PacketIdentifier="string" (required) where string specifies the Data ID that (together with any Secondary Data ID, see below) identifies the type of ANC packet that is being described as given in the specification for the packet. This identifier must be unique to the packet as it is the item by which the software identifies which XML description to use to analyse the data it contains. e.g. PacketIdentifier="0x2E7" Page 5 of 16

6 PacketName="string" (required) where string describes the Packets decoded by this PacketType element. This name is displayed at the start of the description of the packet see the section on Layout (page 11). e.g. PacketName="HDTV audio Group 1" DescriptionLabel="string" where string defines a heading to go above the data. This is particularly useful where a tabular layout is used for the data see the section on Layout (page 11). e.g. DescriptionLabel=" Sample Z V U C F" LabelOffset="integer" where integer specifies that the above label should be positioned one or more lines below its default position in the Extended Dataview display see the section on Layout (page 11). e.g. LabelOffset="1" Repetative="boolean" where boolean is set to "true" where the target packet consists of a repeated sequence of bit fields and "false" in all other instances. Note: You aren t asked to specify the number of repetitions because this can be deduced in any particular case from the length information given in the packet header. e.g. Repetative="false" SecondaryPacketIdentifier="string" where string specifies the Secondary Data ID (SDID) associated with a Type 2 ANC packet. Note: This attribute is optional and may be omitted for Type 1 PacketType definitions. e.g. SecondaryPacketIdentifier="0x260" Example: <PacketType PacketIdentifier="0x2E7" PacketName="HDTV audio Group 1" Repetative="false" DescriptionLabel=" Sample Z P C U V" LabelOffset="1"> Each Packet is composed of a number of bit fields, the descriptions of which are given by individual BitField elements. At present each PacketType element must include at least one BitField element. It may also include Break statements and Switch elements. BitField Statements Each BitField element describes a group of bits that together make up a single item of information within the packet. They typically comprise a BitField statement together with a sequence of Bit statements but, where appropriate, they may also include Determinant statements. There must be at least 1 BitField element within any PacketType element but there is no maximum number. Note: A bit field may stretch across multiple words, but at present may not go above 32 bits in length. <BitField Attributes> </BitField> Attributes: FieldName="string" (required) where string is a suitably descriptive name for the Bit Field. This name will be used to label the associated data in the Dataview, subject to the setting of the Label attribute see below and the section on Layout (page 11). The name used does not have to be unique. e.g. FieldName="CH 1 Audio Data" Page 6 of 16

7 BFWordOffset="integer" (required) where integer identifies the word within the packet at which the bit field starts, by identifying its offset from the start of the UDW block/the start of the current repetition if the PacketType Repetative attribute has been set to "true". e.g. BFWordOffset="2" FieldLength="integer" (required) where integer is the number of bits in the reconstructed bit field. At present, this is limited to a maximum of 32 bits. e.g. FieldLength="22" Repeated="boolean" (required) This distinguishes between bit fields that are repeated and those which are not. boolean is true where the bit field being described is repeated within a repetitive PacketType, but otherwise should be false. e.g. Repeated="true" Repitions="integer" Where Repeated is true, integer gives the number of repetitions. e.g. Repitions="3" BFType="BitFieldType" This is used where the BitField statement is part of a Switch or Case element to specify how the value of the bit field should be treated. BitFieldType may be either Selective, Conditional or Default. Switch elements and Case elements are described on page 9. e.g. BFType="Selective" Label="boolean" (required) where boolean is true where the reconstructed data is to be laid out as a sequence of <field-name> <data> statements but should be false where it is to be laid out as a series of values without any field-name labels (though possibly with a sequence separator between the different items). e.g. Label="false" DisplayBase="integer" where integer sets the base in which the value of the field is to be displayed and is either 10 (decimal) or 16 (hex). If DisplayBase is not set, the data will be displayed in hex. e.g. DisplayBase="16" DisplayWidth="integer" This is used, particularly where the data is laid out in a table, to allocate a specific number of characters to the display of the bit field data see the section on Layout (page 11). e.g. DisplayWidth="6" SequencePosition="integer" where integer gives the position of the bit field data in a sequence of data displayed on the same line of the Extended Dataview display (i.e. Label="false"). e.g. SequencePosition="0" SequenceSeperator="string" where string specifies one or more characters to append to the current bit field data when Label="false", in order to separate it from the data taken from the next bit field see the section on Layout (page 11). e.g. SequenceSeperator=" : " Page 7 of 16

8 Example: <BitField BFWordOffset="2" FieldName="CH 1 Audio Data" FieldLength="22" Repeated="false" Label="false" DisplayWidth="6" DisplayBase="16" SequencePosition="0" SequenceSeperator=" "> Any BitField element must contain at least one Bit statement. Bit Statements Each Bit statement describes a single bit within the associated bit field. There must be at least one Bit statement within any BitField element. The maximum number is 32. <Bit Attributes /> Attributes: BitName="string" (required) where string typically describes the significance of the bit within the bit field. It is used solely as a way of identifying the item in the specification that the bit represents. The name used doesn t have to be unique but it rapidly becomes confusing if the same name is used for different bits within the same bit field. e.g. BitName="audio 10" WordOffset="integer" (required) where integer identifies the word that contains the bit by defining its position relative to the word picked out by the BFWordOffset given in the BitField statement. This is not the same as the offset within the packet and will only ever be greater than 0 where the bit field is longer than 1 word in length. e.g. WordOffset="1" BitOffset="integer" (required) where integer gives the offset of the bit within the word identified by the WordOffset. e.g. BitOffset="6" Destination="integer" (required) where integer gives the offset of the bit within the reconstructed bit field. e.g. Destination="10" Example: <Bit BitName="audio 10" WordOffset="1" BitOffset="6" Destination="10" /> Determinant Statements BitField elements may include one or more Determinant statements. These specify one or more bits within a group of up to 32 bits that are to act as flags, determining whether the BitField element should be applied. If the BitField element includes a number of Determinant statements, the results from the separate Determinant statements are ANDed i.e. all must be satisfied in order for the BitField element to be applied. <Determinant Attributes /> Page 8 of 16

9 Attributes: WordOffset="integer" (required) where integer identifies the word in the packet to be inspected from the start of the UDW block/the start of the current repetition if the PacketType Repetative attribute has been set to "true". e.g. WordOffset="3" Mask="string" (required) where string is a Hexadecimal value that defines a mask to be applied to the data starting at the WordOffset. At present the maximum supported length of a mask is 32 bits. e.g. Mask="0x80" Target="string" (required) where string specifies, in hex, the required value once the Mask has been applied to the data. e.g. Target="0x80" Allow="boolean" (required) where boolean is true where a positive result should allow the BitField element to be applied, and is false where a positive result should prevent the BitField element from being applied. e.g. Allow="true" Example: <Determinant WordOffset="3" Mask="0x80" Target="0x80" Allow="true" /> Switch Statements PacketType elements may include one or more Switch elements. Each Switch element comprises a Switch statement, a BitField element and one or more Case elements (see below). The Switch statement and the BitField element together identify the bit field within the UDW block that determines which of the possible actions is to be selected. The Case elements define the action to take in each case. An example of a Switch element may be found in the RP 188ATCDef.xml file. There is no limit on the number of Switch elements that may be included in any PacketType element. <Switch Attribute> </Switch> Attribute: WordOffset="integer" (required) where integer specifies the word in the UDW block from which the Switch statement operates, counting either from the start of the block or, if appropriate, from the start of the current repetition. e.g. WordOffset="0" Example: <Switch WordOffset="0"> Each Switch statement is followed by a BitField element, together with one or more Case elements (see below). The BitField element defines the data whose value will determine which of the Case elements will be selected. The location of this data is given relative to the word selected by the WordOffset included in the associated Switch statement. Page 9 of 16

10 Case Statement Switch elements include one or more Case elements. These specify how data should be both selected and displayed in the different cases identified by the bit field data selected by the Switch element as the control. Examples of Case elements may be found in the RP 188ATCDef.xml file. There is no limit on the number of Case elements that may be included in any Switch element. <Case Attributes> </Case> Attributes: Target="integer" where integer is the value of the bit field data for which the following BitField element(s) should be applied. e.g. Target="0" Title="string" where string is an optional side-heading that may be inserted before the data extracted by the following BitField elements. e.g. Title="Longitudinal TimeCode" Example: <Case Target="0" Title="Longitudinal TimeCode"> Each Case statement is followed by one or more BitField elements. BREAK Statements PacketType elements may include one or more BREAK statements. BREAK statements are used where multiple items of data are presented on the same line (e.g. in a table) to specify where one line ends and another begins. They can also be used to insert a label at the start of the current line of data. <BREAK Attributes /> Attributes: WordOffset="integer" (required) where integer identifies the word within the UDW after which the break should be inserted. Where appropriate, the offset is calculated from the start of the current repetition. e.g. WordOffset="14" Label="string" where string is the required side-heading. This is inserted at the start of the line of data e.g. Label="Ch 3 : " Example: <BREAK WordOffset="14" Label="Ch 3 : " /> Page 10 of 16

11 3. Layout The items of data extracted from the ANC packets are basically presented as lines of information, all displayed in the system font. However the XML statements detailed in the previous section include attributes which provide some control over how the data is positioned. This section looks at the main ways in which data from an ANC packet might be laid out in the Extended Dataview and describes the statement attributes used to achieve these results. The examples given are all taken from the supplied XML files. List Layout <name> = <data> <name> = <data>. This is the most straightforward way of laying out the data. It is achieved through using individual BitField statements, each with: Fieldname = <name> Label = "true" The following example of this layout being used is taken from the supplied RP188ATC.xml file. Example XML Statements Example Result Tabular Layout <heading1> <heading2> <heading3> <heading4> <heading5> <data1> <data2> <data3> <data4> <data5> <data1> <data2> <data3> <data4> <data5> This layout is achieved through a combination of (i) the PacketType statement; (ii) BitField elements; and (iii) BREAK statements. The PacketType statement sets the column headings and whether these are to be displayed at the beginning of the packet or after any other lines of information. The attributes that set these things are: Page 11 of 16

12 DescriptionLabel = "string" where string defines the line of headings to go above the data, suitably padded to fit with the columns of data set up by the BitField elements. (Each item of data is positioned to the left within the space allocated to it.) LabelOffset="integer" where integer specifies that the above label should be positioned one or more screen lines below its default position in the Extended Dataview display. The BitField statements need to specify that there is no label with the bit field data and to set the widths of the items such that they line up with the headings. The attributes that set these things are: Label = "false" DisplayWidth = "integer" where integer sets the number of characters to be allocated to the data. (The data itself will be positioned to the left within this width. The BREAK statements mark the point at which the current line should be terminated and a new one started. The only attribute to set is: WordOffset="integer" where integer specifies the word within the UDW that ends the current line of data by giving either its offset from the start of the UDW or, where appropriate, its offset from the start of the current repetition. The following example of this layout being used is taken from the supplied ANCHDAudioDef.xml file. Example XML Statements Page 12 of 16

13 Example Result Placing Table Headings on a Particular Line The line of headings defined by the Description Label are placed by default on the line corresponding to the start of the ANC packet. However, it could well be that the packet starts with some data that isn t part of this table. In that case, you may well want to place the line of headings below this other data. This can be achieved by using LabelOffset attribute of the PacketType statement to specify that these Description Label should be placed a given number of screen lines below its default position. The following example of this layout being used is taken from the supplied ANCHDTVAudioDef.xml file. Example XML Statements Example Result Page 13 of 16

14 Handling Timestamps <timestamp-name> <hours> : <minutes> : <seconds> : <frames> This layout is achieved through a combination of BitField elements and a BREAK statement. The details of the BitField statements depend on whether the associated data represents the first item, the last item or one in the middle, as follows. The first BitField statement (e.g. <hours>) needs to include: Label="false" to stop any label associated with the data from being displayed. SequencePosition="0" to place this item firmly at the beginning of the group. SequenceSeperator=" : " to place a colon between the end of this item and the start of the next item. Middle BitField statements (e.g. <minutes>, <seconds>) need to include: Label="false" to stop any label associated with the data from being displayed. SequencePosition="integer" where integer gives the position of the bit field data in a sequence of data displayed on the same line ("2"; "3" etc.). SequenceSeperator=" : " to place a colon between the end of this item and the start of the next item. The last BitField statement (e.g. <fractions of a second>) needs to include: Label="false" to stop any label associated with the data from being displayed. SequencePosition="last" where last gives the number this item should have in the sequence (e.g. "4"). SequenceSeperator="" as this is the last item on the line. The BREAK statement is required both to terminate the time display and to preface the information with a suitable title (e.g. the type of timestamp that is being shown). The attributes to set are: WordOffset="integer" where integer identifies where the break needs to be inserted by giving the offset from either the start of the UDW or the start of the current repetition of the word containing the data that completes the timestamp. Label = "name" This name will precede the timestamp details. The following example of this layout being used is taken from the supplied RP188ATC.xml file. Page 14 of 16

15 Example XML Statements Example Result Page 15 of 16

16 Intec 2 Unit 3, Wade Road, Basingstoke, Hants RG24 8NE, UK Tel: +44 (0) Fax: +44 (0) support@omnitek.tv Web: