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 0x71f9547e1f10> | None = None, audio_destination: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e1f90> | None = None, audio_location: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e20d0> | None = None, timecode: str | None = None, location_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e2810> | None = 1, location_options: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e1a90> | 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 0x71f95462ef50> = 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 0x71f95462ef10> | None = None, reference: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f95462f050> | 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 0x71f95462ef10>, reference: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f95462f050>, general_properties: MemoryLocationProperties, comments: str)

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

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 0x71f9547e2c10>, bit_depth: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e2f50>, ex_format: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e2a10> | None = None, enforce_avid_compatibility: bool = False, resolve_duplicates: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e3250> | 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 0x71f95462c590>, 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 0x71f9547e3a90>)

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 0x71f95462de50>: 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 0x71f95462e090>: 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 0x71f95462e7d0>: Session feet-frames rate.

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

session_video_rate_pull() → <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f95462ea10>: 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 0x71f95462dc90>: 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 0x71f95462dad0>): Set the playback mode.

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

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

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

set_session_start_time(new_start: str, track_offset_opts: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e1a90>, 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 0x71f95462e090>): Set session timecode rate.

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

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

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

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

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

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

clear(special: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e36d0> | 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 0x71f9547cfd90> | None = None, track_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547cf0d0> | None = None, track_timebase: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e0dd0> | None = None): Create new Tracks

select_tracks_by_name(names: ~typing.List[str], mode: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547d00d0> | 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 0x71f95462f510>]]

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 0x71f95462f510>) → 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 0x71f95462f810>]]

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 0x71f95462f810>) → 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 0x71f9547d0310> = 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 0x71f9547e3a90> | None = None, post_roll_enabled: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e3a90> | None = None, update_video_to: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f95462fd50> | None = None, propagate_to_satellites: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547e3a90> | None = None, location_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x71f9547d0310> = 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 0x71f9547d0310>) → 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 0x71f9547d0310>) → 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 0x71f9547d0310> = 5) → Tuple[str, str]

Returns data about the current edit selection.

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