cp.apple.finalcutpro.md

docs » cp.apple.finalcutpro

---

Represents the Final Cut Pro application, providing functions that allow different tasks to be accomplished.

This module provides an API to work with the FCPX application. There are a couple of types of files:

• init.lua - the main module that gets imported.
• axutils.lua - some utility functions for working with axuielement objects.

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

Submodules

• cp.apple.finalcutpro.MenuBar
• cp.apple.finalcutpro.WindowWatcher
• cp.apple.finalcutpro.cmd
• cp.apple.finalcutpro.content
• cp.apple.finalcutpro.export
• cp.apple.finalcutpro.ids
• cp.apple.finalcutpro.import
• cp.apple.finalcutpro.keycodes
• cp.apple.finalcutpro.main
• cp.apple.finalcutpro.plugins
• cp.apple.finalcutpro.prefs
• cp.apple.finalcutpro.windowfilter

API Overview

• Constants - Useful values which cannot be changed
• ALLOWED_IMPORT_AUDIO_EXTENSIONS
• ALLOWED_IMPORT_EXTENSIONS
• ALLOWED_IMPORT_IMAGE_EXTENSIONS
• ALLOWED_IMPORT_VIDEO_EXTENSIONS
• BUNDLE_ID
• EARLIEST_SUPPORTED_VERSION
• FLEXO_LANGUAGES
• PASTEBOARD_UTI
• PREFS_PATH
• PREFS_PLIST_FILE
• PREFS_PLIST_PATH
• SUPPORTED_LANGUAGES
• Functions - API calls offered directly by the extension
• init
• reset
• Fields - Variables which can only be accessed from an object returned by a constructor
• colorInspectorSupported
• currentLanguage
• getVersion
• isFrontmost
• isInstalled
• isModalDialogOpen
• isRunning
• isShowing
• isSupported
• isUnsupported
• Methods - API calls which can only be made on an object returned by a constructor
• application
• browser
• colorBoard
• colorInspector
• commandEditor
• effects
• eventViewer
• exportDialog
• fullScreenWindow
• generators
• getActiveCommandSet
• getActiveCommandSetPath
• getBundleID
• getCommandSet
• getCommandShortcuts
• getDefaultCommandSetPath
• getFlexoLanguages
• getPasteboardUTI
• getPath
• getPreference
• getPreferences
• getSupportedLanguage
• getSupportedLanguages
• hide
• importXML
• inspector
• isSupportedLanguage
• keysWithString
• launch
• libraries
• media
• mediaImport
• menuBar
• performShortcut
• plugins
• preferencesWindow
• primaryWindow
• quit
• restart
• scanPlugins
• secondaryWindow
• selectMenu
• setPreference
• show
• string
• timeline
• transitions
• UI
• unwatch
• viewer
• watch
• windowsUI

API Documentation

Constants

ALLOWED_IMPORT_AUDIO_EXTENSIONS

Signature	cp.apple.finalcutpro.ALLOWED_IMPORT_AUDIO_EXTENSIONS
Type	Constant
Description	Table of audio file extensions Final Cut Pro can import.

ALLOWED_IMPORT_EXTENSIONS

Signature	cp.apple.finalcutpro.ALLOWED_IMPORT_EXTENSIONS
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
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
Type	Constant
Description	Table of video file extensions Final Cut Pro can import.

BUNDLE_ID

Signature	cp.apple.finalcutpro.BUNDLE_ID
Type	Constant
Description	Final Cut Pro's Bundle ID

EARLIEST_SUPPORTED_VERSION

Signature	cp.apple.finalcutpro.EARLIEST_SUPPORTED_VERSION
Type	Constant
Description	The earliest version of Final Cut Pro supported by this module.

FLEXO_LANGUAGES

Signature	cp.apple.finalcutpro.FLEXO_LANGUAGES
Type	Constant
Description	Table of Final Cut Pro's supported Languages for the Flexo Framework

PASTEBOARD_UTI

Signature	cp.apple.finalcutpro.PASTEBOARD_UTI
Type	Constant
Description	Final Cut Pro's Pasteboard UTI

PREFS_PATH

Signature	cp.apple.finalcutpro.PREFS_PATH
Type	Constant
Description	Final Cut Pro's Preferences Path

PREFS_PLIST_FILE

Signature	cp.apple.finalcutpro.PREFS_PLIST_FILE
Type	Constant
Description	Final Cut Pro's Preferences File

PREFS_PLIST_PATH

Signature	cp.apple.finalcutpro.PREFS_PLIST_PATH
Type	Constant
Description	Final Cut Pro's Preferences Path

SUPPORTED_LANGUAGES

Signature	cp.apple.finalcutpro.SUPPORTED_LANGUAGES
Type	Constant
Description	Table of Final Cut Pro's supported Languages

Functions

init

Signature	cp.apple.finalcutpro:init() -> App
Type	Function
Description	Initialises the app instance representing Final Cut Pro.
Parameters	None
Returns	The app.

reset

Signature	cp.apple.finalcutpro:reset() -> none
Type	Function
Description	Resets the language cache
Parameters	None
Returns	None

Fields

colorInspectorSupported

Signature	cp.apple.finalcutpro:colorInspectorSupported <cp.prop: boolean; read-only>
Type	Field
Description	Is the Color Inspector supported in the installed version of Final Cut Pro?

currentLanguage

Signature	cp.apple.finalcutpro.currentLanguage <cp.prop:string>
Type	Field
Description	The current language the FCPX is displayed in.

getVersion

Signature	cp.apple.finalcutpro.getVersion <cp.prop: string; read-only>
Type	Field
Description	Version of Final Cut Pro as string.
Parameters	None
Returns	Version as string or nil if Final Cut Pro cannot be found.
Notes	If Final Cut Pro is running it will get the version of the active Final Cut Pro application as a string, otherwise, it will use hs.application.infoForBundleID() to find the version.

isFrontmost

Signature	cp.apple.finalcutpro:isFrontmost <cp.prop: boolean; read-only>
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?

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>
Type	Field
Description	Is Final Cut visible on screen?

isSupported

Signature	cp.apple.finalcutpro.isSupported <cp.prop: boolean; read-only>
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?

Methods

application

Signature	cp.apple.finalcutpro:application() -> hs.application
Type	Method
Description	Returns the running hs.application for Final Cut Pro.
Parameters	None
Returns	The hs.application, or nil if the application is not running.

browser

Signature	cp.apple.finalcutpro:browser() -> Browser
Type	Method
Description	Returns the Browser instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the Browser

colorBoard

Signature	cp.apple.finalcutpro:colorBoard() -> ColorBoard
Type	Method
Description	Returns the ColorBoard instance from the primary window
Parameters	None
Returns	the ColorBoard

colorInspector

Signature	cp.apple.finalcutpro:colorInspector() -> ColorInspector
Type	Method
Description	Returns the ColorInspector instance from the primary window
Parameters	None
Returns	the ColorInspector

commandEditor

Signature	cp.apple.finalcutpro:commandEditor() -> commandEditor object
Type	Method
Description	Returns the Final Cut Pro Command Editor
Parameters	None
Returns	The Final Cut Pro Command Editor

effects

Signature	cp.apple.finalcutpro:effects() -> EffectsBrowser
Type	Method
Description	Returns the EffectsBrowser instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the EffectsBrowser

eventViewer

Signature	cp.apple.finalcutpro:eventViewer() -> Event Viewer
Type	Method
Description	Returns the Event Viewer instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the Event Viewer

exportDialog

Signature	cp.apple.finalcutpro:exportDialog() -> exportDialog object
Type	Method
Description	Returns the Final Cut Pro Export Dialog Box
Parameters	None
Returns	The Final Cut Pro Export Dialog Box

fullScreenWindow

Signature	cp.apple.finalcutpro:fullScreenWindow() -> fullScreenWindow object
Type	Method
Description	Returns the Final Cut Pro Full Screen Window
Parameters	None
Returns	The Full Screen Playback Window

generators

Signature	cp.apple.finalcutpro:generators() -> GeneratorsBrowser
Type	Method
Description	Returns the GeneratorsBrowser instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the GeneratorsBrowser

getActiveCommandSet

Signature	cp.apple.finalcutpro:getActiveCommandSet([forceReload]) -> table or nil
Type	Method
Description	Returns the 'Active Command Set' as a Table. The result is cached, so pass in
Parameters	[forceReload] - If true, require the Command Set to be reloaded.
Returns	A table of the Active Command Set's contents, or nil if an error occurred

getActiveCommandSetPath

Signature	cp.apple.finalcutpro:getActiveCommandSetPath() -> string or nil
Type	Method
Description	Gets the 'Active Command Set' value from the Final Cut Pro preferences
Parameters	None
Returns	The 'Active Command Set' value, or the 'Default' command set if none is set.

getBundleID

Signature	cp.apple.finalcutpro:getBundleID() -> string
Type	Method
Description	Returns the Final Cut Pro Bundle ID
Parameters	None
Returns	A string of the Final Cut Pro Bundle ID

getCommandSet

Signature	cp.apple.finalcutpro:getCommandSet(path) -> string
Type	Method
Description	Loads the Command Set at the specified path into a table.
Parameters	path - The path to the command set.
Returns	The Command Set as a table, or nil if there was a problem.

getCommandShortcuts

Signature	cp.apple.finalcutpro.getCommandShortcuts(id) -> table of hs.commands.shortcut
Type	Method
Description	Finds a shortcut from the Active Command Set with the specified ID and returns a table
Parameters	id - The unique ID for the command.
Returns	The array of shortcuts, or nil if no command exists with the specified id.

getDefaultCommandSetPath

Signature	cp.apple.finalcutpro:getDefaultCommandSetPath([langauge]) -> string
Type	Method
Description	Gets the path to the 'Default' Command Set.
Parameters	[language] - The optional language code to use. Defaults to the current FCPX language.
Returns	The 'Default' Command Set path, or nil if an error occurred

getFlexoLanguages

Signature	cp.apple.finalcutpro:getFlexoLanguages() -> table
Type	Method
Description	Returns a table of languages Final Cut Pro's Flexo Framework supports
Parameters	None
Returns	A table of languages Final Cut Pro supports

getPasteboardUTI

Signature	cp.apple.finalcutpro:getPasteboardUTI() -> string
Type	Method
Description	Returns the Final Cut Pro Pasteboard UTI
Parameters	None
Returns	A string of the Final Cut Pro Pasteboard UTI

getPath

Signature	cp.apple.finalcutpro:getPath() -> string or nil
Type	Method
Description	Path to Final Cut Pro Application
Parameters	None
Returns	A string containing Final Cut Pro's filesystem path, or nil if Final Cut Pro's path could not be determined.

getPreference

Signature	cp.apple.finalcutpro:getPreference(value, [default], [forceReload]) -> string or nil
Type	Method
Description	Get an individual Final Cut Pro preference
Parameters	value - The preference you want to return [default] - The optional default value to return if the preference is not set. [forceReload] - If true, optionally forces a reload of the app's preferences.
Returns	A string with the preference value, or nil if an error occurred

getPreferences

Signature	cp.apple.finalcutpro:getPreferences([forceReload]) -> table or nil
Type	Method
Description	Gets Final Cut Pro's Preferences as a table. It checks if the preferences
Parameters	[forceReload] - If true, an optional reload will be forced even if the file hasn't been modified.
Returns	A table with all of Final Cut Pro's preferences, or nil if an error occurred

getSupportedLanguage

Signature	cp.apple.finalcutpro:getSupportedLanguage(language) -> boolean
Type	Method
Description	Checks if the provided language is supported by the app and returns the actual support code, or nil if there is no supported version of the language.
Parameters	language - The language code to check. E.g. "en" or "zh_CN"
Returns	true if the language is supported.

getSupportedLanguages

Signature	cp.apple.finalcutpro:getSupportedLanguages() -> table
Type	Method
Description	Returns a table of languages Final Cut Pro supports
Parameters	None
Returns	A table of languages Final Cut Pro supports

hide

Signature	cp.apple.finalcutpro:hide() -> cp.apple.finalcutpro
Type	Method
Description	Hides Final Cut Pro
Parameters	None
Returns	A cp.apple.finalcutpro otherwise nil

importXML

Signature	cp.apple.finalcutpro:importXML(path) -> boolean
Type	Method
Description	Imports an XML file into Final Cut Pro
Parameters	path = Path to XML File
Returns	A boolean value indicating whether the AppleScript succeeded or not

inspector

Signature	cp.apple.finalcutpro:inspector() -> Inspector
Type	Method
Description	Returns the Inspector instance from the primary window
Parameters	None
Returns	the Inspector

isSupportedLanguage

Signature	cp.apple.finalcutpro:isSupportedLanguage(language) -> boolean
Type	Method
Description	Checks if the provided language is supported by the app.
Parameters	language - The language code to check. E.g. "en" or "zh_CN"
Returns	true if the language is supported.

keysWithString

Signature	cp.apple.finalcutpro:keysWithString(string[, lang]) -> {string}
Type	Method
Description	Looks up an application string and returns an array of keys that match. It will take into account current language the app is running in, or use lang if provided.
Parameters	key - The key to look up. [lang] - The language (defaults to current FCPX language).
Returns	The array of keys with a matching string.
Notes	This method may be very inefficient, since it has to search through every possible key/value pair to find matches. It is not recommended that this is used in production.

launch

Signature	cp.apple.finalcutpro:launch() -> boolean
Type	Method
Description	Launches Final Cut Pro, or brings it to the front if it was already running.
Parameters	None
Returns	true if Final Cut Pro was either launched or focused, otherwise false (e.g. if Final Cut Pro doesn't exist)

libraries

Signature	cp.apple.finalcutpro:libraries() -> LibrariesBrowser
Type	Method
Description	Returns the LibrariesBrowser instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the LibrariesBrowser

media

Signature	cp.apple.finalcutpro:media() -> MediaBrowser
Type	Method
Description	Returns the MediaBrowser instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the MediaBrowser

mediaImport

Signature	cp.apple.finalcutpro:mediaImport() -> mediaImport object
Type	Method
Description	Returns the Final Cut Pro Media Import Window
Parameters	None
Returns	The Final Cut Pro Media Import Window

menuBar

Signature	cp.apple.finalcutpro:menuBar() -> menuBar object
Type	Method
Description	Returns the Final Cut Pro Menu Bar
Parameters	None
Returns	A MenuBar object

performShortcut

Signature	cp.apple.finalcutpro:performShortcut(whichShortcut) -> boolean
Type	Method
Description	Performs a Final Cut Pro Shortcut
Parameters	whichShortcut - As per the Command Set name
Returns	true if successful otherwise false

plugins

Signature	cp.apple.finalcutpro:plugins() -> cp.apple.finalcutpro.plugins
Type	Method
Description	Returns the plugins manager for the app.
Parameters	None
Returns	The plugins manager.

preferencesWindow

Signature	cp.apple.finalcutpro:preferencesWindow() -> preferenceWindow object
Type	Method
Description	Returns the Final Cut Pro Preferences Window
Parameters	None
Returns	The Preferences Window

primaryWindow

Signature	cp.apple.finalcutpro:primaryWindow() -> primaryWindow object
Type	Method
Description	Returns the Final Cut Pro Preferences Window
Parameters	None
Returns	The Primary Window

quit

Signature	cp.apple.finalcutpro:quit() -> cp.apple.finalcutpro
Type	Method
Description	Quits Final Cut Pro
Parameters	None
Returns	A cp.apple.finalcutpro otherwise nil

restart

Signature	cp.apple.finalcutpro:restart(waitUntilRestarted) -> boolean
Type	Method
Description	Restart Final Cut Pro
Parameters	waitUntilRestarted - If true, the function will not return until the app has restarted.
Returns	true if Final Cut Pro was running and restarted successfully.

scanPlugins

Signature	cp.apple.finalcutpro:scanPlugins() -> table
Type	Method
Description	Scan Final Cut Pro Plugins
Parameters	None
Returns	A MenuBar object

secondaryWindow

Signature	cp.apple.finalcutpro:secondaryWindow() -> secondaryWindow object
Type	Method
Description	Returns the Final Cut Pro Preferences Window
Parameters	None
Returns	The Secondary Window

selectMenu

Signature	cp.apple.finalcutpro:selectMenu(path) -> boolean
Type	Method
Description	Selects a Final Cut Pro Menu Item based on the list of menu titles in English.
Parameters	path - The list of menu items you'd like to activate, for example: select("View", "Browser", "as List")
Returns	true if the press was successful.

setPreference

Signature	cp.apple.finalcutpro:setPreference(key, value) -> boolean
Type	Method
Description	Sets an individual Final Cut Pro preference
Parameters	key - The preference you want to change value - The value you want to set for that preference
Returns	True if executed successfully otherwise False

show

Signature	cp.apple.finalcutpro:show() -> cp.apple.finalcutpro
Type	Method
Description	Activate Final Cut Pro
Parameters	None
Returns	A cp.apple.finalcutpro otherwise nil

string

Signature	cp.apple.finalcutpro:string(key[, lang]) -> string
Type	Method
Description	Looks up an application string with the specified key.
Parameters	key - The key to look up. [lang] - The language code to use. Defaults to the current language.
Returns	The requested string or nil if the application is not running.

timeline

Signature	cp.apple.finalcutpro:timeline() -> Timeline
Type	Method
Description	Returns the Timeline instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the Timeline

transitions

Signature	cp.apple.finalcutpro:transitions() -> TransitionsBrowser
Type	Method
Description	Returns the TransitionsBrowser instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the TransitionsBrowser

UI

Signature	cp.apple.finalcutpro:UI() -> axuielement
Type	Method
Description	Returns the Final Cut Pro axuielement
Parameters	None
Returns	A axuielementObject of Final Cut Pro

unwatch

Signature	cp.apple.finalcutpro:unwatch(id) -> boolean
Type	Method
Description	Stop watching for events that happen in the application for the specified ID.
Parameters	id - The ID object which was returned from the watch(...) function.
Returns	true if the ID was watching and has been removed.

viewer

Signature	cp.apple.finalcutpro:viewer() -> Viewer
Type	Method
Description	Returns the Viewer instance, whether it is in the primary or secondary window.
Parameters	None
Returns	the Viewer

watch

Signature	cp.apple.finalcutpro:watch(events) -> string
Type	Method
Description	Watch for events that happen in the application.
Parameters	events - A table of functions with to watch. These may be: * active - Triggered when the application is the active application. * inactive - Triggered when the application is no longer the active application. launched - Triggered when the application is launched.</li><li> terminated - Triggered when the application has been closed. * preferences - Triggered when the application preferences are updated.
Returns	An ID which can be passed to unwatch to stop watching.

windowsUI

Signature	cp.apple.finalcutpro:windowsUI() -> axuielement
Type	Method
Description	Returns the UI containing the list of windows in the app.
Parameters	None
Returns	The axuielement, or nil if the application is not running.