Components

The components package provides classes for working with macOS Audio Unit components and bundles.

AudioComponent

Audio Component representation and management.

This module provides classes for working with macOS Audio Unit components, including parsing component metadata and managing their tags and categories.

class logic_plugin_manager.components.audiocomponent.AudioComponent(data: dict, *, lazy: bool = False, tags_path: Path = PosixPath('/home/docs/Music/Audio Music Apps/Databases/Tags'), musicapps: MusicApps = None)[source]

Bases: object

Represents a single Audio Unit component.

An AudioComponent encapsulates metadata about an Audio Unit plugin, including its type, manufacturer, version, and associated tags/categories.

Parameters:

  • data (dict)

  • lazy (bool)

  • tags_path (Path)

  • musicapps (MusicApps)

full_name

Full name in format ‘Manufacturer: Plugin Name’.

manufacturer

Manufacturer/vendor name.

name

Plugin name (without manufacturer prefix).

manufacturer_code

Four-character manufacturer code.

description

Plugin description text.

factory_function

Name of the factory function.

type_code

Four-character Audio Unit type code.

type_name

AudioUnitType enum value.

subtype_code

Four-character subtype code.

version

Plugin version number.

tags_id

Unique identifier for tagset lookup.

tagset

Associated Tagset containing tags and metadata.

categories

List of Category objects this plugin belongs to.

tagset: Tagset
categories: list[Category]
__init__(data: dict, *, lazy: bool = False, tags_path: Path = PosixPath('/home/docs/Music/Audio Music Apps/Databases/Tags'), musicapps: MusicApps = None)[source]

Initialize an AudioComponent from component data dictionary.

Parameters:

  • data (dict) – Dictionary containing component metadata from Info.plist.

  • lazy (bool) – If True, defer loading tagset and categories until needed.

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

  • musicapps (MusicApps) – Shared MusicApps instance for category management.

Raises:

CannotParseComponentError – If required fields are missing or malformed. This can wrap KeyError, IndexError, AttributeError, UnicodeEncodeError, or ValueError from data extraction operations.

full_name: str
manufacturer: str
name: str
manufacturer_code: str
description: str
factory_function: str
type_code: str
type_name: AudioUnitType
subtype_code: str
version: int
tags_id: str
load() → AudioComponent[source]

Load tagset and categories for this component.

Loads the component’s tagset from disk and initializes Category objects for all tags. Invalid categories are logged as warnings and skipped.

Returns:

Self for method chaining.

Return type:

AudioComponent

Raises:
set_nickname(nickname: str | None) → AudioComponent[source]

Set or remove a custom nickname for this component.

Parameters:

nickname (str | None) – Custom nickname string, or None to remove the nickname.

Returns:

Self for method chaining.

Return type:

AudioComponent

Raises:
set_shortname(shortname: str | None) → AudioComponent[source]

Set or remove a custom short name for this component.

Parameters:

shortname (str | None) – Custom short name string, or None to remove the short name.

Returns:

Self for method chaining.

Return type:

AudioComponent

Raises:
set_categories(categories: list[Category]) → AudioComponent[source]

Replace all categories with the provided list.

Parameters:

categories (list[Category]) – List of Category objects to assign.

Returns:

Self for method chaining.

Return type:

AudioComponent

Raises:
add_to_category(category: Category) → AudioComponent[source]

Add this component to a category.

Parameters:

category (Category) – Category to add this component to.

Returns:

Self for method chaining.

Return type:

AudioComponent

Raises:
remove_from_category(category: Category) → AudioComponent[source]

Remove this component from a category.

Parameters:

category (Category) – Category to remove this component from.

Returns:

Self for method chaining.

Return type:

AudioComponent

Raises:

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

  • CannotParseTagsetError – If tagset file cannot be parsed (from Tagset.remove_tag).

  • KeyError – If tag doesn’t exist (from Tagset.remove_tag).

  • TagsetWriteError – If writing tagset fails (from Tagset.remove_tag).

move_to_category(category: Category) → AudioComponent[source]

Move this component to a single category, removing all others.

Parameters:

category (Category) – Category to move this component to exclusively.

Returns:

Self for method chaining.

Return type:

AudioComponent

Raises:
move_to_parents() → AudioComponent[source]

Move this component to the parent categories of all current categories.

For each category this component belongs to, adds it to the parent category and removes it from the child category.

Returns:

Self for method chaining.

Return type:

AudioComponent

Raises:

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

  • CannotParseTagsetError – If tagset file cannot be parsed (from Tagset operations).

  • TagsetWriteError – If writing tagset fails (from Tagset operations).

  • KeyError – If a category tag doesn’t exist during removal (from Tagset.remove_tag).

class logic_plugin_manager.components.audiocomponent.AudioUnitType(*values)[source]

Bases: Enum

Enumeration of Audio Unit types supported by macOS.

Each enum value contains a tuple of (code, display_name, alt_name).

AUFX = ('aufx', 'Audio FX', 'Effect')
AUMU = ('aumu', 'Instrument', 'Music Device')
AUMF = ('aumf', 'MIDI-controlled Effects', 'Music Effect')
AUMI = ('aumi', 'MIDI FX', 'MIDI Generator')
AUGN = ('augn', 'Generator', 'Generator')
property code: str

Get the four-character code for this Audio Unit type.

Returns:

Four-character type code (e.g., ‘aufx’, ‘aumu’).

Return type:

str

property display_name: str

Get the human-readable display name for this Audio Unit type.

Returns:

Display name (e.g., ‘Audio FX’, ‘Instrument’).

Return type:

str

property alt_name: str

Get the alternative name for this Audio Unit type.

Returns:

Alternative name (e.g., ‘Effect’, ‘Music Device’).

Return type:

str

classmethod from_code(code: str) → AudioUnitType | None[source]

Find an AudioUnitType by its four-character code.

Parameters:

code (str) – Four-character type code (case-insensitive).

Returns:

Matching AudioUnitType or None if not found.

Return type:

AudioUnitType | None

classmethod search(query: str) → list[AudioUnitType][source]

Search for AudioUnitTypes matching a query string.

Searches across code, display_name, and alt_name fields.

Parameters:

query (str) – Search query string (case-insensitive).

Returns:

List of matching AudioUnitType values.

Return type:

list[AudioUnitType]

Component

Component bundle representation and parsing.

This module provides the Component class for loading and parsing macOS Audio Component bundles (.component directories) and their Info.plist files.

class logic_plugin_manager.components.component.Component(path: Path, *, lazy: bool = False, tags_path: Path = PosixPath('/home/docs/Music/Audio Music Apps/Databases/Tags'), musicapps: MusicApps = None)[source]

Bases: object

Represents a macOS Audio Component bundle.

A Component bundle (.component) can contain one or more AudioComponents. This class parses the bundle’s Info.plist and instantiates AudioComponent objects for each Audio Unit defined within.

Parameters:

  • path (Path)

  • lazy (bool)

  • tags_path (Path)

  • musicapps (MusicApps)

name

Component bundle name (without .component extension).

bundle_id

CFBundleIdentifier from Info.plist.

short_version

CFBundleShortVersionString from Info.plist.

version

CFBundleVersion from Info.plist.

audio_components

List of AudioComponent instances from this bundle.

name: str
bundle_id: str
short_version: str
version: str
audio_components: list[AudioComponent]
__init__(path: Path, *, lazy: bool = False, tags_path: Path = PosixPath('/home/docs/Music/Audio Music Apps/Databases/Tags'), musicapps: MusicApps = None)[source]

Initialize a Component from a bundle path.

Parameters:

  • path (Path) – Path to .component bundle (with or without .component extension).

  • lazy (bool) – If True, defer loading Info.plist and AudioComponents.

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

  • musicapps (MusicApps) – Shared MusicApps instance for category management.

Note

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

load() → Component[source]

Load and parse the component bundle and its AudioComponents.

Parses Info.plist, extracts bundle metadata, and creates AudioComponent instances for each Audio Unit defined in the AudioComponents array.

Returns:

Self for method chaining.

Return type:

Component

Raises: