Tags & Categories

The tags package manages Logic Pro’s category system and tag database.

Category Management

Category management for plugin organization.

This module provides the Category class for working with Logic Pro’s hierarchical category system used to organize and filter audio plugins.

class logic_plugin_manager.tags.category.Category(name: str, *, musicapps: MusicApps = None, lazy: bool = False)

Bases: object

Represents a Logic Pro plugin category.

Categories form a hierarchical structure using colon-separated names (e.g., ‘Effects:EQ’). Each category tracks plugin count and sorting order.

Parameters:

• name (str)

• musicapps (MusicApps)

• lazy (bool)

name

Category name (colon-separated for hierarchy).

musicapps

MusicApps instance for database access.

is_root

True if this is the root category (empty name).

plugin_amount

Number of plugins in this category.

lazy

Whether lazy loading is enabled.

__init__(name: str, *, musicapps: MusicApps = None, lazy: bool = False)

Initialize a Category.

Parameters:

• name (str) – Category name.

• musicapps (MusicApps) – MusicApps instance (created if None).

• lazy (bool) – If True, defer validation.

Note

If lazy=False, raises can occur from load() during initialization.

name: str

musicapps: MusicApps

is_root: bool

plugin_amount: int

lazy: bool

load()

Validate and load category data from MusicApps database.

Raises:

• CategoryValidationError – If category doesn’t exist in database.

• MusicAppsLoadError – If database files cannot be loaded.

classmethod introduce(name: str, *, musicapps: MusicApps = None, lazy: bool = False)

Create a new category in the database.

Parameters:

• name (str) – Name for the new category.

• musicapps (MusicApps) – MusicApps instance (created if None).

• lazy (bool) – Whether to use lazy loading.

Returns:

Newly created category instance.

Return type:

Category

Raises:

• CategoryExistsError – If category already exists.

• MusicAppsLoadError – If database files cannot be loaded.

• MusicAppsWriteError – If database files cannot be written.

property parent: Category

Get the parent category in the hierarchy.

Returns:

Parent category, or self if this is root.

Return type:

Category

child(name: str) → Category

Create a child category reference.

Parameters:

name (str) – Child category name (without parent prefix).

Returns:

Child category instance.

Return type:

Category

delete()

update_plugin_amount(amount: int)

Parameters:

amount (int)

move_up(steps: int = 1)

Parameters:

steps (int)

move_down(steps: int = 1)

Parameters:

steps (int)

move_to_top()

move_to_bottom()

move_before(other: Category)

Parameters:

other (Category)

move_after(other: Category)

Parameters:

other (Category)

move_to(index: int)

Parameters:

index (int)

swap(other: Category)

Parameters:

other (Category)

property index

property neighbors

property is_first

property is_last

MusicApps Database

MusicApps database management for Logic Pro tags and categories.

This module provides classes for reading and writing Logic Pro’s MusicApps database files (MusicApps.tagpool and MusicApps.properties) which store category definitions, plugin counts, and sorting information.

class logic_plugin_manager.tags.musicapps.MusicApps(tags_path: Path = PosixPath('/home/docs/Music/Audio Music Apps/Databases/Tags'), *, lazy: bool = False)

Bases: object

Main interface to Logic Pro’s MusicApps database.

Provides unified access to both tagpool and properties files, managing category definitions, plugin counts, and sorting preferences.

Parameters:

• tags_path (Path)

• lazy (bool)

tagpool

Tagpool instance managing category/plugin counts.

properties

Properties instance managing sorting and preferences.

tagpool: Tagpool

properties: Properties

__init__(tags_path: Path = PosixPath('/home/docs/Music/Audio Music Apps/Databases/Tags'), *, lazy: bool = False)

Initialize MusicApps from database path.

Parameters:

• tags_path (Path) – Path to tags database directory.

• lazy (bool) – If True, defer loading files.

load() → MusicApps

Load both tagpool and properties files.

Returns:

Self for method chaining.

Return type:

MusicApps

Raises:

MusicAppsLoadError – If files cannot be loaded (from Tagpool/Properties).

introduce_category(name: str)

Add a new category to both tagpool and properties.

Parameters:

name (str) – Category name to introduce.

Raises:

• MusicAppsLoadError – If files cannot be loaded.

• MusicAppsWriteError – If files cannot be written.

remove_category(name: str)

Remove a category from both tagpool and properties.

Parameters:

name (str) – Category name to remove.

Raises:

• MusicAppsLoadError – If files cannot be loaded.

• MusicAppsWriteError – If files cannot be written.

class logic_plugin_manager.tags.musicapps.Properties(tags_path: Path, *, lazy: bool = False)

Bases: object

Represents MusicApps.properties - category sorting and preferences.

The properties file stores the category sorting order and whether user sorting is enabled (vs. alphabetical sorting).

Parameters:

• tags_path (Path)

• lazy (bool)

sorting

Ordered list of category names.

user_sorted

True if user sorting is enabled, False for alphabetical.

sorting: list[str]

user_sorted: bool

__init__(tags_path: Path, *, lazy: bool = False)

Initialize Properties from database path.

Parameters:

• tags_path (Path) – Path to tags database directory.

• lazy (bool) – If True, defer loading the file.

load() → Properties

Load properties data from disk.

Returns:

Self for method chaining.

Return type:

Properties

Raises:

MusicAppsLoadError – If file cannot be loaded (from _parse_plist).

introduce_category(name: str)

Parameters:

name (str)

enable_user_sorting()

enable_alphabetical_sorting()

remove_category(name: str)

Parameters:

name (str)

move_up(category: str, steps: int = 1)

Move a category up in the sorting order.

Parameters:

• category (str) – Category name to move.

• steps (int) – Number of positions to move up.

Raises:

• ValueError – If category not found in sorting.

• MusicAppsLoadError – If file cannot be loaded (from load).

• MusicAppsWriteError – If file cannot be written (from _save_plist).

move_down(category: str, steps: int = 1)

Parameters:

• category (str)

• steps (int)

move_to_top(category: str)

Parameters:

category (str)

move_to_bottom(category: str)

Parameters:

category (str)

move_before(category: str, target: str)

Parameters:

• category (str)

• target (str)

move_after(category: str, target: str)

Parameters:

• category (str)

• target (str)

move_to_index(category: str, index: int)

Parameters:

• category (str)

• index (int)

swap(category1: str, category2: str)

Parameters:

• category1 (str)

• category2 (str)

set_order(categories: list[str])

Parameters:

categories (list[str])

reorder(key_func=None, reverse: bool = False)

Parameters:

reverse (bool)

get_index(category: str) → int

Return type:

int

Parameters:

category (str)

get_at_index(index: int) → str

Return type:

str

Parameters:

index (int)

get_neighbors(category: str) → tuple[str | None, str | None]

Return type:

tuple[str | None, str | None]

Parameters:

category (str)

is_first(category: str) → bool

Return type:

bool

Parameters:

category (str)

is_last(category: str) → bool

Return type:

bool

Parameters:

category (str)

class logic_plugin_manager.tags.musicapps.Tagpool(tags_path: Path, *, lazy: bool = False)

Bases: object

Represents MusicApps.tagpool - category to plugin count mapping.

The tagpool file stores a dictionary mapping category names to the number of plugins assigned to each category.

Parameters:

• tags_path (Path)

• lazy (bool)

categories

Dictionary mapping category names to plugin counts.

categories: dict[str, int]

__init__(tags_path: Path, *, lazy: bool = False)

Initialize Tagpool from database path.

Parameters:

• tags_path (Path) – Path to tags database directory.

• lazy (bool) – If True, defer loading the file.

load() → Tagpool

Load tagpool data from disk.

Returns:

Self for method chaining.

Return type:

Tagpool

Raises:

MusicAppsLoadError – If file cannot be loaded (from _parse_plist).

write_category(name: str, plugin_count: int = 0)

Write or update a category with its plugin count.

Parameters:

• name (str) – Category name.

• plugin_count (int) – Number of plugins in this category.

Raises:

• MusicAppsLoadError – If file cannot be loaded (from load).

• MusicAppsWriteError – If file cannot be written (from _save_plist).

introduce_category(name: str)

Add a new category if it doesn’t exist.

Parameters:

name (str) – Category name to introduce.

Raises:

• MusicAppsLoadError – If file cannot be loaded (from load).

• MusicAppsWriteError – If file cannot be written (from write_category).

remove_category(name: str)

Remove a category from the tagpool.

Parameters:

name (str) – Category name to remove.

Raises:

• MusicAppsLoadError – If file cannot be loaded (from load).

• MusicAppsWriteError – If file cannot be written (from _save_plist).

Tagset Files

Tagset file management for Audio Components.

This module provides the Tagset class for reading and writing .tagset files that store plugin metadata like nicknames, short names, and category tags.

class logic_plugin_manager.tags.tagset.Tagset(path: Path, *, lazy: bool = False)

Bases: object

Represents a .tagset file containing plugin metadata and tags.

Tagset files store custom metadata and category tags for Audio Components. Each tagset is identified by a unique tags_id derived from the component’s type, subtype, and manufacturer codes.

Parameters:

• path (Path)

• lazy (bool)

tags_id

Unique identifier (hex-encoded type-subtype-manufacturer).

nickname

Custom nickname for the plugin.

shortname

Custom short name for the plugin.

tags

Dictionary mapping category names to tag values (e.g., ‘user’).

tags_id: str

nickname: str

shortname: str

tags: dict[str, str]

__init__(path: Path, *, lazy: bool = False)

Initialize a Tagset from a file path.

Parameters:

• path (Path) – Path to .tagset file (extension added automatically if missing).

• lazy (bool) – If True, defer loading the file until needed.

Note

If lazy=False, raises can occur from load() method during initialization.

load() → Tagset

Load and parse the tagset file from disk.

Returns:

Self for method chaining.

Return type:

Tagset

Raises:

• NonexistentTagsetError – If .tagset file doesn’t exist (from _parse_plist).

• CannotParseTagsetError – If plist cannot be parsed (from _parse_plist).

set_nickname(nickname: str | None)

Set or remove the nickname field in the tagset.

Parameters:

nickname (str | None) – New nickname value, or None to remove the nickname.

Raises:

• NonexistentTagsetError – If .tagset file doesn’t exist (from load).

• CannotParseTagsetError – If plist cannot be parsed (from load).

• TagsetWriteError – If writing fails (from _write_plist).

set_shortname(shortname: str | None)

Set or remove the shortname field in the tagset.

Parameters:

shortname (str | None) – New short name value, or None to remove the short name.

Raises:

• NonexistentTagsetError – If .tagset file doesn’t exist (from load).

• CannotParseTagsetError – If plist cannot be parsed (from load).

• TagsetWriteError – If writing fails (from _write_plist).

set_tags(tags: dict[str, str])

Replace all tags with the provided dictionary.

Parameters:

tags (dict[str, str]) – Dictionary mapping category names to tag values.

Raises:

• NonexistentTagsetError – If .tagset file doesn’t exist (from load).

• CannotParseTagsetError – If plist cannot be parsed (from load).

• TagsetWriteError – If writing fails (from _write_plist).

add_tag(tag: str, value: str)

Add or update a single tag.

Parameters:

• tag (str) – Category name.

• value (str) – Tag value (typically ‘user’).

Raises:

• NonexistentTagsetError – If .tagset file doesn’t exist (from load).

• CannotParseTagsetError – If plist cannot be parsed (from load).

• TagsetWriteError – If writing fails (from _write_plist).

remove_tag(tag: str)

Remove a tag from the tagset.

Parameters:

tag (str) – Category name to remove.

Raises:

• NonexistentTagsetError – If .tagset file doesn’t exist (from load).

• CannotParseTagsetError – If plist cannot be parsed (from load).

• KeyError – If tag doesn’t exist in the tagset.

• TagsetWriteError – If writing fails (from _write_plist).

move_to_tag(tag: str, value: str)

Clear all tags and set a single tag.

Parameters:

• tag (str) – Category name.

• value (str) – Tag value (typically ‘user’).

Raises:

• NonexistentTagsetError – If .tagset file doesn’t exist (from load).

• CannotParseTagsetError – If plist cannot be parsed (from load).

• TagsetWriteError – If writing fails (from _write_plist).