Final Cut Pro XML Interchange Format

You don't have the latest version of Adobe Flash Player.

Please update your flash player.

Please login or register to make a comment!

...Description...... more. less.

published in the United States and Canada. EventhoughApplehasreviewedthisdocument, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE.ASARESULT,THIS DOCUMENT IS PROVIDED c AS IS, d AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT,SPECIAL,INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESSORIMPLIED.NoAppledealer,agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights,andyoumayalsohaveotherrightswhich vary from state to state. Contents Chapter 1 About This Document 7 Organization 7 XML Resources 8 Chapter 2 About Interchange Format Documents 9 Exporting Documents 9 Importing Documents 10 Errors During Import 11 Chapter 3 Basics of the Final Cut Pro XML Interchange Format 13 Special Conventions 13 Inheritance 14 The id Attribute 14 Encoding a Clip 14 Associating Media With a Clip 16 Encoding Audio Information 18 Exporting a Clip from the Browser 19 Encoding a Subclip 20 Encoding a Multiclip 21 Encoding a Sequence 23 Format and Outputs 23 Media in a Sequence 25 Linking 27 Transitions 29 Encoding a Project 31 Encoding Effects 32 Keyframes 34 Managing Project Components 35 Managing QuickTime Metadata 36 Notes on the XML Interchange Format 38 Chapter 4 Applications of the Interchange Format 39 Enhancing a Batch List 39 Simplifying Subtitling 42 3 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Choosing Effect Parameters 46 Other Possibilities 51 Chapter 5 Elements of the Interchange Format 53 Major Elements 53 Clips 55 Video and Audio 61 Common Elements 65 Rate and Timecode 66 Effects 68 Application Specific Data 72 Film Data 74 QuickTime Metadata 76 Import Options 77 Appendix A Validating Documents 79 Using the DTDs 79 DTD for Version 1 of the Interchange Format 80 DTD for Version 2 of the Interchange Format 85 DTD for Version 3 of the Interchange Format 91 Appendix B Frame Rates 97 Appendix C Keyframe Interpolation 99 About Final Cut Pro Interpolation 99 Appendix D Apple Events and Final Cut Pro 103 Final Cut Pro Apple Events 104 Appendix E Versions of the Interchange Format 107 Version 1 107 Version 2 107 Version 3 108 Document Revision History 109 Index 111 4 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C O N T E N T S Figures, Tables, and Listings Chapter 2 About Interchange Format Documents 9 Figure 2-1 Export XML dialog 10 Figure 2-2 Final Cut Pro XML file icon 10 Figure 2-3 Import XML dialog 11 Chapter 3 Basics of the Final Cut Pro XML Interchange Format 13 Listing 3-1 A minimum clip 14 Listing 3-2 A clip with additional information 15 Listing 3-3 A clip with associated media 16 Listing 3-4 A clip using inheritance 17 Listing 3-5 A clip with timecode and media 17 Listing 3-6 Encoding audio information 18 Listing 3-7 An exported Browser clip 19 Listing 3-8 A subclip 20 Listing 3-9 A video multiclip 21 Listing 3-10 An empty sequence 23 Listing 3-11 Format information for a video track 24 Listing 3-12 Format information for an audio track 25 Listing 3-13 A sequence with a video track 25 Listing 3-14 An audio element with two tracks 26 Listing 3-15 The link element 27 Listing 3-16 The linkclipref element 28 Listing 3-17 A transition between video clips 29 Listing 3-18 A project 31 Listing 3-19 A gaussian blur effect 32 Listing 3-20 Radius parameter with keyframes and Bezier handles 34 Listing 3-21 Replacing a Clip in the Browser 35 Listing 3-22 Replacing a Clip in a Bin 36 Listing 3-23 Sample Metadata 37 Listing 3-24 Adding Metadata 37 Listing 3-25 Removing Metadata 38 Chapter 4 Applications of the Interchange Format 39 Figure 4-1 Multiple parameter variations in the Canvas 46 Listing 4-1 An enhanced batch list 39 5 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Listing 4-2 Subtitling 43 Listing 4-3 Effect parameter settings 47 Appendix A Validating Documents 79 Listing A-1 Version 1 DTD 80 Listing A-2 Version 2 DTD 85 Listing A-3 Version 3 DTD 91 Appendix B Frame Rates 97 Table B-1 Frames per second 97 Appendix C Keyframe Interpolation 99 Listing C-1 Acceleration coefficients 99 Listing C-2 Control points 100 Listing C-3 Locations 100 Listing C-4 Linear segments 101 Listing C-5 Bezier curve 101 6 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. F I G U R E S , T A B L E S , A N D L I S T I N G S The Final Cut Pro XML Interchange Format provides extensive access to the contents of Final Cut Proprojects,includingeditsandtransitions,effects,layer-compositinginformation,andorganizational structures. Using the interchange format, you can process project content in ways that supplement the capabilities of the Final Cut Pro application itself. You can also share Final Cut Pro information withotherapplicationsorsystemsthatsupportXML 4 includingnonlineareditors,assetmanagement systems, database systems, and broadcast servers. Important: FinalCutStudioincludestheFinalCutProapplicationandcompanionapplicationssuch as Cinema Tools, Compressor, DVD Studio Pro, Motion, and Soundtrack. Only the Final Cut Pro application itself supports the Final Cut Pro XML Interchange Format. The main body of this document describes version 3 of the Final Cut Pro XML Interchange Format. The appendix c Versions of the Interchange Format d (page 107) compares versions 1, 2, and 3 of the interchange format. This document assumes that you are familiar with XML conventions and with the Final Cut Pro 5 application. Organization This document contains the following chapters and appendixes: c About Interchange Format Documents d (page 9) discusses exporting, importing, and validating interchange format documents. c Basics of the Final Cut Pro XML Interchange Format d (page 13) reviews the key elements of the interchange format. c ApplicationsoftheInterchangeFormat d (page39)illustratessomeapplicationsoftheinterchange format to various tasks. c ElementsoftheInterchangeFormat d (page53)providesreferenceinformationabouttheelements of the interchange format. c Interchange Format DTDs d (page 79) lists the DTDs for versions 1, 2, and 3 of the interchange format. Organization 7 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 1 About This Document c Frame Rates d (page 97) indicates the values required to specify various types of video and associated frame rates. c Keyframe Interpolation d (page 99) explains the interpolation method Final Cut Pro uses to construct Bezier curves in keyframes. c Apple Events and Final Cut Pro d (page 103) discusses using Apple Events to export or import interchange format documents. c Versions of the Interchange Format d (page 107) details the differences between the various versions of the interchange format. c Document Revision History d (page 109) provides a history of changes to this document. This document also has an index. XML Resources Here are some recommended XML resources: XML In a Nutshell, Third Edition , published by O'Reilly, is a comprehensive reference guide on XML-related topics. ISBN 0-596-00764-7. XML From the Inside Out ( http://xml.com ) is a useful resource of XML-related information. On the Apple developer website, the document Core Foundation XML describes the Core Foundation objects you can use to parse XML. 8 XML Resources 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 1 About This Document Documents in the Final Cut Pro XML Interchange Format are stored on disk as plain text documents that you can view, parse, and edit on any platform. YoucanvalidateaninterchangeformatdocumentusinganinterchangeformatDTD.(See c Validating Documents d (page 79).) YoucanexportaninterchangeformatdocumentfromFinalCutPro,orimportaninterchangeformat document into Final Cut Pro, using either the Final Cut Pro user interface or, alternatively, Apple Events from an independent application. This chapter describes importing and exporting with the userinterface.ForinformationaboutusingAppleEventssee c AppleEventsandFinalCutPro d (page 103) Exporting Documents To export an interchange format document from Final Cut Pro: 1. Select an item in the Browser that you want to describe in an interchange format document. (If nothing is selected, a description of the entire contents of the Browser is exported.) 2. Choose File > Export > XML. 3. Check the Export XML dialog to make sure that the source for the interchange format document is correct. In Figure 2-1, the source is a single sequence. 4. Choose a file format for the document: XML Interchange Format, version 1 or version 2. (You can drag import files in XML format into Final Cut Pro.) 5. Ifclipsinyoursourcehavemasterclips,youcanselecttheoptiontoIncludeMasterClipsOutside Selection. 6. Click OK. 7. Enter a title for the interchange format document and choose a location. (You may want to use .xml as a suffix.) Exporting Documents 9 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 2 About Interchange Format Documents Figure 2-1 Export XML dialog Interchange format documents you export from Final Cut Pro have the Final Cut Pro XML file icon. Figure 2-2 Final Cut Pro XML file icon Importing Documents There are several ways you can import an interchange format document into Final Cut Pro. You can use the Import menu to import any interchange format document: 1. Choose File > Import > XML. 2. Navigate to the document, select it, and then click Choose. If the document file has a Final Cut Pro XML file icon, you can do any of the following: Double-click the document. Drag the document to the Final Cut Pro icon on the desktop or in the Dock. Use the Import menu. Atthetimeyouimportaninterchangeformatdocument,theImportXMLdialogappears(unlessyou use the importoptions element in the file). 10 Importing Documents 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 2 About Interchange Format Documents Figure 2-3 Import XML dialog The settings in this dialog are: Destination : Select an existing project as the destination of the import, or create a new project for the import. Sequence Settings: Select the default sequence settings for the import. To override the default settings with sequence settings in the import file, check the option "Override with settings from XML." Reconnect to Media Files: Select this option to tell Final Cut Pro to reconnect browser and sequence clips encoded in the file with associated media when possible. If you do not select this option, all imported clips are offline. Include Markers: Select this option to import any clip or sequence marker information encoded in the file. Include Audio/Video Effects: Select this option to import any encoded audio or video filters for Browser or sequence clips. This setting does not affect encoded audio or video transitions. Note: You can bypass the Import XML dialog and import a document directly into Final Cut Pro by using the element importoptions and its subelements. For details, see c Import Options d (page 77). Errors During Import When you import an interchange format document, Final Cut Pro first checks to make sure the documentiswell-formedandthatallrequiredelementsarepresent.Itthentranslatestheinterchange format document into Final Cut Pro components. IfFinalCutProfindscriticalerrorsduringimport,theinterchangeformatdocumentisnotimported. If noncritical errors occur, the document is imported, though the components constructed from the document may differ from your expectations. Importing Documents 11 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 2 About Interchange Format Documents Information about noncritical errors appears in an Final Cut Pro XML Error Log Window. (Note that youcansuppressthereportingofnoncriticalerrorsbysetting displaynoncriticalerrors to FALSE . See c Import Options d (page 77) In general, you should study error information about a document you are attempting to import, modifythedocument,andthenreimportit,continuingthisprocessuntilyoucanimportthedocument without errors. 12 Importing Documents 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 2 About Interchange Format Documents This chapter provides an introduction to the basic features of the Final Cut Pro XML Interchange Format. In particular, it explains how the interchange format can encode a clip, a sequence, a project, and an effect. Forexamplesofapplyingtheinterchangeformattospecifictasks,see c ApplicationsoftheInterchange Format d (page 39) For reference documentation about the elements of the interchange format, see c Elements of the Interchange Format d (page 53) Forinformationaboutthevariousversionsoftheinterchangeformat,see c VersionsoftheInterchange Format d (page 107). This chapter contains the following sections: c SpecialConventions d (page13)introducestheinheritanceand id conventionsoftheinterchange format. c Encoding a Clip d (page 14) shows how to encode a clip. c Encoding a Sequence d (page 23) details encoding a sequence. c Encoding a Project d (page 31) explains the requirements for encoding a project. c Encoding Effects d (page 32) looks at encoding effects. c ManagingProjectComponents d (page35)explainshowtoswapnewcomponentsintoaproject. c Managing QuickTime Metadata d (page 36) discusses QuickTime metadata in Final Cut Pro. c Notes on the XML Interchange Format d (page 38) provides information about some important details on the interchange format. Special Conventions The Final Cut Pro XML Interchange Format uses a set of special conventions beyond the base conventions of XML that affect how a document is parsed and translated when you import it into Final Cut Pro. These conventions 4 inheritance and the id attribute 4 make it possible to efficiently construct more concise interchange format documents. Special Conventions 13 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format Note: Interchange format documents you export from Final Cut Pro only use these conventions in certain circumstances. Inheritance Information for various components of a project is frequently redundant. For example, a sequence and its contents usually have the same frame rate; most clips share the same source media file across multiple tracks; multiple clips in a batch list are likely share the same Reel/Tape identifier, and so on. You can explicitly encode all the information for each component in a project. Alternatively, you can use the inheritance convention of the Final Cut Pro XML Interchange Format with certain elements to encode shared information just once. For example, you can encode a sequence and specify a frame rate of 29.97 fps for the sequence. Clips that are subelements of this sequence inherit this frame rate unless you specifically encode a different rate for a particular clip. An example of the inheritance convention appears in Listing 3-4 (page 17). The id Attribute The id attribute lets you share information between certain "peer" elements 4 elements that are not in an element/subelement relationship with each other. If an element provides an id attribute, Final Cut Pro registers this element in a reference table during import and translation. Then, during subsequent translation, other elements can reference this registered information. Forexample,theclipinformationforavideotrackinasequencemaybeidenticaltotheclipinformation in an audio track in the same sequence. Rather than repeating this information for both tracks, you can encode it once and then reference the information using the id attribute. Note: Not all elements support the use of the id attribute. See c Elements of the Interchange Format d (page 53) for information about the id attribute for specific elements. An example of the id convention appears in Listing 3-14 (page 26). Encoding a Clip Acliprepresentsavirtualpieceoftime-basedmedia.A clip elementhasthreerequiredsubelements: name , duration , and rate . (When a clip appears in a sequence, you also need to specify start and end subelements.) Listing 3-1 shows an example of a minimum clip: Listing 3-1 A minimum clip // 1 <?xml version="1.0" encoding="UTF-8"?> // 2 <!DOCTYPE xmeml> // 3 <xmeml version="3"> <clip> 14 Encoding a Clip 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <name>Jeremy Solo</name> // 4 <duration>188</duration> // 5 <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> </clip> </xmeml> Note: The Final Cut Pro application uses the internal name xmeml for the Final Cut Pro XML Interchange Format. Lines numbered 1 and 2 are the prolog section. Line numbered 1 declares the version of XML and the text encoding; line numbered 2 the document type. Line numbered 3 is the start tag for the root element xmeml that contains all the other elements in an interchange format document. The version attribute in this start tag specifies the version of the Final Cut Pro XML Interchange Format. At line numbered 4, the duration element encodes the total number of frames in the clip. This value does not change even if you set In and Out points for the clip using the in and out elements. (It is the equivalent of the Length timing property, rather than the Duration property.) At line numbered 5, the rate element defines the frame rate for the clip 4 in this case, an NTSC clip with a framerateof 29.97 fps. Notethat this framerateis specified using the ntsc subelement, which takes a Boolean value, and the timebase subelement, which takes an integer value ( 30 ). The NTSC frame rate variant is defined as a 0.01 percent reduction in frame rate. The actual mathematical value of this variant is 29.970029970029... (repeating). The decimal 29.97 is not an accurate representation of this number. Using an interger and an NTSC indicator flag allows any application to process the rate information in its own manner. See Table B-1 (page 97) for a complete listing of the possible settings for timebase and ntsc . Listing 3-2 shows a clip with more information, including In and Out points, master clip, logging, label, and comment information. Listing 3-2 A clip with additional information <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <clip> <name>Jeremy Solo</name> <duration>188</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <in>14</in> <out>149</out> // 1 <masterclipid>Jeremy Solo</masterclipid> // 2 <ismasterclip>true</ismasterclip> <logginginfo> <description>solo male</description> <scene>ballroom</scene> <shottake>Shot1/Take1</shottake> <lognote>LogNote1</lognote> <good>TRUE</good> Encoding a Clip 15 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format </logginginfo> <filmdata> . . . </filmdata> <labels> <label>Good Take</label> <label2>Label 2 (1)</label2> </labels> <comments> <mastercomment1>MC1</mastercomment1> <mastercomment2>MC2</mastercomment2> <mastercomment3>MC3</mastercomment3> <mastercomment4>MC4</mastercomment4> <clipcommenta>CommentA</clipcommenta> <clipcommentb>CommentB</clipcommentb> </comments> </clip> </xmeml> At line numbered 1, the masterclipid element provides the name of the master clip. At line numbered 2, the ismasterclip element indicates whether or not a clip is a master clip. (In this case, it is.) For details about the other elements in this listing, see the reference information in c Elements of the Interchange Format d (page 53). Check the index to locate a particular element. Associating Media With a Clip To associate media with a clip, you use the file element. Listing 3-3 shows a clip associated with a media file. Listing 3-3 A clip with associated media <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <clip id ="Jeremy Solo"> <name>Jeremy Solo</name> <duration>188</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <file id="Jeremy Solo1"> <name>Jeremy Solo1</name> // 1 <pathurl>file://localhost/Jeremy%20Solo</pathurl> // 2 <rate> <timebase>30</timebase> <ntsc>TRUE</ntsc> </rate> // 3 <duration>188</duration> </file> </clip> </xmeml> 16 Encoding a Clip 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format At line numbered 1, the pathurl element specifies the location of the media. Note that the name of the file includes a space character encoded with %20 . At lines numbered 2 and 3, the rate and duration subelements are required for the file element. However, because they are specified earlier in the document by the parent element, the file element can inherit this information . Listing 3-4 shows how this works. Listing 3-4 A clip using inheritance <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <clip id ="Jeremy Solo"> <name>Jeremy Solo</name> <duration>188</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <file id="Jeremy Solo1"> <name>Jeremy Solo1</name> <pathurl>file://localhost/Jeremy%20Solo</pathurl> </file> </clip> </xmeml> Note: Somesubelementsmaybeinherited,othersmaynot. c ElementsoftheInterchangeFormat d (page 53) indicates if a subelement can be inheritied or not. The file elementcanalsohaveoptionalsubelements: timecode and media .Listing3-5isanexample. Listing 3-5 A clip with timecode and media <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <clip id ="Jeremy Solo"> <name>Jeremy Solo</name> <duration>188</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <file id="Jeremy Solo1"> <name>Jeremy Solo1</name> <pathurl>file://localhost/Jeremy%20Solo</pathurl> // 1 <timecode> <string>02:42:35;14</string> <frame>292372</frame> <displayformat>DF</displayformat> <source>source</source> <reel> <name>002</name> </reel> </timecode> // 2 <media> Encoding a Clip 17 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <video> <duration>188</duration> <samplecharacteristics> <width>720</width> <height>480</height> </samplecharacteristics> </video> </media> </file> </clip> </xmeml> Atlinenumbered1,the timecode elementencodesthemediastartingpoint.Itincludesthesubelements string , which specifies the starting timecode in SMPTE format; frame , which specifies the starting frame count; and displayformat , which specifies drop frame or non-drop frame format. Note that either the element string , or the elements frame and format are required, but not all three. Other subelements include source , which categorizes the timecode as a source timecode from the tape, and reel . At line numbered 2, the media element encodes information about the media, including the height and width in pixels. Encoding Audio Information Media can also include audio tracks. You use the audio element to specify information about these tracks, as seen in Listing 3-6 . Listing 3-6 Encoding audio information <file> <name>myFile.mov</name> <pathurl> file://localhost/myFile.mov</pathurl> <rate> <timebase>24</timebase> <ntsc>TRUE</ntsc> </rate> <duration>3671</duration> <media> <video>...</video> // 1 <audio> <samplecharacteristics> <samplerate>48000</samplerate> <depth>16</depth> </samplecharacteristics> <layout>stereo</layout> <channelcount>2</channelcount> <audiochannel> <channellabel>right</channellabel> </audiochannel> <audiochannel> <channellabel>left</channellabel> </audiochannel> </audio> // 2 <audio> <samplecharacteristics> 18 Encoding a Clip 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <samplerate>48000</samplerate> <depth>16</depth> </samplecharacteristics> <channelcount>2</channelcount> </audio> </media> </file> At line numbered 1, the first stereo audio track is encoded. It has two channels. The first channel is specifiedastherightchannel,thesecondastheleftchannel.(Thisisthereverseofthedefaultsettings.) At line numbered 2, the second audio track in the media is encoded. When layout is not specified, stereo is assumed See c Elements of the Interchange Format d (page 53) for more information about the subelements used to encode audio information. Exporting a Clip from the Browser WhenyouexportasingleclipfromtheBrowser,theresultinglistingincludesthe media elementwith track information. Listing 3-7 shows excerpts from such an export. Listing 3-7 An exported Browser clip <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <clip id="Jeremy Solo"> // 1 <uuid>970C270C-8692-4E6A-A58C-F378CC3EB776</uuid> <updatebehavior>add</updatebehavior> <name>Jeremy Solo</name> <duration>188</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> // 2 <in>14</in> <out>149</out> <masterclipid>Jeremy Solo</masterclipid> <logginginfo> <good>FALSE</good> </logginginfo> <media> // 3 <video> // 4 <track> // 5 <clipitem> <name>Jeremy Solo</name> <duration>188</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <enabled>TRUE</enabled> <anamorphic>FALSE</anamorphic> <alphatype>none</alphatype> Encoding a Clip 19 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <file id="Jeremy Solo1"> . . . </file> <sourcetrack> <mediatype>video</mediatype> </sourcetrack> </clipitem> <enabled>TRUE</enabled> <locked>FALSE</locked> </track> </video> </media> </clip> </xmeml> Atlinenumbered1,the uuid elementandthe updatebehavior elementinthenextlineletyoumanage projectcomponents.See c ManagingProjectComponents d (page35).Youcanalsouse updatebehavior to manage QuickTime metadata. See c Managing QuickTime Metadata d (page 36). At line numbered 3, the video element identifies the type of media. At line numbered 4, the track element starts the encoding for the first (and only) track in the media. Atlinenumbered5,the clipitem elementencodesinformationthatisspecifictotheassociatedmedia. Encoding a Subclip YoucouldusetheclipencodedinListing3-7togenerateasubclip.Listing3-8showstheresults(with some details omitted). Listing 3-8 A subclip <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <clip id="Jeremy Solo Subclip"> <name>Jeremy Solo Subclip</name> // 1 <duration>135</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> // 2 <in>-1</in> <out>-1</out> <masterclipid>Jeremy Solo Subclip</masterclipid> . . . <media> <video> <track> <clipitem> <name>Jeremy Solo Subclip</name> <duration>135</duration> . . . <in>0</in> <out>135</out> 20 Encoding a Clip 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <start>0</start> <end>135</end> // 3 <subclipinfo> <startoffset>14</startoffset> <endoffset>39</endoffset> </subclipinfo> . . . <file id="Jeremy Solo"> . . . <media> <video> // 4 <duration>188</duration> <samplecharacteristics> <width>720</width> <height>480</height> </samplecharacteristics> </video> </media> </file> <sourcetrack> <mediatype>video</mediatype> </sourcetrack> </clipitem> <enabled>TRUE</enabled> <locked>FALSE</locked> </track> </video> </media> </clip> </xmeml> At line numbered 1, the duration of the subclip is 135 . At line numbered 2, the values for in and out are 3 1 , indicating that no In and Out points are set. At line numbered 3, the subclipinfo element indicates the starting offset and ending offset for the subclip.Thesevaluesareoffsetsinframesfromthemediastartandmediaendoftheassociatedmedia file, calculated using the in and out points for the clip from which the subclip was generated. (See Listing 3-7, line numbered 1.) At line numbered 4, the value for the duration element for the media associated with the subclip remains at 188 , compared to the value of 135 at line numbered 2. Encoding a Multiclip Multiclips let you group multiple camera angle clips together and switch or cut between angles in real time. You can also make a multiclip with multiple audio tracks. A video multiclip is represented by Listing 3-9. Listing 3-9 A video multiclip <clip id="Billiards1"> <name>Billiards1</name> <duration>2700</duration> <rate> Encoding a Clip 21 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <in>-1</in> <out>-1</out> <ismasterclip>FALSE</ismasterclip> <media> <video> <track> <clipitem> <name>Billiards1</name> <duration>2700</duration> . . . // 1 <multiclip id="Multiclip 1 "> <name>Multiclip 1</name> <collapsed>FALSE</collapsed> <synctype>1</synctype> // 2 <angle> <activevideoangle>TRUE</activevideoangle> <activeaudioangle>TRUE</activeaudioangle> <clip id="Billards1"/> </angle> <angle> <clip id="Billiards2"> <name>Billiards2</name> <duration>2700</duration> . . . // 3 <defaultangle>2</defaultangle> </clip> </angle> <angle> <clip id="Billiards3"> <name>Billards3</name> <duration>2700</duration> . . . <defaultangle>3</defaultangle> </clip> </angle> </multiclip> // 4 <mediadelay>900</mediadelay> </clipitem> <enabled>TRUE</enabled> <locked>FALSE</locked> </track> </video> </media> </clip> At line numbered 1, the multiclip element is a subelement of clipitem . It has two required subelements: name and angle .Othersubelementsinclude collapsed ,whichindicatesifthemulticlip is collapsed or not, and synctype , which spcifies how the the angles in the muticlip should be synchronized. 22 Encoding a Clip 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format At line numbered 2, the angle element includes the optional subelements activevideoangle and activeaudioangle . These take Boolean values ( TRUE or FALSE ) and indicate whether an angle is activeornot.(Onlyoneangleinamulticlipcanbeactiveatatime.)Iftheseelementsarenotspecificed inanangle,thedefaultsettingsarefalse.Ifnoanglesinamulticlipareencodedwiththesesubelements, the first angle is assumed to be the active angle. Atlinenumbered3,theelement defaultangle isusedforclipsintheBrowser.Itencodesidentifying information (a number or a letter) about the camera angle. Atlinenumbered4,theelement mediadelay isasubelementof clipitem .Itshiftsthemulticlipsync point from the start of the clip item to the specified delay. Encoding a Sequence To encode a sequence in the Final Cut Pro XML Interchange Format, you use the sequence element. You specify subelements for the name of the sequence, the duration, the frame rate, and the starting timecode. You also use the media element to encode subelements for the video and audio tracks. Listing 3-10 shows an empty sequence with one video track and two audio tracks. Listing 3-10 An empty sequence <?xml version="1.0" encoding="UTF-8"?> <xmeml version="3"> <sequence> <name>Sequence 1</name> <duration></duration> <rate>. . .</rate> <timecode>. . .</timecode> <media> <video> // 1 <format></format> <track></track> </video> <audio> // 2 <format></format> // 3 <outputs></outputs> <track></track> <track></track> </audio> </media> </sequence> </xmeml> Format and Outputs At lines numbered 1 and 2, the format element in Listing 3-10 encodes information about the video and audio media, while, at line numbered 3, the outputs element encodes information about the audio media. These elements and their subelements are equivalent to the sequence settings in Final Cut Pro. Encoding a Sequence 23 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format Listing 3-11 shows sample format information for a video track. See c Elements of the Interchange Format d (page 53) for details about the elements displayed here. Listing 3-11 Format information for a video track <video> <format> <samplecharacteristics> <width>720</width> <height>480</height> <anamorphic>FALSE</anamorphic> <pixelaspectratio>NTSC-CCIR-601</pixelaspectratio> <fielddominance>lower</fielddominance> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <colordepth>24</colordepth> <codec> <name>Apple DV - NTSC</name> <appspecificdata> <appname>Final Cut Pro</appname> <appmanufacturer>Apple Computer, Inc.</appmanufacturer> <appversion>4.0</appversion> <data> // 1 <qtcodec> . . . </qtcodec> </data> </appspecificdata> </codec> </samplecharacteristics> <appspecificdata> <appname>Final Cut Pro</appname> <appmanufacturer>Apple Computer, Inc.</appmanufacturer> <appversion>4.0</appversion> <data> // 2 <fcpimageprocessing> <useyuv>TRUE</useyuv> <usesuperwhite>FALSE</usesuperwhite> <rendermode>YUV8BPP</rendermode> </fcpimageprocessing> </data> </appspecificdata> </format> . . . </video> At line numbered 1, the qtcodec element provides information (omitted) about a QuickTime codec. At line numbered 2, the fcpimageprocessing element encodes details about image processing settings. Listing 3-12 shows sample format and outputs information for an audio track. 24 Encoding a Sequence 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format Listing 3-12 Format information for an audio track <audio> <format> // 1 <samplecharacteristics> <depth>16</depth> <samplerate>48000</samplerate> </samplecharacteristics> </format> // 2 <outputs> <group> <index>1</index> <numchannels>2</numchannels> <downmix>4</downmix> <channel> <index>1</index> </channel> <channel> <index>2</index> </channel> </group> </outputs> Atlinenumbered1,the samplecharacteristics elementencodesinformationabouttheaudiodepth and sample rate. At line numbered 2, the outputs element specifies information about the audio output settings. Media in a Sequence To add media to a sequence, you use a clipitem subelement in the track element. Listing 3-13 A sequence with a video track <sequence id = "Sequence 1"> . . . <media> <video> <format> . . . </format> <track> <clipitem id = "Seq1Clip1"> <name>Rob Dialog</name> <duration>751</duration> // 1 <in>0</in> <out>751</out> // 2 <start>0</start> <end>751</end> . . . <file id = "Rob Dialog"> <name>Rob Dialog</name> <pathurl>. . .</pathurl> <duration>751</duration> . . . </file> Encoding a Sequence 25 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format // 3 <sourcetrack> <mediatype>video</mediatype> <trackindex>1</trackindex> </sourcetrack> </clipitem> </track> </video> </media> . . . </sequence> A clipitem encoded in a track is similar to a clip in the Browser. It has a name, duration, timecode, associated media file, and so on. At line numbered 1, it has in and out subelements that indicate the portion of the source media file to reference. At line numbered 2, it has start and end subelements that specify the relative position of the clip in the parent sequence. At line numbered 3, the sourcetrack element indicates the media track to use in the source media file; in this case, video track 1. To encode the stereo audio that goes with this video clip, you use an audio element and the first two track subelements within it.12 Listing 3-14 An audio element with two tracks <sequence id = "Sequence 1"> . . . <media> <video> <format> . . . </format> <track> // 1 <clipitem id = "Seq1Clip1"> <name>Rob Dialog</name> <duration>751</duration> <in>0</in> <out>751</out> <start>0</start> <end>751</end> <file id = "Rob Dialog"> . . . </file> . . . </clipitem> </track> </video> // 2 <audio> <format> . . . </format> <outputs> . . . </outputs> 26 Encoding a Sequence 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <track> // 3 <clipitem id = "Seq1Clip1"> // 4 <file id = "Rob Dialog"/> // 5 <sourcetrack> <mediatype>audio</mediatype> <trackindex>1</trackindex> </sourcetrack> </clipitem> </track> // 6 <track> <clipitem id = "Seq1Clip1"> <file id = "Rob Dialog"/> <sourcetrack> <mediatype>audio</mediatype> <trackindex>2</trackindex> </sourcetrack> </clipitem> </track> </audio> </media> . . . </sequence> At line numbered 2, you have the start tag of the audio element. At line numbered 3, you can reference the id attribute specified earlier at line numbered 1. See c The id Attribute d (page 14). You don't have to repeat all the information for duration, the in and out points, and so on. At line numbered 4, you can reference the id attribute for the media file and then override the source track information at line numbered 5. You are using the same source media that you used for the video track, but are now referencing audio track 1. Starting at line numbered 6, you can construct the information for the second audio track in the same manner. Linking With the video track and the two audio tracks encoded, you now need to link the tracks together so thattheyaremanagedasasinglecomponentwithinthesequence.Youdothisusingthe link element. Listing 3-15 The link element <media> <video> <format> ... </format> <track> <clipitem id = "Seq1Clip1"> <name>Rob Dialog</name> <duration>751</duration> <in>0</in> <out>751</out> <start>0</start> <end>751</end> . . . // 1 <link> <mediatype>video</mediatype> Encoding a Sequence 27 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <trackindex>1</trackindex> <clipindex>1</clipindex> </link> <link> <mediatype>audio</mediatype> <trackindex>1</trackindex> <clipindex>1</clipindex> <groupindex>1</groupindex> </link> <link> <mediatype>audio</mediatype> <trackindex>2</trackindex> <clipindex>1</clipindex> <groupindex>1</groupindex> </link> <file id = "Rob Dialog"> . . . </file> </clipitem> </track> </video> <audio> <format> . . . </format> <outputs> . . . </outputs> <track> <clipitem id = "Seq1Clip1"> <file id = "Rob Dialog"> . . . </file> </clipitem> </track> <track> <clipitem id = "Seq1Clip1"> <file id = "Rob Dialog"> . . . </file> </clipitem> </track> </audio> </media> The link information always appears in the first track in the group of tracks that you are linking together. Here, this is the video track at line numbered 1, which is linked with the two audio tracks. Since the two audio clips use the id convention to reference the contents of the video clip, all three clips use the same link information. Alternatively, you can link tracks together using the id attribute and the linkclipref element. Listing 3-16 The linkclipref element <media> <video> <format> . . .</format> <track> <clipitem id = "Seq1Clip1v"> <name>Clip 001</name> <duration>751</duration> <in>0</in> 28 Encoding a Sequence 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <out>751</out> <start>0</start> <end>751</end> <link> // 1 <linkclipref>Seq1Clip1v</linkclipref> </link> <link> // 2 <linkclipref>Seq1Clip1a1</linkclipref> <groupindex>1</groupindex> </link> <link> // 3 <linkclipref>Seq1Clip1a2</linkclipref> <groupindex>1</groupindex> </link> <file id = "Rob Dialog"> . . . </file> </clipitem> </track> </video> <audio> <format> . . . </format> <outputs> . . . </outputs> <track> <clipitem id = "Seq1Clip1a1"> <file id="Rob Dialog"/> </clipitem> </track> <track> <clipitem id = "Seq1Clip1a2"> <file id="Rob Dialog"/> </clipitem> </track> </audio> </media> Note that you cannot use linkclipref for multiple clips in a track with the same ID. Transitions A sequence usually includes transitions between video clips you can encode with a transitionitem element. Listing 3-17 shows an example of a sequence with a single video track with a transition between two clips. Listing 3-17 A transition between video clips <sequence> <name>Sequence 1</name> <duration>243</duration> . . . <media> <video> <format> . . . </format> <track> <clipitem> Encoding a Sequence 29 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <name>Bloomies</name> <duration>248</duration> <in>74</in> // 1 <out>227</out> <start>0</start> // 2 <end>-1</end> <file id = "Bloomies1"> <duration>248</duration> . . . </file> . . . </clipitem> // 3 <transitionitem> <rate>. . .</rate> <start>123</start> <end>153</end> <alignment>center</alignment> // 4 <effect> <name>Cross Dissolve</name>  </effect> </transitionitem> <clipitem> <name>Jeremy Solo</name> <duration>188</duration> // 5 <in>36</in> <out>156</out> // 6 <start>-1</start> <end>243</end> <file id = "Jeremy Solo"> <duration>188</duration> . . . </file> . . . </clipitem> </track> </video> </media> </sequence> At line numbered 3, the transitionitem element encodes the start and end of the transition. At line numbered 4, the effect subelement determines the specific transition that is used. See c Encoding Effects d (page 32) for a discussion of effects. In the Viewer, the Out point for the first clip in the sequence (Bloomies) was set at 212 . Note that at line numbered 1, the Out point is extended to 227 to provide additional frames for input into the transition effect. In a similar fashion, the In point for the second clip (Jeremy Solo) at line numbered 5 is changed to 36 from its original setting of 51 . Also, because the end time for the first clip now dependsonthenextiteminthesequence,the end elementatlinenumbered2issetto 3 1 .Thisindicates thatthevalueshouldbecomputed.Similarly,the start elementfor thesecondclip atlinenumbered 6 is set to 3 1 . 30 Encoding a Sequence 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format Encoding a Project Listing 3-18 shows skeleton XML for a Final Cut Pro project that has two bins and one sequence. Listing 3-18 A project <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> // 1 <project> <name>Swing</name> // 2 <children> // 3 <bin> <name>Audio</name> // 4 <children> <clip id="Jumptown.aif"> <name>Jumptown.aif</name> . . . </clip> </children> </bin> // 5 <sequence id="Dance"> <name>Dance</name> . . . </sequence> // 6 <bin> <name>Video</name> <children> <clip id="Bloomies"> <name>Bloomies</name> . . . </clip> <clip id="Jeremy Solo"> <name>Jeremy Solo</name> . . . </clip> <clip id="Johnny n Cari"> <name>Johnny n Cari</name> . . . </clip> <clip id="Overhead"> <name>Overhead</name> . . . </clip> <clip id="Rob Dialog"> <name>Rob Dialog</name> . . . </clip> <clip id="Round n Round"> <name>Round n Round</name> . . . </clip> </children> </bin> </children> Encoding a Project 31 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format </project> </xmeml> Atlinenumbered1,the project start-taginitiatestheencodingfortheproject.Thenextlinespecifies the name of the project ( Swing ). At lines numbered 2 and 4, the required children elements enclose elements in a project or bin. At line numbered 3, the first bin ( Audio ) is encoded. It contains a single audio clip. Atlinenumbered5,thesequence( Dance )isencoded.Notethata children subelementisnotspecified. At line numbered 6, the second bin ( Video ) is encoded. In contains six clips. Encoding Effects Effects in Final Cut Pro are generally categorized as transition effects or filter effects. You encode an effect using either the transitionitem or filter element, and the effect subelement. Listing 3-17 at lines numbered 3 and 4 shows a skeleton example of a transition effect (a cross dissolve). Listing 3-19 shows the encoding for a filter effect (a gaussian blur). Listing 3-19 A gaussian blur effect <filter> <start>-1</start> <end>-1</end> <effect> // 1 <name>Gaussian Blur</name> // 2 <effectid>Gaussian Blur</effectid> <effectcategory>Blur</effectcategory> // 3 <effecttype>filter</effecttype> // 4 <mediatype>video</mediatype> <parameter> // 5 <parameterid>channel</parameterid> <name>Channel</name> <valuemin>1</valuemin> <valuemax>7</valuemax> // 6 <valuelist> <valueentry> <name>Alpha+RGB</name> <value>1</value> </valueentry> <valueentry> <name>Alpha</name> <value>2</value> </valueentry> <valueentry> <name>RGB</name> <value>3</value> </valueentry> <valueentry> <name>Red</name> <value>4</value> </valueentry> 32 Encoding Effects 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format <valueentry> <name>Green</name> <value>5</value> </valueentry> <valueentry> <name>Blue</name> <value>6</value> </valueentry> <valueentry> <name>Luminance</name> <value>7</value> </valueentry> </valuelist> // 7 <value>1</value> </parameter> <parameter> <parameterid>radius</parameterid> <name>Radius</name> <valuemin>0</valuemin> <valuemax>100</valuemax> // 8 <value>2</value> </parameter> </effect> </filter> At lines numbered 1 and 2, either the element name or the element effectid is required to identify aparticulareffect.Theelement effectid islanguageindependent.Theelement name maybelocalized, dependingontheapplicationgeneratingthedocument.(Whenparsinginstalledeffects,applications should look first at effectid and use name as a fallback if no matching effect is found.) Atlinesnumbered3and4,bothelements effecttype and mediatype arerequiredinordertoprovide the application parsing the document with enough information to correctly identify the effect, or to mapittoareasonablesubstitute.(The mediatype elementalsoallowsinheritedeffectstobepropagated to the correct type of track or clip.) Thegaussianblureffecthastwoparameters: channel and radius .Bothparametersuse parameterid and name . The element parameterid is language independent, while name can be localized. At line numbered 5, the channel parameter is a pop-up list with seven choices. At line numbered 6, the valuelist element encodes the names and ordinal value of each of these choices. The encoding for the actual selection from the list occurs at line numbered 7, where value is set to 1 . Alternatively, you can use the name of the pop-up list choice for the value element ( <value>Alpha+RGB</value> ). Encoding Effects 33 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format Important: The valuelist element is not required for import. When you export an effect with a pop-up list parameter, valuelist provides a convenient summary of the pop-up options. In general, this document does not provide detailed information about effects and their parameters in the Final Cut Pro XML Interchange Format. To see the interchange format details for an effect, you can apply the effect to a clip and then export that clip in XML. Keyframes Atlinenumbered8inListing3-19,the radius parameterisencodedwithastaticvalueof 2 .Suppose, however,thatyouwanttousekeyframestomodifytheeffectovertime.(Akeyframeisacombination of a time value and optional curve or interpolation information.) Listing 3-20 shows the radius parameter encoded with three keyframe elements, which replace the value element at line numbered 7 in Listing 3-19. To "smooth out" the behavior of the effect, you can add Bezier handles for the last two keyframe elements. Listing 3-20 Radius parameter with keyframes and Bezier handles <parameter> <parameterid>radius</parameterid> <name>Radius</name> // 1 <interpolation> <name>FCPCurve</name> </interpolation> // 2 <keyframe> <when>35</when> <value>5</value> </keyframe> // 3 <keyframe> <when>50</when> <value>17</value> <inscale>0</inscale> <inbez> <horiz>9.5</horiz> <vert>3.14159</vert> </inbez> <outscale>0</outscale> <outbez> <horiz>9.5</horiz> <vert>0</vert> </outbez> </keyframe> // 4 <keyframe> <when>88</when> <value>4</value> <inscale>0</inscale> <inbez> <horiz>9.5</horiz> <vert>-3.14159</vert> </inbez> </keyframe> </parameter> 34 Encoding Effects 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format Atlinenumbered1,the interpolation elementidentifiestheinterpolationmethodforthekeyframes. Since this clip is for use in Final Cut Pro, the interpolation method is FCPCurve . See c Keyframe Interpolation d (page 99) for details of the Final Cut Pro interpolation method. At line numbered 2, the encoding for the first keyframe sets when at 35 and value at 5 . At line numbered 3, the second keyframe includes information for a Bezier handle that is specific to the FCPCurve format. It consists of an offset ( inbez and outbez ) and a magnitude ( inscale and outscale ). At line numbered 4, note that the last keyframe has a one-sided Bezier handle. You can also set the range of an effect. By default, an effect uses the in and out values from its parent clip. The effect modifies the media within this range. You can alter this by encoding specific start and end points for filter or transitionitem . Managing Project Components Version 3 of the Final Cut Pro XML Interchange Format adds the ability to modify or update open projects using two new elements for clips, sequences, and bins: uuid and updatebehavior . The uuid element uniquely and persistently identifies individual components in a project. Since it is saved with the project file, you can use it to track detailed changes during your workflow. Important: A uuid entryisonlyguaranteeduniquenessonaperprojectbasis.Ifyoucopyaclipfrom oneprojecttoanother,the uuid entryfortheclipremainsthesame.Likewise,ifyouexportaclipand then import it into a different project, the uuid entry is unchanged. If you then modify the clip in one project, the clip in the other project has a matching UUID but is no longer identical. The UUID has ceased to be a unique identifier. The updatebehavior elementallowsyoutomodifyUUID-identifiedcomponentsinanopenproject. Thetargetcomponentinaprojectcanbeaclip,bin,orsequence.Aswell,youcanuse updatebehavior to modify metadata in a QuickTime file. (See c Managing QuickTIme Metadata d (page 36)) A target component is identified by its uuid entry. For example, here is a XML snippet that replaces a clip in the Browser: Listing 3-21 Replacing a Clip in the Browser <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <clip id="clip2 "> <uuid>7ACBD5FC-C166-40F9-AE36-55B39476D8E6</uuid> <updatebehavior>replaceiffound</updatebehavior>  </clip> Managing Project Components 35 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format When this snippet is imported, Final Cut Pro looks for a component in the project with a matching UUID. If it finds one, it replaces the component with the clip specified in the interchange format document. (In this case, the replacement clip appears at the topmost level of the Browser.) If it doesn 9 t find the target clip, nothing happens. To replace a clip in a bin, you have to specify the bin and all its contents. For example, Listing 3-22 replaces a clip in Bin 1. Listing 3-22 Replacing a Clip in a Bin <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <bin> <uuid>4FDDECFA-D312-4272-8DE8-BE98E4BA5F92</uuid> <updatebehavior>replaceiffound</updatebehavior> <name>Bin 1</name> <children> <clip id="clip2 "> <uuid>7ACBD5FC-C166-40F9-AE36-55B39476D8E6</uuid> <updatebehavior>add</updatebehavior>  </clip> </bin> Similarly, to replace a particular clipitem in a sequence, you must replace the entire sequence. The way you specify the location of the replacement component in the import document has precedence. For example, if the target clip is in Bin 1 and if you import a snippet such as Listing 3-21, FinalCutProremovestheclipfromBin1andputsthereplacementclipatthetopleveloftheBrowser. The desired behavior at the time of import is specified by the entry for updatebehavior . The valid entries are: replaceiffound Replaces the target component if found. If not found, does nothing. replaceoradd Replacesthetargetcomponentiffound.Ifnotfound,addstheimportedcomponent to the project. addifnotfound Adds the imported component to the project provided the target component is not found. If the target component is found, does nothing. add Adds the imported component to the project. If a component with the same uuid entry is present, changes the uuid entry of the imported object. remove Removes the target object if found. If not found, does nothing. Managing QuickTime Metadata Final Cut Pro 5.1.2 supports metadata in QuickTime files. When Final Cut Pro opens or re-reads a QuickTime file with metadata, it caches a copy of the metadata in the project. (The file is the authoritative source of the metadata; if the file changes, the cached copy changes.) 36 Managing QuickTime Metadata 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format To manage QuickTime metadata, version 3 of the Final Cut Pro XML Interchange Format provides the element metadata and its subelements. (See c QuickTime Metadata d (page 76).) With these new elements, you can display the metadata in a project by exporting an interchange format document. In additionl, you can actually modify the metadata in a QuickTime file by importing an interchange format document with appropriately specified elements. In Final Cut Pro, QuickTime metadata appears at the movie or track levels; that is, the parents of metadata can be file , video , or audio . Here is an XML fragment that displays some metadata at the movie level. Listing 3-23 Sample Metadata <file id="clouds"> <name>clouds</name> <pathurl>file://localhost/Users/. . .</pathurl> <rate> <timebase>8</timebase> </rate> <duration>91</duration> <metadata> <storage>QuickTime</storage> <key>com.mycompany.myapp.myid.mymd</key> <size>11</size> <type>UTF8</type> <value>My metadata</value> </metadata> <media> . . . When you import interchange format documents with metadata information, Final Cut Pro caches the imported metadata. However, when Final Cut Pro reconnects referenced QuickTime files to the project, the metadata in these files replaces the metadata you imported. You can permanently alter the metadata in a QuickTime file by using the element updatebehavior as a subelement of metadata . In this context, updatebehavior has two valid entries: add or remove . Here is an XML fragment using add . Listing 3-24 Adding Metadata <metadata> <updatebehavior>add</updatebehavior> <storage>QuickTime</storage> <key>com.mycompany.myapp.myid.mymd</key> <size>22</size> <type>UTF8</type> <value>My additional metadata</value> </metadata> Metadata in QuickTime files is stored as a key-value pair. In Listing 3-24, the value and the key are added to the metadata in the file. If the file already has an identical key, the imported value does not replace any existing values. Instead, the new value is stored alongside the existing values for that key. Note that a key is specified with a reverse-dns string to help ensure uniqueness. Using remove , on the other hand, does affect existing metadata in a file. Here is an example: Managing QuickTime Metadata 37 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format Listing 3-25 Removing Metadata <metadata> <updatebehavior>remove</updatebehavior> <storage>QuickTime</storage> <key>com.mycompany.myapp.myid.mymd</key> </metadata> Thisremovesthespecifiedkeyandallitsassociatedvaluesfromthefile.(Notethatitisnotnecessary to specify the subelements type , size , or value .) When you import an interchange format document with metadata specifications, Final Cut Pro first processes the specifications with remove , and then those with add . (This allows you to easily replace values for a particular key from a single import document.) Notes on the XML Interchange Format Here are some additional details about the Interchange Format. You cannot encode user interface information such as the size and position of a window, or the source and destination settings for a track, or the height of a sequence track. Transitions or filters in the Browser are not exported. If you export a sequence with a custom 3rd part transition and then import the sequence on a machine where the custom effect is not available, the system uses the default transition since the FXScript text for the custom transition is not exported. If you create a transition between two clips in a sequence, export the sequence, and then import it into the same project, the icon on the transition in the original sequence may lose its name. 38 Notes on the XML Interchange Format 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 3 Basics of the Final Cut Pro XML Interchange Format ThischapterdescribesthreetoolsbasedontheFinalCutProXMLInterchangeFormatthatdevelopers might create to help streamline certain postproduction tasks. It includes these sections: c Enhancing a Batch List d (page 39) shows how a batch list can include extra features usually associated with a "paper edit." c Simplifying Subtitling d (page 42) demonstrates how the time-consuming subtitling process can be simplified and made significantly more efficient. c Choosing Effect Parameters d (page 46) illustrates how an editor can more easily choose appropriate parameters for an effect. c Other Possibilities d (page 51) lists some other ideas for applications of the interchange format. Enhancing a Batch List A filmmaker may generate tens or hundreds of hours of footage during production. Frequently, this footage is logged into a word processor, spreadsheet, or database program. The filmmaker may then use this information to create a batch list for import into Final Cut Pro. Using the Final Cut Pro XML Interchange Format, a developer can create a simple tool that greatly enhances the capabilities of the traditional batch list, integrating into it many of the editing decisions usually expressed in a paper edit. For example, the tool can translate information from a spreadsheet fileintoaninterchangeformatdocumentthatrepresentsseparatedbinsofclips,predefinedsequences containing selected categories of clips, and even clips with effects already applied. Listing4-1showsabriefexampleofanenhancedbatchlistintheinterchangeformat.Inthisexample, there is a single bin with five offline clips. The logging information entered for each clip in the spreadsheet has also allowed the tool (at the user's request) to set up a sequence of all the clips of a couple dancing. Listing 4-1 An enhanced batch list <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE xmeml> <xmeml version="3"> <project> <name>EnhancedBatchList</name> <children> Enhancing a Batch List 39 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 4 Applications of the Interchange Format <bin> <name>Dance shots</name> <children> <clip id="Bloomies"> <name>Bloomies</name> <duration>248</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <logginginfo> <lognote>couple</lognote> </logginginfo> <timecode> <string>02:12:02;17</string> <source>source</source> <reel> <name>002</name> </reel> </timecode> </clip> <clip id="Jeremy Solo"> <name>Jeremy Solo</name> <duration>188</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <logginginfo> <lognote>solo male</lognote> <good>FALSE</good> </logginginfo> <timecode> <string>02:42:35;14</string> <source>source</source> <reel> <name>002</name> </reel> </timecode> </clip> <clip id="Johnny n Cari"> <name>Johnny n Cari</name> <duration>148</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <logginginfo> <lognote>couple</lognote> <good>FALSE</good> </logginginfo> <timecode> <string>02:41:42;10</string> <source>source</source> <reel> <name>002</name> </reel> </timecode> 40 Enhancing a Batch List 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 4 Applications of the Interchange Format </clip> <clip id="Overhead"> <name>Overhead</name> <duration>321</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <logginginfo> <lognote>group</lognote> <good>FALSE</good> </logginginfo> <timecode> <string>02:39:26;28</string> <source>source</source> <reel> <name>002</name> </reel> </timecode> </clip> <clip id="Round n Round"> <name>Round n Round</name> <duration>308</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <logginginfo> <lognote>couple</lognote> <good>FALSE</good> </logginginfo> <timecode> <string>02:12:18;07</string> <source>source</source> <reel> <name>002</name> </reel> </timecode> </clip> </children> </bin> <sequence id="Couples"> <name>Couples</name> <duration>704</duration> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <timecode> <rate> <ntsc>TRUE</ntsc> <timebase>30</timebase> </rate> <string>01:00:00;00</string> <frame>107892</frame> <source>source</source> <displayformat>DF</displayformat> </timecode> Enhancing a Batch List 41 2006-09-23 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. C H A P T E R 4 Applications of the Interchange Format <media> <video> <track> <clipitem> <name>Bloomies</name> <start>0</start> <end>248</end> <file id="Bloomies1"/> </clipitem> <clipitem> <name>Johnny n Cari</name> <start>248</start> <end>396</end> <file id="Johnny n Cari"/> </clipitem> <clipitem> <name>Round n Round</name> <start>396</start> <end>704</end> <file id="Round n Round"/> </clipitem> </track> </video> </media> </sequence> </children> </project> </xmeml> Simplifying Subtitling Using the capabilities of the Final Cut Pro XML Interchange Format and text generators, a developer can create a tool or suite of tools to help simplify and streamline the subtitling process. First, an editor completes the offline edit without subtitles. Then the editor adds a new slug video track and creates through edits at the points where the subtitling should change. For those parts of thevideowherenosubtitlingshouldappear,theeditordeletesthematchingportionoftheslugtrack. Theeditorthenexportsthesequenceintheinterchangeformat.Theslugtrackintheresultingdocument containsthestartandendinformationrequiredtocorrectlyspecifythestartandendofatextgenerator for each

less