FilmLight Python API

This document details the Python API for the FilmLight API server.

The FilmLight Python API connects to an API server running on a local or remote machine, and provides a set of functions and classes which can be used to manipulate the native Baselight and Daylight databases and services.

Supports:

Dependencies:

Module

Installation on Linux

The flapi python module can be found at the following locations:

On Linux:

/usr/fl/baselight-<version>/share/flapi/python
/usr/fl/daylight-<version>/share/flapi/python

To install the flapi python module you can use the pip packagement management utility.

To install flapi for all users on your machine:

sudo pip install /usr/fl/baselight/share/flapi/python

To install flapi for only the current user:

pip install --user /usr/fl/baselight/share/flapi/python

Alternatively, add the flapi python directory to your PYTHONPATH environment variable:

PYTHONPATH=/path/to/share/flapi/python python myscript.py

flapi requires the websocket-client library. If you do not use the above pip command to install flapi, you will need to install websocket-client manually. It is available via pip.

sudo pip install websocket-client

Installation on macOS

The flapi python module can be found at the following locations:

/Applications/Baselight/<version>/Utilities/Resources/share/flapi/python
/Applications/Daylight/<version>/Utilities/Resources/share/flapi/python

To install the flapi python module you can use the pip packagement management utility.

On macOS, pip is not installed by default, but can be installed via the Python easy_install tool:

sudo easy_install pip
sudo pip install --upgrade pip

To install flapi with pip on macOS for all users on your machine:

sudo pip install /Applications/Baselight/Current/Utilities/Resources/share/flapi/python

To install flapi with pip on macOS for the current user:

pip install --user /Applications/Baselight/Current/Utilities/Resources/share/flapi/python

Alternatively, add the flapi python directory to your PYTHONPATH environment variable:

PYTHONPATH=/path/to/share/flapi/python python myscript.py

flapi requires the websocket-client library. If you do not use pip commto install flapi, you will need to install websocket-client manually. It is available via pip:

sudo pip install websocket-client

Protocol

For details of the underlying protocol, see the FilmLight JSON API specification.

Connection

In order to perform actions through the FilmLight Python API, you must first open a connection to the FilmLight API server.

This is implemented via the flapi.Connection class.

The Python API allows connecting to a local or remote FilmLight API server.

Python scripts can also be launched from within a FilmLight application, and the FilmLight Python API can be used to connect back to the parent FilmLight process.

Authentication

This release of FLAPI for Baselight and Daylight 5.3 and later has introduced authentication for Connections.

You must provide a username and token to connect to a FLAPI daemon.

For FLAPI connections to the local machine, the token can be determined automatically for the current user.

For FLAPI connections to remote hosts, a username and token must be supplied when creating the connection to FLAPI. If a token does not exist for a given user on the FLAPI server, it can be created by running /usr/fl/baselight/bin/fl-setup-flapi-token for that user on the remote server.

On the FLAPI server, the token for a given user is stored in the following location:

On Linux: 

$HOME/.filmlight/flapi-token

On macOS: 

/Users/<username>/Library/Preferences/FilmLight/flapi-token

Connect to FLAPI server on localhost

import flapi

# Create local FLAPI connection
conn = flapi.Connection()
conn.connect()

# Call methods...

# Close connection
conn.close()

Connect to FLAPI server on remote host

import flapi

# Create remote FLAPI connection
hostname = "remotehost"
username = "myusername"
token = "...token..."
conn = flapi.Connection( hostname, username=username, token=token )
conn.connect()

# Call methods...

# Close connection
conn.close()

Calling methods

Each class exposed via the FilmLight API is accessed via the Connection object.

Calling Static Methods

You can call static methods on those classes via the class members provided by the Connection object.

import flapi

# Create local connection
conn = flapi.Connection()

# Open connection
conn.connect()

# Access static get_jobs methods on the class JobManager class
jobs = conn.JobManager.get_jobs("localhost")

# Close connection
conn.close()

Calling Instance Methods

Instances of each class are then created by the static class functions.

import flapi

# Create local connection
conn = flapi.Connection()

# Open connection
conn.connect()

# Create a scene in the database using the static 'new_scene' method
scenePath = conn.Scene.parse_path( "localhost:myjob:newscene" )
options = {
    "format": "HD 1920x1080",
    "colourspace": "FilmLight_TLog_EGamut",
    "field_order": flapi.FIELDORDER_PROGRESSIVE,
    "frame_rate": 24.0
}
scene = conn.Scene.new_scene( scenePath, options )

# Save the scene using the 'save_scene' instance method
scene.save_scene()

# Close the scene
scene.close_scene()
scene.release()

# Close the connection
conn.close()

Object lifecycles

Whenever you call a function on an FLAPI connection that creates a new object, an object will be created on the server and you must release that object when you finished with it.

Every instance of a class in FLAPI inherits from the flapi.Interface class, which implements the release() method.

# Create Scene object via new_scene()
scene = conn.Scene.new_scene( ... )

# Do stuff with Scene object

scene.close_scene()

# Release Scene object, informing the server you are finished with it
scene.release()

If you do not call release() you will leak objects on the server until your connection closes, at which point those objects will be destroyed.

Signals

Some classes like Scene and QueueManager can emit signals from the server to notify your application when actions occur.

You can connect these signals to methods in your Python script which will be executed when the signal is received from the server.

An example of listening to a signal from the server:

::: python
import flapi, sys
stop = False

def handle_queue_ops_changed(sender, signal, args):
    print( "List of operations changed" )
    stop = True

conn = flapi.Connection()
conn.connect()
qm = conn.QueueManager.create_local()

# Connect a function to be called when this signal is received
qm.connect( "QueueOpsChanged", handle_queue_ops_changed )

# Subscribe to update signals from QueueManager
qm.enable_updates()

while not stop:
    conn.wait()

# Close up objects on first signal received -- this was just a test
# Disable updates from server
qm.disable_updates()

# Disconnect our signal handler
qm.disconnect( "QueueOpsChanged", handle_queue_ops_changed )

# Release our QueueManager instance
qm.release()

conn.close()

Error Handling

FLAPIException

If an error occurs as part of the function call via FLAPI, it will be returned via an FLAPIException raised from the method you are calling.

Server Logs

If the FilmLight API method calls are malfunctioning, extra information can be retrieved via the flapid server log files.

The log files can be found at the following locations:

On Linux:

/usr/fl/log/<hostname>-flapid/console.txt

On macOS:

/Library/Application Support/FilmLight/log/<hostname>-flapid/console.txt

Release Notes

Baselight 5.3:

Baselight 5.2:

Beta Classes and Methods

Some classes and methods are marked BETA.

This means that the API is currently in flux and subject to change in subsequent releases.

Changes to API since last release

Classes

Key: Static MethodInstance MethodBeta

Application

The Application class provides information about the host application and access to its global state.

Signals

Methods

Application.get_application_info()

Information describing the application exposed via the FilmLight API

Arguments

Result

Application.get_sdk_versions()

Get SDK version information

Arguments

Result

Application.get_connections_info()

Get array of current connections. Each entry in the array will be a ConnectionInfo object describing that connection.

Arguments

Result

Application.get_video_streaming_supported()

Is video streaming supported (hardware, setup & licensed)

Arguments

Result

Application.get_video_streaming_enabled()

Is video streaming currently enabled

Arguments

Result

Application.get_video_stream_address()

Return address for video stream

Arguments

Result

Application.is_playing()

Is playback currently in progress

Arguments

Result

Application.get() BETA

Return instance of the Application object (typically for signal connection)

Arguments

Result

get_current_scene() BETA

Return the currently active Scene within the application

Arguments

Result

get_current_scene_name() BETA

Return the name of the currently active Scene within the application

Arguments

Result

get_open_scene_names() BETA

Return array of names of scenes currently open in the application. You can get the Scene object for a given name by calling get_scene_by_name().

Arguments

Result

get_scene_by_name(name) BETA

Return the Scene object for the scene with the given name. If no matching scene can be found, NULL is returned.

Arguments

Result

get_current_cursor() BETA

Return the currently active Cursor within the application

Arguments

Result

get_cursors() BETA

Return active Cursor objects within the application

Arguments

Result

log(category, severity, message) BETA

Log message in application Log view

Arguments

Result

message_dialog(title, message, buttons) BETA

Present a message box in the Application for the user to interact with

Arguments

Result

list_dialog(title, message, items) BETA

Present a dialog to the user containing a list of items that the user can select from

Arguments

Result

set_custom_data(data_key, data_value)

Set a custom data value in the application with the supplied (string) key. Existing custom data values can be deleted from the application by supplying NULL/None/null as the data value (for an existing key).

Arguments

Result

get_custom_data(data_key)

Get a custom data value from the application previously set using set_custom_data.

Arguments

Result

get_custom_data_keys()

Return sorted array of (string) keys that can be used to fetch application custom data values via get_custom_data.

Arguments

Result

AudioSync

audio sync operation

Signals

Methods

AudioSync.create()

Create a new audio sync operation object

Arguments

Result

audio_sync(scene, settings, shot_ids)

Perform audio sync operation using the given audio sync settings

Arguments

Result

get_log()

Return log of progress information

Arguments

Result

ClientViewManager

Manages settings for connected Client Views.

Signals

Methods

ClientViewManager.get()

Get reference to the (singleton) ClientViewManager object

Arguments

Result

get_host_user_settings()

Get object containing Settings for the Client View's host user

Arguments

Result

get_client_settings()

Get the connected Client View's config/settings object.

Arguments

Result

get_stream_settings()

Get array of stream settings objects.

Arguments

Result

get_streaming_enabled()

Is streaming currently enabled.

Arguments

Result

get_session_name()

Get the current Client View session name.

Arguments

Result

get_session_clients()

Get array of current session clients. Each entry in the array will be a ConnectionInfo object describing that connection.

Arguments

Result

CurrentGrade

Used to monitor an in-progress Baselight grading session. Clients should first obtain a CurrentGrade (singleton) instance using the (static) get() function. Clients can register with this instance to receive signals when the current grade changes.

Signals

Methods

CurrentGrade.get()

Get (singleton) current grade interface for the connected client

Arguments

Result

request_update_current_shot_signal()

Explicitly request an 'UpdateCurrentShot' signal. This can be useful, for example, when first connecting to the current grade module for initialising a client's internal state.

Arguments

Result

get_current_cursor()

Get an interface to the cursor currently in use by Baselight for grading.

Arguments

Result

is_enabled()

Is this interface currently enabled. Note: The current grade interface may be arbitrarily enabled/disabled from the host application itself.

Arguments

Result

Cursor

Interface for accessing cursors within a scene.

Signals

Methods

get_time()

Get cursor's position in the timeline in seconds

Arguments

Result

get_frame()

Get cursor's position in the timeline as a frame number

Arguments

Result

get_record_timecode()

Get cursor's position in the timeline as a timecode

Arguments

Result

get_viewing_format_name()

Get the name of the cursor's current viewing format.

Arguments

Result

get_viewing_format_dims()

Get basic geometry (width, height and aspect ratio) of the cursor's current viewing format

Arguments

Result

get_viewing_format_mask_name()

Get current viewing format mask name

Arguments

Result

get_viewing_format_mask()

Get current viewing format mask rectangle

Arguments

Result

get_age()

Get the cursor's 'age'. The age is an integer, incremented whenever an attribute which could result in a visual change to the image display has been modfied.

Arguments

Result

is_using_truelight()

Is Truelight currently in use (ie. a profile has been selected & Truelight is enabled) in this cursor.

Arguments

Result

DynamicDialog (BETA)

This class can be used to show a complex dialog box to the user BETA

Signals

Methods

DynamicDialog.create(title, defns, settings) BETA

Create a Dialog object

Arguments

Result

DynamicDialog.modal(title, defns, settings, width, height) BETA

Display a Dialog object and return the settings

Arguments

Result

show_modal(width, height) BETA

Show dialog to user

Arguments

Result

get_settings() BETA

Return current dialog settings

Arguments

Result

set_settings(settings) BETA

Set current dialog settings

Arguments

Result

set_timer_callback(delay, repeat) BETA

Set time until callback signal TimerCallback will be sent

Arguments

Result

cancel_timer_callback() BETA

Cancel any pending timer callback

Arguments

Result

Export

Export operation

Signals

Methods

Export.create()

Create a new Export operation object

Arguments

Result

select_all()

Select all snots in Scene to export

Arguments

Result

clear_selection()

Clear selection of shots in Scene to export

Arguments

Result

select_shots(shots)

Set the selection to the given Shots for rendering

Arguments

Result

select_shot(shot)

Add the given shot to the selection to be exported.

Arguments

Result

do_export_BLG(queue, scene, settings)

Perform export BLG operation using the given Export settings

Arguments

Result

do_export_CDL(queue, scene, settings)

Perform export CDL operation using the given Export settings

Arguments

Result

do_export_cube(queue, scene, settings)

Perform export LUT operation using the given Export settings

Arguments

Result

do_export_still(queue, scene, settings)

Perform export still operation using the given Export settings

Arguments

Result

get_log()

Return log of progress information

Arguments

Result

get_presets(scene, export_type) BETA

Return array of presets.

Note: this function is provided to make it easier to discover what settings are required when you want a particular export format (in particular for stills where it may not be obvious how to choose quality / compression settings etc). It is not, currently, intended to be a full-fledged interface to the Baselight presets.

Arguments

Result

Format

Format defines an image resolution and pixel aspect ratio with associated masks and burnins

Signals

Methods

get_description()

Return description of format

Arguments

Result

get_resolution(res)

Return FormatInfo for given resolution of Format

Arguments

Result

get_mapping_names()

Return names of mapping from this format to other formats

Arguments

Result

get_mapping(name)

Return definition of mapping from this format to named format

Arguments

Result

get_masks()

Return array of FormatMasks defined for this format

Arguments

Result

get_burnin_names()

Return array of names of burnins defined for this format

Arguments

Result

add_burnin(name)

Create a new burnin with the given name, and return a FormatBurnin object for it

Arguments

Result

get_burnin(name)

Return FormatBurnin object for the named burnin

Arguments

Result

delete_burnin(name)

Delete the burnin with the given name

Arguments

Result

FormatBurnin

Definition of a burn-in for a Format

Signals

Methods

get_opacity()

Get burnin opacity

Arguments

Result

set_opacity(opacity)

Set burnin opacity

Arguments

Result

get_box_colour()

Set colour of box around text items

Arguments

Result

set_box_colour(colour)

Set colour of box around text items

Arguments

Result

get_font()

Get font name for this burnin

Arguments

Result

set_font(name)

Get font name for this burnin

Arguments

Result

add_item(item)

Add new item to the burnin

Arguments

Result

get_num_items()

Return number of items defined within this burnin

Arguments

Result

get_item(index)

Return definition for the burnin item at the given index

Arguments

Result

set_item(index, item)

Return definition for the burnin item at the given index

Arguments

Result

delete_item(index)

Delete the burnin item at the given index

Arguments

Result

FormatSet

The FormatSet interface allows enumeration of available resources on the FilmLight system such as formats, colour spaces, display render transforms, LUTs, etc.

Signals

Methods

FormatSet.factory_formats()

Return factory FormatSet object for factory (built-in) formats

Arguments

Result

FormatSet.global_formats()

Return global FormatSet object for formats defined in formats database

Arguments

Result

FormatSet.job_formats(hostname, jobname)

Return FormatSet object for formats defined in the given Job database

Arguments

Result

FormatSet.get_drt_names()

Return array of Display Rendering Transform names

Arguments

Result

FormatSet.get_drt_info(name)

Return information for the given Display Rendering Transform name

Arguments

Result

get_scope()

Return scope this is FormatSet represents

Arguments

Result

get_scope_path()

Return the path for FormatSets representing a job/scene scope

Arguments

Result

get_format_names()

Return array of format names

Arguments

Result

get_basic_format_name(width, height, pixelAspectRatio)

Return name for a basic (auto-generated) format

Arguments

Result

get_format(name)

Return Format object for the named format

Arguments

Result

get_colour_space_names()

Return array of colour space names

Arguments

Result

get_colour_space_info(name)

Return information on the given colour space

Arguments

Result

add_format(name, description, width, height, pixelAspectRatio)

Add a new format to this FormatSet

Arguments

Result

delete_format(name)

Delete a format from the FormatSet

Arguments

Result

Image

Signals

Methods

Image.get_raw_metadata(filename)

Returns raw metadata for the image or movie at the supplied path

Arguments

Result

JobManager

Query and manipulate the FilmLight job database

Signals

Methods

JobManager.get_jobs(host)

Fetch list of jobs in job database

Arguments

Result

JobManager.get_folders(host, job, folder, recursive)

Fetch list of folder names within job/folder in job database

Arguments

Result

JobManager.get_scenes(host, job, folder)

Fetch list of scene names within job/folder in job database

Arguments

Result

JobManager.create_job(host, jobname)

Create a new job

Arguments

Result

JobManager.rename_job(host, jobname, new_jobname)

Rename job

Arguments

Result

JobManager.delete_job(host, jobname, force)

Delete job

Arguments

Result

JobManager.job_exists(host, jobname)

Check if job exists

Arguments

Result

JobManager.create_folder(host, jobname, foldername)

Create a folder within job

Arguments

Result

JobManager.rename_folder(host, jobname, foldername, new_foldername)

Rename folder

Arguments

Result

JobManager.delete_folder(host, jobname, foldername)

Delete folder

Arguments

Result

JobManager.get_scene_info(host, jobname, scenename)

Return information about scene

Arguments

Result

JobManager.scene_exists(host, jobname, scenename)

Check if scene exists

Arguments

Result

JobManager.delete_scene(host, jobname, scenename, ignoreLocks)

Delete scene

Arguments

Result

JobManager.rename_scene(host, jobname, scenename, newname)

Rename scene

Arguments

Result

Licence

Licence management

Signals

Methods

Licence.get_system_id()

Return the system ID used to identify this system for licensing

Arguments

Result

Licence.get_licence_info(include_expired)

Return licence information

Arguments

Result

Licence.install_licence(licenceData)

Install the given licence data

Arguments

Result

Mark

Mark defined in a Shot or Scene

Signals

Methods

get_id()

Return Mark object ID

Arguments

Result

get_type()

Return Mark type

Arguments

Result

get_position()

Return Mark position For Shot marks, this value is a frame number relative to the start of the image sequence. For Strip marks, this value is a time in seconds relative to the start of the strip. For Timeline marks, this value is a time in seconds relative to the start of the timeline.

Arguments

Result

get_time()

Return Mark position in seconds For Shot and Strip marks, this returns the time relative to the start of the shot For Timeline marks, this returns the time relative to the start of the timeline

Arguments

Result

get_note_text()

Return Mark note text

Arguments

Result

get_colour()

Return Mark colour

Arguments

Result

get_category()

Return Mark category

Arguments

Result

get_source_frame(eye)

Return the source image frame number for this mark Only applicable for Shot/Strip marks. Will fail for Timeline marks

Arguments

Result

get_source_timecode(eye)

Return the source image timecode for this mark Only applicable for Shot/Strip marks. Will fail for Timeline marks

Arguments

Result

get_record_frame()

Return the source image frame number for this mark

Arguments

Result

get_record_timecode()

Return the source image timecode for this mark

Arguments

Result

get_properties()

Return dictionary of properties for this Mark object

Arguments

Result

set_properties(props)

Set the property values for the given dictionary of keys & values. Setting a value to NULL will remove it from the property set.

Arguments

Result

A menu in the application user interface, which contains MenuItems BETA

Signals

Methods

Create new Menu object

Arguments

Result

Add MenuItem to menu

Arguments

Result

Get number of items in menu

Arguments

Result

Get MenuItem at given index within menu

Arguments

Result

Return the index of the given MenuItem within this Menu

Arguments

Result

Remove menu item at the given index

Arguments

Result

Remove menu item from menu

Arguments

Result

Remove all menu items from menu

Arguments

Result

A menu item in the application user interface, which can trigger actions BETA

Signals

Methods

Create a new MenuItem object

Arguments

Result

Register this menu item to insert it into the application's UI

Arguments

Result

Get menu item title

Arguments

Result

Set menu item title

Arguments

Result

Get menu item enabled state

Arguments

Result

Set menu item enabled state

Arguments

Result

Get menu item hidden state

Arguments

Result

Set menu item hidden state

Arguments

Result

Get sub-menu for this menu item

Arguments

Result

Set sub-menu for this menu item

Arguments

Result

MultiPaste

Multi-Paste operation

Signals

Methods

MultiPaste.create()

Create a new Multi-Paste operation object

Arguments

Result

multi_paste(scene, settings, shot_ids)

Perform multi-paste operation using the given Multi-Paste settings

Arguments

Result

get_log()

Return log of progress information

Arguments

Result

ProgressDialog (BETA)

Display a progress dialog within the application BETA

Signals

Methods

ProgressDialog.create(title, msg, cancellable) BETA

Create a new ProgressDialog

Arguments

Result

show(delay) BETA

Show the progress dialog

Arguments

Result

set_title(title) BETA

Set the title of the progress dialog

Arguments

Result

set_progress(progress, message) BETA

Update the progress & message displayed in dialog

Arguments

Result

hide() BETA

Hide the progress dialog

Arguments

Result

QueueManager

Interface for managing the Queue on a Baselight/Daylight system

Signals

Methods

QueueManager.create(zone)

Create a QueueManager object to examine and manipulate the queue on the given zone

Arguments

Result

QueueManager.create_local()

Create a QueueManager object to examine and manipulate the queue on the local zone

Arguments

Result

QueueManager.create_no_database()

Create a QueueManager object to examine and manipulate a non-database queue in the FLAPI process. In addition, the QueueManager object will process any operations added to the queue within the FLAPI process.

Arguments

Result

QueueManager.get_queue_zones()

Return list of available zones running queue services

Arguments

Result

get_operation_ids()

Return list operation IDs in queue

Arguments

Result

get_operation(id)

Return definition of given operation ID

Arguments

Result

get_operation_status(id)

Return status of given operation ID

Arguments

Result

get_operation_log(id)

Return log for given operation ID

Arguments

Result

pause_operation(id)

Pause operation with given operation ID

Arguments

Result

resume_operation(id)

Resume operation with given operation ID

Arguments

Result

restart_operation(id)

Restart operation with given operation ID

Arguments

Result

delete_operation(id)

Delete operation with given operation ID

Arguments

Result

archive_operation(id)

Archive operation with given operation ID

Arguments

Result

enable_updates()

Enable status update signals

Arguments

Result

disable_updates()

Disable status update signals

Arguments

Result

new_operation(opType, desc, params, tasks, dependsOn) BETA

Create a new custom operation and return its ID

Arguments

Result

add_tasks_to_operation(opid, tasks) BETA

Add more tasks to the given operation

Arguments

Result

set_operation_ready(opid) BETA

Mark operation as ready to process. Should be called after calling add_tasks_to_operation().

Arguments

Result

get_next_operation_of_type(opType, wait) BETA

Find the next operation for the given operation type that is ready to execute

Arguments

Result

get_operation_params(opid) BETA

Get params for given operation ID

Arguments

Result

get_next_task(opid) BETA

Get the next task ready to execute for the given operation ID

Arguments

Result

set_task_progress(opid, taskseq, progress) BETA

Set task progress

Arguments

Result

set_task_done(opid, taskseq, msg) BETA

Mark task as completed

Arguments

Result

set_task_failed(opid, taskseq, msg, detail, frame) BETA

Mark task as failed

Arguments

Result

add_operation_log(opid, type, msg, detail) BETA

Add log entry for operation

Arguments

Result

add_task_log(opid, taskseq, type, msg, detail, frame) BETA

Add log entry for operation

Arguments

Result

RenderProcessor

A RenderProcessor will execute a RenderSetup and produce deliverable data

Signals

Methods

RenderProcessor.get()

Get RenderProcessor instance

Arguments

Result

start(renderSetup)

Start render operation for the given RenderSetup

Arguments

Result

get_progress()

Returns current render progress

Arguments

Result

get_log()

Get log of operation progress

Arguments

Result

shutdown()

Shutdown the RenderProcessor instance. This releases any resources in use by the RenderProcessor.

Arguments

Result

RenderSetup

Setup Baselight/Daylight scene for rendering

Signals

Methods

RenderSetup.get_image_types()

Return array of supported image types for rendering

Arguments

Result

RenderSetup.get_movie_types()

Return array of movie types for rendering

Arguments

Result

RenderSetup.get_movie_codecs(movieType)

Return array of video codecs available for the given movie type

Arguments

Result

RenderSetup.get_movie_audio_codecs(movieType)

Return array of audio codecs available for the given movie type

Arguments

Result

RenderSetup.create()

Create a new RenderSetup instance

Arguments

Result

RenderSetup.create_from_scene(scene)

Create a new RenderSetup instance configured to render the given Scene using its default deliverables

Arguments

Result

get_scene()

Return Scene object for RenderSetup

Arguments

Result

set_scene(scene)

Set Scene to Render

Arguments

Result

save_into_scene(scene)

Save the deliverables from this RenderSetup into the Scene. If a delta is not in progress on the Scene, a new delta will be created for the save operation.

Arguments

Result

set_deliverables_from_scene(scene)

Load Deliverables from Scene object assigned to this RenderSetup object

Arguments

Result

get_num_deliverables()

Render number of deliverables defined for this Scene

Arguments

Result

get_deliverable_names()

Return array of deliverable names

Arguments

Result

get_deliverable(index)

Return the RenderDeliverable definition at the given index

Arguments

Result

set_deliverable(index, deliverable)

Set the settings for the deliverable at the given index

Arguments

Result

get_deliverable_by_name(name)

Get the settings for the RenderDeliverable definition with the given name. Returns NULL if not matching deliverable can be found.

Arguments

Result

set_deliverable_by_name(name, deliverable)

Set the settings for the RenderDeliverable definition with the given name

Arguments

Result

add_deliverable(deliverable)

Add a new deliverable to be generated as part of this render operation

Arguments

Result

delete_deliverable(index)

Delete the deliverable at the given index

Arguments

Result

delete_all_deliverables()

Delete all deliverables defined in the RenderSetup

Arguments

Result

get_deliverable_enabled(index)

Get enabled state of deliverable at given index

Arguments

Result

set_deliverable_enabled(index, enabled)

Set enabled state of deliverable at given index

Arguments

Result

get_output_filename_for_deliverable(index, leave_container, frame)

Return the full filename for the given frame number of a deliverable

Arguments

Result

set_container(container)

Set the output container directory for all deliverables

Arguments

Result

get_frames()

Get list of frame ranges to render

Arguments

Result

set_frames(frames)

Set list of frame ranges to render

Arguments

Result

select_all()

Select all frames in Scene to render

Arguments

Result

select_shots(shots)

Select the given Shots for rendering

Arguments

Result

select_shot_ids(shotids)

Select the given Shots identified by their ID for rendering

Arguments

Result

select_graded_shots()

Select all graded shots to render

Arguments

Result

select_timeline_marks(categories)

Select timeline marks matching the categories in the given category set

Arguments

Result

select_shot_marks(categories)

Select shot marks matching the categories in the given category set

Arguments

Result

select_poster_frames()

Select all shot poster frames to render

Arguments

Result

select_shots_of_category(categories)

Select shots marked with one of the categories in the given category set

Arguments

Result

submit_to_queue(queue, opname)

Submit the current Render operation to a Queue for processing

Arguments

Result

Scene

Interface for opening, creating, accessing and modifying Scenes.

Scene modifications are usually made using a delta. A delta batches together one or more scene edits/modifications into a single, undo-able transaction. A client wishing to modify a scene would typically:

  1. Start a delta using the start_delta() method (supplying a user friendly name for the delta/operation they're performing).
  2. Make edits on the scene using whatever 'set' type methods are required for the operation.
  3. End the delta using the end_delta() method.

Signals

Methods

Scene.parse_path(str)

Convert the given string into a ScenePath object contaning Host, Job, Scene components, or raise an error if the path is invalid

Arguments

Result

Scene.path_to_string(scenepath)

Convert the given ScenePath object into a string

Arguments

Result

Scene.create()

Create an empty Scene object, which can then be used to create a temporary scene, a new scene, or load an existing scene. After creating an empty Scene object, you must call ::temporary_scene_nonblock::, ::new_scene_nonblock:: or ::open_scene_nonblock::.

Arguments

Result

Scene.new_scene(scenepath, options)

Create a new scene stored in a database. This function will block until the new scene has been created in the database. If the new scene cannot be created, this function will raise an exception containing an error message.

Arguments

Result

Scene.open_scene(scenepath, flags)

Open a scene. This function will block until the scene has been opened. If the scene cannot be opened, this function will raise an exception containing an error message.

Arguments

Result

Scene.temporary_scene(options)

Create a temporary scene that is not stored in a database. This function will block until the temporary scene has been created. If the temporary scene cannot be created, this function will raise an exception containing an error message.

Arguments

Result

new_scene_nonblock(scenepath, options)

Create a new scene

Arguments

Result

open_scene_nonblock(scenepath, flags)

Open a scene

Arguments

Result

temporary_scene_nonblock(options)

Create a temporary scene that is not stored in a database

Arguments

Result

save_scene()

Save changes to scene into database

Arguments

Result

get_open_status()

Fetch status of scene open operation

Arguments

Result

wait_until_open()

Wait for any scene opening/creation operations to complete, and return the status

Arguments

Result

close_scene()

Close scene

Arguments

Result

get_scene_pathname()

Get current scene's 'pathname' string (typically 'host:job:scene')

Arguments

Result

get_scene_container()

Get the current container for the scene

Arguments

Result

set_scene_container(container)

Set the current container for the scene

Arguments

Result

start_delta(name)

Start a 'delta' on a scene that has been opened read/write. A delta is a set of modifcations/edits on a scene that together constitute a single, logical operation/transaction. Each start_delta call must have a matching end_delta call (with one or more editing operations in between). Every delta has a user visible name (eg. 'Change Film Grade Exposure'). Once a delta has been completed/ended it becomes an atomic, undoable operation.

Arguments

Result

cancel_delta()

Cancel a 'delta' (a set of scene modifications/edits) previously started via the start_delta() method, reverting the Scene back to the state it was in before start_delta().

Arguments

Result

end_delta()

End a 'delta' (a set of scene modifications/edits) previously started via the start_delta() method.

Arguments

Result

is_read_only()

Has this scene interface been opened 'read only'. Interfaces opened read only cannot modify their scene using the standard start_delta, make changes, end_delta paradigm. At any given time, multiple interfaces may reference/open the same scene in read only mode. However, at most only a single interface may reference a scene in read/write mode

Arguments

Result

is_read_only_for_host()

Is the scene opened 'read only' for the host application. Note: This will be false if any interface has opened the scene in read/write mode (or the host has explicitly opened the scene read/write itself)

Arguments

Result

get_formats()

Return FormatSet for formats defined within this Scene

Arguments

Result

get_scene_settings()

Return SceneSettings object for this Scene

Arguments

Result

get_category(key)

Return category definition

Arguments

Result

set_category(name, colour)

Overwrites an existing category in the scene, or adds a new category if a category of that name doesn't exist. Will fail if an attempt is made to overwrite an built-in, read-only category.

Arguments

Result

get_mark_categories()

Return array of mark category keys

Arguments

Result

get_strip_categories()

Return array of strip category keys

Arguments

Result

get_start_frame()

Get frame number of start of first shot in scene

Arguments

Result

get_end_frame()

Get frame number of end of last shot in scene

Arguments

Result

get_working_frame_rate()

Get the working frame rate of the current scene (in FPS)

Arguments

Result

get_record_timecode_for_frame(frame_num)

Get record timecode for a given (timeline) frame number

Arguments

Result

get_shot_index_range(startFrame, endFrame)

Get index range of shots intersecting the (end exclusive) timeline frame range supplied

Arguments

Result

get_num_shots()

Get number of Shots within scene

Arguments

Result

get_shot_id_at(frame)

Return the ID of the shot at the timeline frame number supplied

Arguments

Result

get_shot_id(index)

Return the ID for the shot at the given index within the Scene

Arguments

Result

get_shot_ids(firstIndex, lastIndex)

Get an array of shots in the supplied indexed range. Each array entry is an object containing basic information for that shot. Explicitly, each shot entry will contain the following keys:

Returns new array shot list on success, NULL on error.

Arguments

Result

get_shot(shot_id)

Create a new Shot object for the given shot ID

Arguments

Result

delete_shot(shot_id, cleanup, closeGap)

Delete the given shot and its associated layers from the Scene

Arguments

Result

insert_bars(barType, duration, where, relativeTo, barsColourSpace, stackColourSpace)

Insert a Bars strip into the Scene

Arguments

Result

insert_blank(red, green, blue, duration, where, relativeTo, colourSpace)

Insert a Blank strip into the Scene

Arguments

Result

insert_sequence(sequence, where, relativeTo, colourSpace, format)

Insert an image/movie sequence into the Scene

Arguments

Result

insert_text(text, duration, where, relativeTo, alignment)

Insert a Text strip into the Scene

Arguments

Result

get_num_marks(type)

Return number of Timeline Marks in Scene

Arguments

Result

get_mark_ids(offset, count, type)

Return array of mark ids

Arguments

Result

get_mark_ids_in_range(startF, endF, type)

Return array of mark ids within the given frame range in the Scene

Arguments

Result

get_mark(id)

Return Mark object for the given mark ID

Arguments

Result

add_mark(frame, category, note)

Add new Mark to the Scene at the given frame number

Arguments

Result

delete_mark(id)

Remove Mark object with the given ID

Arguments

Result

get_metadata_definitions()

Return array of metadata item definitions

Arguments

Result

add_metadata_defn(name, type)

Add a new Metadata Item field to the Scene

Arguments

Result

delete_metadata_defn(key)

Delete a Metadata Item field from the Scene

Arguments

Result

get_metadata_property_types()

Return list of properties that can be defined for each MetadataItem

Arguments

Result

get_metadata_defn_property(key, property)

Set the value for the given property for the given metadata item key

Arguments

Result

set_metadata_defn_property(key, property, value)

Set the value for the given property for the given metadata item key

Arguments

Result

Scene.get_look_names()

Return names of available Looks

Arguments

Result

Scene.get_look_infos()

Get an array of available Looks. Each array entry is a LookInfo object containing the Name and Group for each Look. Explicitly, each entry will contain the following keys:

Returns new array of LookInfo objects on success, NULL on error.

Arguments

Result

set_transient_write_lock_deltas(enable) BETA

Use to enable (or disable) creation of deltas in a scene where FLAPI does not have the write lock. In particular, this is needed for FLAPI scripts running inside the main application that wish to modify the current scene.

When you open such a delta, you are preventing anything else from being able to make normal scene modifications. You should therefore ensure you hold it open for as short a time as possible. Note also that you should not disable transient deltas while a transient delta is in progress.

Arguments

Result

set_custom_data(data_key, data_value)

Set a custom data value in the scene with the supplied (string) key. Setting a custom data value does not require a delta. Also custom data values are unaffected by undo/redo. Existing custom data values can be deleted from a scene by supplying NULL/None/null as the data value (for an existing key).

Arguments

Result

get_custom_data(data_key)

Get a custom data value from the scene previously set using set_custom_data.

Arguments

Result

get_custom_data_keys()

Return sorted array of (string) keys that can be used to fetch scene custom data values via get_custom_data.

Arguments

Result

SceneSettings

This class provides an interface to get/set scene settings, which affect all Shots in a Scene.

Signals

Properties

These properties names can be used as keys with the get() and set() methods to read or modify scene settings.


Methods

get_setting_keys()

Return array of keys that can be used to get/set Scene Settings parameters

Arguments

Result

get_setting_definition(key)

Return SceneSettings parameter type definition for the given key

Arguments

Result

get(keys)

Return values for given SceneSettings keys

Arguments

Result

get_single(key)

Return value for given SceneSettings key

Arguments

Result

set(values)

Set values for the given SceneSettings keys

Arguments

Result

set_single(key, value)

Set value for the given SceneSettings key

Arguments

Result

SequenceDescriptor

A SequenceDescriptor represents a movie file (e.g. /vol/bl000-images/myjob/media/A001_C001_00000A_001.R3D) or a sequence of image files (e.g. /vol/bl000-images/myjob/renders/day1_%.7F.exr) on disk. It has a frame range (which does not have to cover the full length of the media on disk) and associated metadata. Audio-only media (e.g. OpAtom MXF audio, or .wav files) is also described using a SequenceDescriptor.

Signals

Methods

SequenceDescriptor.get_for_template(template, start, end)

Search the filesystem and return zero or more SequenceDescriptors which match the given filename template (e.g. "/vol/images/A001B002.mov" or "/vol/san/folder/%.6F.dpx", and optionally intersecting the given start and end frame numbers.

Arguments

Result

SequenceDescriptor.get_for_template_with_timecode(template, startTC, endTC)

Search the filesystem and return zero or more SequenceDescriptors which match the given filename template (e.g. "/vol/images/A001B002.mov" or "/vol/san/folder/%.6F.dpx", and optionally intersecting the given start and end timecodes.

Arguments

Result

SequenceDescriptor.get_for_file(filepath)

Create a SequenceDescriptor for a single file

Arguments

Result

get_start_frame()

Return the first frame number, which does not necessarily correspond with the first frame of the files on disk.

Arguments

Result

get_end_frame()

Return the last frame number, which does not necessarily correspond with the last frame of the files on disk.

Arguments

Result

get_start_timecode(index)

Return the timecode at the first frame of the sequence. Some media can support two timecode tracks, so you must specify which one you want (0 or 1).

Arguments

Result

get_end_timecode(index)

Return the timecode at the last frame of the sequence. Some media can support two timecode tracks, so you must specify which one you want (0 or 1).

Arguments

Result

get_start_keycode()

Return the keycode at the first frame of the sequence.

Arguments

Result

get_end_keycode()

Return the keycode at the last frame of the sequence.

Arguments

Result

get_start_handle()

Return the first frame number on disk (0 for movie files).

Arguments

Result

get_end_handle()

Return the last frame number on disk (inclusive).

Arguments

Result

get_width()

Return the width (in pixels) of the images in this sequence. Returns 0 for audio-only media.

Arguments

Result

get_height()

Return the height (in pixels) of the images in this sequence. Returns 0 for audio-only media.

Arguments

Result

get_pixel_aspect_ratio()

Return the pixel aspect ratio (width/height) of the images in this sequence. Returns 1.0 if unknown.

Arguments

Result

get_path()

Return the path to the folder containing this sequence.

Arguments

Result

get_name()

Return the filename (for a movie) or the filename template (for an image sequence, using FilmLight %.#F syntax for frame numbering), excluding the folder path.

Arguments

Result

get_ext()

Return the filename extension (including the leading '.') for this sequence.

Arguments

Result

get_prefix()

Return filename prefix before numeric component

Arguments

Result

get_postfix()

Return filename postfix after numeric component

Arguments

Result

get_format_len()

Return number of digits in numerical component of filename

Arguments

Result

get_base_filename_with_F()

Return filename (without path) using FilmLight %.#F syntax for the frame number pattern

Arguments

Result

get_base_filename_with_d()

Return filename (without path) using printf %0#d syntax for the frame number pattern

Arguments

Result

get_full_filename_with_F()

Return filename (with path) using FilmLight %.#F syntax for the frame number pattern

Arguments

Result

get_full_filename_with_d()

Return filename (with path) using printf %0#d syntax for the frame number pattern

Arguments

Result

get_base_filename(frame)

Return filename (without path) for the given frame number

Arguments

Result

get_filename_for_frame(frame)

Return filename (with path) for the given frame number

Arguments

Result

get_tape(index)

Return the tape name. Some media can support two tracks, so you must specify which one you want (0 or 1).

Arguments

Result

get_metadata()

Return the metadata read when the sequence was scanned on disk, in human-readable form.

Arguments

Result

is_movie()

Return whether sequence is a movie file

Arguments

Result

has_blg()

Return whether sequence has BLG (Baselight Linked Grade) information

Arguments

Result

is_blg()

Return whether sequence is a BLG (Baselight Linked Grade)

Arguments

Result

has_audio()

Return whether movie file has audio

Arguments

Result

get_audio_channels()

Return number of audio channels in movie

Arguments

Result

get_audio_sample_rate()

Return audio sample rate (in Hz)

Arguments

Result

get_audio_length_in_samples()

Return total number of audio samples in file

Arguments

Result

trim_movie(output, start, length)

Create (if possible) a trimmed copy of the movie specified by this descriptor

Arguments

Result

Shot

A shot in Baselight is a set of strips comprising a top strip (typically containing a Sequence operator referencing input media) and the strips lying directly underneath it. These strips apply image-processing and other operations to the top strip.

Signals

Methods

is_valid()

Called to determine if the shot object references a valid top strip an open scene. A shot object may become invalid in a couple of ways:

Arguments

Result

get_scene()

Get the scene object which this shot is a part of.

Arguments

Result

get_id()

Get the shot's identifier, an integer which uniquely identifies the shot within the timeline. The id is persistent, remaining constant even if the scene containing the shot is closed and reopened.

Arguments

Result

get_start_frame()

Get the start frame of the shot within the scene which contains it. Because the time extent of a shot is actually defined by the shot's top strip, the start frame is actually the start frame of the top strip.

Arguments

Result

get_end_frame()

Get the end frame of the shot within the scene which contains it. Because the time extent of a shot is defined by the shot's top strip, the end frame is actually the end frame of the top strip. In Baselight, shot extents are defined in floating-point frames and are start-inclusive and end-exclusive. This means that the shot goes all the way up to the beginning of the end frame, but doesn't include it.

So a 5-frame shot starting at frame 100.0 would have an end frame 105.0 and 104.75, 104.9 and 104.99999 would all lie within the shot.

Arguments

Result

get_poster_frame()

Get the poster frame of the shot within the scene that contains it.

Arguments

Result

get_start_timecode()

Get the start record timecode of the shot

Arguments

Result

get_end_timecode()

Get the end record timecode of the shot

Arguments

Result

get_timecode_at_frame(frame)

Get the record timecode at the given frame within the shot

Arguments

Result

get_src_start_frame()

Return start frame number within source sequence/movie

Arguments

Result

get_src_end_frame()

Return end frame number within source sequence/movie (exclusive)

Arguments

Result

get_src_start_timecode()

Return start timecode within source sequence/movie

Arguments

Result

get_src_end_timecode()

Return end timecode within source sequence/movie (exclusive)

Arguments

Result

get_src_timecode_at_frame(frame)

Return source timecode at the given frame within the shot

Arguments

Result

get_src_start_keycode()

Return start keycode within source sequence/movie

Arguments

Result

get_src_end_keycode()

Return end keycode within source sequence/movie (exclusive)

Arguments

Result

get_input_colour_space(eye)

Return the input colour space defined for this shot. Can be 'None', indicating no specific colour space defined. For RAW codecs, this may be 'auto' indicating that the input colour space will be determined by the SDK used to decode to the image data. In either case the actual input colour space can be determined by call get_actual_input_colour_space().

Arguments

Result

set_input_colour_space(name, eye)

Set the input colour space

Arguments

Result

set_stack_colour_space(name, eye)

Set the stack colour space

Arguments

Result

get_actual_input_colour_space(eye)

Return the input colour space for this shot. If the input colour space is set to 'Auto', the actual colour space name will be returned.

Arguments

Result

get_input_format(eye)

Return the input format name for this shot

Arguments

Result

set_input_format(name, eye)

Set the input format name for this shot

Arguments

Result

get_input_video_lut(eye)

Return the input video lut value for this shot

Arguments

Result

set_input_video_lut(video_lut, eye)

Set the input video LUT for this shot

Arguments

Result

get_metadata(md_keys)

Get metadata values for the keys provided. The possible keys and the value type for each key are obtained using the Scene.get_metadata_definitions method.

Arguments

Result

get_metadata_strings(md_keys)

Get metadata values expressed as strings for the keys provided. The possible keys are obtained using the Scene.get_metadata_definitions method.

Arguments

Result

set_metadata(metadata)

Set metadata values for the keys provided. The possible keys and the value type for each key are obtained using the Scene.get_metadata_definitions method.

Arguments

Result

get_sequence_descriptor()

Get a SequenceDescriptor object that represents the input media for this shot.

Arguments

Result

supports_client_event_data()

Does this shot support client event lists/data.

Arguments

Result

get_client_event_list(list_frame)

Get array of client events (notes/flags) for either an entire shot, or a specific frame of a shot. When querying the event list at a specific frame, NULL/None/null will be returned if no event list exists at that frame or the shot. The events array returned will be chronologically sorted (oldest first). Each event entry is itself a dictionary describing that event.

Arguments

Result

add_client_note(client_name, note_text, event_list_frame)

Add a client note to either the client event list for an entire shot, or to the client event list at a specific frame number.

Arguments

Result

add_client_flag(client_name, event_list_frame)

Add a new client flag entry to either the client event list for an entire shot, or to the client event list at a specific frame number. A client event list only supports a single flag event for a given client name; If one already exists, a call to this method will replace it with a new one.

Arguments

Result

delete_client_event(event_id)

Delete the (note or flag) event with the supplied id from the shot's client event list.

Arguments

Result

set_client_event_metadata(client_event_id, metadata)

Set custom metadata key/value pairs for the client event with the supplied ID.

Arguments

Result

get_client_event_metadata(client_event_id, md_keys)

Get custom metadata key/value pairs for the client event with the supplied ID.

Arguments

Result

delete_client_event_metadata(client_event_id, metadata_key)

Delete a single metadata key/value item from the client event with the supplied ID.

Arguments

Result

get_client_event_list_frames()

Get array of (shot start relative) frame numbers of frames with client event lists

Arguments

Result

delete_frame_client_event_list(list_frame)

Delete the entire client event list at the given shot frame (if any).

Arguments

Result

get_client_data_summary()

Get summary info on any client data associated with this shot.

Arguments

Result

get_num_marks(type)

Get number of marks within shot. If type is supplied, only return number of marks of the given type

Arguments

Result

get_mark_ids(offset, count, type, eye)

Get shot mark ids within the shot. Shot marks are marks which are attached to the shot's top strip. If type is specified, only return marks of matching type.

Arguments

Result

get_mark(id)

Get Mark object for given ID

Arguments

Result

add_mark(frame, category, note, eye)

Add new Mark to the shot at the given source frame

Arguments

Result

delete_mark(id, eye)

Delete the Mark object with the given mark ID

Arguments

Result

get_categories()

Get the set of categories assigned to this shot.

Arguments

Result

set_categories(categories)

Set the categories assigned to this shot

Arguments

Result

insert_blg_stack(blg_path)

Insert a BLG stack at the bottom of the shot.

Arguments

Result

get_blg_payload()

Returns the BLG payload for this shot.

Arguments

Result

apply_blg_payload(blg_payload, blg_resources)

Insert a BLG stack at the bottom of the shot.

Arguments

Result

get_blg_resources()

Returns the BLG resources for this shot.

Arguments

Result

insert_basegrade_layer(values)

Insert a BaseGrade layer at the bottom of the stack.

Arguments

Result

insert_cdl_layer(cdl_values)

Insert a CDLGrade layer at the bottom of the shot.

Arguments

Result

insert_cdl_layer_above(cdl_values)

Insert a CDLGrade layer at the top of the shot.

Arguments

Result

insert_look_layer(look_name)

Insert a Look kayer at the bottom of the shot.

Arguments

Result

insert_truelight_layer(lut_path)

Insert a Truelight layer at the bottom of the shot. The Truelight operator is used for applying 1D and 3D LUTs to an image.

Arguments

Result

insert_shape_layer_from_svg(svg_path, fit_mode, mask_format, mask_name)

Insert a layer with a shape strip populated from an SVG file at the bottom of the shot.

Arguments

Result

insert_colour_space_layer(toColourSpace, drt, identify)

Insert a ColourSpace operator at the bottom of the stack for this shot

Arguments

Result

insert_lut_layer(location, file, inputColourSpace, outputColourSpace, inputLegalRange, outputLegalRange, tetrahedral)

Insert a LUT operator at the bottom of the stack for this shot

Arguments

Result

delete_all_layers()

Remove all layers from the shot.

Arguments

Result

get_codec()

Method to obtain the codec of the input media of the shot.

Arguments

Result

Shot.get_decode_parameter_types()

Return list of supported decode parameter codec keys

Arguments

Result

Shot.get_decode_parameter_type_for_codec(codec)

Return the key identifying the decode parameters type to use for the given video codec

Arguments

Result

Shot.get_decode_parameter_definitions(decode_type)

Static method called to obtain the image decode parameter definitions for a given codec. The decode parameters are used to control how an RGBA image is generated from RAW formats like ARRIRAW, R3D etc.

This method returns an array of image decode parameter definitions for a given decode parameter type, one per parameter. Each parameter definition is a collection of key/value pairs, with different entries dependent on the type of parameter.

Arguments

Result

get_decode_parameters()

This method returns the image decode parameters for the shot.

Arguments

Result

set_decode_parameters(decode_params)

Set some or all of the image decode parameters for the shot.

Arguments

Result

get_audio_settings()

Return the audio settings defined for this shot. Returns NULL if the shot has no audio defined.

Arguments

Result

set_audio_settings(audio_settings)

Set the audio settings for this shot.

Arguments

Result

ThumbnailManager

Interface used to generate shot thumbnails

Signals

Methods

ThumbnailManager.get_poster_uri(shot_if, options)

Get a poster (or specific) frame thumbnail URI for a shot

Arguments

Result

ThumbnailManager.get_scrub_uri_template(scene_if, shot_id, options)

Get a scrub image URI template (prefix & suffix strings). This can be used while scrubbing to generate image URIs without additional roundtrips/calls to the server.

Arguments

Result

Timer (BETA)

A Timer allows your script to be triggered periodically to perform processing BETA

Signals

Methods

Timer.create(interval, repeat)

Create a new Timer object

Arguments

Result

start()

Start timer running

Arguments

Result

is_started()

Inquire if timer is started

Arguments

Result

stop()

Stop timer firing

Arguments

Result

get_interval()

Return interval between timer ticks firing

Arguments

Result

set_interval(interval)

Set interval between timer ticks firing

Arguments

Result

Utilities

Utility functions

Signals

Methods

Utilities.timecode_from_string(str, fps, wraphour)

Convert string to Timecode

Arguments

Result

Utilities.get_allowed_enum_values(enumType)

Returns an array of EnumInfo objects representing the allowed values for a given enumeration type. Explictly, each returned entry has two fields: * Value - The (unique) internal value. * Desc - The user-friendly description for the value (so that you would typically present Desc to the user and use Value in calls to FLAPI functions).

Arguments

Result

Volumes

Query and configure storage for this system

Signals

Methods

Volumes.get_volume_keys()

Return keys for volumes accessible from this system

Arguments

Result

Volumes.get_local_volume_keys()

Return volumes defined locally on this system

Arguments

Result

Volumes.get_volume_info(keys)

Return VolumeInfo describing the volume with the given key

Arguments

Result

Value Types

APIUserInfo

Settings for an API user

Fields

AudioSequenceSettings

Settings defining the behaviour of an Audio Sequence

Fields

AudioSyncProgress

Progress information from audio sync operation

Fields

AudioSyncSettings

Settings to use for AudioSync operation

Fields

BLGExportSettings

Settings to use for BLG exports

Fields

CDLExportSettings

Settings to use for CDL exports

Fields

CategoryInfo

Definition of a Category used to annotate marks, shots or strips

Fields

ClientViewClientSettings

Settings for a connected Client View

Fields

ClientViewHostUserSettings

Settings for user hosting the Client View

Fields

ClientViewStreamSettings

Settings for a Client View stream

Fields

ColourSpaceInfo

Description of a Truelight Colour Space

Fields

ConnectionInfo

Dictionary describing a single connection.

Fields

CubeExportSettings

Settings to use for Cube exports

Fields

CustomerInfo

Dictionary containing customer related settings/preferences.

Fields

DRTInfo

Description of a Truelight Display Rendering Transform

Fields

DecodeParameterChoice

Fields

DecodeParameterDefinition

This type is returned by get_decode_parameter_definitions to define the data type, label, ranges and values for each decode parameter that can be get or set for a Shot.

Fields

DialogItem (BETA)

Definition of an item to be shown in a DynamicDialog BETA

Fields

EnumInfo

Information about a defined enumerated value

Fields

ExportOpInfo

This type is returned to return information about export operations queued via QueueManager

Fields

ExportProgress

Progress information from Export operation

Fields

FormatBurninItem

Definition of a text element within a FormatBurnin

Fields

FormatInfo

Specifies the width, height, pixel aspect ratio

Fields

FormatMapping

Defines the mapping from one Format to another Format

Fields

FormatMask

Specifies the area of Mark defined with a Format

Fields

FrameRange

Defines a range of frames

Fields

KeyTextItem

A mapping for a key object to a user-readable string describing that key

Fields

LicenceItem

Description of a installed licence option

Fields

LookInfo

Information for a Look

Fields

MetadataItem

Definition of a Metadata field that exists across all shots in a Scene

Fields

MetadataProperty

Definition of a Property that can specified for each MetadataItem defined in a Scene

Fields

MultiPasteProgress

Progress information from Multi-Paste operation

Fields

MultiPasteSettings

Settings to use for MultiPaste operation

Fields

NewSceneOptions

Options for create a new database or temporary scene

Fields

OpenSceneStatus

Status of scene opening or creation operation

Fields

QueueLogItem

Log Item from Queue Operation

Fields

QueueOp

Description of an Operation in a Queue

Fields

QueueOpStatus

Status of an Operation in a Queue

Fields

Rational

Holds a rational number. Used in situations where exact ratios are required.

Fields

RenderCodecInfo

Definition of a Codec that is supported for an image or movie file type

Fields

RenderCodecParameterInfo

Definition of a parameter to an image or movie codec

Fields

RenderCodecParameterValue

Definition of a valid value for a codec parameter

Fields

RenderDeliverable

This type is used to specify the render settings for an individual deliverable defined within a RenderSetup

Fields

RenderFileTypeInfo

Definition of an image or movie type

Fields

RenderOpInfo

This type is returned to return information about render operations queued via QueueManager

Fields

RenderProcessorLogItem

Log Item from RenderProcessor

Fields

RenderStatus

Status of render operation

Fields

SDKVersion

Version information for 3rd-party SDKs used in the application

Fields

SceneInfo

Return general information about the state of a scene

Fields

ScenePath

A ScenePath defines the host, job, folder and scene names required to create or open a FilmLight scene

Fields

SceneSettingDefinition

Type information for an SceneSettings parameter

Fields

ShotIndexRange

shot index range

Fields

ShotInfo

Shot info object

Fields

StillExportSettings

Settings to use for Still exports

Fields

VolumeInfo

Definition of a volume attached to, or accessible from, a FilmLight system

Fields

Constants & Enumerations

Constants are defined at the top level of the flapi module, and can be accessed like so:

import flapi

fieldOrder = flapi.FIELDORDER_PROGRESSIVE

AUDIOSEQ_TYPE

Type of Audio in an Audio Sequence

AUDIOSYNCSTATUS

Status info related to audio sync progress

AUDIOSYNC_CRITERIA

Values for AudioSyncSettings Criteria

AUDIOSYNC_FPS

Values for AudioSyncSettings FPS

AUDIOSYNC_METADATA

Values for AudioSyncSettings Metadata

AUDIOSYNC_RATIO

Values for AudioSyncSettings Ratio

AUDIOSYNC_READLTC

Values for AudioSyncSettings ReadLTC

AUDIOSYNC_SUBSEARCH

Values for AudioSyncSettings SubSearch

AUDIO_RATE

Audio Sample Rate

BLGEXPORT_LOCKGRADE

Values for BLGExportSettings LockGrade

BLGEXPORT_SCALE

Values for BLGExportSettings Scale

BURNIN_BORDER

Define border type for burnin text item

BURNIN_HALIGN

Define horizontal alignment of burnin text item

BURNIN_ITEM_TYPE

Specify burnin item type

BURNIN_VALIGN

Define vertical alignment of burnin text item

CDLEXPORT_CDLLAYER

Values for CDLExportSettings CDLLayer

CDLEXPORT_FORMAT

Values for CDLExportSettings Format

CUBEEXPORT_CUBERESOLUTION

Values for CubeExportSettings CubeResolution

CUBEEXPORT_EXTENDEDRANGES

Values for CubeExportSettings ExtendedRanges

CUBEEXPORT_LUT1OPTIONS

Values for CubeExportSettings LUT1Options

CUBEEXPORT_LUT2OPTIONS

Values for CubeExportSettings LUT2Options

CUBEEXPORT_LUT3OPTIONS

Values for CubeExportSettings LUT3Options

CUBEEXPORT_LUTFORMAT

Values for CubeExportSettings LUTFormat

CUBEEXPORT_LUTRESOLUTION

Values for CubeExportSettings LUTResolution

CUBEEXPORT_NUMLUTS

Values for CubeExportSettings NumLUTs

DECODEPARAM_TYPE

Data type for a DecodeParameterDefinition

DECODEQUALITY

Decode Qulity to use for decoding source images for RAW codecs

DIALOG_ITEM_TYPE

Type for a DynamicDialogItem used in a DynamicDialog BETA

EXPORTSTATUS

Status info related to Export progress

EXPORTTYPE

Type of Exporter BETA

EXPORT_CATEGORYMATCH

Values for Exporter CategoryMatch field

EXPORT_FRAMES

Values for Exporter Frames field

EXPORT_OVERWRITE

Values for Exporter Overwrite field

EXPORT_SOURCE

Values for Exporter Source field

EXPORT_STEREO

Values for Exporter Stereo field

FIELDORDER

Field order behaviour

FORMATSET_SCOPE

Defines the scope that a FormatSet is defined in

FSFILTER

Type of items to return from Filesystem get_items method

IMAGETRANSFORM_MODE

Specify filtering kernel to use for image resampling/transform operations

INSERT_POSITION

Specify where to insert a sequence in a Scene

LOG_SEVERITY

Log Message Severity BETA

LUT_LOCATION

Specify where LUT data should be found for a LUT operator

MARK_TYPE

Used to distinguish between timeline, shot and strip marks

Location within application of new menu or menu item BETA

MULTIPASTESTATUS

Status info related to Multi-Paste progress

MULTIPASTE_BLGRESOURCECONFLICT

Values for MultiPasteSettings BLGResourceConflict

MULTIPASTE_DESTSELECTION

Values for MultiPasteSettings DestSelection

MULTIPASTE_DESTSHOTS

Values for MultiPasteSettings DestShots

MULTIPASTE_EDLAPPLYASCCDL

Values for MultiPasteSettings EDLApplyASCCDL

MULTIPASTE_LAYERZEROBEHAVIOUR

Values for MultiPasteSettings LayerZeroBehaviour

MULTIPASTE_LAYERZEROCATEGORIES

Values for MultiPasteSettings LayerZeroCategories

MULTIPASTE_MATCHBY

Values for MultiPasteSettings MatchBy

MULTIPASTE_MATCHQUALITY

Values for MultiPasteSettings MatchQuality

MULTIPASTE_PASTELOCATION

Values for MultiPasteSettings PasteLocation

MULTIPASTE_SOURCE

Values for MultiPasteSettings Source

MULTIPASTE_SOURCESHOTS

Values for MultiPasteSettings SourceShots

OPENFLAG

Flags used to control opening a scene

OPERATOR_BARS_TYPE

Define the type of Bars to render

OPSTATUS

Status of an operation in Queue or Processor

OPTICALFLOW_QUALITY

Optical Flow Quality

OPTICALFLOW_SMOOTHING

Optical Flow Smoothing

PROXY_RESOLUTION

Proxy Resolution of Render Format

QUEUE_LOG_TYPE

Message type for log entry queue operation log BETA

RENDER_CLIPNAME_SOURCE

Which clip name to embed into rendered output

RENDER_COLOURSPACE

Special values to use for RenderColourSpace in RenderDeliverable

RENDER_EMPTY_BEHAVIOUR

Action to take when encountering frames in timeline with no strips/shots

RENDER_ERROR_BEHAVIOUR

Action to take when encountering frames in timeline with no strips/shots

RENDER_FORMAT

Special values to use for RenderFormat in RenderDeliverable

RENDER_FRAMENUM

Specify how frame number for sequence should be calculated

RENDER_INCOMPLETE_BEHAVIOUR

Action to take when encountering shots with missing strips

RENDER_LAYER

Layers to include when rendering. This can be a layer number or one of the following constants.

RENDER_MASK

Select whether to crop to the mask, or set the black value for the masked area

RENDER_NCLC_TAG

Which NCLC tag to use in QuickTime Movie files for colourimetry

RENDER_TAPENAME_SOURCE

Which tape name to embed into rendered output

RENDER_TIMECODE_SOURCE

Which timecode to embed into rendered output

ROP_TEXT_ALIGN

Text alignment

SEQRESAMPLE_MODE

Sequence Resample Mode to use when resampling a sequence to a different video frame rate

STEREO_EYE

Stereo eye

STILLEXPORT_BURNIN

Values for StillExportSettings Burnin

STILLEXPORT_DECODEQUALITY

Values for StillExportSettings DecodeQuality

STILLEXPORT_FILETYPE

Values for StillExportSettings FileType

STILLEXPORT_FORMAT

Values for StillExportSettings Format

STILLEXPORT_MASK

Values for StillExportSettings Mask

STILLEXPORT_MASKMODE

Values for StillExportSettings MaskMode

STILLEXPORT_RESOLUTION

Values for StillExportSettings Resolution

STILLEXPORT_TRUELIGHT

Values for StillExportSettings Truelight

SVGFITMODE

Controls how an SVG is transformed/fitted into a shape strip's 'target area' (the working format area or an optional mask area transformed to the working format).

VIDEOLUT

Video Scaling LUT

Examples

Opening a connection

import os
import sys
import flapi

c = flapi.Connection("localhost")

try:
    c.connect()
except flapi.FLAPIException as exc:
    print( "Error: %s" % exc )
    sys.exit(1)

print( "Connection OK" )

Listing jobs in database

import flapi

c = flapi.Connection("localhost")

c.connect()

jobs = c.JobManager.get_jobs("localhost")

print( "Found %d jobs on localhost:" % len(jobs) )
for j in jobs:
    print( "  %s" % j )

print( "Done" )

Querying Shot metadata in a Scene

import flapi
import time
import sys

if len(sys.argv) < 2:
    print( "No scene specified" )
    print( "Usage: %s host:job:scene" % sys.argv[0] )
    exit(1)

# Connect o  FLAPI
conn = flapi.Connection()
try:
    conn.connect()
except flapi.FLAPIException as ex:
    print( "Cannot connect to FLAPI: %s" % ex )
    sys.exit(1)

# Open the given scene
scene_path = conn.Scene.parse_path( sys.argv[1]  )

try:
    scene = conn.Scene.open_scene( scene_path, { flapi.OPENFLAG_READ_ONLY } )
except flapi.FLAPIException as ex:
    print( "Error loading scene: %s" % ex )
    sys.exit(1)

# Lookup names for each metadata item
tc_keys = {
    "srctc",
    "rectc"
}

md_keys = { 
    "filename", 
    "clip", 
    "tape", 
    "comment"
}

md_names = {}
mddefns = scene.get_metadata_definitions()
for k in tc_keys | md_keys:
    defns = [x for x in mddefns if x.Key == k]
    if defns and len(defns) > 0:
        md_names[k] = defns[0].Name

cat_names = {}
cat_keys = scene.get_strip_categories()
for k in cat_keys:
    cat_defn = scene.get_category(k)
    cat_names[k] = cat_defn.Name

# Lookup shots
nshots = scene.get_num_shots()
print( "Found %d shot(s)" % nshots )

if nshots > 0:
    shots = scene.get_shot_ids(0, nshots)
    for shot_ix, shot_inf in enumerate(shots):
        print("Shot %d:" % shot_ix)

        # Get Shot object for shot with the given ID
        shot = scene.get_shot(shot_inf.ShotId)

        # Get start/end source and record timecode metadata as native Timecode objects
        # using the get_metadata() method
        shot_tcs = shot.get_metadata( tc_keys )
        for tc_key, tc_val in shot_tcs.items():
            print("%15s: %s - %s" % (md_names[tc_key], shot_tcs[tc_key][0], shot_tcs[tc_key][1]))

        # Get other shot metadata in String form using the get_metadata_strings() method
        shot_md = shot.get_metadata_strings(md_keys)
        for md_key, md_val in shot_md.items():
            print("%15s: %s" % (md_names[md_key], md_val))

        # Get marks in shot
        mark_ids = shot.get_mark_ids()
        if len(mark_ids) > 0:
            print( "%15s:" % "Marks" )
            for ix,m in enumerate(mark_ids):
                mark = shot.get_mark(m)
                print( "%20d: Frame %d Type '%s' Message '%s'" % (
                        ix,
                        mark.get_record_frame(),
                        mark.get_category(),
                        mark.get_note_text()
                    )
                )
                mark.release()

        # Get shot categories
        categories = shot.get_categories()
        if len(categories) > 0:
            print("%15s: %s" % ("Categories", set(map(lambda c: cat_names.get(c), categories ) )) )

        # Release Shot object
        shot.release()

scene.close_scene()
scene.release()

Querying SequenceDescriptors for Shots in a Scene

import flapi
import time
import sys
import six

if len(sys.argv) < 2:
    print( "No scene specified" )
    print( "Usage: %s host:job:scene" % sys.argv[0] )
    exit(1)

# Connect to FLAPI
conn = flapi.Connection()
conn.connect()

# Open scene
scene_path = conn.Scene.parse_path( sys.argv[1] )

try:
    scene = conn.Scene.open_scene( scene_path, { flapi.OPENFLAG_READ_ONLY } )
except flapi.FLAPIException as ex:
    print( "Error loading scene: %s" % ex )
    sys.exit(1)

# Lookup shots
nshots = scene.get_num_shots()
print( "Found %d shots" % nshots )

if nshots > 0:
    shots = scene.get_shot_ids(0, nshots)

    # Get Shot IDs
    for shot_ix, shot_inf in enumerate(shots):
        print("shot %d:" % shot_ix)

        #Get shot object
        shot = scene.get_shot(shot_inf.ShotId)

        # Get Shot SequenceDescriptor object
        shot_seq = shot.get_sequence_descriptor()
        if shot_seq:
            print("  Path:  %s" % shot_seq.get_full_filename_with_F() )
            print("  Start: %d" % shot_seq.get_start_frame() )
            print("  End:   %d" % shot_seq.get_end_frame() )
        else:
            print("  No SequenceDescriptor available" )

        shot_seq.release()
        shot.release()

six.moves.input( "Press Enter to close scene & exit" )
print( "Closing scene" )

scene.close_scene()
scene.release()

Inserting a Sequence into a Scene

import sys
import flapi

if len(sys.argv) < 2:
    print( "usage: insert_seq.py <path_to_sequence> [<start frame> <end frame>]" )
    sys.exit(1)

conn = flapi.Connection("localhost")

try:
    conn.connect()
except flapi.FLAPIException as ex:
    print( "Cannot connect to FLAPI: %s" % ex )
    sys.exit(1)

jm = conn.JobManager
if not jm.job_exists("localhost", "flapi"):
    jm.create_job( "localhost", "flapi" )

if jm.scene_exists( "localhost", "flapi", "insert_test" ):
    jm.delete_scene( "localhost", "flapi", "insert_test", ignoreLocks=1 )

sceneOptions = {
    "format": "HD 1920x1080",
    "colourspace": "FilmLight_TLog_EGamut",
    "frame_rate": 24.0,
    "field_order" : flapi.FIELDORDER_PROGRESSIVE
}

scene_path = flapi.ScenePath({ "Host": "localhost", "Job": "flapi", "Scene": "insert_test"})

try:
    scene = conn.Scene.new_scene( scene_path, sceneOptions )
except flapi.FLAPIException as ex:
    print( "Error creating scene: %s" % ex )
    sys.exit(1)

# Create SequenceDescriptor for the given path/frame-range
template = sys.argv[1]
if len(sys.argv) > 2:
    startFrame = int( sys.argv[2], 10 )
    endFrame = int( sys.argv[3], 10 )
else:
    startFrame = None
    endFrame = None

seqs = conn.SequenceDescriptor.get_for_template( template, None, None )
if len(seqs)==0:
    print( "Cannot find SequenceDescriptor for " + template )
    sys.exit(1)

# Insert SequenceDescriptor into Scene, producing a Shot object
scene.start_delta("Insert Sequence(s)")

shots = []
for seq in seqs:
    shot = scene.insert_sequence( seq, flapi.INSERT_END, None, None, None )
    shots.append(shot)
    seq.release()

scene.end_delta()

# Print out some info about the sequence we just inserted
for shot in shots:
    md = shot.get_metadata_strings( [ "clip", "tape", "srctc" ] )
    for mdk in md:
        print( "    %s: %s" % (mdk, md[mdk]) )

# Release Shot objects
for shot in shots:
    shot.release()

# Save changes
scene.save_scene()
scene.close_scene()
scene.release()

Rendering a Scene using the Queue

import flapi
import sys
import time

if len(sys.argv) < 2:
    print("usage: %s host:job:scene")
    sys.exit(1)

conn = flapi.Connection("localhost")
try:
    conn.connect()
except flapi.FLAPIException as ex:
    print( "Cannot connect to FLAPI: %s" % ex )
    sys.exit(1)

# Open the scene
scene_path = conn.Scene.parse_path( sys.argv[1] )

try:
    scene = conn.Scene.open_scene( scene_path )
except flapi.FLAPIException as ex:
    print( "Error loading scene: %s" % ex )
    sys.exit(1)

# Create RenderSetup
print( "Create RenderSetup for Scene")
renderSetup = conn.RenderSetup.create_from_scene( scene )

# Check that at least one deliverable is enabled
if 0 not in [renderSetup.get_deliverable(i).Disabled for i in range(renderSetup.get_num_deliverables())]:
    print("No render deliverables are enabled in this scene. Enable at least one in the Render View in the Baselight UI and save the scene.")
    sys.exit(1)

# Create Queue Manager
print( "Opening QueueManager connection" )
qm = conn.QueueManager.create_local()

# Submit render job to Queue
print( "Submitting to queue" )
opinfo = renderSetup.submit_to_queue( qm, "FLAPI Render Test " + sys.argv[1] )

print( "Created operation id %d" % opinfo.ID )
if opinfo.Warning != None:
    print( "Warning: %s" % opinfo.Warning )

# We're finished with RenderSetup now
renderSetup.release()

# We're finished with Scene now
scene.close_scene()
scene.release()

# Wait on job to finish
print( "Waiting on render job to complete" )
while True:
    opstat = qm.get_operation_status( opinfo.ID )
    print( "  Status: {Status} {Progress:.0%} {ProgressText}".format(**vars(opstat)) )
    if opstat.Status == "Done":
        break
    time.sleep(0.5)

print( "Operation complete" )

# Remove completed operation from queue
print( "Archiving operaton" )
qm.archive_operation( opinfo.ID )

qm.release()

Querying operation status in the Queue

import flapi
import sys

conn = flapi.Connection("localhost")

conn.connect()

qm = conn.QueueManager.create_local()

ids  = qm.get_operation_ids()
for id_ in ids:
    print( "Operation %d" % id_ )

    op = qm.get_operation( id_ )
    status = qm.get_operation_status( id_ )
    log = qm.get_operation_log( id_ )

    print( "  Desc:  %s" % op.Description  )

    print( "  Status: %s"  % status.Status )
    print( "  Progress: %.1f" % (status.Progress * 100.0) )
    print( "  Last Message:  %s" %  status.ProgressText )

    print( "  Log:" )
    for l in log:
        print( "   %s %s: %s" % (l.Time, l.Message, l.Detail) )

Generated on Wed 14 Jun 2023 at 09:09:55