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

API Overview

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

currentLanguage

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

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

getVersion

Signature cp.apple.finalcutpro.getVersion <cp.prop: string; read-only>
Type Constant
Description Version of Final Cut Pro
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, otherwise, it will use hs.application.infoForBundleID() to find the version.

PASTEBOARD_UTI

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

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

getMotionTheme

Signature `cp.apple.finalcutpro.scannplugins.getMotionTheme(filename) -> string nil` </span>
Type Function
Description Process a plugin so that it's added to the current scan
Parameters
  • filename - Filename of the plugin
Returns
  • The theme name, or `nil` if not found.
Notes
  • getMotionTheme("~/Movies/Motion Templates.localized/Effects.localized/3065D03D-92D7-4FD9-B472-E524B87B5012.localized/DAEB0CAD-E702-4BF9-94B5-AE89D7F8FB00.localized/DAEB0CAD-E702-4BF9-94B5-AE89D7F8FB00.moef")

init

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

Fields

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

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 - (optional) 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` - (optional) The 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

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 - (optional) The default value to return if the preference is not set.
  • forceReload = (optional) If true, 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() -> table or nil
Type Method
Description Gets Final Cut Pro's Preferences as a table. It checks if the preferences
Parameters
  • forceReload - (optional) if true, a reload will be forced even if the file hasn't been modified.
  • preventMultipleReloads - (optional) if true, adds a 0.01 delay before reloading preferences (for use with the watcher)
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() -> 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
Signature cp.apple.finalcutpro:menuBar() -> menuBar object
Type Method
Description Returns the Final Cut Pro Menu Bar
Parameters
  • None
Returns
  • A MenuBar object

path

Signature cp.apple.finalcutpro:path() -> 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.

performShortcut

Signature cp.apple.finalcutpro:performShortcut() -> 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() -> 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() -> 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.
  • `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.

results matching ""

    No results matching ""