Engine Class

engine.open_engine(**kwargs): Open a ptsl engine. Engine will close with the context. :param company_name: The company name to register. :param application_name: The application name to register. :param certificate_path: A path to a certificate (deprecated).

class ptsl.Engine(company_name: str | None = None, application_name: str | None = None, certificate_path: str | None = None, address='localhost:31416')

A callable interface for PTSL.

The Engine exposes PTSL commands as methods, translating call arguments into corresponding requests, and then translating responses into return objects. So, instead of creating a request, dispatching a command to the client with the request object, receving a response (or error) and processing it, you can simply call a method on the Engine with parameters, and that method returns a value.

One of the goals of the engine class is to hide as many redundant value classes from the PTSL protocol as possible, so where the PTSL client may return an enumeration value for the session sample rate, the Engine returns a simple integer. Entity types, like Track or MemoryLocation objects are retained.

The Engine initializes a new Client object by passing its initialization parameters to __init__()

close(): Close the engine.

ptsl_version() → int

Requests the current PTSL version running on the server and returns the reponse value.

Returns:: The server’s PTSL version number.
Return type:: int

host_ready_check(): Runs the HostReadyCheck message on the host, any error is returned as an exception.

Note

This method will succeed even if the client connection is not registered.

create_session(name: str, path: str) → CreateSessionBuilder

Create a new Pro Tools session. Returns a CreateSessionBuilder object used to customize the creation request.

Creating a session with a builder

b = engine.create_session("My Session", "/Path/to/Session")
b.wave_format()
b.sample_rate(96000)
b.bit_depth(32)
b.create() # Session is created

Parameters:

name (str) – Session Name
path (str) – Path to the new session

create_session_from_template(template_group: str, template_name: str, name: str, path: str) → CreateSessionFromTemplateBuilder

Create a new session with an installed template.

Parameters:

template_group (str) – Name of the template group
template_name (str) – Name of the template to use
name (str) – Name of the new session
path (str) – Path for the new session

create_session_from_aaf(name: str, path: str, aaf_path: str) → CreateSessionFromAAFBuilder

Create a session from an AAF.

Parameters:

name (str) – Name of the new session
path (str) – Path for the new session
aaf_path (str) – Path to the AAF file to convert

open_session(path: str): Open a session.

close_session(save_on_close: bool): Close the currently-open session.

save_session(): Save the currently-open session.

save_session_as(path: str, name: str)

Save the currently-open session as a new name to a different path.

Parameters:

path (str) – Path to the new session
name (str) – New name for the session

export_session_as_text() → ExportSessionTextBuilder: Export the open session as text.

import_data(session_path: str) → ImportSessionDataBuilder: Import session data into the currently-open session.

import_audio(file_list: ~typing.List[str], destination_path: str | None = None, audio_operations: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53391710> | None = None, audio_destination: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53391790> | None = None, audio_location: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533918d0> | None = None, timecode: str | None = None, location_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392010> | None = 1, location_options: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53391290> | None = 3) → None: Import audio data into the currently-open session. location_data needs to be provided regardless if empty. Just a basic implementation for audio data import TC based only.

select_all_clips_on_track(track_name: str)

Select all clips on track.

Parameters:: track_name (str) – Name of the track to select all clips on.

extend_selection_to_target_tracks(tracks: List[str])

Extend selection to target tracks.

Parameters:: tracks (List[str]) – A list of track names to extend the selection to.

trim_to_selection(): Trim selected clips to the edit selection range.

create_batch_fades(preset_name: str, adjust_bounds: bool)

Create batch fades for the timeline selection based on a preset.

Parameters:

preset_name (str) – Name of the batch fades preset to use.
adjust_bounds (bool) – Auto-adjust clip boundaries to accomodate fades.

rename_target_track(old_name: str, new_name: str)

Renames a track in the currently-open session.

Parameters:

old_name (str) – The name of the track to rename.
new_name (str) – The new name to give the track.

rename_selected_clip(new_name: str, rename_file: bool = True, clip_location: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da750> = 2)

Renames a clip in the current session.

Parameters:

new_name (str) – New name for the clip
rename_file (bool) – If true, file will be renamed as well
clip_location (CL_ClipLocation) – Clip selection location, defaults to CL_Timeline

rename_target_clip(clip_name: str, new_name: str, rename_file: bool = True): Renames a named clip in the current session.

toggle_play_state(): Toggle the play state.

toggle_record_enable(): Toggle record enable.

play_half_speed(): Play at half speed.

record_half_speed(): Record at half speed.

create_memory_location(start_time: str | None = None, memory_number: int | None = None, name: str | None = None, end_time: str | None = None, location: str | None = None, track_name: str | None = None, time_properties: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da710> | None = None, reference: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da850> | None = None, general_properties: MemoryLocationProperties | None = None, comments: str | None = None, color_index: int | None = None) → None: Create a new memory location.

edit_memory_location(location_number: int, name: str, start_time: str, end_time: str, time_properties: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da710>, reference: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da850>, general_properties: MemoryLocationProperties, comments: str, color_index: int | None = None)

Edit a memory location.

Parameters:

location_number (int) – Location number to edit (if location does not exist, this will create a new location in 2023.6)
name (str) – Location name
start_time (str) – Start time
end_time (str) – End time
time_properties (TimeProperties) – Time properties, either this is a range or a marker
reference (MemoryLocationReference) – Reference
general_properties (MemoryLocationProperties) – Location properties
comments (str) – Comment field
color_index (int) – Optional color index. If omitted, Pro Tools will cycle to the next color in its palette rather than preserving the existing color.

get_memory_locations() → List[MemoryLocation]: Get a list of all memory locations in currently-open session.

consolidate_clip(): Consolidate time selection.

export_clips_as_files(path: str, ftype: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392410>, bit_depth: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392750>, ex_format: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392210> | None = None, enforce_avid_compatibility: bool = False, resolve_duplicates: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392a50> | None = None)

Export clips as files.

Parameters:

path – Export directory path. (A MacOS path to a folder, must end with a colon “:”.)
ftype – File type, WAV/AIFF/etc.
bit_depth – Bit Depth
ex_format – Export file format, mono/multiple mono/interleaved
enforce_avid_compatibilty – Enforce Avid compatibility
resolve_duplicates – Duplicate name resolution method

Raises:

CommandError A PT_UnknownError if the path argument does not end with a colon.

get_file_location(filters=None) → List[FileLocation]

Get a list of file locations meeting a set of criteria.

Parameters:: filters – a List of FileLocationTypeFilter If none, defaults to [All_Files]
Returns:: a List of FileLocation

export_mix(base_name: str, file_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53393d50>, sources: ~typing.List[~PTSL_pb2.EM_SourceInfo], audio_info: ~PTSL_pb2.EM_AudioInfo, video_info: ~PTSL_pb2.EM_VideoInfo, location_info: ~PTSL_pb2.EM_LocationInfo, dolby_atmos_info: ~PTSL_pb2.EM_DolbyAtmosInfo, offline_bounce: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53393290>)

Export mixes/”Bounce to Disk” busses in the currently-open session.

Note

This method runs synchronously and will not return until the bounce has completed.

Parameters:

file_type (EM_FileType) – Export file type
sources (List[EM_SourceInfo]) – Busses to bounce
audio_info (EM_AudioInfo) – Audio options
video_info (EM_VideoInfo) – Video options
location_info (EM_LocationInfo) – Output folder settings
dolby_atmos_info (EM_DolbyAtmosInfo) – Dolby Atmos output settings
offline_bounce (bool) – Bounce offline option

session_name() → str: Name of the current open session.

session_path() → str: Path to the current open session.

session_sample_rate() → int | None: Open session sample rate.

session_audio_format() → <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d9650>: Open session audio format.

session_interleaved_state() → bool: Session audio file interleaved state.

session_timecode_rate() → <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d9890>: Session timecode rate.

session_start_time() → str: Session start time.

session_length() → str

Session length.

Returns:: Session length, as a string in the current time code format.

session_feet_frames_rate() → <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d9fd0>: Session feet-frames rate.

session_audio_rate_pull() → <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da210>: Audio pull setting of the currently-open session.

session_video_rate_pull() → <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da210>: Video pull setting of the currently-open session.

transport_state() → str: Current transport state.

transport_armed() → bool: Transport record-arm state.

playback_modes() → Tuple[bool, bool, bool]

Transport’s current set of playback modes.

Returns:: A Tuple of (is_normal, is_loop, is_dynamic_transport)

record_mode() → <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d9490>: Transport’s current record mode.

track_list(filters: List[TrackListInvertibleFilter] = []) → List[Track]

Get a list of the tracks in the current session.

Parameters:: filters – Track list filters. Defaults to [ptsl.PTSL_pb2.TrackListFilter.All]

set_playback_mode(new_mode: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d92d0>): Set the playback mode.

set_record_mode(new_mode: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d9490>, record_arm_transport: bool): Set the record mode.

set_session_bit_depth(new_bit_depth: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392750>): Set session bit depth.

set_session_audio_format(new_audio_format: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d9650>): Set session audio format.

set_session_start_time(new_start: str, track_offset_opts: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53391290>, maintain_relative: bool)

Set session start time.

Parameters:

new_start – New timecode start time
track_offset_opts – The time format of new_start.
maintain_relative – If True, clips will retain their time position relative to the beginning of the session.

set_session_length(new_length: str): Set the session length as a timecode value string.

Important

The new_length value must be greater than “06:00:00:00”, the PTSL server will reject the change and return an error otherwise.

set_session_interleaved_state(new_state: bool): Set session interleaved state.

set_session_time_code_rate(tc_rate: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d9890>): Set session timecode rate.

set_session_feet_frames_rate(ff_rate: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533d9fd0>): Set session feet+frames rate.

set_session_audio_rate_pull(pull_rate: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da210>): Set session audio rate pull.

set_session_video_rate_pull(pull_rate: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533da210>): Set session video rate pull.

cut(special: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392ed0> | None = None): Execute an Edit > Cut.

copy(special: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392ed0> | None = None): Execute an Edit > Copy.

paste(special: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533930d0> | None = None): Execute an Edit > Paste.

clear(special: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53392ed0> | None = None): Execute an Edit > Clear.

refresh_target_audio_files(files: List[str])

Refresh target audio files.

Parameters:: files – A list of files to refresh.

refresh_all_modified_audio_files(): Refreshes all modified audio files.

create_new_tracks(number_of_tracks: int | None = None, track_name: str | None = None, track_format: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c5357b590> | None = None, track_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c5357a8d0> | None = None, track_timebase: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533905d0> | None = None): Create new Tracks

select_tracks_by_name(names: ~typing.List[str], mode: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533db890> | None = 1): Selects all tracks matching any of the passed names literally.

get_edit_mode() → dict[str, ~google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper | list[<google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533dad10>]]

Gets the current session edit mode as well as all possible options

Returns:: A dictionary containing the current edit mode

and all possible edit modes

set_edit_mode(mode: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533dad10>) → None: Sets the current session edit mode

get_edit_tool() → dict[str, ~google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper | list[<google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533db010>]]

Gets the current session edit tool as well as all possible options

Returns:: A dictionary containing the current edit tool

and all possible edit tools

set_edit_tool(tool: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533db010>) → None: Sets the current session edit tool

recall_zoom_preset(preset: int) → None: Recall a zoom preset in Pro Tools.

get_timeline_selection(format: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533dbad0> = 5) → Tuple[str, str]

Returns data about the current timeline selection.

Returns:: a Tuple of the In and Out time.

set_timeline_selection(in_time: str | None, play_start_marker_time: str | None = None, out_time: str | None = None, pre_roll_start_time: str | None = None, post_roll_stop_time: str | None = None, pre_roll_enabled: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53393290> | None = None, post_roll_enabled: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53393290> | None = None, update_video_to: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533db550> | None = None, propagate_to_satellites: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c53393290> | None = None, location_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533dbad0> = 5) → None: Set Selection at Timecode

select_memory_location(mem_loc_id: int) → None: Select a memory location given an index value

set_track_mute_state(track_names: List[str], new_state: bool) → None: Sets the mute state of the specified tracks (except Video and MasterFader types of tracks).

set_track_solo_state(track_names: List[str], new_state: bool) → None: Sets the solo state of the specified tracks (except Video and MasterFader types of tracks).

set_track_solo_safe_state(track_names: List[str], new_state: bool) → None: Sets the solo safe state of the specified tracks (except Video and MasterFader types of tracks)

set_track_record_enable_state(track_names: List[str], new_state: bool) → None: Sets the record enable state of the specified tracks (Audio, Instrument, Midi and VCA types of tracks only).

set_track_record_safe_enable_state(track_names: List[str], new_state: bool) → None: Sets the record safe enable state of the specified tracks (Audio, Instrument, Midi and VCA types of tracks only).

set_track_input_monitor_state(track_names: List[str], new_state: bool) → None: Sets the input monitor state of Audio, Instrument and VCA track types.

set_track_smart_dsp_state(track_names: List[str], new_state: bool) → None: Sets the smart DSP state of the specified tracks (except Video, Midi, VCA and Basic Folder types of tracks).

set_track_hidden_state(track_names: List[str], new_state: bool) → None: Sets the hidden state of the specified tracks.

set_track_inactive_state(track_names: List[str], new_state: bool) → None: Set the inactive state of the specified tracks (except Video tracks).

set_track_frozen_state(track_names: List[str], new_state: bool) → None: Sets the frozen state of the specified tracks (Audio, Instrument, AuxInput and Routing Folder types of tracks only).

set_track_online_state(track_name: str, new_state: bool) → None: Sets the online state of the specified track (Video tracks only).

set_track_open_state(track_names: List[str], new_state: bool) → None: Sets the open state of the specified tracks (Folder tracks only).

get_session_ids() → dict[str, str]

Provides originId, instanceId and parentId of the current opened session:

originId is the main ID of the session (or project), and it remains the same in all variations of the session through Save As, Save Copy In, etc. instanceId is unique for each session variation. In a new/original session file, the instanceId is equal to originId. When variants are introduced via Save As, Save Copy In, and several others, instanceId is set to a new unique ID. parentId is set to the instanceId of the source session for sessions based off of a previous session. For new/original sessions, the parentId is set to zeros. That means parentId is equal to originId for first-generation variants, and is different for second and later generation variations.

Returns:: A dictionary containing the originId, instanceId,

and parentId of the current opened session

get_memory_locations_manage_mode() → bool: Returns the Memory Locations Manage Mode state (see menu Window -> Memory Locations in the UI).

set_memory_locations_manage_mode(new_mode: bool) → None: Sets the Memory Locations Manage Mode (see menu Window -> Memory Locations in the UI).

set_main_counter_format(new_loc_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533dbad0>) → None: Sets the time format of the Main Counter.

set_sub_counter_format(new_loc_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533dbad0>) → None: Sets the time format of the Sub Counter.

get_main_counter_format() → dict[str, str]: Gets the time format of the Main Counter as well as all possible options.

get_sub_counter_format() → dict[str, str]: Gets the time format of the Sub Counter as well as all possible options.

undo(depth: int = 1) → dict[str, list[dict[str, str]]]

Undoes the last number of operations, according to depth parameter.

Returns:: A dictionary of successfully undone operations

redo(depth: int = 1) → dict[str, list[str]]

Redos the last number of operations, according to depth parameter.

Returns:: A dictionary of successfully redone operations

undoall() → dict[str, list[str]]

Undoes all operations in Undo History.

Returns:: A dictionary of successfully undone operations

redoall() → dict[str, list[str]]

Redoes all operations in Redo History.

Returns:: A dictionary of successfully redone operations

clear_undo_queue() → None: Clears the undo queue.

set_track_dsp_mode_safe_state(track_names: List[str], new_state: bool) → None: Sets the DSP Mode Safe state for the specified tracks.

get_system_delay() → int

Get the current system delay.

Returns:: the delay in samples.

group_clips() → None: Creates a new clip group based on the Edit selection made across tracks.

ungroup_clips() → None: Reveals all underlying clips and any nested clip groups within a selected clip group, making them independent and editable.

ungroup_all_clips() → None: Reveals all clips within a selected clip group and any of its nested clip groups, making them independent and editable.

regroup_clips() → None: Reassembles a previously ungrouped clip group, including any nested clip groups, restoring its original structure.

repeat_selection(repeats: int = 1) → None: Duplicate selected material by the number passed in to repeats

duplicate_selection() → None: Copies a selection and places it immediately after the end of the selection.

clear_all_memory_locations() → None: Clears all the memory locations in the session.

get_monitor_output_path() → str

Gets monitor output path from I/O Setup.

Returns:: a string containing the monitor output path

get_edit_selection(loc_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x7a9c533dbad0> = 5) → Tuple[str, str]

Returns data about the current edit selection.

Returns:: a Tuple of the In and Out time.