Elements Catalog

This chapter describes all the elements of the Final Cut Pro XML Interchange Format.

Information about the elements of the Final Cut Pro Interchange Format is presented in the following sections:

Major Elements


xmeml
Description
Root element for an XML Interchange Format document.
Attribute
version (for example: version = "5")
Subelements
importoptions, project, bin, clip, sequence
Notes
You can encode multiple xmeml elements in a single document, as long as there is an xmeml document type declaration at the top of the file.


project
Description
Encodes a Final Cut Pro project.
Parent
xmeml
Subelements
+name, +children


bin
Description
Encodes a bin, a named container within a project.
Parents
xmeml, children
Subelements
+*name, +*children, *labels, *comments, uuid, updatebehavior


children
Description
Encloses a collection of elements within a bin or project.
Parents
bin, project
Subelements
clip, sequence, bin


sequence
Description
Encodes a collection of clips and generators sequenced in relation to each other by time, layer, and position.
Parents
xmeml, children, clipitem
Subelements
+name, +duration, +rate, in, out, *timecode, media, *marker, sequence, *labels, *comment, *masterclipid, *ismasterclip, *descriptionlogginginfo, filmdata, file, pixelaspectratio, uuid, updatebehavior
Attribute
id


media
Description
Encodes specific media tracks for a clip or a sequence.
Parents
clip, sequence, file
Subelements
*video, *audio


track
Description
Encodes data specific to one or more video or audio elements for a track.
Parents
video, audio
Subelements
*clipitem, *generatoritem, *transitionitem, enabled, locked, *outputchannelindex


locked
Description
A Boolean value specifying whether or not a track is locked.
Parent
track
Notes
If TRUE, the parent track is locked and cannot be modified in the Timeline. The default is FALSE.


outputchannelindex
Description
An integer specifying the output channel index for a track.
Parent
track


link
Description
Encodes a link between different clips in a sequence.
Parent
clipitem
Subelement
+linkclipref or (+mediatype, +trackindex, +clipindex, +groupindex)


linkclipref
Description
A string specifying a clip id attribute that encodes a link between sequence items sharing the same clip reference.
Parent
link
Notes
You cannot use linkclipref with multiple clips in a track with the same id.


clipindex
Description
An integer specifying the clip index.
Parent
link


groupindex
Description
An integer specifying the index of a group of audio outputs.
Parent
link
Notes
A groupindex element specifies a subset in an audio link array. (A video link should not have a groupindex subelement.) Items sharing a groupindex are part of a stereo pair. The groupindex should never exceed the number of audio items specified in the link array.


uuid
Description
A unique identifier.
Parents
clip, sequence, bin, itemhistory
Notes
Valid entries are in the standard UUID format. For the hex characters A through F, case is ignored. Note that UUID’s for clips, sequences, and bins are guaranteed to be unique only within a single project. If you copy or import a clip from one project to another, the uuid entry remains the same. Note also that the UUID element, which is a subelement of data, is distinct from uuid.


updatebehavior
Description
Allows an imported interchange format document to modify an open project or metadata in a QuickTIme file.
Parents
clip, sequence, bin, metadata
Notes
Valid entries are replaceiffound, replaceoradd, addifnotfound, add, remove. (Only add is a valid entry for PSD files and multiclips.) See “Managing Project Components” The default entry is add. If you use updatebehavior and add with a clip, and if there is clip with the same UUID already in the project, then Final Cut assigns a new UUID to the clip you’re importing.


itemhistory
Description
A list of UUIDs associated with a clipitem.
Parent
clipitem
Subelements
uuid
Notes
Final Cut generates a UUID for a clipitem when the item is first exported, and subsequently whenever the item is modified and exported again. The top UUID in the list is the current UUID for the item and is guaranteed to be unique. The rest of the list is a historical record of the UUIDs associated with the item. (The bottom UUID item in the list is the initial UUID generated for the clipitem or the UUID of the original item from which the current item was derived.). See “itemhistory”

Clips


clip
Description
Encodes a clip in the Browser.
Parents
xmeml, children
Subelements
+name, +duration, +rate, in, out, *masterclipid, *subclipmasterid, *ismasterclip, *logginginfo, *enabled, *file, *timecode, *media, marker, *anamorphic, *alphatype, *alphareverse, *labels, *comments, sourcetrack, *compositemode, subclipinfo, filter, stillframe, *stillframeoffset, *startoffset, *endoffset , defaultangle, subframeoffset, start, end, pixelaspectratio, filmdata, uuid, updatebehavior
Attribute
id


clipitem
Description
Encodes a clip in a track.
Parent
track
Subelements
+*name, +duration, +rate, +*start, +*end, link, syncoffset, *enabled, *in, *out, *masterclipid, *subclipmasterid, ismasterclip, *logginginfo, file, *timecode, *marker, *anamorphic, *alphatype, *alphareverse, *labels, *comments, sourcetrack, *compositemode, subclipinfo, *filter, stillframe, *stillframeoffset, *sequence, multiclip,mediadelay, subframeoffset, *mixedratesoffset,filmdata, pixelaspectratio, fielddominance, gamma, primarytimecode*itemhistory
Attribute
id
Notes
Note that start, end, link, syncoffset, and enabled are subelements of clipitem, but not of clip.


file
Description
Encodes a media file reference for use within a clip.
Parents
clip, clipitem
Subelements
+duration, +rate, +*name or +pathurl (or both), *timecode, *media, width, height, mediaSource
Attribute
id


pathurl
Description
A UTF-8 string specifying a pathname for a file.
Parent
file
Notes
A file referenced by pathurl must be on a local volume. The URL must start with file://localhost or file:///.
A character that is not a legal URL character according to the RFC 2396 standard needs to be escaped by writing it in hexadecimal notation preceded by the % character. (To process URL strings programmatically, you can use functions such as CFURLCreateStringByAddingPercentEscapes in the Carbon library.)


mediaSource
Description
A string describing a media source (such as a slug) built in to Final Cut Pro.
Parent
file


anamorphic
Description
A Boolean value characterizing a piece of video used in a track.
Parents
clip, clipitem, generatoritem, samplecharacteristics
Notes
If TRUE, video has a 16:9 aspect ratio. If FALSE, video has a 4:3 aspect ratio.


alphatype
Description
A string specifying the alpha mode for a clip.
Parents
clip, clipitem, generatoritem, media, video
Notes
Valid entries are none, straight, black, or white. Note that these entries are always in English, even for versions of Final Cut Pro in other languages.


alphareverse
Description
A Boolean value specifying whether or not Reverse Alpha is set.
Parents
clip, clipitem


compositemode
Description
A string specifying the composite mode for a clip.
Parents
clip, clipitem
Notes
Valid entries are normal, add, subtract, difference, multiply, screen, texturize, hardlight, softlight, darken, lighten, mask, or lumamask. Note that these entries are always in English, even for versions of Final Cut Pro in other languages.


masterclipid
Description
A string specifying the master clip id.
Parents
clip, clipitem, sequence
Notes
You do not have to encode a masterclipid element before you encode any affiliate clips. (In a sequence, all clips are affiliate or independent clips. Independent clips have no masterclipid element.)


subclipmasterid
Description
A string specifying the id of the parent clip for a subclip.
Parents
clip, clipitem, generatoritem


ismasterclip
Description
A Boolean value specifying whether or not a clip is a master clip.
Parents
clip, clipitem, sequence
Notes
If ismasterclip is not encoded, the clip is assumed to be an affiliate or independent clip.


logginginfo
Description
Encodes logging information for a clip.
Parents
clip, clipitem
Subelements
*description, *scene, *shottake, *lognote, *good, scenenote, shotnote, takenote


description
Description
A string describing a clip or sequence.
Parents
logginginfo, sequence


scene
Description
A string specifying a scene identifier or name for a clip.
Parent
logginginfo


shottake
Description
A string specifying a shot or take identifier.
Parent
logginginfo


lognote
Description
A string specifying the logging note for a clip.
Parent
logginginfo


good
Description
A Boolean value specifying the state for a clip.
Parent
logginginfo


scenenote
Description
A string with scene information from the Cinema Tools database.
Parent
logginginfo


shotnote
Description
A string with shot information from the Cinema Tools database.
Parent
logginginfo


takenote
Description
A string with take information from the Cinema Tools database.
Parent
logginginfo


labels
Description
Encodes Label and Label 2 information for a clip.
Parents
clip, clipitem, bin, sequence
Subelements
*label, *label2


label
Description
Specifies Label information for a clip.
Parent
labels
Notes
Since the user can modify label names in User Preferences, the system matches imported information for this element against the current Label settings in Final Cut Pro.


label2
Description
A string specifying Label 2 information.
Parent
labels


comments
Description
Encodes comment information for a clip.
Parents
clip, clipitem, bin, sequence
Subelements
*mastercomment[n], *clipcommenta, *clipcommentb
Notes
Four masterComment subelements, and two unique comment subelements are available.


mastercomment[n]
Description
A string specifying a master comment.
Parent
comments
Notes
Valid elements are mastercomment1 through mastercomment4. The mastercomment[n] element specifies text stored inside a clip definition. This information is shared between master and affiliate clips and is kept consistent if modified inside Final Cut Pro.


clipcommenta, clipcommentb
Description
A string specifying a unique clip comment.
Parent
comments
Notes
The elements clipcommenta and clipcommentb contain comment text stored inside a clip definition. This information is unique to each clip instance.


sourcetrack
Description
Encodes details of the media connected with a clip.
Parents
clip, clipitem, generatoritem
Subelements
mediatype, trackindex
Notes
The designated media can be a specific piece of media or a nested sequence with multiple types of media.


start
Description
An integer specifying the relative starting point for a clip in a track. (See “Timing Values.”)
Parents
clipitem, generatoritem
Notes
A value of -1 indicates that a clipitem in a sequence is preceeded by a transition. The actual value of start is computed from the beginning of the transition.


end
Description
An integer specifying the relative ending point for a clip in a track. (See “Timing Values.”)
Parents
clipitem, generatoritem
Notes
A value of -1 indicates that a clipitem in a sequence is followed by a transition. The actual value of end is computed from the end of the transition.


subclipinfo
Description
Encodes offset information for a subclip.
Parents
clip, clipitem
Subelements
*startoffset, *endoffset


startoffset
Description
An integer specifying the offset in frames from the start media value, calculated using the In point of the clip from which the subclip was created.
Parents
subclipinfo, clip, clipitem


endoffset
Description
An integer specifying the offset in frames from the end media value, calculated using the Out point of the clip from which the subclip was created.
Parents
subclipinfo, clip, clipitem


stillframe
Description
A Boolean value specifying whether or not a clip is a still frame.
Parents
clip, clipitem
Notes
Photoshop PSD files, jpeg files, tiff files, or other still images imported into Final Cut have stillframe set to TRUE.


stillframeoffset
Description
An integer specifying the offset in frames from the start media value to the frame to use as a freeze frame.
Parents
clip, clipitem


syncoffset
Description
An integer specifying the offset in frames from the beginning of the first track in a group of linked tracks that have been marked in sync.
Parents
clip, clipitem


multiclip
Description
Encodes a multiclip.
Parents
clipitem
Subelements
+name, +angle, collapsed, synctype


angle
Description
Encodes an angle is a multiclip.
Parents
multiclip
Subelements
activevideoangle, activeaudioangle, +clip


activevideoangle
Description
A Boolean value specifying if an angle is the active angle in a multiclip.
Parents
angle
Notes
Only one angle in a multiclip can be active at a time. Default setting is FALSE. If no angles are specified as active, the first angle is assumed to be the active angle.


activeaudioangle
Description
A Boolean value specifying if an angle is the active angle in a multiclip.
Parents
angle
Notes
Only one angle in a multiclip can be active at a time. Default setting is FALSE. If no angles are specified as active, the first angle is assumed to be the active angle.


collapsed
Description
A Boolean value specifying if a multiclip is collapsed or not.
Parents
multclip
Notes
Default is FALSE.


synctype
Description
An integer specifying the synchronizatrion for the multiclip.
Parents
multclip
Notes
Valid entries are 1 (In point), 2 (Out point), 3 (timecode), 4 (aux 1 timecode), and 5 (aux 2 timecode).


mediadelay
Description
Integer specifying the starting offset (in frames) for a clipitem used in a multiclip or subclip. (See Figure 4-3).
Parents
clipitem


defaultangle
Description
A string identifying the angle of a clip in the Browser.
Parents
clip


subframeoffset
Description
Specifies the offset when a track is slipped by less than a frame.
Parents
clip, clipitem


mixedratesoffset
Description
An integer specifying an offset for footage played at mixed rates
Parent
clipitem
Notes
In points are stored in the frame rate of a sequence. Before the introduction of mixedratesoffset in version 6 of Final Cut, this could cause problems. For example, if you edited a 60fps clip with an in point of 3 into a 30fps sequence, the in point became 1 and Final Cut played frame 2 instead of frame 3. Final Cut 6, however, uses mixedratesoffet to handle these mixed rates situations. In this example, the value of mixedratesoffset would be set to +1 and the sequence would play correctly from frame 3. Note that mixedratesoffset is only available in version 4 of xmeml.


gamma
Description
Number specifying the gamma setting for a still.
Parents
clipitem
Notes
Specifies a still gamma setting when a gamma setting is supported by the codec. The entry is a decimal with three digits of precision. The thousandths place is rounded up. For example, an entry of 1.2345 becomes 1.235. If gamma is unspecified, Final Cut Pro uses the source gamma setting.

Video and Audio


video
Description
Encodes data specific to video media.
Parent
media
Subelements
track, *duration, format, *samplecharacteristics, in, out, stillframe, *layerindex, *alphatype , trackcount (version 1 only)
Notes
Video data that you can encode for specific video tracks includes In and Out points, video format, and rate information.


layerindex
Description
An integer specifying a layer in source media such as a PhotoShop PSD file.
Parent
video
Notes
Valid entries are from 1 to the number of layers in the media.


audio
Description
Encodes data specific to audio media.
Parent
media
Subelements
*in, *out,track, format, outputs, *channelcount,channeldescription, rate, *samplecharacteristics,*duration, layout, audiochannel,trackcount (version 1 only)
Notes
Audio data that you can encode for specific audio tracks include In and Out points and audio format information.


channelcount
Description
An integer specifying the number of audio channels.
Parent
audio


trackcount
Description
For version 1 of the interchange format only. An integer specifying the number of tracks defined for the parent media type.
Parents
video, audio
Notes
The trackcount element is required when explicitly encoding the subelements of a file element where there is more than one track of a particular media type. It is optional for clips or sequences, where trackcount is implied by the number of track elements encoded.


channeldescription
Description
A string specifying the audio channels.
Parent
audio
Notes
Valid entries are mono, stereo, A1, A2, or A1+A2.


layout
Description
A string specifying the layout of an the audio channels.
Parent
audio
Notes
Valid entries are mono, and stereo. Default is stereo.


audiochannel
Description
Encodes information about an audio channel.
Parent
audio
Subelements
channellabel, sourcechannel


channellabel
Description
A string labelling the channel
Parent
audiochannel
Notes
Valid entries are left, right, and discrete.


sourcechannel
Description
An integer specifying the source channel.
Parent
audiochannel
Notes
Valid entries are 1 or greater.


outputs
Description
Encodes information about audio outputs.
Parent
audio
Subelement
*group
Notes
The information corresponds to the outputs tab of the sequence settings.


group
Description
Encodes information about a group of audio output channels.
Parent
outputs
Subelements
index, numchannels, downmix, channel


index
Description
An integer specifying the index of a group or channel.
Parents
group, channel


numchannels
Description
An integer specifying the number of channels in a group.
Parent
group


downmix
Description
An integer specifying the amount of volume adjustment, in decibels, to apply to each channel when performing a downmix for the specified group.
Parent
group
Notes
Valid entries are +10, +6, +4, +2, 0, -2, -4, -6, or -10.


channel
Description
Encodes the output device index of a channel in a group.
Parent
group
Subelement
index


format
Description
Encodes format information for video or audio media in a track.
Parents
video, audio
Subelements
samplecharacteristics, appspecificdata


samplecharacteristics
Description
Encodes characteristics of video or audio media.
Parents
video, audio, format
Subelements
Video: *width, *height, anamorphic, pixelaspectratio, fielddominance, rate, colordepth, codec
Audio: depth, samplerate


width
Description
An integer specifying the width, in pixels, of video media.
Parent
samplecharacteristics, file


height
Description
An integer specifying the height, in pixels, of video media.
Parent
samplecharacteristics, file


pixelaspectratio
Description
A string specifying the pixel aspect ratio.
Parent
samplecharacteristics
Notes
Valid entries are NTSC-601, PAL-601, square, DVCPROHD-720P or HD-(960x720), DVCPROHD-1080i60 or HD-(1280x1080), DVCPROHD-1080i50 or HD-(1440x1080).


fielddominance
Description
A string specifying the field dominance.
Parent
samplecharacteristics
Notes
Valid entries are none, lower, upper, odd, or even.


colordepth
Description
An integer specifying the color depth.
Parent
samplecharacteristics
Notes
Valid entries are 8, 6, or 24.


codec
Description
Encodes details about a codec.
Parent
samplecharacteristics
Subelements
name, appspecificdata


depth
Description
An integer specifying the bit depth of audio media.
Parent
samplecharacteristics
Notes
Valid entries are 8 or 16.


samplerate
Description
An integer specifying the audio sample rate.
Parent
samplecharacteristics
Notes
Valid entries are 32000, 44100, or 48000.

Common Elements

Common elements are subelements of more than one parent element.


name
Description
A string specifying a name.
Parents
project, bin, sequence, clip, clipitem, multiclip, generatoritem, file, marker, effect, interpolation, source, transitionitem


duration
Description
An integer specifying duration in number of frames. (See “Timing Values.”)
Parents
sequence, clip, clipitem, generatoritem, file, video, audio, transitionitem
Notes
The number is interpreted based on the frame rate in effect at the time. Note that in the case of still frames, the value for duration represents minutes rather than frames.


enabled
Description
A Boolean value specifying whether or not the parent element is enabled.
Parents
track, clipitem, clip, generatoritem, sequence, filter
Notes
If you do not specify enabled, the default setting is TRUE.


marker
Description
Encodes a named time or range of time in a clip or sequence.
Parents
clip, clipitem, sequence
Subelements
+*name, +in, +out,*marker, *comment, color


color
Description
Encodes the color value of a marker.
Parent
marker
Subelements
red, green, blue, or alpha.


comment
Description
A string describing a marker.
Parent
marker


in
Description
An integer specifying a starting time. (See “Timing Values.”)
Parents
sequence, clip, clipitem, generatoritem, marker, effect
Notes
The valid range is from 0 to the duration of the component. The value must be less than the value of out. A value of -1 indicates that no in point is set for a browser clip or a sequence. Also, you can use -1 to override an existing encoding with an undefined or default value. Like duration, the value of in is interpreted based on the frame rate in effect at the time.


out
Description
An integer specifying an ending time. (See “Timing Values.”)
Parents
sequence, clip, clipitem, generatoritem, marker, effect
Notes
The valid range is from 0 to the duration of the component. The value must be greater than the value of in. A value of -1 indicates that no out point is set for a browser clip or a sequence. Also, you can use -1 to override an existing encoding with an undefined or default value. Like duration, the value of out is interpreted based on the frame rate in effect at the time.


mediatype
Description
A string defining the media type.
Parents
link, sourcetrack, effect
Notes
Valid strings are video or audio.


trackindex
Description
An integer specifying the track index in a link element or in a media source.
Parents
link, sourcetrack
Notes
If the media has a single video track and no audio tracks, specifying trackindex may cause an error.

Rate and Timecode


rate
Description
Encodes a time scale to interpret time values for a clip, sequence, timecode, or other component.
Parents
sequence, clip, clipitem, generatoritem, timecode, audio, effect
Subelements
+timebase (for video: ntsc)


timebase
Description
An integer specifying the timebase of the frame rate.
Parent
rate
Notes
You use timebase in conjunction with ntsc to define the time scale. See Table B-1


ntsc
Description
A Boolean value specifying the NTSC rate reduction.
Parent
rate
Notes
If you set ntsc to TRUE, the NTSC rate reduction (0.01%) is applied to timebase. See Table B-1


timecode
Description
Encodes a timecode value for a clip, sequence, or file.
Parents
sequence, clip, clipitem, file, value, generatoritem
Subelements
+*string or (+frame and +displayformat), +rate, field, reel, source, format
Attribute
id
Notes
A timecode represents the address of a particular video frame on a time-based media storage device, such as a videotape recorder. Note that timecode requires a rate definition (local or inherited), and either a string subelement, or frame and displayformat subelements. (You can also specify all three subelements.) For example, a string set to 01:00:2;05 with a rate of 29.97 fps translates to a frame count of 107657 formatted using drop frame notation.


string
Description
A string specifying a timecode.
Parent
timecode
Notes
The value is based on an SMPTE timecode string, with a semicolon indicating that the drop frame format is being used. The application uses the current frame rate to interpret this value. (If you specify string, you do not need to specify frame and displayformat.)


frame
Description
An integer specifying the frame count.
Parent
timecode
Notes
This element defines a frame count that Final Cut Pro interprets into a timecode using the parent rate and format definitions. Note that frame contains an actual frame count, not simply a time index. For a drop frame timecode, the skipped numbers are taken into account. The frame count starts at zero, and rolls over at 23 hours, 59 minutes, 59 seconds, and n frames (where n is the frame rate).


displayformat
Description
A string specifying the format modifier to use for the parent timecode element.
Parent
timecode
Notes
Valid values are DF (for drop frame) or NDF (for non-drop frame) Note that values other than NDF are valid only for a timecode with a rate of 30 frames per second. If not specified, non-drop frame timecode formatting is used.


field
Description
An integer specifying the field offset for a timecode.
Parent
timecode
Notes
Valid values are 0 or 1, with a default to 0 if field is not specified.


reel
Description
Encodes the source identifier for a timecode.
Parent
timecode
Subelement
+*name
Notes
In common usage, reel identifies the source archive device or media (videotape) from which the timecode was taken.


source
Description
A string specifying either the timecode source or the track identifier.
Parent
timecode
Notes
Valid entries are source, aux1, aux2, or sound. If not specified, source is assumed.

Effects


generatoritem
Description
Encodes information about a generator in a track.
Parent
track
Subelement
+name, +duration, +rate, in, out, start, end, enabled, anamorphic, alphatype, effect, sourcetrack, filter, timecode, primarytimecode, alphareverse, link, logginginfo, labels, comments, mediadelay, fielddominance, filmdata, subframeoffset, masterclipid, compositemode, syncoffset, marker, subclipmasterID


primarytimecode
Description
A string specifying the default timecode to display for this item.
Parents
generatoritem, clipitem


transitionitem
Description
Encodes a transition in a track.
Parent
track
Subelements
rate, *start, *end, *alignment, effect, *name


alignment
Description
A string specifying an alignment for a transition.
Parent
transitionitem
Notes
Valid entries are start, center, end, end-black, or start-black.


filter
Description
Encodes a filter effect.
Parents
clip, clipitem
Subelements
*enabled, *start, *end, effect


effect
Description
Encodes an effect or processing operation.
Parents
transitionitem, filter, generatoritem
Subelements
+*name, +*effectid, +*effecttype, +*mediatype, *effectcategory, parameter, keyframe, appspecificdata, wipecode, wipeaccuracy, rate, startratio, endratio, reverse, duration , privatestate, multiclip, effectclass
Notes
You should encode an effect so that the importing application can accurately find the matching effect. If the effect is not found, the application may use a generic proxy effect.


effectid
Description
A string providing a language-independent constant identifier for an effect.
Parent
effect


effectcategory
Description
A string specifying the category of an effect.
Parent
effect


effecttype
Description
A string specifying the type of an effect.
Parent
effect
Notes
Valid entries are filter,transition, motion, or generator.


effectclass
Description
A string specifying an FxPlug effect.
Parent
effect
Notes
The only valid entry is FxPlug. For any other effects, you should leave this element unspecified.


wipecode
Description
An integer specifying the SMPTE wipe code.
Parent
effect


wipeaccuracy
Description
An integer specifying the SMPTE wipe accuracy.
Parent
effect


startratio
Description
For a transition effect, a number specifying what fraction of the effect has been executed at the start of the transition.
Parent
effect
Notes
Valid entries in the range 0.0 to 1.0. The default is 0.0.


endratio
Description
For a transition effect, a number specifying what fraction of the effect will have been executed at the end of the transition.
Parent
effect
Notes
Valid entries in the range 0.0 to 1.0. The default is 1.0.


reverse
Description
For a transition effect, a Boolean value indicating whether or not an effect should be reversed, with the end result applied to the start and vice versa.
Parent
effect
Notes
The default is FALSE.


privatestate
Description
Data for an After Effects plug-in effect.
Parent
effect


parameter
Description
Encodes a parameter for an effect.
Parent
effect
Subelements
+name or +parameterid (or both), +value or +keyframe (but not both), parameterspecifier, valuemin, valuemax, valuelist, interpolation, appspecificdata, privatestate, parameterspecifier


parameterid
Description
A string providing a constant identifier for an effect parameter.
Parent
parameter
Notes
For an AudioUnits effect, you should use both parameterid and parameterspecifier.


parameterspecifier
Description
A string providing a constant identifier for an AudioUnit effect parameter.
Parent
parameter
Notes
The parameterspecifier element is only supported for for AudioUnit effects. When combined with the effectid element, it unambiguously identifies a particular parameter for an AudioUnit effect. The value of parameterspecifier is a combination of the values AudioUnitParameterID, AudioUnitScope, and AudioUnitElement. It is packaged as a string with colon-separated decimal numeric values. For example, if an AudioUnit parameter has an ID of 42, a scope of kAudioUnitScope_Global, and an element of 1, the encoding for the parameterspecifier element would be the string 42:0:1.


valuemin
Description
A number specifying the minimum value for a parameter.
Parent
parameter


valuemax
Description
A number specifying the maximum value for a parameter.
Parent
parameter


valuelist
Description
Encodes information about a pop-up list in a parameter.
Parent
parameter
Subelements
valueentry


valueentry
Description
Encodes information about the choice in a pop-up list in a parameter.
Parent
valuelist
Subelements
name, value
Notes
The entry for value indicates the ordinal position of the item in the pop-up list.


value
Description
Encodes or specifies a fixed value for an effect parameter or a keyframe.
Parents
parameter, keyframe, valueentry, timecode, (metadata)
Subelements
red, green, blue, alpha, horiz, vert, timecode, clip, sequence
Notes
For some parameters, the subelements red, green, and blue are required. For others, the horz and vert subelements are required. In some cases, you can directly specify a numeric or Boolean value in value and not use any subelements.


keyframe
Description
Encodes a keyframe for an effect.
Parent
parameter
Subelements
+*when, +*value, interpolation, *inscale, *outscale, *inbez, *outbez,*speedvirtualkf, *speedkfin, *speedkfout, *speedkfstart, *speedkfend, *origvalue, *hadbezierin, *hadbezierout


when
Description
An integer specifying the time location for a keyframe.
Parent
keyframe


inscale
Description
A number specifying the incoming magnitude value for a keyframe.
Parent
keyframe
Notes
The value is specific for keyframes using the FCPCurve interpolation.


inbez
Description
Encodes the incoming handle value for a keyframe.
Parent
keyframe
Subelements
horiz, vert


outscale
Description
A number specifying the outgoing magnitude value for a keyframe.
Parent
keyframe
Notes
The value is specific for keyframes using the FCPCurve interpolation.


outbez
Description
Encodes the outgoing handle value for a keyframe.
Parent
keyframe
Subelements
horiz, vert


red, green, blue
Description
A number specifying color information for an effect parameter.
Parents
value, color


alpha
Description
An integer specifying the alpha value of a channel.
Parents
value, color
Notes
Valid entries are from 0 to 255. 0 is transparent; 255 is opaque.


horiz, vert
Description
A number specifying the horizontal or vertical coordinate. When these values specify the Center parameters in the Motion settings, they are scale values ranging from -100 to 100. This allows the size of the image to change at import time while still maintaining the positioning.
Parents
value, inbez, outbez
Notes
The value is specific for keyframes using the FCPCurve interpolation. When used as subelements of inbez and outbez, these elements represent polor coordinates. The horiz element is the radius and the vert element is the angle in radians.


interpolation
Description
Encodes the type of curve interpretation and data to use in the parent element
Parents
keyframe, parameter
Subelement
+*name
Notes
The interpolation element only occurs in an effect parameter with keyframes. For Final Cut Pro, the interpolation method is FCPCurve. See “Keyframe Interpolation” for more information about this method.

The Time Remap Effect

The Time Remap effect allows you to set the constant speed, variable speed, and playback direction for a clipitem. When you use this effect, Final Cut automatically creates two “virtual” keyframes in the graphdict parameter at the beginning and end of the item. For keyframes in this parameter, value encodes the frame in the media file to be remapped to a time encoded by when. Virtual keyframes in the graphdict parameter also use these additional elements:


speedvirtualkf
Description
A Boolean value indicating whether a keyframe has been created by Final Cut (TRUE) or by the user (FALSE).
Parent
keyframe


speedkfin
Definition
A Boolean value indicating whether a virtual keyframe is at the setting for in.
Parent
keyframe


speedkfout
Definition
A Boolean value indicating whether a virtual keyframe is at the the setting for out.
Parent
keyframe


speedkfstart
Definition
A Boolean value indicating whether a virtual keyframe is at the setting for start.
Parent
keyframe


speedkfend
Definition
A Boolean value indicating whether a virtual keyframe is at the setting for end.
Parent
keyframe


origvalue
Definition
An integer indicating the original value of the value element.
Parent
keyframe


anchoroffset
An optional double value that specifies an offset from a keyframe for playback. See “The anchoroffset Element.”
Parent
keyframe


hadbezierin
A Boolean value indicating whether keyframe once had an in Bezier handle.
Parent
keyframe

Notes

Not required, not inherited.


hadbezierout
Definition
A Boolean value indicating whether a virtual keyframe once had an out Bezier handle.
Parent
keyframe

Application Specific Data


appspecificdata
Description
Encodes application-specific data.
Parents
format, codec, parameter
Subelements
appname, appmanufacturer, appversion, data


appname
Description
A string specifying the application name.
Parent
appspecificdata


appmanufacturer
Description
A string specifying a manufacturer.
Parent
appspecificdata


appversion
Description
A string specifying a version number.
Parent
appspecificdata


data
Description
Encodes data about an application or codec.
Parent
appspecificdata
Subelements
fcpimageprocessing, qtcodec , qteffectid, UUID


fcpimageprocessing
Description
Encodes information about image processing.
Parent
data
Subelements
useyuv, usesuperwhite, rendermode


useyuv
Description
A Boolean value specifying the use of YUV color space.
Parent
fcpimageprocessing


usesuperwhite
Description
A Boolean value specifying the use of super-white.
Parent
fcpimageprocessing


rendermode
Description
A string specifying the color space to be used for rendering.
Parent
fcpimageprocessing
Notes
Valid entries YUV8BPP, RGB, Float10BPP, or Float


qtcodec
Description
Encodes QuickTime-specific codec identification and configuration information.
Parent
data
Subelements
codecname, codectypename, codectypecode, codecvendorcode, spatialquality, temporalquality, keyframerate, datarate


codecname
Description
A string specifying the registered name for the codec.
Parent
qtcodec


codectypename
Description
A string specifying the registered short name (type name) for the codec.
Parent
qtcodec


codectypecode
Description
A string specifying the registered fourCC (4-byte) type code for the codec.
Parent
qtcodec


codecvendorcode
Description
A string specifying the registered fourCC (4-byte) vendor or manufacturer code for the codec.
Parent
qtcodec


spatialquality
Description
An integer specifying the spatial compression quality.
Parent
qtcodec
Notes
Valid entries are in the range 0 through 1023. This property may not be supported by a particular codec.


temporalquality
Description
An integer specifying the temporal compression quality.
Parent
qtcodec
Notes
Valid entries are in the range 0 through 1023. This property may not be supported by a particular codec.


keyframerate
Description
An integer specifying the keyframe rate for the codec.
Parent
qtcodec
Notes
A value of 0 indicates that keyframes should not be used. This property may not be supported by a particular codec.


datarate
Description
An integer specifying the data rate limit for a codec and QuickTime.
Parent
qtcodec
Notes
A value of 0 indicates that no data rate limit should be used by QuickTime. This property may not be supported by a particular codec.


qteffectid
Description
An integer specifying a QuickTime effect id.
Parent
data


UUID
Description
A string specifying a unique identifier for an application or codec.
Notes
The UUID element is distinct from the uuid element.
Parent
data

Film Data


filmdata
Description
Encodes metadata imported from Cinema Tools.
Parent
clip, clipitem
Subelements
appspecificdata, filmslate, cameraroll, labroll, keycode, dailyroll, inknumber, filmstandard, telecinespeed
Notes
You cannot enter or edit this data from Final Cut Pro, but you can import it.


filmslate
Description
Encodes information about the scene and take.
Parent
filmdata
Subelements
scene, take, slate
Notes
The Cinema Tools database has separate text field for Scene and Take, which appear concantenated as Slate in the application.


scene
Description
A string describing the scene.
Parent
filmslate


take
Description
A string describing the take.
Parent
filmslate


slate
Description
A string specifying the Cinema Tools Slate information.
Parent
filmslate


cameraroll
Description
A string describing the camera roll.
Parent
filmdata


labroll
Description
A string describing the lab roll.
Parent
filmdata


dailyroll
Description
A string describing the daily roll.
Parent
filmdata


keycode
Description
Encodes information about the keycode for a film.
Parent
filmdata
Subelements
+prefix, +feetframes, perfoffset, reversed


prefix
Description
Prefix information for the keycode.
Parent
keycode,inknumber
Notes
Appers in Browser concatenated with feetframes.


feetframes
Description
A string representing feet (four digits) and frames (two digits).
Parent
keycode, inknumber
Notes
Appers in Browser concatenated with prefix.


perfoffset
Description
A string describing the 3-perf offset.
Parent
keycode


reversed
Description
A Boolean value set to TRUE if the keycode runs backwards.
Parent
keycode


inknumber
Description
Encodes information about the keycode for a film.
Parent
filmdata
Subelements
+prefix, +feetframes


filmstandard
Description
A string specifying a supported format: 35mm4p, 35mm3p, or 16mm20.
Parent
filmdata


telecinespeed
Description
A string specifying the telecine speed: 24, 25, or 30.
Parent
filmdata

QuickTime Metadata


metadata
Description
Encapsulates metadata in a QuickTime file.
Parents
file, video, audio
Subelements
+storage, +key, updatebehavior, size, type, value
Notes
A metadata specification, regardless of it's purpose, requires storage and key subelements. To add or remove metadata from a QuickTime file, use the updatebehavior subelement with add or remove. See “About master clips”


storage
Description
A string defining the storage container for a specified metadata.
Parent
metadata
Notes
The only valid entry is QuickTime.


key
Description
A reverse-dns string identifying the metadata.
Parent
metadata
Notes
Reverse-dns strings (such as com.mycompany.myid.md1) help ensure uniqueness.


size
Description
A number defining the size in bytes of the metadata.
Parent
metadata
Notes
While not absolutely required for strings, this specification is important for numbers and binary data blocks.


type
Description
A string defining the type of metadata.
Parent
metadata
Notes
Valid entries are binary, UTF8, UTF16, MacRoman, signed, unsigned,float32, and float64.


value
Description
The data stored as metadata in the QuickTime file.
Parents
metadata, (parameter, keyframe, valueentry, timecode)
Notes
All data values are stored as plain text, with the exception of binary data elements. These are uuencoded and wrapped in a CDATA scope.

Import Options


importoptions
Description
Encodes import options specific to Final Cut Pro.
Parent
xmeml
Subelements
*createnewproject, *targetprojectname, *defsequencepresetname, *filterreconnectmediafiles, *filterincludemarkers, *filterincludeeffects, *filterincludesequencesettings, *displaynonfatalerrors,*createfcpprojectatxmlfilepath, *deletethisxmlfileatimport
Notes
Using importoptions allows you to bypass the Import XML dialog shown in Figure 2-3 and import an interchange format document directly into Final Cut Pro. (You must specify the subelements createnewproject and defsequencepresetname to do this.) The subelements specify the same choices as those in the dialog.


createnewproject
Description
A Boolean value specifying whether or not to create a new project.
Parent
importoptions
Notes
If TRUE, the system creates a new project with the name "Untitled Project [n]."


targetprojectname
Description
A string specifying the target project.
Parent
importoptions
Notes
The components specified in the interchange format document are imported into the target project.


defsequencepresetname
Description
A string specifying the name of a sequence preset.
Parent
importoptions
Notes
For a list of valid entries, see the pop-up list on the XML Import dialog. Using the entry useFirstClipSettings or any invalid entry is the same as using the Auto setting in the Import XML dialog. (See “Importing Documents.”)


filterreconnectmediafiles
Description
A Boolean value specifying whether or not to reconnect clips to media files on import.
Parent
importoptions
Notes
The default setting is TRUE.


filterincludemarkers
Description
A Boolean value specifying whether or not to import encoded markers.
Parent
importoptions
Notes
The default setting is TRUE.


filterincludeeffects
Description
A Boolean value specifying whether or not to import encoded effects.
Parent
importoptions
Notes
The default setting is TRUE.


filterincludesequencesettings
Description
A Boolean value specifying whether or not to imported encoded sequence settings.
Parent
importoptions
Notes
The default setting is TRUE.


displaynonfatalerrors
Description
A Boolean value specifying whether or not to display nonfatal errors.
Parent
importoptions
Notes
The default setting is TRUE.


createfcpprojectatxmlfilepath
Description
A Boolean value indicating whether a project file should be created at the same location as the imported xml file.
Parent
importoptions
Notes
If this element is set to TRUE, importing the xml file /foo/bar/clouds.xml would create the file /foo/bar/clouds.fcp.


deletethisxmlfileatimport
Description
A Boolean value indicating whether an xml file should be deleted at the end of import.
Parent
importoptions
Notes
By default, the value for this element is FALSE. If critical errors are encountered during import, the file is not deleted.