PartielsPy package

Submodules

partielspy.document module

PartielsPy - Document Module

class partielspy.document.Document(document_file: str | Path = None, audio_file_layout: AudioFileLayout | str | Path | AudioFileChannel = None)

Bases: object

This class represents a document in PartielsPy.

It contains an AudioFileLayout that describes the audio file layout of the document, and a collection of Group, each of which can contain multiple Track. The document can be loaded from and saved to an ptldoc file.

Parameters:

  • document_file (str | Path, optional) – The path to the ptldoc file to load. If not provided, an empty document is created.

  • audio_file_layout (AudioFileLayout | str | Path | AudioFileChannel, optional) – The audio file layout for the document. This can be an instance of AudioFileLayout, a string or a Path to an audio file, or an instance of AudioFileChannel. If not provided, an empty audio file layout is created.

add_group(group: Group)

Add a group to the document.

This method checks if the group is an instance of Group and if it already exists in the document. If the group is valid and not already present, it adds the group to the document’s groups.

Parameters:

group (Group) – The group to add to the document.

Raises:

  • TypeError – If the group is not an instance of Group.

  • ValueError – If the group already exists in the document.

property audio_file_layout: AudioFileLayout
property groups: list[Group]
classmethod load(file: Any)

Load a document from an ptldoc file.

Parameters:

file (Any) – The file to load.

Returns:

An instance of the Document class populated with data from the ptldoc file.

Return type:

Document

Raises:

ValueError – If the document is invalid (does not have the correct root ‘document’ tag).

remove_group(group: Group)

Remove a group from the document.

This method searches for the group in the document’s groups and removes it if found.

Parameters:

group (Group) – The group to remove from the document.

Raises:

ValueError – If the group is not found in the document.

save(file: str | Path)

Save the document to an ptldoc file.

Parameters:

file (str | Path) – The path to the file where the document will be saved.

partielspy.export_config module

A class for export configuration

class partielspy.export_config.ExportConfig(format: Formats, ignore_matrix_tracks: bool = False, csv_include_header: bool = False, csv_columns_separator: CsvColumnSeparators = CsvColumnSeparators.COMMA, json_include_plugin_description: bool = False, reaper_type: ReaperTypes = ReaperTypes.REGION, image_width: int = 1280, image_height: int = 720, image_ppi: int = 72, image_group_overlay: bool = False)

Bases: object

Export configuration class

This is the class used to configure the export of the document.

Parameters:

  • format (ExportConfig.Formats) – the export format (default: CSV)

  • ignore_matrix_tracks (bool) – the matrix tracks are ignored (default: False)

  • csv_include_header (bool) – the header row is included before the data rows (default: False)

  • csv_columns_separator (ExportConfig.CsvColumnSeparators) – the separator character between columns (default: COMMA)

  • json_include_plugin_description (bool) – the plugin description is included (default: False)

  • reaper_type (ExportConfig.ReaperTypes) – the type of the reaper format (default: REGION)

  • image_width (int) – the image_width of the image in pixels (default: 1280)

  • image_height (int) – the image_height of the image in pixels (default: 720)

  • image_ppi (int) – the pixel density of the exported image in pixels per inch (default: 72)

  • image_group_overlay (bool) – the images of groups are exported instead of the images of tracks (default: False)

class CsvColumnSeparators(value)

Bases: StrEnum

Enum for the CSV column separators

COLON = 'colon'
COMMA = 'comma'
PIPE = 'pipe'
SLASH = 'slash'
SPACE = 'space'
TAB = 'tab'
class Formats(value)

Bases: StrEnum

Enum for the export formats

CSV = 'csv'
CUE = 'cue'
JPEG = 'jpeg'
JSON = 'json'
LAB = 'lab'
PNG = 'png'
REAPER = 'reaper'
class ReaperTypes(value)

Bases: StrEnum

Enum for the Reaper export types

MARKER = 'marker'
REGION = 'region'
property csv_columns_separator: CsvColumnSeparators
property csv_include_header: bool
property format: Formats
property ignore_matrix_tracks: bool
property image_group_overlay: bool
property image_height: int
property image_ppi: int
property image_width: int
property json_include_plugin_description: bool
property reaper_type: ReaperTypes
to_cli_args() → list[str]

partielspy.file_info module

A class for tracks file information

class partielspy.file_info.FileInfo(path: Path | str = '', csv_columns_separator: CsvColumnSeparators = None, csv_use_end_time: bool = None)

Bases: object

This class represents file information in a track.

It contains the path to the file used by the track for the export and parsing information for the CSV format. The supported file formats are JSON, CSV, LAB and CUE (with the extension .json, .csv, .lab and .cue). If the file path is defined, the track will use file instead of performing the analysis on the audio data. The csv_columns_separator and csv_use_end_time arguments should only be used for CSV files.

Parameters:

  • path (Path | str) – The path to the file associated with the track (default: “”)

  • csv_columns_separator (FileInfo.CsvColumnSeparators) – The separator used in the CSV file (default: COMMA)

  • csv_use_end_time – Whether to use the end time in the CSV file (default: False)

class CsvColumnSeparators(value)

Bases: StrEnum

Enum for the CSV column separators

COLON = ':'
COMMA = ','
PIPE = '|'
SLASH = '/'
SPACE = ' '
TAB = '\t'
property csv_columns_separator: CsvColumnSeparators
property csv_use_end_time: bool
property path: str

partielspy.group module

PartielsPy - Group Module

class partielspy.group.Group(name: str = 'New Group')

Bases: object

This class represents a group of tracks in PartielsPy.

It contains a name and a collection of Track.

Parameters:

name (str) – The name of the group (default: “New Group”)

add_track(track: Track)

Add a track to the group.

This method checks if the track is an instance of Track and if it already exists in the group. If the track is valid and not already present, it adds the track to the group’s tracks.

Parameters:

track(class – Track <partielspy.track>): The track to add to the group.

Raises:

  • TypeError – If the track is not an instance of Track.

  • ValueError – If the track already exists in the group.

property name: str
remove_track(track: Track)

Remove a track from the group.

This method searches for the track in the group’s tracks and removes it if found.

Parameters:

track(class – Track <partielspy.track>): The track to remove from the group.

Raises:

ValueError – If the track is not found in the group.

property tracks: list[Track]

Return a list of tracks in the group.

partielspy.partiels module

A main class for Partiels Wrapper

class partielspy.partiels.Partiels

Bases: object

A class to manage Partiels executable

The executable path is determined by searching the system’s PATH environment variable. If the executable is still not found, it checks common installation directories based on the operating system. You can use the PARTIELS_PATH environment variable to set the executable path, in this case only the PARTIELS_PATH will be used. If the executable is not found, it raises a RuntimeError. If the executable is found, its version is compared to the PartielsPy compatibility version and a warning is trigger if not matching. If the VAMP_PATH environment variable is set, it will be used to find the VAMP plugins. If not set, the default VAMP plugins directories will be used.

property executable_path: str

Return Partiels’s executable path

property executable_version: str

Return Partiels’s executable version

export(document: Document, output_path: str | Path, export_config: ExportConfig)

Export the document to the specified output path using the given export configuration.

Parameters:

  • document (Document) – the document to export

  • output_path (str) – the path to the output folder

  • export_config (ExportConfig) – the export configuration

get_plugin_list() → PluginList

Get the list of all available plugins from Partiels installed in the VAMP paths (defined by the VAMP_PATH environment variable).

Returns:

A PluginList object containing the list of plugins

Return type:

PluginList

partielspy.plugin_key module

A class to manage plugin keys

class partielspy.plugin_key.PluginKey(identifier: str = '', feature: str = '')

Bases: object

This class is used to represent a key for a plugin. It contains an identifier and a feature, which are used to uniquely identify the key. Each Track class has a plugin key associated with it. The plugin key is used to identify the plugin that is associated with the track. The get_plugin_list() method of the Partiels class returns a list of PluginKey based on all the available plugins.

Parameters:

  • identifier (str) – the identifier of the key (default: “”)

  • feature (str) – the feature of the key (default: “”)

property feature: str
property identifier: str

partielspy.plugin_list module

A class to display the list of available plugins in Partiels

class partielspy.plugin_list.PluginList(iterable=(), /)

Bases: list[PluginKey]

This class is not intended to be instantiated directly, but rather through the get_plugin_list method of the Partiels class. It contains a list of PluginKey, each representing a plugin key with an identifier and a feature. Its purpose is to provide a convenient way to access and display the list of plugins.

Example usage:

from partielspy import Partiels

partiels = Partiels()

plugin_list = partiels.get_plugin_list()

print(plugin_list)

partielspy.track module

PartielsPy - Track Module

class partielspy.track.Track(name: str = 'New Track')

Bases: object

This class represents a track in PartielsPy.

A track contains a PluginKey and a FileInfo, along with a name. If the file_info is set (with a non-empty path) the plugin_key will be ignored for the export.

Parameters:

  • name (str) – The name of the track (default: “New Track”)

  • plugin_key (PluginKey) – The plugin key associated with the track (default: a new empty PluginKey instance)

  • file_info (FileInfo) – The file associated with the track (default: a new empty FileInfo instance).

property file_info: FileInfo
property name: str
property plugin_key: PluginKey

partielspy.version module

A class for managing version compatibility in PartielsPy

class partielspy.version.Version

Bases: object

Compatibility version class for PartielsPy

This class is used to manage the compatibility versions of PartielsPy with the Partiels executable. It provides methods to retrieve the compatibility version and the minimum compatibility versions. The versions are defined as a string in semantic versioning format (major.minor.patch). The integer representation is calculated by shifting the major, minor, and patch numbers to create a single integer value.

static get_compatibility_version() → str

Return the compatibility version

static get_compatibility_version_int() → int

Return the integer representation of the compatibility version

static get_min_compatibility_version() → str

Return the minimum compatibility version

static get_min_compatibility_version_int() → int

Return the integer representation of the minimum compatibility version

Module contents

class partielspy.AudioFileChannel(file: Path | str, channel: int = 0)

Bases: object

This class represents an audio file channel and its associated channel number.

property channel: int
property file: str
class partielspy.AudioFileLayout(iterable=(), /)

Bases: list[AudioFileChannel]

This class represents the audio file layout of a document.

class partielspy.Document(document_file: str | Path = None, audio_file_layout: AudioFileLayout | str | Path | AudioFileChannel = None)

Bases: object

This class represents a document in PartielsPy.

It contains an AudioFileLayout that describes the audio file layout of the document, and a collection of Group, each of which can contain multiple Track. The document can be loaded from and saved to an ptldoc file.

Parameters:

  • document_file (str | Path, optional) – The path to the ptldoc file to load. If not provided, an empty document is created.

  • audio_file_layout (AudioFileLayout | str | Path | AudioFileChannel, optional) – The audio file layout for the document. This can be an instance of AudioFileLayout, a string or a Path to an audio file, or an instance of AudioFileChannel. If not provided, an empty audio file layout is created.

add_group(group: Group)

Add a group to the document.

This method checks if the group is an instance of Group and if it already exists in the document. If the group is valid and not already present, it adds the group to the document’s groups.

Parameters:

group (Group) – The group to add to the document.

Raises:

  • TypeError – If the group is not an instance of Group.

  • ValueError – If the group already exists in the document.

property audio_file_layout: AudioFileLayout
property groups: list[Group]
classmethod load(file: Any)

Load a document from an ptldoc file.

Parameters:

file (Any) – The file to load.

Returns:

An instance of the Document class populated with data from the ptldoc file.

Return type:

Document

Raises:

ValueError – If the document is invalid (does not have the correct root ‘document’ tag).

remove_group(group: Group)

Remove a group from the document.

This method searches for the group in the document’s groups and removes it if found.

Parameters:

group (Group) – The group to remove from the document.

Raises:

ValueError – If the group is not found in the document.

save(file: str | Path)

Save the document to an ptldoc file.

Parameters:

file (str | Path) – The path to the file where the document will be saved.

class partielspy.ExportConfig(format: Formats, ignore_matrix_tracks: bool = False, csv_include_header: bool = False, csv_columns_separator: CsvColumnSeparators = CsvColumnSeparators.COMMA, json_include_plugin_description: bool = False, reaper_type: ReaperTypes = ReaperTypes.REGION, image_width: int = 1280, image_height: int = 720, image_ppi: int = 72, image_group_overlay: bool = False)

Bases: object

Export configuration class

This is the class used to configure the export of the document.

Parameters:

  • format (ExportConfig.Formats) – the export format (default: CSV)

  • ignore_matrix_tracks (bool) – the matrix tracks are ignored (default: False)

  • csv_include_header (bool) – the header row is included before the data rows (default: False)

  • csv_columns_separator (ExportConfig.CsvColumnSeparators) – the separator character between columns (default: COMMA)

  • json_include_plugin_description (bool) – the plugin description is included (default: False)

  • reaper_type (ExportConfig.ReaperTypes) – the type of the reaper format (default: REGION)

  • image_width (int) – the image_width of the image in pixels (default: 1280)

  • image_height (int) – the image_height of the image in pixels (default: 720)

  • image_ppi (int) – the pixel density of the exported image in pixels per inch (default: 72)

  • image_group_overlay (bool) – the images of groups are exported instead of the images of tracks (default: False)

class CsvColumnSeparators(value)

Bases: StrEnum

Enum for the CSV column separators

COLON = 'colon'
COMMA = 'comma'
PIPE = 'pipe'
SLASH = 'slash'
SPACE = 'space'
TAB = 'tab'
class Formats(value)

Bases: StrEnum

Enum for the export formats

CSV = 'csv'
CUE = 'cue'
JPEG = 'jpeg'
JSON = 'json'
LAB = 'lab'
PNG = 'png'
REAPER = 'reaper'
class ReaperTypes(value)

Bases: StrEnum

Enum for the Reaper export types

MARKER = 'marker'
REGION = 'region'
property csv_columns_separator: CsvColumnSeparators
property csv_include_header: bool
property format: Formats
property ignore_matrix_tracks: bool
property image_group_overlay: bool
property image_height: int
property image_ppi: int
property image_width: int
property json_include_plugin_description: bool
property reaper_type: ReaperTypes
to_cli_args() → list[str]
class partielspy.FileInfo(path: Path | str = '', csv_columns_separator: CsvColumnSeparators = None, csv_use_end_time: bool = None)

Bases: object

This class represents file information in a track.

It contains the path to the file used by the track for the export and parsing information for the CSV format. The supported file formats are JSON, CSV, LAB and CUE (with the extension .json, .csv, .lab and .cue). If the file path is defined, the track will use file instead of performing the analysis on the audio data. The csv_columns_separator and csv_use_end_time arguments should only be used for CSV files.

Parameters:

  • path (Path | str) – The path to the file associated with the track (default: “”)

  • csv_columns_separator (FileInfo.CsvColumnSeparators) – The separator used in the CSV file (default: COMMA)

  • csv_use_end_time – Whether to use the end time in the CSV file (default: False)

class CsvColumnSeparators(value)

Bases: StrEnum

Enum for the CSV column separators

COLON = ':'
COMMA = ','
PIPE = '|'
SLASH = '/'
SPACE = ' '
TAB = '\t'
property csv_columns_separator: CsvColumnSeparators
property csv_use_end_time: bool
property path: str
class partielspy.Group(name: str = 'New Group')

Bases: object

This class represents a group of tracks in PartielsPy.

It contains a name and a collection of Track.

Parameters:

name (str) – The name of the group (default: “New Group”)

add_track(track: Track)

Add a track to the group.

This method checks if the track is an instance of Track and if it already exists in the group. If the track is valid and not already present, it adds the track to the group’s tracks.

Parameters:

track(class – Track <partielspy.track>): The track to add to the group.

Raises:

  • TypeError – If the track is not an instance of Track.

  • ValueError – If the track already exists in the group.

property name: str
remove_track(track: Track)

Remove a track from the group.

This method searches for the track in the group’s tracks and removes it if found.

Parameters:

track(class – Track <partielspy.track>): The track to remove from the group.

Raises:

ValueError – If the track is not found in the group.

property tracks: list[Track]

Return a list of tracks in the group.

class partielspy.Partiels

Bases: object

A class to manage Partiels executable

The executable path is determined by searching the system’s PATH environment variable. If the executable is still not found, it checks common installation directories based on the operating system. You can use the PARTIELS_PATH environment variable to set the executable path, in this case only the PARTIELS_PATH will be used. If the executable is not found, it raises a RuntimeError. If the executable is found, its version is compared to the PartielsPy compatibility version and a warning is trigger if not matching. If the VAMP_PATH environment variable is set, it will be used to find the VAMP plugins. If not set, the default VAMP plugins directories will be used.

property executable_path: str

Return Partiels’s executable path

property executable_version: str

Return Partiels’s executable version

export(document: Document, output_path: str | Path, export_config: ExportConfig)

Export the document to the specified output path using the given export configuration.

Parameters:

  • document (Document) – the document to export

  • output_path (str) – the path to the output folder

  • export_config (ExportConfig) – the export configuration

get_plugin_list() → PluginList

Get the list of all available plugins from Partiels installed in the VAMP paths (defined by the VAMP_PATH environment variable).

Returns:

A PluginList object containing the list of plugins

Return type:

PluginList

class partielspy.PluginKey(identifier: str = '', feature: str = '')

Bases: object

This class is used to represent a key for a plugin. It contains an identifier and a feature, which are used to uniquely identify the key. Each Track class has a plugin key associated with it. The plugin key is used to identify the plugin that is associated with the track. The get_plugin_list() method of the Partiels class returns a list of PluginKey based on all the available plugins.

Parameters:

  • identifier (str) – the identifier of the key (default: “”)

  • feature (str) – the feature of the key (default: “”)

property feature: str
property identifier: str
class partielspy.Track(name: str = 'New Track')

Bases: object

This class represents a track in PartielsPy.

A track contains a PluginKey and a FileInfo, along with a name. If the file_info is set (with a non-empty path) the plugin_key will be ignored for the export.

Parameters:

  • name (str) – The name of the track (default: “New Track”)

  • plugin_key (PluginKey) – The plugin key associated with the track (default: a new empty PluginKey instance)

  • file_info (FileInfo) – The file associated with the track (default: a new empty FileInfo instance).

property file_info: FileInfo
property name: str
property plugin_key: PluginKey