Internationalisation
Bundled Plugins API
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

API Overview

API Documentation

Constants

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.
Signature
cp.apple.fcpxml.AUDIO_FADE_TYPE -> table
Type
Constant
Description
Supported Audio Fade Type Values.
Signature
cp.apple.fcpxml.AUDIO_OUTPUT_CHANNEL -> table
Type
Constant
Description
Supported Audio Output Channel Values.
Signature
cp.apple.fcpxml.AUDIO_SAMPLE_RATE -> table
Type
Constant
Description
Supported Audio Sample Rate values.
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.
Signature
cp.apple.fcpxml.COLLECTION_TYPES -> table
Type
Constant
Description
Supported Collection Types in FCPXML Documents.
Signature
cp.apple.fcpxml.COLOR_SPACE -> table
Type
Constant
Description
Supported Field Order values.
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.
Signature
cp.apple.fcpxml.EVENT_ITEM_TYPES -> table
Type
Constant
Description
Supported Event Item Types in FCPXML Documents.
Signature
cp.apple.fcpxml.FIELD_ORDER -> table
Type
Constant
Description
Supported Field Order values.
Signature
cp.apple.fcpxml.MARKER_ITEMS -> table
Type
Constant
Description
Supported Marker Item Values.
Signature
cp.apple.fcpxml.METADATA_TYPES -> table
Type
Constant
Description
Supported Metadata Types in FCPXML Documents.
Signature
cp.apple.fcpxml.PROJECTION -> table
Type
Constant
Description
Supported Projection values.
Signature
cp.apple.fcpxml.PROJECTION_OVERRIDE -> table
Type
Constant
Description
Supported Projection Override values.
Signature
cp.apple.fcpxml.RESOURCE_TYPES -> table
Type
Constant
Description
Supported Resource Types in FCPXML Documents.
Signature
cp.apple.fcpxml.STEREOSCOPIC -> table
Type
Constant
Description
Supported Stereoscopic values.
Signature
cp.apple.fcpxml.STEREOSCOPIC_OVERRIDE -> table
Type
Constant
Description
Supported Stereoscopic Override values.
Signature
cp.apple.fcpxml.TIMECODE_FORMAT -> table
Type
Constant
Description
Supported Timecode Format values.

Functions

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".
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.
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.
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.
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.
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.
Signature
cp.apple.fcpxml.newResource() -> fcpxmlResource Object
Type
Constructor
Description
Creates a new resource object.
Parameters
  • None
Returns
  • A new resource object.
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
Signature
cp.apple.fcpxml:allEventItemNames() -> table
Type
Method
Description
The names of all items from all events.
Parameters
  • None
Returns
  • A table
Signature
cp.apple.fcpxml:allEventItems() -> table
Type
Method
Description
All items from all events.
Parameters
  • None
Returns
  • A table
Signature
cp.apple.fcpxml:allProjectNames() -> table
Type
Method
Description
The names of all projects from all events.
Parameters
  • None
Returns
  • A table
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
| 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.
|
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
Signature
cp.apple.fcpxml:effectResources() -> table
Type
Method
Description
An table of all effect resources in the FCPXML document.
Parameters
  • None
Returns
  • A table
Signature
cp.apple.fcpxml:eventNames() -> table
Type
Method