cp.apple.fcpxml.md

docs » cp.apple.fcpxml

---

This extension adds functions and methods that simplify the creation and management of the FCPXML document structure. It allows you to load FCPXML files from file, or build them from scratch using Lua - which you can then export back to a FCPXML file.

With the Final Cut Pro X XML (FCPXML) format, you can transfer the details of your events and projects between Final Cut Pro X and third-party applications, devices, and media asset management tools that do not natively recognize Final Cut Pro X events or projects. FCPXML 1.8 requires Final Cut Pro X 10.4.1 or later.

FCPXML describes certain aspects of projects and events that are useful for other applications. It does not describe all possible data, and therefore is not a substitute for the native project and event data organized in a library bundle.

You can use Final Cut Pro X to export and import FCPXML documents to accomplish the following tasks:

• Exchange Final Cut Pro X event and project data with other applications.
• Create new Final Cut Pro X events and projects.

The Key Features of this extension include:

• Access an FCPXML document’s resources, events, clips, and projects through simple object properties.
• Create and modify resources, events, clips, and projects with included properties and methods.
• Easily manipulate timing values.
• Output FCPXML files with proper text formatting.
• Validate FCPXML documents with the DTD.

Here is a list of Final Cut Pro X terms used in this extension:

• A clip is a reference to media, such as a video, audio, or still image file, that allows you to edit and annotate the media without directly modifying it. A clip controls which portions of the media you would like to use, and it allows you to organize the media based on keywords you have applied. Clips can also contain other clips to represent composite media.
• Use a Final Cut Pro X project and its primary container, a sequence, to build a finished movie. The sequence defines your movie’s final appearance. You build a sequence by bringing clips into it from one or more events, or by creating new clips within the sequence. You adjust and arrange the clips, along with other story elements in the sequence, to produce your movie. Every clip in a project is unique to that project (not shared), but referenced media always resides in an event and may be shared across more than one project.
• Use a Final Cut Pro X event to store and organize clips and projects. You can import media files into a new or existing event. You can copy these files into an event’s own media folder, or reference them in their original locations. Final Cut Pro X tracks each imported file as an asset and ensures your event contains at least one clip per asset.
• Use a Final Cut Pro X library to organize your events. The library is a container that you use to keep track of all events, projects, and media related to your work.

This extension was inspired and uses code based on Pipeline. Thank you Reuel Kim for making something truly awesome, and releasing it as Open Source!

Submodules

• cp.apple.fcpxml.compoundClip
• cp.apple.fcpxml.event
• cp.apple.fcpxml.gap
• cp.apple.fcpxml.multicamClip
• cp.apple.fcpxml.multicamResource
• cp.apple.fcpxml.project
• cp.apple.fcpxml.resource
• cp.apple.fcpxml.secondaryStoryline
• cp.apple.fcpxml.title

API Overview

• Constants - Useful values which cannot be changed
• ANCHOR_ITEMS
• AUDIO_FADE_TYPE
• AUDIO_OUTPUT_CHANNEL
• AUDIO_SAMPLE_RATE
• CLIP_ITEMS
• COLLECTION_TYPES
• COLOR_SPACE
• COLOR_SPACE_OVERRIDE
• EQ_MODE
• EVENT_ITEM_TYPES
• FIELD_ORDER
• MARKER_ITEMS
• METADATA_TYPES
• PROJECTION
• PROJECTION_OVERRIDE
• RESOURCE_TYPES
• STEREOSCOPIC
• STEREOSCOPIC_OVERRIDE
• TIMECODE_FORMAT
• Functions - API calls offered directly by the extension
• latestDTDVersion
• supportedDTDs
• Constructors - API calls which return an object, typically one that offers API methods
• new
• newCompoundClip
• newEvent
• newGap
• newMulticamClip
• newMulticamResource
• newProject
• newResource
• newSecondaryStoryline
• newTitle
• open
• Methods - API calls which can only be made on an object returned by a constructor
• add
• allClips
• allEventItemNames
• allEventItems
• allProjectNames
• allProjects
• assetResources
• compoundResources
• effectResources
• eventNames
• events
• formatResources
• lastResourceID
• lastTextStyleID
• library
• multicamResources
• remove
• removeAllEvents
• removeAllResources
• resource
• resources
• roles
• saveToFile
• valid
• xmlVersion

API Documentation

Constants

ANCHOR_ITEMS

Signature	cp.apple.fcpxml.ANCHOR_ITEMS -> table
Type	Constant
Description	Supported Anchor Item Values. The 'anchor_item' entity declares the valid anchorable story elements. When present, anchored items must have a non-zero 'lane' value.

AUDIO_FADE_TYPE

Signature	cp.apple.fcpxml.AUDIO_FADE_TYPE -> table
Type	Constant
Description	Supported Audio Fade Type Values.

AUDIO_OUTPUT_CHANNEL

Signature	cp.apple.fcpxml.AUDIO_OUTPUT_CHANNEL -> table
Type	Constant
Description	Supported Audio Output Channel Values.

AUDIO_SAMPLE_RATE

Signature	cp.apple.fcpxml.AUDIO_SAMPLE_RATE -> table
Type	Constant
Description	Supported Audio Sample Rate values.

CLIP_ITEMS

Signature	cp.apple.fcpxml.CLIP_ITEMS -> table
Type	Constant
Description	Supported Clip Item Values. The 'clip_item' entity declares the primary story elements that may appear inside a clip.

COLLECTION_TYPES

Signature	cp.apple.fcpxml.COLLECTION_TYPES -> table
Type	Constant
Description	Supported Collection Types in FCPXML Documents.

COLOR_SPACE

Signature	cp.apple.fcpxml.COLOR_SPACE -> table
Type	Constant
Description	Supported Field Order values.

COLOR_SPACE_OVERRIDE

Signature	cp.apple.fcpxml.COLOR_SPACE_OVERRIDE -> table
Type	Constant
Description	Supported Color Space Override values.

EQ_MODE

Signature	cp.apple.fcpxml.EQ_MODE -> table
Type	Constant
Description	Supported EQ Mode Values.

EVENT_ITEM_TYPES

Signature	cp.apple.fcpxml.EVENT_ITEM_TYPES -> table
Type	Constant
Description	Supported Event Item Types in FCPXML Documents.

FIELD_ORDER

Signature	cp.apple.fcpxml.FIELD_ORDER -> table
Type	Constant
Description	Supported Field Order values.

MARKER_ITEMS

Signature	cp.apple.fcpxml.MARKER_ITEMS -> table
Type	Constant
Description	Supported Marker Item Values.

METADATA_TYPES

Signature	cp.apple.fcpxml.METADATA_TYPES -> table
Type	Constant
Description	Supported Metadata Types in FCPXML Documents.

PROJECTION

Signature	cp.apple.fcpxml.PROJECTION -> table
Type	Constant
Description	Supported Projection values.

PROJECTION_OVERRIDE

Signature	cp.apple.fcpxml.PROJECTION_OVERRIDE -> table
Type	Constant
Description	Supported Projection Override values.

RESOURCE_TYPES

Signature	cp.apple.fcpxml.RESOURCE_TYPES -> table
Type	Constant
Description	Supported Resource Types in FCPXML Documents.

STEREOSCOPIC

Signature	cp.apple.fcpxml.STEREOSCOPIC -> table
Type	Constant
Description	Supported Stereoscopic values.

STEREOSCOPIC_OVERRIDE

Signature	cp.apple.fcpxml.STEREOSCOPIC_OVERRIDE -> table
Type	Constant
Description	Supported Stereoscopic Override values.

TIMECODE_FORMAT

Signature	cp.apple.fcpxml.TIMECODE_FORMAT -> table
Type	Constant
Description	Supported Timecode Format values.

Functions

latestDTDVersion

Signature	cp.apple.fcpxml.latestDTDVersion() -> string
Type	Function
Description	Gets the latest supported FCPXML DTD version.
Parameters	None
Returns	The latest DTD version as a string, for example: "1.8".

supportedDTDs

Signature	cp.apple.fcpxml.supportedDTDs() -> table
Type	Function
Description	Returns a table containing the version numbers of all the DTD documents included in this extension.
Parameters	None
Returns	A table of supported DTD versions as strings.

Constructors

new

Signature	cp.apple.fcpxml.new() -> fcpxmlDocument Object
Type	Constructor
Description	Create a new empty FCPXML Document object.
Parameters	None
Returns	A new FCPXML object.

newCompoundClip

Signature	cp.apple.fcpxml.newCompoundClip(name, ref, offset, duration, startTimecode, useAudioSubroles) -> fcpxmlCompoundClip Object
Type	Constructor
Description	Creates a new ref-clip FCPXML Document object.
Parameters	name - The name of the Compound Clip as string. ref - The reference ID of the compound clip as string. offset - The offset of the compound clip in flicks. duration - The duration of the compound clip in flicks. startTimecode - The start timecode in flicks. useAudioSubroles - A boolean.
Returns	A new Compound Clip object.

newEvent

Signature	cp.apple.fcpxml.newEvent(name[, items]) -> fcpxmlEvent Object
Type	Constructor
Description	Creates a new event object.
Parameters	name - The name of the event. items - An optional table of items to add to the event.
Returns	A new event object.

newGap

Signature	cp.apple.fcpxml.newGap(offset, duration, startTimecode) -> fcpxmlGap Object
Type	Constructor
Description	Creates a new gap to be used in a timeline.
Parameters	offset - The offset of the Gap clip in flicks. duration - The duration of the Gap clip in flicks. startTimecode - The start timecode of the Gap clip in flicks.
Returns	A new Gap Clip object.

newMulticamClip

Signature	cp.apple.fcpxml.newMulticamClip(name, refID, offset, startTimecode, duration, mcSources) -> fcpxmlMulticamClip Object
Type	Constructor
Description	Creates a new multicam event clip FCPXML Document object.
Parameters	name - The name of the Multicam Clip as a string. refID - The reference ID of the Multicam Clip. offset - The offset of the Multicam clip in flicks. startTimecode - The start timecode in flicks. duration - The duration of the Multicam clip. mcSources - A table of multicam sources.
Returns	A new Multicam Clip object.

newMulticamResource

Signature	cp.apple.fcpxml.newMulticamResource(name, id, formatRef, startTimecode, timecodeFormat, renderColorSpace, angles) -> fcpxmlMulticamResource Object
Type	Constructor
Description	Creates a new FCPXML multicam reference FCPXML Document object.
Parameters	name - The name of the Multicam Resource as a string. id - The ID of the Multicam Resource as a string. formatRef - The format of the Multicam Resource. startTimecode - The start timecode in flicks. timecodeFormat - The timecode format (see: cp.apple.fcpxml.TIMECODE_FORMAT). renderColorSpace - The render color space (see: cp.apple.fcpxml.COLOR_SPACE). angles - A table of angle objects.
Returns	A new Multicam Resource object.

newProject

Signature	cp.apple.fcpxml.newProject(name, format, duration, timecodeStart, timecodeFormat, audioLayout, audioRate, renderColorSpace[, clips]) -> fcpxmlProject Object
Type	Constructor
Description	Creates a new project FCPXML object and optionally adds clips to it.
Parameters	name - The name of the project as a string. format - The format of the project. duration - The duration of the project. timecodeStart - The start timecode of the project. timecodeFormat - The timecode format of the project. audioLayout - The audio layout of the project. audioRate - The audio sample rate of the project. renderColorSpace - The render color space of the project. clips - An optional table of clips you want to add to the project.
Returns	A new project object.

newResource

Signature	cp.apple.fcpxml.newResource() -> fcpxmlResource Object
Type	Constructor
Description	Creates a new resource object.
Parameters	None
Returns	A new resource object.

newSecondaryStoryline

Signature	cp.apple.fcpxml.newSecondaryStoryline(lane, offset, formatRef, clips) -> fcpxmlSecondaryStoryline Object
Type	Constructor
Description	Creates a new secondary storyline FCPXML Document object.
Parameters	lane - The lane you want the secondary storyline to appear. offset - The offset of the secondary storyline in flicks. formatRef - The format of the secondary storyline. clips - A table of clips.
Returns	A new Secondary Storyline object.

newTitle

Signature	cp.apple.fcpxml.newTitle(titleName, lane, offset, ref, duration, start, role, titleText, textStyleID, newTextStyle, newTextStyleAttributes) -> fcpxmlTitle Object
Type	Constructor
Description	Creates a new title to be used in a timeline.
Parameters	titleName lane offset ref duration start role titleText textStyleID newTextStyle newTextStyleAttributes
Returns	A new Title object.
Notes	newTextStyleAttributes is only used if newTextStyle is set to true. When newTextStyle is set to true, the following atttributes can be used within the newTextStyleAttributes table: font - The font name as string (defaults to "Helvetica"). fontSize - The font size a number (defaults to 62). fontFace - The font face as a string (defaults to "Regular"). fontColor - The font color as a hs.drawing.color object (defaults to black). strokeColor - The stroke color as a hs.drawing.color object (defaults to nil). strokeWidth - The stroke width as a number (defaults to 2). shadowColor - The stroke color as a hs.drawing.color object (defaults to nil). shadowDistance - The shadow distance as a number (defaults to 5). shadowAngle - The shadow angle as a number (defaults to 315). shadowBlurRadius - The shadow blur radius as a number (defaults to 1). alignment - The text alignment as a string (defaults to "center"). xPosition - The x position of the title (defaults to 0). yPosition - The y position of the title (defaults to 0).

open

Signature	cp.apple.fcpxml.open(file) -> fcpxmlDocument Object
Type	Constructor
Description	Create a new FCPXML Document object from the specified file.
Parameters	file - An FCPXML document you want to read from an external file.
Returns	A new FCPXML object.

Methods

add

Signature	cp.apple.fcpxml:add(resources) -> boolean
Type	Method
Description	Adds one or more resources to the FCPXML document.
Parameters	resources - A single resourceObject or a table of resourceObject's to add to the FCPXML document.
Returns	true if successfully added, otherwise false.

allClips

Signature	cp.apple.fcpxml:allClips() -> table
Type	Method
Description	An table of all clips in all events in the FCPXML document.
Parameters	None
Returns	A table

allEventItemNames

Signature	cp.apple.fcpxml:allEventItemNames() -> table
Type	Method
Description	The names of all items from all events.
Parameters	None
Returns	A table

allEventItems

Signature	cp.apple.fcpxml:allEventItems() -> table
Type	Method
Description	All items from all events.
Parameters	None
Returns	A table

allProjectNames

Signature	cp.apple.fcpxml:allProjectNames() -> table
Type	Method
Description	The names of all projects from all events.
Parameters	None
Returns	A table

allProjects

Signature	cp.apple.fcpxml:allProjects() -> table
Type	Method
Description	An table of all projects in all events in the FCPXML document.
Parameters	None
Returns	A table

assetResources

| Signature | cp.apple.fcpxml:assetResources(file) -> table | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns asset resources that match the given file. | | Parameters |

• file - The file path.

| | Returns |

• A table of resource objects or nil if no assets match.

|

compoundResources

Signature	cp.apple.fcpxml:compoundResources() -> table
Type	Method
Description	An table of all compound clip resources in the FCPXML document.
Parameters	None
Returns	A table

effectResources

Signature	cp.apple.fcpxml:effectResources() -> table
Type	Method
Description	An table of all effect resources in the FCPXML document.
Parameters	None
Returns	A table

eventNames

Signature	cp.apple.fcpxml:eventNames() -> table
Type	Method
Description	The names of all events as strings in a table.
Parameters	None
Returns	A table containing all of the event names as strings.

events

Signature	cp.apple.fcpxml:events() -> table
Type	Method
Description	An table of all event elements in the FCPXML document.
Parameters	None
Returns	A table

formatResources

Signature	cp.apple.fcpxml:formatResources() -> table
Type	Method
Description	An table of all format resources in the FCPXML document.
Parameters	None
Returns	A table

lastResourceID

Signature	cp.apple.fcpxml:lastResourceID() -> number
Type	Method
Description	The highest resource ID number used in the FCPXML document.
Parameters	None
Returns	A number

lastTextStyleID

Signature	cp.apple.fcpxml:lastTextStyleID() -> number
Type	Method
Description	The highest text style ID number used in the FCPXML document.
Parameters	None
Returns	A number

library

Signature	cp.apple.fcpxml:library() -> libraryObject
Type	Method
Description	Gets the Final Cut Pro Library.
Parameters	None
Returns	A libraryObject

multicamResources

Signature	cp.apple.fcpxml:multicamResources() -> table
Type	Method
Description	An table of all multicam resources in the FCPXML document.
Parameters	None
Returns	A table

remove

Signature	cp.apple.fcpxml:remove(resources) -> boolean
Type	Method
Description	Removes one or more resources from the FCPXML document.
Parameters	resources - A single resourceObject or a table of resourceObject's to add to the FCPXML document.
Returns	true if successfully removed, otherwise false.

removeAllEvents

Signature	cp.apple.fcpxml:removeAllEvents() -> boolean
Type	Method
Description	Removes all events from the library.
Parameters	None
Returns	true if successful, otherwise false.

removeAllResources

Signature	cp.apple.fcpxml:removeAllResources() -> boolean
Type	Method
Description	Removes all resources from the FCPXML document.
Parameters	None
Returns	true if successful, otherwise false.

resource

| Signature | cp.apple.fcpxml:resource(id) -> resourceObject | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Returns the resource that matches the given ID string. | | Parameters |

• id - The ID string of the resource you want to access.

| | Returns |

• A resource object or nil if the resource does not exist.

|

resources

Signature	cp.apple.fcpxml:resources() -> table
Type	Method
Description	An table of all resources in the FCPXML document.
Parameters	None
Returns	A table

roles

Signature	cp.apple.fcpxml:roles() -> table
Type	Method
Description	An table of all roles used in the FCPXML document.
Parameters	None
Returns	A table

saveToFile

Signature	cp.apple.fcpxml:saveToFile(filename) -> boolean
Type	Method
Description	Saves the FCPML Document to the specified filename.
Parameters	filename - the path and name of the file to save.
Returns	Status - a boolean value indicating success (true) or failure (false).

valid

Signature	cp.apple.fcpxml:valid(filename[, version]) -> boolean
Type	Method
Description	Validates an FCPXML document against a document type definition (DTD).
Parameters	filename - The path and filename of the FCPXML document you want to validate. version - The optional FCPXML version you want to validate against.
Returns	true if valid, otherwise false.

xmlVersion

Signature	cp.apple.fcpxml:xmlVersion([version]) -> string
Type	Method
Description	Gets or sets the FCPXML version of the FCPXML document.
Parameters	version - An optional string to set the version of the FCPXML document (for example: "1.8").
Returns	A string containing the XML version of the FCPXML document.