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.

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.

New in Final Cut Pro 6.0.2

Final Cut Pro 6.0.2 provides new Apple Events that support 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.

Note: The Apple Developer website provides sample code that demonstrates the use of Apple events in Final Cut Pro. The sample code includes a header file you can use in constructing your own application.

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.

Description

Close Project (kFCPSaveAndCloseProjectFile 'cfcP' )
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.

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.

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 a project file is not specified, no XML is returned.
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. If the project is not open, it is first opened and brought to the foreground. If no project file or UUID is provided, no XML is returned.
Parameters: kFCPProjectFileKey 'fcpP' typeFSRef/typeFileURL. The project to operate on.
: kFCPItemUUID 'fcIU' typeUTF8Text. The UUID for the item.
: 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.

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.

Description

Find Items (kFCPFindItemsInProject 'ffcP')
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.

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.