Apple Events and Final Cut Pro

Final Cut Pro version 5.1.2 and later offers support for Apple events that external applications can use to directly manage the import and export of XML in a Final Cut project.

These custom Apple events provide the following functions:

• Open a project file.

• Close a project file, either saving or discarding any changes.

• Retrieve the XML representation of a project file.

• Send XML data to Final Cut Pro directly for import.

• Update the media file.

To alert the user to changes in a project that result from these import or export operations, there are also several Apple events that control the display of project information, including:

• Select a single item in the Browser and highlight it for the user.

• Open individual items from the Browser into the Viewer window.

• Use Final Cut's built-in Find mechanism to locate specific elements of a project.

Final Cut Pro 6.0.2 provided Apple Events in support of the following functions:

• Get a list of all open project files.

• Update information about a media file.

• Get an XML representation of all available effects.

• Retrieve the XML representation of a single item.

New in Final Cut Pro 7.0

Final Cut Pro 7.0 provides new Apple Events that support the following functions:

• Save a specified project file.

• Get a table of contents (bins, clips, sequences) for a specified project.

Final Cut Pro Apple Events

Open Project ( kFCPOpenProjectFile 'ofcP' )

Description

Opens a specified project file. If the project file is already open, the event brings it to the foreground inside Final Cut Pro.

Parameter

kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project file to open.

Close Project (kFCPSaveAndCloseProjectFile 'cfcP' )

Description

Closes the specified project file, either saving any changes or discarding them.

Parameters

kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project to close. If the project is not open, nothing happens. If no project is specified, the most recently opened file is closed.

kFCPProjectFileCloseFlagsKey 'fcCF' typeSInt32. A flag controlling the behavior of the close event. The possible values are:

• kFCPSaveAndCloseProject - saves any changes and then closes the file.

• kFCPDiscardAndCloseProject - discards any changes and closes the file.

If no flag is specified, the default behavior is save and close.

Save Project As (kFCPSaveProjectFileAs 'sfcP')

Description

Saves the specified project file, possibly to a new name and location. If the specified project is not open, nothing happens. If no project file is specified, the top-most open project is saved.

Parameters

kFCPProjectFileKey 'fcpP'. The project file to save (FSRef).

kFCPProjectFileURL 'fcpU'. The name and location for the saved project file (file url).

kFCPProjectFileOverwriteFlag 'fsOF'. An optional Boolean flag controlling overwriting. TRUE means Final Cut Pro overwrites a project file with the same name and location; FALSE means Final Cut Pro cancels the save operation if a project exists with the same name and location. The default setting is FALSE.

Get Table of Contents (kFCPGetProjectTOC 'eTCX')

Description

Returns a Table of Contents list of bins, clips, and sequences in the given project. If no project file parameter is sent, the top-most project is used.

Parameter

kFCPProjectFileKey 'fcpP' . The project file to list.

Results

kFCPXMLDataKey 'xmlD'. An XML stream listing out a 'table of contents' for the project. Each listing includes the name, uuid, duration, and rate information for the specified item.

Get Open Projects List (kFCPGetAllOpenProjects 'fcLP' )

Description

Returns a list of open project files as FSRefs. Only projects with an associated file are returned.

Results

kFCPOpenProjectList 'fcOP'. An AEList of AERecords, each of which has a kFCPOneOpenProjectFile parameter.

kFCPOneOpenProjectFile 'fcPf'. A single path to a project file in the list of open projects. This parameter only occurs within the AEList returned by kFCPOpenProjectList. Its value is a file FSRef.

Get Project XML (kFCPGetDocumentXML 'eXML')

Description

Requests the XML representation of a Final Cut project. If the project file is closed, it is first opened. The project is always brought to the foreground in Final Cut. If no project file is specified, Final Cut Pro returns XML for the front-most project.

Parameters

kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project to operate on.

kFCPXMLDataVersion 'xmlV' typeFloat. The version of the Final Cut Pro XML Interchange Format to use. If unspecified, then the current version is used.

Results

kFCPXMLDataKey 'xmlD' typeUTF8Text. The XML data for the project represented as a UTF-8 string.

Get Item XML (kFCPGetItemXML 'gXML')

Description

Requests the XML representation of a single item in a Final Cut Pro project by UUID.

Parameters

kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project to operate on. If you omit this parameter and specify a UUID parameter only, Final Cut looks for the item in the front-most project.

kFCPItemUUID 'fcIU' typeUTF8Text. The UUID for the item. If you omit this parameter and specify a project that is open, Final Cut returns the XML for the front-most sequence, whether this sequence is in the specified project or not. If you omit this parameter and specify a project that is closed, Final Cut opens the project, makes any open sequence in that project front-most, and returns the XML for that sequence.

kFCPXMLDataVersion 'xmlV' typeFloat. The version of the Final Cut Pro XML Interchange Format to use. If unspecified, then the current version is used.

Results

kFCPXMLDataKey 'xmlD' typeUTF8Text. The XML data for the item represented as a UTF-8 string.

Import XML (kFCPImportXMLToDocument 'iXML')

Description

Directly imports XML into Final Cut Pro without referencing XML saved on disk. You can specify a specific project file to import the XML into. If you don’t specify a file, the XML is imported into a new, untitled project. Using updatebehavior, you can specify whether the imported items replace items in the project or are simply appended to the project.

Parameter

kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project to import into. If unspecified, a new untitled project is created.

kFCPXMLDataKey 'xmlD' typeUTF8Text. The XML data to import represented as a UTF-8 string. Note this is a buffer of XML data, not a URL. See the sample code for Apple Events in Final Cut Pro.

Get All Effects (kFCPGetAllEffectsXML 'eFXX')

Description

Allows an application to request the XML representation of all installed effects.

Parameters

kFCPXMLDataVersion 'xmlV' typeFloat. An optional value controlling the version of the XML Interchange Format to use. The default is the current version.

Results

kFCPXMLDataKey 'xmlD' typeUTF8Text. The XML data represented as a UTF-8 string. NOTE: The XML for effects cannot be imported back into Final Cut Pro.

Update Media File (kFCPUpdateMediaFile 'udfF' )

Description

Requests Final Cut Pro to examine a media file modification time and perform a silent reconnect or update if necessary.

Parameters

kFCPMediaFileKey 'fcpM' typeFSRef/typeFileURL. The media file to examine and update.

kFCPUpdateFileIgnoreModDate 'fIMD'. An optional Boolean flag controlling updating. TRUE means Final Cut Pro updates the media file regardless of its modification time; FALSE means Final Cut Pro updates the media file only if it has changed since the last time Final Cut examined the file. The default setting is FALSE.

Select Item (kFCPSelectItemInBrowser 'fcSI')

Description

Highlights a specified item or items in the Browser window. Use this event to bring one or more items to the attention of the user.

Parameters

kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project file to operate on.

kFCPItemUUID 'fcIU' typeUTF8Text. The UUID of a single item to select in the Browser.

kFCPItemsToSelectList 'fcSL' AEDescList. A list specifying multiple items to select at the same time. The parameter is an AEList of AERecords each of which has a single kFCPItemUUID parameter.

NOTE: You can use either a kFCPItemUUID parameter or a kFCPItemsToSelectList parameter, but not both.

Open Item (kFCPOpenItemInProject 'fcOI')

Description

Opens a specified item. Clips open in the Viewer; sequences in the Timeline; bins in a separate window.

Parameters

kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project file to operate on.

kFCPItemUUID 'fcIU' typeUTF8Text. The UUID of the item to open.

Find Items (kFCPFindItemsInProject 'ffcP')

Description

Searches for items. If the Find Results window is active, the search takes place among elements in this window. Otherwise, the search takes place in the Browser. The search results are displayed in a new Find Results window. This lets you bring multiple items to the attention of the user at one time.

The kFCPFindParameters list contains one or more entries that compose the search criteria. You can use multiple entries to precisely control the results obtained. For example, one entry can specify that the Name column of the items must start with a string 'Camera' and the next entry specifies that the Notes column must not contain the string 'bad take'. Each criteria entry is made up of four elements: the string to search for, the way to match the string, the column to search, and whether to use matching or non-matching items. Note that each criteria entry is an AERecord, so the list consists of records, each of which contains several parameters.

Parameters

kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project file to operate on.

kFCPFindLogicMode 'fndL' typeSInt32. The logic mode for the search. You can combine search criteria using AND (all criteria apply) or OR (only one criteria need apply). Possible values are:

• kFCPFindLogicAnd = 0

• kFCPFindLogicOr = 1

kFCPFindParameters 'fndP' typeAEList typeAERecord. An AEDescList list of criteria AERecords. The list is made up of one or more "criteria" records that define the string to search for, the string matching logic to use, whether to find matching items or items that don't match (i.e. 'skip'), and the name of a Browser column to search in. There are four criteria you can specify: kFCPFindSearchString, kFCPFindOmitCriteria, kFCPFindMatchMode and kFCPFindColumnName .

Search criteria

kFCPFindSearchString 'fndS' typeUFT8Text. The string to search for.

kFCPFindOmitCriteria 'fndO' typeSInt32. The way the seach criteria should be used. A zero value means find items that match the search string. A non-zero value means find items that don't match the seach string. (That is, skip any item matching the search string.)

kFCPFindMatchMode 'fndM' typeSInt32. The way a string should be matched. Valid entries are:

• kFCPFindMatchStartsWith = (1 << 0)

• kFCPFindMatchContains = (1 << 1)

• kFCPFindMatchEquals = (1 << 2 )

• kFCPFindMatchEndsWith = (1 << 3)

• kFCPFindMatchLessThan = (1 << 4)

• kFCPFindMatchGreaterThan = (1 << 5)

kFCPFindColumnName 'fndC' typeUTF8Text. Restricts the search to a specific Browser column. If not specified or if the passed string is not a valid entry, then all columns are searched. Valid column names are: name, duration, in, out, start, end, scene, shottake, lognote, good, label, label2, mastercomment1, mastercomment2, mastercomment3, mastercomment4, clipcommenta, clipcommentb.