finalcutpro

​
Represents the Final Cut Pro application, providing functions that allow different tasks to be accomplished.
Generally, you will require the cp.apple.finalcutpro module to import it, like so:
local fcp = require "cp.apple.finalcutpro"
Then, there are the UpperCase files, which represent the application itself:
MenuBar - The main menu bar.
prefs/PreferencesWindow - The preferences window.
etc...
The fcp variable is the root application. It has functions which allow you to perform tasks or access parts of the UI. For example, to open the Preferences window, you can do this:
fcp.preferencesWindow:show()
In general, as long as Final Cut Pro is running, actions can be performed directly, and the API will perform the required operations to achieve it. For example, to toggle the 'Create Optimized Media' checkbox in the 'Import' section of the 'Preferences' window, you can simply do this:
fcp.preferencesWindow.importPanel:toggleCreateOptimizedMedia()
The API will automatically open the Preferences window, navigate to the 'Import' panel and toggle the checkbox.
The UpperCase classes also have a variety of UI methods. These will return the axuielement for the relevant GUI element, if it is accessible. If not, it will return nil. These allow direct interaction with the GUI if necessary. It's most useful when adding new functions to UpperCase files for a particular element.
This can also be used to 'wait' for an element to be visible before performing a task. For example, if you need to wait for the Preferences window to finish loading before doing something else, you can do this with the just library:
local just = require "cp.just"
​
local prefsWindow = fcp.preferencesWindow
​
local prefsUI = just.doUntil(function() return prefsWindow:UI() end)
​
if prefsUI then
	-- it's open!
else
	-- it's closed!
end
By using the just library, we can do a loop waiting until the function returns a result that will give up after a certain time period (10 seconds by default).
Of course, we have a specific support function for that already, so you could do this instead:
if fcp.preferencesWindow:isShowing() then
	-- it's open!
else
	-- it's closed!
end
Delegates to: app, menu​
Note: All values/methods/props from delegates can be accessed directly from the cp.apple.finalcutpro instance. For example:
fcp.app:UI() == fcp:UI() -- the same `cp.prop` result.
Submodules
​cp.apple.finalcutpro.app​
​cp.apple.finalcutpro.browser​
​cp.apple.finalcutpro.cmd​
​cp.apple.finalcutpro.content​
​cp.apple.finalcutpro.export​
​cp.apple.finalcutpro.import​
​cp.apple.finalcutpro.inspector​
​cp.apple.finalcutpro.main​
​cp.apple.finalcutpro.menu​
​cp.apple.finalcutpro.plugins​
​cp.apple.finalcutpro.prefs​
​cp.apple.finalcutpro.strings​
​cp.apple.finalcutpro.timeline​
​cp.apple.finalcutpro.viewer​
API Overview
Constants - Useful values which cannot be changed
​ALLOWED_IMPORT_AUDIO_EXTENSIONS​
​ALLOWED_IMPORT_EXTENSIONS​
​ALLOWED_IMPORT_IMAGE_EXTENSIONS​
​ALLOWED_IMPORT_VIDEO_EXTENSIONS​
​EARLIEST_SUPPORTED_VERSION​
​EVENT_DESCRIPTION_PATH​
​FLEXO_LANGUAGES​
​PASTEBOARD_UTI​
​preferences​
​WORKSPACES_PATH​
Variables - Configurable values
​activeCommandSet​
​customWorkspaces​
​openAndSavePanelDefaultPath​
​selectedWorkspace​
Functions - API calls offered directly by the extension
​commandSet​
​matches​
​matches​
​userCommandSetPath​
​workflowExtensions​
Constructors - API calls which return an object, typically one that offers API methods
​Color​
​TranscodeMedia​
Fields - Variables which can only be accessed from an object returned by a constructor
​activeCommandSetPath​
​alert​
​audioEnhancements​
​audioLanes​
​backgroundTasksDialog​
​browser​
​color​
​colorBoard​
​colorCorrection​
​commandEditor​
​contentUI​
​contentUI​
​deselectAll​
​effects​
​effects​
​eventViewer​
​exportDialog​
​findAndReplaceTitleText​
​fullScreenWindow​
​generators​
​inspector​
​inspectorUnits​
​isFrontmost​
​isInstalled​
​isModalDialogOpen​
​isPlaying​
​isPlaying​
​isRunning​
​isShowing​
​isSupported​
​isUnsupported​
​keywordEditor​
​libraries​
​media​
​mediaImport​
​pan​
​preferencesWindow​
​preset​
​primaryWindow​
​resetDialogWarnings​
​secondaryWindow​
​textArea​
​textLayerLeft​
​textLayerRight​
​timeDisplay​
​timeline​
​toolbar​
​transcodeMedia​
​transitions​
​UI​
​validateAudioUnits​
​viewer​
​volume​
​windowsUI​
Methods - API calls which can only be made on an object returned by a constructor
​activeLibraryPaths​
​closeLibrary​
​defaultCommandSetPath​
​doShortcut​
​getCommandShortcuts​
​getPath​
​hide​
​importXML​
​isSupportedLocale​
​keysWithString​
​launch​
​openLibrary​
​plugins​
​quit​
​recentLibraryNames​
​recentLibraryPaths​
​scanPlugins​
​selectLibrary​
​show​
​string​
​userCommandSets​
API Documentation
Constants
​ALLOWED_IMPORT_AUDIO_EXTENSIONS​
Signature
cp.apple.finalcutpro.ALLOWED_IMPORT_AUDIO_EXTENSIONS -> table
Type
Constant
Description
Table of audio file extensions Final Cut Pro can import.
​ALLOWED_IMPORT_EXTENSIONS​
Signature
cp.apple.finalcutpro.ALLOWED_IMPORT_EXTENSIONS -> table
Type
Constant
Description
Table of all file extensions Final Cut Pro can import.
​ALLOWED_IMPORT_IMAGE_EXTENSIONS​
Signature
cp.apple.finalcutpro.ALLOWED_IMPORT_IMAGE_EXTENSIONS -> table
Type
Constant
Description
Table of image file extensions Final Cut Pro can import.
​ALLOWED_IMPORT_VIDEO_EXTENSIONS​
Signature
cp.apple.finalcutpro.ALLOWED_IMPORT_VIDEO_EXTENSIONS -> table
Type
Constant
Description
Table of video file extensions Final Cut Pro can import.
​EARLIEST_SUPPORTED_VERSION​
Signature
cp.apple.finalcutpro.EARLIEST_SUPPORTED_VERSION -> string
Type
Constant
Description
The earliest version of Final Cut Pro supported by this module.
​EVENT_DESCRIPTION_PATH​
Signature
cp.apple.finalcutpro.EVENT_DESCRIPTION_PATH -> string
Type
Constant
Description
The Event Description Path.
​FLEXO_LANGUAGES​
Signature
cp.apple.finalcutpro.FLEXO_LANGUAGES -> table
Type
Constant
Description
Table of Final Cut Pro's supported Languages for the Flexo Framework
​PASTEBOARD_UTI​
Signature
cp.apple.finalcutpro.PASTEBOARD_UTI -> string
Type
Constant
Description
Final Cut Pro's Pasteboard UTI
​preferences​
Signature
cp.apple.finalcutpro.preferences <cp.app.prefs>
Type
Constant
Description
The cp.app.prefs for Final Cut Pro.
​WORKSPACES_PATH​
Signature
cp.apple.finalcutpro.WORKSPACES_PATH -> string
Type
Constant
Description
The path to the custom workspaces folder.
Variables
​activeCommandSet​
Signature
cp.apple.finalcutpro.activeCommandSet <cp.prop: table; live>
Type
Variable
Description
Contins the 'Active Command Set' as a table. The result is cached, but
​customWorkspaces​
Signature
cp.apple.finalcutpro:customWorkspaces <cp.prop: table; live>
Type
Variable
Description
A table containing the display names of all the user created custom workspaces.
​openAndSavePanelDefaultPath​
Signature
cp.apple.finalcutpro:openAndSavePanelDefaultPath <cp.prop: string>
Type
Variable
Description
A string containing the default open/save panel path.
​selectedWorkspace​
Signature
cp.apple.finalcutpro.selectedWorkspace <cp.prop: string; live>
Type
Variable
Description
The currently selected workspace name. The result is cached, but updated
Functions
​commandSet​
Signature
cp.apple.finalcutpro.commandSet(path) -> string
Type
Function
Description
Gets the Command Set at the specified path as a table.
Parameters
path - The path to the Command Set.
Returns
The Command Set as a table, or nil if there was a problem.
​matches​
Signature
cp.apple.finalcutpro.main.CommandEditor.matches(element) -> boolean
Type
Function
Description
Checks to see if an element matches what we think it should be.
Parameters
element - An axuielementObject to check.
Returns
true if matches otherwise false
​matches​
Signature
cp.apple.finalcutpro.viewer.TranscodeMedia.matches(element) -> boolean
Type
Function
Description
Checks if the element is an TranscodeMedia instance.
Parameters
element - The axuielement to check.
Returns
true if it matches the pattern for a Viewer TranscodeMedia.
​userCommandSetPath​
Signature
cp.apple.finalcutpro.userCommandSetPath() -> string or nil
Type
Function
Description
Gets the path where User Command Set files are stored.
Parameters
None
Returns
A path as a string or nil if the folder doesn't exist.
​workflowExtensions​
Signature
cp.apple.finalcutpro.workflowExtensions() -> table
Type
Function
Description
Gets the names of all the installed Workflow Extensions.
Parameters
None
Returns
A table of Workflow Extension names
Constructors
​Color​
Signature
cp.apple.finalcutpro.main.Color(app) -> Color
Type
Constructor
Description
Creates a new Color instance.
Parameters
app - The Final Cut Pro app instance.
Returns
The new Color.
​TranscodeMedia​
Signature
cp.apple.finalcutpro.viewer.TranscodeMedia(viewer)
Type
Constructor
Description
Creates a new TranscodeMedia instance.
Parameters
parent - The parent object.
Returns
The new TranscodeMedia.
Fields
​activeCommandSetPath​
Signature
cp.apple.finalcutpro.activeCommandSetPath <cp.prop: string>
Type
Field
Description
Gets the 'Active Command Set' value from the Final Cut Pro preferences
​alert​
Signature
cp.apple.finalcutpro.alert <cp.ui.Alert>
Type
Field
Description
Provides basic access to any 'alert' dialog windows in the app.
​audioEnhancements​
Signature
cp.apple.finalcutpro.inspector.color.VideoInspector.audioEnhancements <cp.prop: PropertyRow>
Type
Field
Description
Audio Enhancements
​audioLanes​
Signature
cp.apple.finalcutpro.timeline.audioLanes <cp.prop: boolean>
Type
Field
Description
Indicates if audio lanes are currently showing. May be set to ensure it is showing or hidden.
​backgroundTasksDialog​
Signature
cp.apple.finalcutpro.backgroundTasksDialog <cp.apple.finalcutpro.main.BackgroundTasksDialog>
Type
Field
Description
The BackgroundTasksDialog dialog window.
​browser​
Signature
cp.apple.finalcutpro.browser <cp.apple.finalcutpro.main.Browser>
Type
Field
Description
The Browser instance, whether it is in the primary or secondary window.
​color​
Signature
cp.apple.finalcutpro.color <ColorInspector>
Type
Field
Description
The ColorInspector instance from the primary window
​colorBoard​
Signature
cp.apple.finalcutpro.colorBoard <ColorBoard>
Type
Field
Description
The ColorBoard instance from the primary window
​colorCorrection​
Signature
cp.apple.finalcutpro.presfs.GeneralPanel.colorCorrection <cp.ui.PopUpButton>
Type
Field
Description
The "Color Correction" PopUpButton.
​commandEditor​
Signature
cp.apple.finalcutpro.commandEditor <CommandEditor>
Type
Field
Description
The Final Cut Pro Command Editor
​contentUI​
Signature
cp.apple.finalcutpro.inspector.color.ShareInspector.contentUI <cp.prop: hs._asm.axuielement; read-only>
Type
Field
Description
The axuielement containing the properties rows, if available.
​contentUI​
Signature
cp.apple.finalcutpro.inspector.color.TextInspector.contentUI <cp.prop: hs._asm.axuielement; read-only>
Type
Field
Description
The axuielement containing the properties rows, if available.
​deselectAll​
Signature
cp.apple.finalcutpro.inspector.color.TextInspector.deselectAll <cp.ui.Button>
Type
Field
Description
The left text layer arrow at the bottom of the Inspector.
​effects​
Signature
cp.apple.finalcutpro.inspector.color.VideoInspector.effects <cp.prop: PropertyRow>
Type
Field
Description
Effects
​effects​
Signature
cp.apple.finalcutpro.effects <cp.apple.finalcutpro.main.EffectsBrowser>
Type
Field
Description
The EffectsBrowser instance, whether it is in the primary or secondary window.
​eventViewer​
Signature
cp.apple.finalcutpro.eventViewer <cp.apple.finalcutpro.viewer.Viewer>
Type
Field
Description
The Event Viewer instance, whether it is in the primary or secondary window.
​exportDialog​
Signature
cp.apple.finalcutpro.exportDialog <cp.apple.finalcutpro.main.ExportDialog>
Type
Field
Description
The Final Cut Pro Export Dialog Box
​findAndReplaceTitleText​
Signature
cp.apple.finalcutpro.findAndReplaceTitleText <cp.apple.finalcutpro.main.FindAndReplaceTitleText>
Type
Field
Description
The FindAndReplaceTitleText dialog window.
​fullScreenWindow​
Signature
cp.apple.finalcutpro.fullScreenWindow <FullScreenWindow>
Type
Field
Description
Returns the Final Cut Pro Full Screen Window (usually triggered by Cmd+Shift+F)
​generators​
Signature
cp.apple.finalcutpro.generators <cp.apple.finalcutpro.main.GeneratorsBrowser>
Type
Field
Description
The GeneratorsBrowser instance, whether it is in the primary or secondary window.
​inspector​
Signature
cp.apple.finalcutpro.inspector <cp.apple.finalcutpro.inspector.Inspector>
Type
Field
Description
The Inspector instance from the primary window.
​inspectorUnits​
Signature
cp.apple.finalcutpro.presfs.GeneralPanel.inspectorUnits <cp.ui.PopUpButton>
Type
Field
Description
The "Inspector Units" PopUpButton.
​isFrontmost​
Signature
cp.apple.finalcutpro:isFrontmost <cp.prop: boolean; read-only; live>
Type
Field
Description
Is Final Cut Pro Frontmost?
​isInstalled​
Signature
cp.apple.finalcutpro.isInstalled <cp.prop: boolean; read-only>
Type
Field
Description
Is any version of Final Cut Pro Installed?
​isModalDialogOpen​
Signature
cp.apple.finalcutpro:isModalDialogOpen <cp.prop: boolean; read-only>
Type
Field
Description
Is a modal dialog currently open?
​isPlaying​
Signature
cp.apple.finalcutpro.main.Viewer.isPlaying <cp.prop: boolean>
Type
Field
Description
The 'playing' status of the viewer. If true, it is playing, if not it is paused.
​isPlaying​
Signature
cp.apple.finalcutpro.main.ControlBar.isPlaying <cp.prop: boolean>
Type
Field
Description
The 'playing' status of the viewer. If true, it is playing, if not it is paused.
​isRunning​
Signature
cp.apple.finalcutpro.isRunning <cp.prop: boolean; read-only>
Type
Field
Description
Is Final Cut Pro Running?
​isShowing​
Signature
cp.apple.finalcutpro.isShowing <cp.prop: boolean; read-only; live>
Type
Field
Description
Is Final Cut visible on screen?
​isSupported​
Signature
cp.apple.finalcutpro.isSupported <cp.prop: boolean; read-only; live>
Type
Field
Description
Is a supported version of Final Cut Pro installed?
​isUnsupported​
Signature
cp.apple.finalcutpro.isUnsupported <cp.prop: boolean; read-only>
Type
Field
Description
Is an unsupported version of Final Cut Pro installed?
​keywordEditor​
Signature
cp.apple.finalcutpro.keywordEditor <KeywordEditor>
Type
Field
Description
The Final Cut Pro Keyword Editor
​libraries​
Signature
cp.apple.finalcutpro.libraries <cp.apple.finalcutpro.main.LibrariesBrowser>
Type
Field
Description
The LibrariesBrowser instance, whether it is in the primary or secondary window.
​media​
Signature
cp.apple.finalcutpro.media <cp.apple.finalcutpro.main.MediaBrowser>
Type
Field
Description
The MediaBrowser instance, whether it is in the primary or secondary window.
​mediaImport​
Signature
cp.apple.finalcutpro.mediaImport <MediaImport>
Type
Field
Description
The Final Cut Pro Media Import Window
​pan​
Signature
cp.apple.finalcutpro.inspector.color.VideoInspector.pan <cp.prop: PropertyRow>
Type
Field
Description
Pan
​preferencesWindow​
Signature
cp.apple.finalcutpro.preferencesWindow <PreferencesWindow>
Type
Field

Submodules

API Overview

API Documentation

Constants

​ALLOWED_IMPORT_AUDIO_EXTENSIONS​

​ALLOWED_IMPORT_EXTENSIONS​

​ALLOWED_IMPORT_IMAGE_EXTENSIONS​

​ALLOWED_IMPORT_VIDEO_EXTENSIONS​

​EARLIEST_SUPPORTED_VERSION​

​EVENT_DESCRIPTION_PATH​

​FLEXO_LANGUAGES​

​PASTEBOARD_UTI​

​preferences​

​WORKSPACES_PATH​

Variables

​activeCommandSet​

​customWorkspaces​

​openAndSavePanelDefaultPath​

​selectedWorkspace​

Functions

​commandSet​

​matches​

​matches​

​userCommandSetPath​

​workflowExtensions​

Constructors

​Color​

​TranscodeMedia​

Fields

​activeCommandSetPath​

​alert​

​audioEnhancements​

​audioLanes​

​backgroundTasksDialog​

​browser​

​color​

​colorBoard​

​colorCorrection​

​commandEditor​

​contentUI​

​contentUI​

​deselectAll​

​effects​

​effects​

​eventViewer​

​exportDialog​

​findAndReplaceTitleText​

​fullScreenWindow​

​generators​

​inspector​

​inspectorUnits​

​isFrontmost​

​isInstalled​

​isModalDialogOpen​

​isPlaying​

​isPlaying​

​isRunning​

​isShowing​

​isSupported​

​isUnsupported​

​keywordEditor​

​libraries​

​media​

​mediaImport​

​pan​

​preferencesWindow​

ALLOWED_IMPORT_AUDIO_EXTENSIONS

ALLOWED_IMPORT_EXTENSIONS

ALLOWED_IMPORT_IMAGE_EXTENSIONS

ALLOWED_IMPORT_VIDEO_EXTENSIONS

EARLIEST_SUPPORTED_VERSION

EVENT_DESCRIPTION_PATH

FLEXO_LANGUAGES

PASTEBOARD_UTI

preferences

WORKSPACES_PATH

activeCommandSet

customWorkspaces

openAndSavePanelDefaultPath

selectedWorkspace

commandSet

matches

matches

userCommandSetPath

workflowExtensions

Color

TranscodeMedia

activeCommandSetPath

alert

audioEnhancements

audioLanes

backgroundTasksDialog

browser

color

colorBoard

colorCorrection

commandEditor

contentUI

contentUI

deselectAll

effects

effects

eventViewer

exportDialog

findAndReplaceTitleText

fullScreenWindow

generators

inspector

inspectorUnits

isFrontmost

isInstalled

isModalDialogOpen

isPlaying

isPlaying

isRunning

isShowing

isSupported

isUnsupported

keywordEditor

libraries

media

mediaImport

pan

preferencesWindow