Skip to main content

Keyframe Pro 2 Documentation

Python Client API Reference

The methods listed in this reference can be accessed through the KeyframePro2ClientApi class found in the keyframe_pro_2_client_api.py file.

For code samples, see the Python Client API Examples.

The Python Client API can be downloaded from the Keyframe Pro main page.

Connect and Initialize

Commands


__init__(self, timeout=2)

Initialize the client instance.

  • timeout: Wait time before a command times out.

connect(self, port=-1, display_errors=True)

Create a connection with Keyframe Pro 2.

  • port: The port Keyframe Pro 2 is listening on. (-1 for default).
  • display_errors: Log connection errors to trace.
  • return: True if connection was successful (or already exists). False otherwise.

disconnect(self)

Disconnect from Keyframe Pro 2.

  • return: True if the existing connection was disconnected successfully. False otherwise.

is_connected(self)

Test if a connection exists.

  • return: True if a connection exists. False otherwise.

initialize(self)

One time initialization required by Keyframe Pro 2.

  • return: True if successfully initalized. False otherwise.

echo(self, text)

Get an echo response from Keyframe Pro 2.

  • text: The string to be sent to the application.
  • return: A string containing the text on success. None otherwise.

get_config(self)

Get the configuration settings for Keyframe Pro 2.

  • return: Dictionary containing the config values.

new_project(self, empty=False)

Create a new project.

  • empty: Create an empty project.
  • return: True if new project created. False otherwise.

open_project(self, file_path)

Open an existing project.

  • file_path: Path to the project.
  • return: True if the project is opened. False otherwise.

import_project(self, file_path)

Import an existing project.

  • file_path: Path to the project.
  • return: True if the project is imported. False otherwise.

save_project(self, file_path)

Save the current project.

  • file_path: Path to the project.
  • return: True if the project is saved. False otherwise.

get_project_path(self)

Get the path to the current project.

  • return: The path to the project. None if there is an error.

import_file(self, file_path, name="", range_start=-1, range_end=-1, parent_id="")

Import a source file into the project.

  • file_path: Path to the source
  • name: Name of the source
  • range_start: Range start frame
  • range_end: Range end frame
  • parent_id: Parent folder of the source
  • return: Dictionary representing the source object. None on error.

add_folder(self, name="", parent_id="")

Add a folder to the project.

  • name: Name of the folder
  • parent_id: Parent folder of the folder
  • return: Dictionary representing the folder object. None on error.

add_timeline(self, name="", parent_id="")

Add a timeline to the project.

  • name: Name of the timeline
  • parent_id: Parent folder of the timeline
  • return: Dictionary representing the timeline object. None on error.

remove(self, id, force=False)

Remove a folder, timeline or source from the project.

  • id: ID for the object to be removed.
  • force: (Source only) Force removal if the source is in use in one or more timelines.
  • return: True on successful removal. False otherwise.

update(self, obj)

Update the folder, timeline or source object with the values contained in the obj dict. Editable obj values that are different will be modified.

  • obj: Dictionary representing the object to be updated.
  • return: Dictionary representing the updated object. None on error.

insert_element_in_timeline(self, source_id, timeline_id, index=-1)

Insert a source element into a timeline.

  • source_id: ID of the source to be added to the timeline.
  • timeline_id: ID of the timeline.
  • index: Index to insert source at. Inserted at the end if index is out of range.
  • return: True on successful insertion. False otherwise.

remove_element_from_timeline(self, timeline_id, index)

Remove a source element from a timeline.

  • timeline_id: ID of the timeline.
  • index: Index of the element to be removed.
  • return: True on successful removal. False otherwise.

get_timeline_elements(self, timeline_id)

Get an ordered list of the sources in a timeline.

  • timeline_id: ID of the timeline.
  • return: An ordered list of dictionaries representing the sources in a timeline. None on error.

get_folders(self)

Get an unordered list of the folders in the project.

  • return: An unordered list of dictionaries representing the folders in the project. None on error.

get_timelines(self)

Get an unordered list of timelines in the project.

  • return: An unordered list of dictionaries representing the timelines in the project. None on error.

get_sources(self)

Get an unordered list of sources in the project.

  • return: An unordered list of dictionaries representing the sources in the project. None on error.

get_frame(self)

Get the current frame of the (primary) active timeline.

  • return: The frame of the (primary) active timeline. Zero on error.

set_frame(self, frame, audio=False, from_range_start=False)

Set the current frame of the (primary) active timeline.

  • frame: Requested frame number
  • audio: Play audio for the frame after setting it.
  • from_range_start: Frame number is relative to the range start.
  • return: The frame of the (primary) active timeline. Zero on error.

get_range(self)

Get the current range of the (primary) active timeline.

  • return: Tuple containing the range of the (primary) active timeline. None on error.

set_range(self, start_frame, end_frame)

Set the current range of the (primary) active timeline.

  • start_frame: Requested range start frame number.
  • end_frame: Requested range end frame number.
  • return: Tuple containing the range of the (primary) active timeline. None on error.

get_bookmarks(self, id="", include_empty_timelines=True)

Get a list of bookmarks and annotations for one or all sources/timelines in the current project. For this method, the bookmarks list only includes bookmarks without any annotation data.

  • id: The ID of a source/timeline to query. All timelines will be included if this is an empty string.
  • include_empty_timelines: Include timelines with no bookmarks/annotations in the final list.
  • return: A list of dictionaries containing the timeline id, name and lists for bookmark and annotation frame numbers.

set_playing(self, playing, play_forwards=True)

Set the play state to playing or paused. Option to control play direction.

  • playing: Enable playing state
  • play_forwards: Play direction (ignored if playing is False)
  • return: True on success. False otherwise.

is_autoplay(self)

Get the autoplay state of the player.

  • return: Autoplay state (True/False). None on error.

get_default_timeline(self)

Get the project default timeline. Imported files (sources) are automatically added to this timeline.

  • return: Dictionary representing the timeline object (may be empty if unassigned). None on error.

set_default_timeline(self, id)

Set the project default timeline. An empty 'id' string will result unassign the default timeline. Imported files (sources) are automatically added to this timeline.

  • id: ID of the timeline to set as the default timeline.
  • return: Dictionary representing the timeline object (may be empty if unassigned). None on error.

get_active_in_viewer(self, index)

Get the source/timeline assigned to a viewer.

  • index: Viewer index. (0 - Viewer A, 1 - Viewer B)
  • return: Dictionary representing the timeline object (may be empty if unassigned). None on error.

set_active_in_viewer(self, id, index)

Set the source/timeline assigned to a viewer. An empty 'id' string will unassign a timeline from the viewer.

  • id: ID of the timeline to be assigned to the viewer.
  • index: Viewer index. (0 - Viewer A, 1 - Viewer B)
  • return: Dictionary representing the timeline object (may be empty if unassigned). None on error.

set_viewer_layout(self, layout="single")

Set the viewer layout to single, split horizontal or split vertical.

  • layout: Desired layout ("single", "horizontal" or "vertical")
  • return: True on success. False otherwise.

queue_export(self, output_dir_path, base_file_name, ext, width, height, ignore_range=False, exclude_audio=False, viewer_capture=False, frames_to_capture="all", exclude_annotations=False, frame_numbering="zero_based", annotation_bg_color=[])

Queue an export operation. This will queue an export and return. The export process begins after the return occurs. Poll for completion/results using query_export().

  • output_dir_path: The output directory path)
  • base_file_name: The file name (excluding extension) for the output file
  • ext: The file extension for the final output
  • width: Output width
  • height: Output height
  • ignore_range: Export the full timeline range
  • exclude_audio: Ignore any audio streams in the final output
  • viewer_capture: Export rendered frames from the viewer (to include annotations, multiple viewports, etc...)
  • frames_to_capture: Determines which viewer frames are exported ("all", "stepped", "bookmarks")
  • exclude_annotations: Exclude annotations from the final output of viewer capture export
  • frame_numbering: Only applies to image sequences (png, jpg). Sets the frame numbering for the sequence ("zero_based", "one_based", "match_frame")
  • annotation_bg_color: Temporarily changes the annotation bg color/opacity on export (if not empty). Integer list representing RGBA values (0-255)
  • return: True if queued sucessfully, False otherwise.

query_export(self, timeout=300, show_poll_timeout_errors=False)

Query the last export. If an export operation is in progress, this command will continue to poll until completion or timeout whichever comes first.

  • timeout: Maximum time to poll for results
  • show_poll_timeout_errors: Log polling timeout messages
  • return: Tuple containing success (boolean) and error messages (if any).