# cp.apple.finalcutpro.viewer.Viewer

Viewer Module.

# API Overview

Constants - Useful values which cannot be changed

  • BACKGROUND
  • PLAYBACK_MODE

Functions - API calls offered directly by the extension

  • matches

Constructors - API calls which return an object, typically one that offers API methods

  • Viewer

Fields - Variables which can only be accessed from an object returned by a constructor

  • background
  • betterQuality
  • contentsUI
  • controlBar
  • frame
  • framerate
  • getFormat
  • hasPlayerControls
  • infoBar
  • isEventViewer
  • isMainViewer
  • isOnPrimary
  • isOnSecondary
  • playbackMode
  • playButton
  • timecode
  • timecodeField
  • title
  • usingProxies
  • videoImage
  • videoImageUI

Methods - API calls which can only be made on an object returned by a constructor

  • app
  • currentWindow
  • doHide
  • doPause
  • doPlay
  • doShowOnPrimary
  • doShowOnSecondary
  • hide
  • notifier
  • showOnPrimary
  • showOnSecondary

# API Documentation

# Constants

# BACKGROUND

Signature cp.apple.finalcutpro.viewer.Viewer.BACKGROUND -> table
Type Constant
Description Lists the possible background values: BLACK, WHITE, CHECKERBOARD.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 472

# PLAYBACK_MODE

Signature cp.apple.finalcutpro.viewer.Viewer.PLAYBACK_MODE -> table
Type Constant
Description Lists the possible playback modes for the viewer: ORIGINAL_BETTER_QUALITY, ORIGINAL_BETTER_PERFORMANCE, PROXY_PREFERRED, PROXY_ONLY.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 383

# Functions

# matches

Signature cp.apple.finalcutpro.viewer.Viewer.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
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 101

# Constructors

# Viewer

Signature cp.apple.finalcutpro.viewer.Viewer(app, eventViewer) -> Viewer
Type Constructor
Description Creates a new Viewer instance.
Parameters
  • app - The FCP application.
  • eventViewer - If true, the viewer is the Event Viewer.
Returns
  • The new Viewer instance.
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 121

# Fields

# background

Signature cp.apple.finalcutpro.viewer.Viewer.background -> <cp.prop: number, live?>
Type Field
Description The viewer background mode. See Viewer.BACKGROUND for options.
Notes
  • sets the background for all viewers.
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 481

# betterQuality

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | cp.apple.finalcutpro.viewer.Viewer.betterQuality <cp.prop: boolean, read-only> | | Type | Field | | Description | Checks if the viewer is using playing with better quality (true) or performance (false). | | **Notes** | <ul><li>Use playbackMode` to change modes between original/proxy/quality/performance. | | Source | src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 457 |

# contentsUI

Signature cp.apple.finalcutpro.viewer.Viewer.contentsUI <cp.prop: hs.axuielement; read-only>
Type Field
Description Provides the axuielement for the media contents of the Viewer, or nil if not available.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 252

# controlBar

Signature cp.apple.finalcutpro.viewer.Viewer.controlBar <cp.apple.finalcutpro.viewer.ControlBar>
Type Field
Description Provides the ControlBar for this Viewer.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 295

# frame

Signature cp.apple.finalcutpro.viewer.Viewer.frame <cp.prop: table; read-only>
Type Field
Description Returns the current frame for the viewer, or nil if it is not available.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 242

# framerate

Signature cp.apple.finalcutpro.viewer.Viewer.framerate <cp.prop: number; read-only>
Type Field
Description Provides the framerate as a number, or nil if not available.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 498

# getFormat

Signature cp.apple.finalcutpro.viewer.Viewer.getFormat <cp.prop: string; read-only>
Type Field
Description Provides the format text value, or nil if none is available.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 491

# hasPlayerControls

Signature cp.apple.finalcutpro.viewer.Viewer.hasPlayerControls <cp.prop: boolean; read-only>
Type Field
Description Checks if the viewer has Player Controls visible.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 318

# infoBar

Signature cp.apple.finalcutpro.viewer.Viewer.infoBar <cp.apple.finalcutpro.viewer.InfoBar>
Type Field
Description Provides the InfoBar for this Viewer.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 287

# isEventViewer

Signature cp.apple.finalcutpro.viewer.Viewer.isEventViewer <cp.prop: boolean>
Type Field
Description Returns true if this is the Event Viewer.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 518

# isMainViewer

Signature cp.apple.finalcutpro.viewer.Viewer.isMainViewer <cp.prop: boolean>
Type Field
Description Returns true if this is the main Viewer.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 511

# isOnPrimary

Signature cp.apple.finalcutpro.viewer.Viewer.isOnPrimary <cp.prop: boolean; read-only>
Type Field
Description Checks if the Viewer is showing on the Primary Window.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 232

# isOnSecondary

Signature cp.apple.finalcutpro.viewer.Viewer.isOnSecondary <cp.prop: boolean; read-only>
Type Field
Description Checks if the Viewer is showing on the Secondary Window.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 222

# playbackMode

Signature cp.apple.finalcutpro.viewer.Viewer.playbackMode -> Viewer.PLAYBACK_MODE
Type Field
Description Reports and allows modification of the current playback mode.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 393

# playButton

Signature cp.apple.finalcutpro.viewer.Viewer.playButton <cp.ui.Button>
Type Field
Description The Play Button object.
Parameters
  • None
Returns
  • A Button
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 713

# timecode

Signature cp.apple.finalcutpro.viewer.Viewer.timecode <cp.prop: string; live>
Type Field
Description The current timecode value, with the format "hh:mm:ss:ff". Setting also supports "hh:mm:ss;ff".
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 310

# timecodeField

Signature cp.apple.finalcutpro.viewer.Viewer.timecodeField <cp.ui.StaticText>
Type Field
Description The StaticText containing the timecode value.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 303

# title

Signature cp.apple.finalcutpro.viewer.Viewer.title <cp.ui.StaticText>
Type Field
Description Provides the Title of the clip in the Viewer as a StaticText
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 325

# usingProxies

Signature cp.apple.finalcutpro.viewer.Viewer.usingProxies <cp.prop: boolean, read-only>
Type Field
Description Indicates if the viewer is using Proxies (true) or Optimized/Original media (false).
Notes
  • Use playbackMode to change modes between original/proxy/quality/performance.
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 443

# videoImage

Signature cp.apple.finalcutpro.viewer.Viewer.videoImage <cp.ui.Image>
Type Field
Description The Image for the video content.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 280

# videoImageUI

Signature cp.apple.finalcutpro.viewer.Viewer.videoImageUI <cp.prop: hs.axuielement; read-only>
Type Field
Description Provides the axuielement for video image within the Viewer, or nil if not available.
Notes None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 267

# Methods

# app

Signature cp.apple.finalcutpro.viewer.Viewer:app() -> application
Type Method
Description Returns the application.
Parameters
  • None
Returns
  • The application.
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 209

# currentWindow

Signature cp.apple.finalcutpro.viewer.Viewer:currentWindow() -> PrimaryWindow | SecondaryWindow
Type Method
Description Gets the current window object.
Parameters
  • None
Returns
  • The PrimaryWindow or the SecondaryWindow.
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 531

# doHide

Signature cp.apple.finalcutpro.viewer.Viewer:doHide() -> cp.rx.go.Statement
Type Method
Description A Statement that hides the Viewer.
Parameters
  • None
Returns
  • The Statement, resolving to true, or sends an error.
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 684

# doPause

Signature cp.apple.finalcutpro.viewer.Viewer.doPause() -> cp.rx.go.Statement
Type Method
Description Pause the Viewer.
Parameters
  • None
Returns
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 359

# doPlay

Signature cp.apple.finalcutpro.viewer.Viewer:doPlay() -> cp.rx.go.Statement
Type Method
Description Returns a Statement that will play the Viewer.
Parameters
  • None
Returns
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 344

# doShowOnPrimary

Signature cp.apple.finalcutpro.viewer.Viewer:doShowOnPrimary() -> cp.rx.go.Statement
Type Method
Description A Statement that shows the Viewer on the Primary display.
Parameters
  • None
Returns
  • The Statement, which resolves to true, or sends an error message.
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 578

# doShowOnSecondary

Signature cp.apple.finalcutpro.viewer.Viewer:doShowOnSecondary() -> cp.rx.go.Statement
Type Method
Description A Statement that shows the Viewer on the Secondary display.
Parameters
  • None
Returns
  • The Statement, resolving to true, or sending an error message.
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 630

# hide

Signature cp.apple.finalcutpro.viewer.Viewer:hide() -> self
Type Method
Description Hides the Viewer.
Parameters
  • None
Returns
  • Self
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 656

# notifier

Signature cp.apple.finalcutpro.viewer.Viewer:notifier() -> cp.ui.notifier
Type Method
Description Returns a notifier that is tracking the application UI element. It has already been started.
Parameters
  • None
Returns
  • The notifier.
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 726

# showOnPrimary

Signature cp.apple.finalcutpro.viewer.Viewer:showOnPrimary() -> self
Type Method
Description Shows the Viewer on the Primary display.
Parameters
  • None
Returns
  • Self
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 548

# showOnSecondary

Signature cp.apple.finalcutpro.viewer.Viewer:showOnSecondary() -> self
Type Method
Description Shows the Viewer on the Seconary display.
Parameters
  • None
Returns
  • Self
Notes None
Examples None
Source src/extensions/cp/apple/finalcutpro/viewer/Viewer.lua line 604

© Copyright 2026 LateNite Films Pty Ltd. All rights reserved.