While version 1 XML batch files will continue to be supported, the new CatDV version 2 XML file format is more modern and more flexible and properly supports sequences, subclips, markers, metaclips, thumbnails, and more.
To import a clip by analysing the media file but specifying certain metadata fields you can write:
<catdv version=”2.0″>
<options analyseMedia=”true” updateOrAdd=”add” />
<clip>
<name>My clip name</name>
<notes>This is a clip with metadata</notes>
<tape>Tape001</tape>
<bin>Bin name</bin>
<metadata>
<field index=”1″ name=”User 1″>User field 1</field>
<field index=”23″ type=”multi-picklist” name=”Weather”>
<value>Rain</value>
<value>Cloud</value>
</field>
</metadata>
<media>
<filePath>/Volumes/Media/File2.mp4</filePath>
<metadata>
<field key=”Author”>Joe Smith</field>
</metadata>
</media>
</clip>
</catdv>
You can use XML to delete an existing clip on the server:
<catdv>
<options updateOrAdd=”delete” searchBy=”remoteID”/>
<clip>
<remoteID>623462</remoteID>
</clip>
</catdv>
The following example demonstrates creating a clip and a subclip referring to the same source media object, without performing media file analysis:
<catdv>
<clip>
<name>File.mov</name>
<type>Movie</type>
<notes>Master clip</notes>
<in seconds=”0.0″>0:00:00:00</in>
<out seconds=”10.0″>0:00:10:00</out>
<timecodeFormat>25.0</timecodeFormat>
<media id=”0″>
<filePath>/Volumes/Media/Offline/File.mov</filePath>
<video>Apple ProRes 422 (HQ) (1920×1080 25.0fps)</video>
<audio>24-bit Integer (48.0 kHz, stereo, 16 bit)</audio>
</media>
</clip>
<clip>
<name>Subclip</name>
<type>Movie</type>
<in seconds=”5.0″>0:00:05:00</in>
<out seconds=”7.0″>0:00:07:00</out>
<media id=”0″/>
</clip>
</catdv>
Notes on the new XML file format:
- Although none of the fields are mandatory when importing a clip, in order to create a useful clip (without relying on CatDV or the Worker analysing a media file) as a minimum you should ideally provide all the following: <name>, <type>, <timecodeFormat>, <in>, <out> (or <duration>), plus a <media> object with <filePath>, <video> and <audio> elements.
- The following timecode formats are supported: 1.0, 10.0, 15.0, 23.98, 24.0, 25.0, 29.97, 29.97 and, 30.0, 50.0, 59.94, 59.94 and, 60.0, 100.0.
- <clip> and <media> (and <importSource>) elements can include an id attribute, which allows multiple subclips that refer to the same source media object to be represented. It also allows sequences to refer to their source clips. (For <media> and <importSource> the id is an integer, while <clip> can use any unique string.)
- There is a consistent syntax for user-defined and media metadata fields, paving the way for general metadata fields in CatDV Server 7
- Multi-grouping fields take multiple values by providing multiple <value> elements rather than using a new line delimiter.
- Markers have separate elements for <name>, <category> and <description>, which allows for additional custom marker columns to be added when using CatDV Server 7.
- Time code values and timestamps (and also file sizes, data rates, and clip types) are stored both as an internal representation and a user-friendly formatted representation. For example, <in seconds=”1.5″>0:00:01;15</in>, <modified timestamp=”1420560808038″>Jan 6, 2015 16:13:28</modified>, <fileSize bytes=”1116192000″>1.04 GB</fileSize>, etc. On export both representations are used but during import the internal representation is preferred.
- Thumbnails can be embedded in the XML file, stored as base64 encoded JPEG data (which must not exceed 64KB per thumbnail). This allows a complete clip representation including thumbnails to be imported into CatDV via XML, even if the media file is offline.
- For examples of other features such as as <sequence>, <metaclip>, and <importSource> elements please export a version 2 XML file from CatDV or the Worker. A DTD can be provided on request.
When importing an XML file you can provide an <options> element to control how the XML file is interpreted on import and whether to update existing clips or add new ones:
- You can control whether to analyse the media file on import (to determine the clip duration, technical metadata, extract metadata from the file name or a sidecar file) using <options analyseMedia=”true”/>. By default, media files are not analysed and all the technical and other metadata is specified in the XML file.
- You can specify whether to update existing clips stored on the server or insert new clips using an element such as <options updateOrAdd=”updateOrAdd” searchBy=”filePath”/>.
- Valid update modes are “add” (this is the default and results in new clips being added even if they already exist), “addIfNew” (add a clip if it doesn’t already exist, otherwise do nothing), “updateOrAdd” (update an existing clip if it exists or add a new one), “updateOrIgnore” (update an existing clip if it exists, otherwise do nothing) and “updateOrFail” (update an existing clip if it is found, otherwise report an error).
- The special update mode “delete” can be used to delete existing clips on the server.
- Existing clips can be searched for by “remoteID” (the unique integer database id of a clip), “clipRef” (the user-settable clip ID), “filePath”, “clipRefAndPath”, “catalogAndPath”, or “catalogAndClipRef”. Note that only remoteID is guaranteed to be absolutely unique so any of the other options could result in multiple clips being updated (or deleted).
- If you update an existing clip via XML only those fields which are specified in the XML file are updated and other fields keep their original values. You can update user defined and media metadata fields, standard clip fields such as name, notes, status, tape, bin, record date, and rating, markers, plus the media path and archive status, via XML. With care you can also update the clip in and out points, type, poster, and clipRef. When updating markers, the markers you specify are normally added to any existing markers unless you specify <markers replace=”true”>…</markers>
- When updating an existing clip you can specify how to combine the new value for certain elements (<notes>, <bigNotes>, and <field>) with the existing value by adding a merge attribute with values: “replace” (overwrite the old value), “prepend” (prepend the new value to an existing value), append (append the new value), “default” or “true” (don’t overwrite an existing value but set it with new value if it is currently not set), and “merge” or “combine” (split the values into lines and merge the two sets of lines). For example <notes merge=”true”>Under review</notes>
- You can have several <options> elements, each of which will apply to all subsequent clips in that file until the next <options> element is encountered.
- When importing clips via XML the import source is normally set to describe the XML file the clips were imported from. It is possible to override this by providing an <importSource> element and specifying <options importSource=”true”/>.