FCPXML Concepts

Here is a list of Final Cut Pro X terms you’ll encounter throughout this document:

Refer to Final Cut Pro X Help for more information on Final Cut Pro X concepts.

Document Structure

An FCPXML document represents one of the following Final Cut Pro X objects:

Refer to Importing XML for FCPXML examples.

The root top-level container element is <fcpxml>. The root element contains the following:

Some of the child elements that appear under the <fcpxml> element are summarized in Table 1-1, while others are listed in Table 2-1.

Table 1-1  Descendants of the <fcpxml> element

Element

Description

<event>

A single event in a library. The name attribute specifies the name of the event.

<import-options>

A container for options related to importing events and projects. See Import Options.

<library>

A single library. This element has the following attributes:

  • colorProcessing—Specifies whether the library supports standard, wide, or wide-hdr color gamut. The default is standard.

  • location—Specifies the URL of the library on export, but is ignored during import. Refer to the library location import option in Import Options.

<project>

A project timeline. The name attribute specifies the name of the project.

<resources>

A container for relevant data that events and projects depend on, such as media assets, video formats, and effects. See Resources for details on the supported resource types.

Collections

An event may group clips into keyword and smart collections, and a library may group clips into smart collections. Collections are represented by the elements in Table 1-2 as children of the <event> or <library> element.

Table 1-2  Collection elements

Element

Description

<collection-folder>

A container to group other collection elements.

<keyword-collection>

Group clips and projects based on matching keywords.

<smart-collection>

Group clips and projects matching various search criteria. Matching criteria elements are listed in Table 1-3.

Smart collections use the elements listed in Table 1-3 to specify matching criteria for grouping clips and projects.

Table 1-3  Smart collection match elements

Element

Description

<match-clip>

Match clips based on type (one of audition, synchronized, compound, multicam, layeredGraphic, or project).

<match-keywords>

Match clips based on assigned keywords.

<match-media>

Match clips or projects based on media type (one of audioOnly, stills, videoOnly, or videoWithAudio).

<match-property>

Match clips or projects based on media format and metadata properties.

<match-ratings>

Match clips based on assigned ratings.

<match-roles>

Match clips based on assigned roles.

<match-shot>

Match clips based on assigned shot type.

<match-stabilization>

Match clips based on the stabilization type.

<match-text>

Match clips or projects based on the specified text.

<match-time>

Match clips or projects created or imported based on a specific date.

<match-timeRange>

Match clips or projects created or imported based on a range of time.

Importing XML

You can import an FCPXML document into Final Cut Pro X in the following ways:

Importing a Library

Listing 1-1 shows FCPXML representing a library.

Listing 1-1  A library with a simple project as FCPXML

<fcpxml version="1.7">
    <!-- Resources -->
    <resources>
        <asset id="r1" src="file:///Volumes/Media/MyMovie.mov" start="0s" duration="10s" hasVideo="1" hasAudio="1" format="r2" audioSources="1" audioChannels="2" audioRate="48000"/>
        <format id="r2" name="FFVideoFormat1080p30"/>
    </resources>
    <library>
        <!-- Events -->
        <event name="MyEvent">
            <project name="MyProject">
                <!-- Project Story Elements -->
                <sequence format="r2">
                    <spine>
                        <asset-clip name="MyMovie" ref="r1" start="0s" duration="5s" audioRole="dialogue"/>
                    </spine>
                </sequence>
            </project>
            <!-- Clips -->
            <asset-clip name="MyMovie" ref="r1" format="r2" duration="5s" audioRole="dialogue"/>
        </event>
    </library>
</fcpxml>

In Listing 1-1, the library has an event named MyEvent that in turn has a project named MyProject. The MyProject project uses two resources:

  • A reference to an external asset located at /Volumes/Media/MyMovie.mov

  • A built-in video format, FFVideoFormat1080p30

When Final Cut Pro X imports the FCPXML in Listing 1-1, it:

  • Creates a new event called MyEvent in the library the user chooses. If an event named MyEvent already exists in the chosen library, Final Cut Pro X imports the project into that event.

  • Imports MyMovie.mov into MyEvent by either copying or linking, depending on the application preference, and creates a browser clip referencing the imported asset.

  • Creates a new project called MyProject with a sequence using a 1080p, 30 fps video format specified by FFVideoFormat1080p30. If a project named MyProject already exists in the event named MyEvent, Final Cut Pro X asks whether you want to create a new project or replace the existing project. Creating a new project appends a numerical suffix to the project name, for example MyProject 1.

  • Inserts the first 5 seconds of video and audio from MyMovie.mov into the project timeline.

Importing Events

Listing 1-2 shows FCPXML representing an event.

Listing 1-2  An event with multiple clips as FCPXML

<fcpxml version="1.7">
    <!-- Resources -->
    <resources>
        <format id="r1" name="FFVideoFormat1080p30"/>
        <asset id="r2" src="file:///Volumes/Media/MyMovie1.mov" start="0s" duration="10s" hasVideo="1" hasAudio="1" format="r1" audioSources="1" audioChannels="2" audioRate="48000"/>
        <asset id="r3" src="file:///Volumes/Media/MyMovie2.mov" start="0s" duration="20s" hasVideo="1" hasAudio="1" format="r1" audioSources="1" audioChannels="2" audioRate="48000"/>
        <asset id="r4" src="file:///Volumes/Media/MyMovie3.mov" start="10s" duration="40s" hasVideo="1" hasAudio="1" format="r1" audioSources="1" audioChannels="2" audioRate="48000"/>
    </resources>
    <!-- Events -->
    <event name="MyEvent">
        <!-- Clips -->
        <asset-clip name="MyMovie1" ref="r2" format="r1" duration="5s" audioRole="dialogue"/>
        <asset-clip name="MyMovie2" ref="r3" format="r1" duration="15s" audioRole="dialogue"/>
        <asset-clip name="MyMovie3" ref="r4" format="r1" duration="30s" audioRole="dialogue"/>
    </event>
</fcpxml>

In Listing 1-2, the event MyEvent uses these resources:

  • Three external assets named MyMovie1.mov, MyMovie2.mov, and MyMovie3.mov located at /Volumes/Media/

  • A built-in video format, FFVideoFormat1080p30

When Final Cut Pro X imports this FCPXML, it:

  • Creates a new event called MyEvent in the library you choose. If an event named MyEvent already exists in the chosen library, Final Cut Pro X imports the clips into that event.

  • Imports MyMovie1.mov, MyMovie2.mov, and MyMovie3.mov into MyEvent by either copying or linking, depending on the application preference.

  • Creates three clips (MyMovie1, MyMovie2, and MyMovie3) containing audio and video data from the imported media and using a 1080p, 30 fps video format specified by FFVideoFormat1080p30. If a clip already exists, with the same name in the event named MyEvent, Final Cut Pro X asks whether you want to create a new clip or replace the existing clip. Creating a new clip appends a numerical suffix to the clip name, for example, MyMovie1 1.

Importing Clips

Listing 1-3 shows FCPXML representing a group of clips.

Listing 1-3  A group of clips as FCPXML

<fcpxml version="1.7">
    <!-- Resources -->
    <resources>
        <format id="r1" name="FFVideoFormat1080p30"/>
        <asset id="r2" src="file:///Volumes/Media/MyMovie1.mov" start="0s" duration="10s" hasVideo="1" hasAudio="1" format="r1" audioSources="1" audioChannels="2" audioRate="48000"/>
        <asset id="r3" src="file:///Volumes/Media/MyMovie2.mov" start="0s" duration="20s" hasVideo="1" hasAudio="1" format="r1" audioSources="1" audioChannels="2" audioRate="48000"/>
        <asset id="r4" src="file:///Volumes/Media/MyMovie3.mov" start="10s" duration="40s" hasVideo="1" hasAudio="1" format="r1" audioSources="1" audioChannels="2" audioRate="48000"/>
    </resources>
    <!-- Clips -->
    <asset-clip name="MyMovie1" ref="r2" format="r1" duration="5s" audioRole="dialogue"/>
    <asset-clip name="MyMovie2" ref="r3" format="r1" duration="15s" audioRole="dialogue"/>
    <asset-clip name="MyMovie3" ref="r4" format="r1" duration="30s" audioRole="dialogue"/>
</fcpxml>

In Listing 1-3, the group of clips uses these resources:

  • Three external assets named MyMovie1.mov, MyMovie2.mov, and MyMovie3.mov located at /Volumes/Media/

  • A built-in video format, FFVideoFormat1080p30

When Final Cut Pro X imports this FCPXML, it:

  • Creates a new event using the current date, such as 10-17-16, as the name in the library you choose. If there is already an event with that name in the chosen library, Final Cut Pro X creates another event in the library and appends a numerical suffix to the name, such as 10-17-16 1.

  • Imports MyMovie1.mov, MyMovie2.mov, and MyMovie3.mov into the new event by either copying or linking, depending on the application preference.

  • Creates three clips (MyMovie1, MyMovie2, and MyMovie3) containing audio and video data from the imported media and using a 1080p, 30 fps video format specified by FFVideoFormat1080p30.

Importing Collections

Listing 1-4 shows FCPXML representing an event with collections.

Listing 1-4  An event with collections as FCPXML

<fcpxml version="1.7">
    <!-- Resources -->
    <resources>
        <format id="r1" name="FFVideoFormat1080p30"/>
        <asset id="r2" name="MyMovie1" src="file:///Volumes/Media/MyMovie1.mov" start="0s" duration="10s" hasVideo="1" format="r1" hasAudio="1" audioSources="1" audioChannels="2" audioRate="48000"/>
        <asset id="r3" name="MyMovie2" src="file:///Volumes/Media/MyMovie2.mov" start="0s" duration="20s" hasVideo="1" format="r1" hasAudio="1" audioSources="1" audioChannels="2" audioRate="48000"/>
        <asset id="r4" name="MyMovie3" src="file:///Volumes/Media/MyMovie3.mov" start="10s" duration="40s" hasVideo="1" format="r1" hasAudio="1" audioSources="1" audioChannels="2" audioRate="48000"/>
    </resources>
    <event name="MyEvent">
        <!-- Clips -->
        <asset-clip name="MyMovie1" ref="r2" duration="10s" audioRole="dialogue" format="r1">
            <keyword start="5s" duration="2s" value="MyKeyword1"/>
        </asset-clip>
        <asset-clip name="MyMovie2" ref="r3" duration="20s" audioRole="dialogue" format="r1">
            <keyword start="3s" duration="12s" value="MyKeyword2"/>
        </asset-clip>
        <asset-clip name="MyMovie3" ref="r4" duration="40s" start="10s" audioRole="dialogue" format="r1">
            <keyword start="45s" duration="5s" value="MyKeyword3"/>
        </asset-clip>
        <!-- Collections -->
        <keyword-collection name="MyKeyword1"/>
        <keyword-collection name="MyKeyword2"/>
        <keyword-collection name="MyKeyword3"/>
    </event>
</fcpxml>

In Listing 1-4, the event MyEvent uses these resources:

  • Three external assets named MyMovie1.mov, MyMovie2.mov, and MyMovie3.mov located at /Volumes/Media/

  • A built-in video format, FFVideoFormat1080p30

When Final Cut Pro X imports this FCPXML, it:

  • Creates a new event called MyEvent in the library you choose. If an event named MyEvent already exists in the chosen library, Final Cut Pro X imports the collection into that event.

  • Imports MyMovie1.mov, MyMovie2.mov, and MyMovie3.mov into MyEvent by either copying or linking, depending on the application preference.

  • Creates three clips (MyMovie1, MyMovie2, and MyMovie3) containing audio and video data from the imported media and using a 1080p, 30 fps video format specified by FFVideoFormat1080p30.

  • Adds keywords (MyKeyword1, MyKeyword2, and MyKeyword3) over the specified time range to the respective clips.

  • Creates keyword collections (MyKeyword1, MyKeyword2, and MyKeyword3) in MyEvent.

Import Options

The <import-options> element, as a child of the <fcpxml> element, can contain zero or more <option> elements that describe options for importing events and projects.

Table 1-4  Option element attributes

Attribute

Description

key

A string that identifies one of the following import options:

  • copy assets—Copy (1) or link (0) assets referenced in the imported XML.

  • library location—The location (URL) of the library to which to add the event or project. If the specified URL represents a directory, the default library name is used. If no library exists at the location specified, a new library is created.

  • suppress warnings—Suppress (≥1) or show (0) warnings generated during import.

value

The value for the import option.