713 lines
19 KiB
ReStructuredText
713 lines
19 KiB
ReStructuredText
Usage Examples
|
|
==============
|
|
|
|
This page provides practical examples for common use cases.
|
|
|
|
Plugin Discovery & Inspection
|
|
------------------------------
|
|
|
|
List All Plugins
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
print(f"Total plugins: {len(logic.plugins.all())}")
|
|
|
|
for plugin in logic.plugins.all():
|
|
print(f"{plugin.full_name}")
|
|
print(f" Type: {plugin.type_name.display_name}")
|
|
print(f" Version: {plugin.version}")
|
|
print(f" Categories: {', '.join(c.name for c in plugin.categories)}")
|
|
print()
|
|
|
|
Filter by Type
|
|
~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Get all instruments
|
|
instruments = logic.plugins.get_by_type_code("aumu")
|
|
print(f"Found {len(instruments)} instruments")
|
|
|
|
# Get all effects
|
|
effects = logic.plugins.get_by_type_code("aufx")
|
|
print(f"Found {len(effects)} effects")
|
|
|
|
Find Plugins by Manufacturer
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# List all manufacturers
|
|
manufacturers = set()
|
|
for plugin in logic.plugins.all():
|
|
manufacturers.add(plugin.manufacturer)
|
|
|
|
for mfr in sorted(manufacturers):
|
|
plugins = logic.plugins.get_by_manufacturer(mfr)
|
|
print(f"{mfr}: {len(plugins)} plugins")
|
|
|
|
# Get specific manufacturer's plugins
|
|
fabfilter = logic.plugins.get_by_manufacturer("fabfilter")
|
|
for plugin in fabfilter:
|
|
print(f" - {plugin.name}")
|
|
|
|
Inspect Plugin Details
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
plugin = logic.plugins.get_by_full_name("fabfilter: pro-q 3")
|
|
|
|
if plugin:
|
|
print(f"Full Name: {plugin.full_name}")
|
|
print(f"Manufacturer: {plugin.manufacturer}")
|
|
print(f"Name: {plugin.name}")
|
|
print(f"Description: {plugin.description}")
|
|
print(f"Type: {plugin.type_name.display_name} ({plugin.type_code})")
|
|
print(f"Subtype: {plugin.subtype_code}")
|
|
print(f"Manufacturer Code: {plugin.manufacturer_code}")
|
|
print(f"Version: {plugin.version}")
|
|
print(f"Factory Function: {plugin.factory_function}")
|
|
print(f"Tags ID: {plugin.tags_id}")
|
|
print(f"Tagset Path: {plugin.tagset.path}")
|
|
|
|
if plugin.tagset.nickname:
|
|
print(f"Nickname: {plugin.tagset.nickname}")
|
|
if plugin.tagset.shortname:
|
|
print(f"Short Name: {plugin.tagset.shortname}")
|
|
|
|
print(f"Categories: {', '.join(c.name for c in plugin.categories)}")
|
|
|
|
Search & Discovery
|
|
------------------
|
|
|
|
Simple Text Search
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Simple substring search
|
|
reverb_plugins = logic.plugins.search_simple("reverb")
|
|
|
|
print(f"Found {len(reverb_plugins)} plugins with 'reverb' in name")
|
|
for plugin in reverb_plugins:
|
|
print(f" - {plugin.full_name}")
|
|
|
|
Advanced Fuzzy Search
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Fuzzy search with scoring
|
|
results = logic.plugins.search(
|
|
query="compressor",
|
|
use_fuzzy=True,
|
|
fuzzy_threshold=80,
|
|
max_results=10
|
|
)
|
|
|
|
for i, result in enumerate(results, 1):
|
|
print(f"{i}. {result.plugin.full_name}")
|
|
print(f" Score: {result.score:.1f}")
|
|
print(f" Matched field: {result.match_field}")
|
|
print()
|
|
|
|
Search by Multiple Criteria
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
def find_plugins(search_term, plugin_type=None, category=None):
|
|
"""Search plugins with optional filters."""
|
|
results = logic.plugins.search(search_term, use_fuzzy=True)
|
|
|
|
plugins = [r.plugin for r in results]
|
|
|
|
# Filter by type if specified
|
|
if plugin_type:
|
|
plugins = [p for p in plugins if p.type_code == plugin_type]
|
|
|
|
# Filter by category if specified
|
|
if category:
|
|
plugins = [
|
|
p for p in plugins
|
|
if any(c.name == category for c in p.categories)
|
|
]
|
|
|
|
return plugins
|
|
|
|
# Find reverb effects (not instruments)
|
|
reverbs = find_plugins("reverb", plugin_type="aufx")
|
|
|
|
# Find synthesizers in Instruments category
|
|
synths = find_plugins("synth", plugin_type="aumu", category="Instruments")
|
|
|
|
Category Management
|
|
-------------------
|
|
|
|
List All Categories
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
print("Categories:")
|
|
for name, category in sorted(logic.categories.items()):
|
|
print(f" {name} ({category.plugin_amount} plugins)")
|
|
|
|
Create Category Hierarchy
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Create nested categories
|
|
categories_to_create = [
|
|
"My Plugins",
|
|
"My Plugins:Favorites",
|
|
"My Plugins:Favorites:Mixing",
|
|
"My Plugins:Favorites:Mastering",
|
|
]
|
|
|
|
for cat_name in categories_to_create:
|
|
if cat_name not in logic.categories:
|
|
category = logic.introduce_category(cat_name)
|
|
print(f"Created: {cat_name}")
|
|
else:
|
|
print(f"Already exists: {cat_name}")
|
|
|
|
Add Plugins to Category
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Create or get category
|
|
favorites = logic.categories.get("Favorites")
|
|
if not favorites:
|
|
favorites = logic.introduce_category("Favorites")
|
|
|
|
# Add single plugin
|
|
plugin = logic.plugins.get_by_full_name("fabfilter: pro-q 3")
|
|
if plugin:
|
|
plugin.add_to_category(favorites)
|
|
print(f"Added {plugin.full_name} to {favorites.name}")
|
|
|
|
# Update category count
|
|
logic.sync_category_plugin_amount(favorites)
|
|
|
|
Bulk Category Assignment
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Find all FabFilter plugins
|
|
fabfilter_plugins = logic.plugins.get_by_manufacturer("fabfilter")
|
|
|
|
# Create category
|
|
fabfilter_cat = logic.categories.get("FabFilter")
|
|
if not fabfilter_cat:
|
|
fabfilter_cat = logic.introduce_category("FabFilter")
|
|
|
|
# Bulk add
|
|
logic.add_plugins_to_category(fabfilter_cat, fabfilter_plugins)
|
|
print(f"Added {len(fabfilter_plugins)} FabFilter plugins")
|
|
|
|
Move Plugins Between Categories
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Get plugins from one category
|
|
dynamics_plugins = logic.plugins.get_by_category("Effects:Dynamics")
|
|
|
|
# Filter for compressors
|
|
compressors = {
|
|
p for p in dynamics_plugins
|
|
if "compress" in p.name.lower()
|
|
}
|
|
|
|
# Move to specific category
|
|
comp_category = logic.categories.get("Effects:Dynamics:Compressor")
|
|
if comp_category:
|
|
logic.move_plugins_to_category(comp_category, compressors)
|
|
logic.sync_category_plugin_amount(comp_category)
|
|
|
|
Organize Uncategorized Plugins
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Get plugins without categories
|
|
uncategorized = logic.plugins.get_by_category(None)
|
|
|
|
print(f"Found {len(uncategorized)} uncategorized plugins")
|
|
|
|
# Auto-categorize by manufacturer
|
|
for plugin in uncategorized:
|
|
manufacturer = plugin.manufacturer.strip()
|
|
category_name = f"By Manufacturer:{manufacturer}"
|
|
|
|
# Create category if needed
|
|
if category_name not in logic.categories:
|
|
logic.introduce_category(category_name)
|
|
|
|
category = logic.categories[category_name]
|
|
plugin.add_to_category(category)
|
|
|
|
# Update all category counts
|
|
logic.sync_all_categories_plugin_amount()
|
|
|
|
Category Sorting
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Get category
|
|
category = logic.categories["Effects:EQ"]
|
|
|
|
# Check current position
|
|
print(f"Current index: {category.index}")
|
|
prev, next_cat = category.neighbors
|
|
if prev:
|
|
print(f"Previous: {prev.name}")
|
|
if next_cat:
|
|
print(f"Next: {next_cat.name}")
|
|
|
|
# Move category
|
|
category.move_to_top()
|
|
category.move_up(steps=5)
|
|
category.move_down()
|
|
|
|
# Move relative to another category
|
|
target = logic.categories["Effects:Delay"]
|
|
category.move_before(target)
|
|
|
|
Custom Plugin Metadata
|
|
----------------------
|
|
|
|
Set Nicknames
|
|
~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Set custom nicknames for easier identification
|
|
plugins_to_rename = {
|
|
"fabfilter: pro-q 3": "PQ3 - Main EQ",
|
|
"fabfilter: pro-c 2": "PC2 - Main Compressor",
|
|
"valhalla shimmer": "Shimmer - Ambient Verb",
|
|
}
|
|
|
|
for full_name, nickname in plugins_to_rename.items():
|
|
plugin = logic.plugins.get_by_full_name(full_name)
|
|
if plugin:
|
|
plugin.set_nickname(nickname)
|
|
print(f"Renamed: {full_name} -> {nickname}")
|
|
|
|
Set Short Names
|
|
~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Set short names for UI display
|
|
shortnames = {
|
|
"fabfilter: pro-q 3": "PQ3",
|
|
"fabfilter: pro-c 2": "PC2",
|
|
"serum": "SRM",
|
|
}
|
|
|
|
for full_name, shortname in shortnames.items():
|
|
plugin = logic.plugins.get_by_full_name(full_name)
|
|
if plugin:
|
|
plugin.set_shortname(shortname)
|
|
|
|
Batch Metadata Updates
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Add manufacturer prefix to all plugin nicknames
|
|
for plugin in logic.plugins.all():
|
|
if not plugin.tagset.nickname:
|
|
manufacturer = plugin.manufacturer.upper()
|
|
nickname = f"[{manufacturer}] {plugin.name}"
|
|
plugin.set_nickname(nickname)
|
|
print(f"Set nickname for {plugin.full_name}")
|
|
|
|
Advanced Operations
|
|
-------------------
|
|
|
|
Export Plugin Inventory
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
import csv
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Export to CSV
|
|
with open("plugin_inventory.csv", "w", newline="") as f:
|
|
writer = csv.writer(f)
|
|
writer.writerow([
|
|
"Full Name", "Manufacturer", "Type", "Version",
|
|
"Categories", "Subtype Code", "Tags ID"
|
|
])
|
|
|
|
for plugin in sorted(logic.plugins.all(), key=lambda p: p.full_name):
|
|
writer.writerow([
|
|
plugin.full_name,
|
|
plugin.manufacturer,
|
|
plugin.type_name.display_name,
|
|
plugin.version,
|
|
"; ".join(c.name for c in plugin.categories),
|
|
plugin.subtype_code,
|
|
plugin.tags_id,
|
|
])
|
|
|
|
print("Exported plugin inventory to plugin_inventory.csv")
|
|
|
|
Clone Category Structure
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
def clone_category(source: str, target: str, logic: Logic):
|
|
"""Clone plugins from source category to target category."""
|
|
# Get plugins in source
|
|
source_plugins = logic.plugins.get_by_category(source)
|
|
|
|
# Create target if needed
|
|
if target not in logic.categories:
|
|
logic.introduce_category(target)
|
|
|
|
target_category = logic.categories[target]
|
|
|
|
# Add plugins to target
|
|
logic.add_plugins_to_category(target_category, source_plugins)
|
|
|
|
print(f"Cloned {len(source_plugins)} plugins from {source} to {target}")
|
|
|
|
logic = Logic()
|
|
clone_category("Effects:EQ", "My Plugins:EQ", logic)
|
|
|
|
Find Duplicate Plugins
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from collections import defaultdict
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Group by name (ignoring manufacturer)
|
|
by_name = defaultdict(list)
|
|
for plugin in logic.plugins.all():
|
|
by_name[plugin.name.lower()].append(plugin)
|
|
|
|
# Find duplicates
|
|
duplicates = {
|
|
name: plugins
|
|
for name, plugins in by_name.items()
|
|
if len(plugins) > 1
|
|
}
|
|
|
|
print(f"Found {len(duplicates)} plugin names with multiple versions:\n")
|
|
for name, plugins in sorted(duplicates.items()):
|
|
print(f"{name}:")
|
|
for plugin in plugins:
|
|
print(f" - {plugin.full_name} (v{plugin.version})")
|
|
print()
|
|
|
|
Backup and Restore Categories
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
import json
|
|
from pathlib import Path
|
|
from logic_plugin_manager import Logic
|
|
|
|
def backup_categories(output_file: Path):
|
|
"""Backup all plugin category assignments."""
|
|
logic = Logic()
|
|
|
|
backup_data = {}
|
|
for plugin in logic.plugins.all():
|
|
backup_data[plugin.tags_id] = {
|
|
"full_name": plugin.full_name,
|
|
"categories": [c.name for c in plugin.categories],
|
|
}
|
|
|
|
with open(output_file, "w") as f:
|
|
json.dump(backup_data, f, indent=2)
|
|
|
|
print(f"Backed up {len(backup_data)} plugin assignments")
|
|
|
|
def restore_categories(backup_file: Path):
|
|
"""Restore plugin category assignments from backup."""
|
|
logic = Logic()
|
|
|
|
with open(backup_file) as f:
|
|
backup_data = json.load(f)
|
|
|
|
restored = 0
|
|
for tags_id, data in backup_data.items():
|
|
plugin = logic.plugins.get_by_tags_id(tags_id)
|
|
if plugin:
|
|
# Restore categories
|
|
categories = [
|
|
logic.categories[name]
|
|
for name in data["categories"]
|
|
if name in logic.categories
|
|
]
|
|
if categories:
|
|
plugin.set_categories(categories)
|
|
restored += 1
|
|
|
|
print(f"Restored {restored} plugin assignments")
|
|
|
|
# Usage
|
|
backup_categories(Path("categories_backup.json"))
|
|
# restore_categories(Path("categories_backup.json"))
|
|
|
|
Generate Category Report
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
print("=" * 60)
|
|
print("CATEGORY REPORT")
|
|
print("=" * 60)
|
|
print()
|
|
|
|
# Sort categories by hierarchy
|
|
sorted_categories = sorted(logic.categories.items())
|
|
|
|
for name, category in sorted_categories:
|
|
# Calculate depth based on colons
|
|
depth = name.count(":")
|
|
indent = " " * depth
|
|
|
|
# Get plugins in this exact category
|
|
plugins = logic.plugins.get_by_category(name)
|
|
|
|
print(f"{indent}├─ {name.split(':')[-1]}")
|
|
print(f"{indent}│ Count: {category.plugin_amount}")
|
|
print(f"{indent}│ Index: {category.index}")
|
|
|
|
if plugins:
|
|
print(f"{indent}│ Plugins:")
|
|
for plugin in sorted(plugins, key=lambda p: p.full_name)[:5]:
|
|
print(f"{indent}│ - {plugin.full_name}")
|
|
if len(plugins) > 5:
|
|
print(f"{indent}│ ... and {len(plugins) - 5} more")
|
|
print()
|
|
|
|
Working with Component Bundles
|
|
-------------------------------
|
|
|
|
Inspect Component Bundles
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
print(f"Total component bundles: {len(logic.components)}\n")
|
|
|
|
for component in logic.components:
|
|
print(f"Bundle: {component.name}")
|
|
print(f" ID: {component.bundle_id}")
|
|
print(f" Version: {component.version} ({component.short_version})")
|
|
print(f" Audio Components: {len(component.audio_components)}")
|
|
|
|
for audio_comp in component.audio_components:
|
|
print(f" - {audio_comp.full_name}")
|
|
print()
|
|
|
|
Find Multi-Plugin Bundles
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic
|
|
|
|
logic = Logic()
|
|
|
|
# Find bundles with multiple plugins
|
|
multi_plugin_bundles = [
|
|
comp for comp in logic.components
|
|
if len(comp.audio_components) > 1
|
|
]
|
|
|
|
print(f"Found {len(multi_plugin_bundles)} bundles with multiple plugins:\n")
|
|
|
|
for component in multi_plugin_bundles:
|
|
print(f"{component.name} - {len(component.audio_components)} plugins:")
|
|
for plugin in component.audio_components:
|
|
print(f" - {plugin.name} ({plugin.type_name.display_name})")
|
|
print()
|
|
|
|
Error Handling Examples
|
|
-----------------------
|
|
|
|
Robust Plugin Search
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import Logic, PluginLoadError
|
|
|
|
def safe_find_plugin(plugin_name: str) -> None:
|
|
"""Safely search for a plugin with error handling."""
|
|
try:
|
|
logic = Logic()
|
|
except PluginLoadError as e:
|
|
print(f"Error loading plugins: {e}")
|
|
return
|
|
|
|
plugin = logic.plugins.get_by_full_name(plugin_name)
|
|
|
|
if plugin:
|
|
print(f"Found: {plugin.full_name}")
|
|
print(f"Type: {plugin.type_name.display_name}")
|
|
|
|
# Try to load tagset
|
|
try:
|
|
print(f"Categories: {', '.join(c.name for c in plugin.categories)}")
|
|
except Exception as e:
|
|
print(f"Could not load categories: {e}")
|
|
else:
|
|
print(f"Plugin '{plugin_name}' not found")
|
|
|
|
# Try fuzzy search
|
|
results = logic.plugins.search(plugin_name)
|
|
if results:
|
|
print(f"\nDid you mean:")
|
|
for result in results[:3]:
|
|
print(f" - {result.plugin.full_name}")
|
|
|
|
safe_find_plugin("fabfilter: pro-q 3")
|
|
|
|
Graceful Category Operations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. code-block:: python
|
|
|
|
from logic_plugin_manager import (
|
|
Logic,
|
|
CategoryValidationError,
|
|
MusicAppsLoadError
|
|
)
|
|
|
|
def safe_add_to_category(plugin_name: str, category_name: str):
|
|
"""Add plugin to category with error handling."""
|
|
try:
|
|
logic = Logic()
|
|
except MusicAppsLoadError as e:
|
|
print(f"Database error: {e}")
|
|
return
|
|
|
|
# Find plugin
|
|
plugin = logic.plugins.get_by_full_name(plugin_name)
|
|
if not plugin:
|
|
print(f"Plugin '{plugin_name}' not found")
|
|
return
|
|
|
|
# Get or create category
|
|
try:
|
|
category = logic.categories[category_name]
|
|
except KeyError:
|
|
try:
|
|
category = logic.introduce_category(category_name)
|
|
print(f"Created new category: {category_name}")
|
|
except Exception as e:
|
|
print(f"Could not create category: {e}")
|
|
return
|
|
|
|
# Add to category
|
|
try:
|
|
plugin.add_to_category(category)
|
|
logic.sync_category_plugin_amount(category)
|
|
print(f"Added {plugin.full_name} to {category_name}")
|
|
except Exception as e:
|
|
print(f"Error adding to category: {e}")
|
|
|
|
safe_add_to_category("fabfilter: pro-q 3", "My Favorites")
|