Internationalisation
Bundled Plugins API
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:
1
local fcp = require "cp.apple.finalcutpro"
Copied!
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:
1
fcp.preferencesWindow:show()
Copied!
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:
1
fcp.preferencesWindow.importPanel:toggleCreateOptimizedMedia()
Copied!
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:
1
local just = require "cp.just"
2
3
local prefsWindow = fcp.preferencesWindow
4
5
local prefsUI = just.doUntil(function() return prefsWindow:UI() end)
6
7
if prefsUI then
8
-- it's open!
9
else
10
-- it's closed!
11
end
Copied!
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:
1
if fcp.preferencesWindow:isShowing() then
2
-- it's open!
3
else
4
-- it's closed!
5
end
Copied!
Delegates to: app, menu
Note: All values/methods/props from delegates can be accessed directly from the cp.apple.finalcutpro instance. For example:
1
fcp.app:UI() == fcp:UI() -- the same `cp.prop` result.
Copied!

Submodules

API Overview

API Documentation

Constants

Signature
cp.apple.finalcutpro.ALLOWED_IMPORT_AUDIO_EXTENSIONS -> table
Type
Constant
Description
Table of audio file extensions Final Cut Pro can import.
Signature
cp.apple.finalcutpro.ALLOWED_IMPORT_EXTENSIONS -> table
Type
Constant
Description
Table of all file extensions Final Cut Pro can import.
Signature
cp.apple.finalcutpro.ALLOWED_IMPORT_IMAGE_EXTENSIONS -> table
Type
Constant
Description
Table of image file extensions Final Cut Pro can import.
Signature
cp.apple.finalcutpro.ALLOWED_IMPORT_VIDEO_EXTENSIONS -> table
Type
Constant
Description
Table of video file extensions Final Cut Pro can import.
Signature
cp.apple.finalcutpro.EARLIEST_SUPPORTED_VERSION -> string
Type
Constant
Description
The earliest version of Final Cut Pro supported by this module.
Signature
cp.apple.finalcutpro.EVENT_DESCRIPTION_PATH -> string
Type
Constant
Description
The Event Description Path.
Signature
cp.apple.finalcutpro.FLEXO_LANGUAGES -> table
Type
Constant
Description
Table of Final Cut Pro's supported Languages for the Flexo Framework
Signature
cp.apple.finalcutpro.PASTEBOARD_UTI -> string
Type
Constant
Description
Final Cut Pro's Pasteboard UTI
Signature
cp.apple.finalcutpro.preferences <cp.app.prefs>
Type
Constant
Description
The cp.app.prefs for Final Cut Pro.
Signature
cp.apple.finalcutpro.WORKSPACES_PATH -> string
Type
Constant
Description
The path to the custom workspaces folder.

Variables

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
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.
Signature
cp.apple.finalcutpro:openAndSavePanelDefaultPath <cp.prop: string>
Type
Variable
Description
A string containing the default open/save panel path.
Signature
cp.apple.finalcutpro.selectedWorkspace <cp.prop: string; live>
Type
Variable
Description
The currently selected workspace name. The result is cached, but updated

Functions

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.
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.
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.
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

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.
Signature
cp.apple.finalcutpro.inspector.color.VideoInspector.audioEnhancements <cp.prop: PropertyRow>
Type
Field
Description
Audio Enhancements
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.
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
Signature
cp.apple.finalcutpro.colorBoard <ColorBoard>
Type
Field
Description
The ColorBoard instance from the primary window
Signature
cp.apple.finalcutpro.presfs.GeneralPanel.colorCorrection <cp.ui.PopUpButton>
Type
Field
Description
The "Color Correction" PopUpButton.
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.
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.
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.
Signature
cp.apple.finalcutpro.exportDialog <cp.apple.finalcutpro.main.ExportDialog>
Type
Field
Description
The Final Cut Pro Export Dialog Box
Signature
cp.apple.finalcutpro.findAndReplaceTitleText <cp.apple.finalcutpro.main.FindAndReplaceTitleText>
Type
Field
Description
The FindAndReplaceTitleText dialog window.
Signature
cp.apple.finalcutpro.fullScreenWindow <FullScreenWindow>
Type
Field
Description
Returns the Final Cut Pro Full Screen Window (usually triggered by Cmd+Shift+F)
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.
Signature
cp.apple.finalcutpro.presfs.GeneralPanel.inspectorUnits <cp.ui.PopUpButton>
Type
Field
Description
The "Inspector Units" PopUpButton.
Signature
cp.apple.finalcutpro:isFrontmost <cp.prop: boolean; read-only; live>
Type
Field
Description
Is Final Cut Pro Frontmost?
Signature
cp.apple.finalcutpro.isInstalled <cp.prop: boolean; read-only>
Type
Field
Description
Is any version of Final Cut Pro Installed?
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