Picard Plugins Registry

Official registry and maintenance tools for MusicBrainz Picard plugins (v3).

Plugin developers: Want to submit your plugin? See the Plugin Submission Guide.

Note

This registry is for Picard v3 plugins only. Legacy v2 plugins are managed through the old plugin repository.

Overview

This repository contains:

• plugins.toml - The official plugin registry (DO NOT EDIT MANUALLY)
• registry - CLI tool for maintaining the registry (USE THIS)
• Validation and testing infrastructure

Setup

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/metabrainz/picard-plugins-registry.git
cd picard-plugins-registry
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Activate virtual environment
source .venv/bin/activate

Note: After activating the virtual environment with source .venv/bin/activate, you can run registry commands directly. All examples below assume the virtual environment is activated. If not activated, prefix commands with uv run (e.g., uv run registry plugin list).

Git Requirements

For fetching manifests from well-known hosts (GitHub, GitLab, Sourcehut, Codeberg, Bitbucket), no extra dependencies are needed — files are fetched via HTTP.

For other git hosts, one of the following is required:

• pygit2 (recommended): uv pip install pygit2 — pure Python, no external tools needed
• git CLI: must be available in PATH

Usage

Add a Plugin

registry plugin add https://github.com/user/plugin-name \
    --trust community \
    --categories metadata,coverart

# With custom git ref
registry plugin add https://github.com/user/plugin-name \
    --trust community \
    --refs develop

# With multiple refs for different Picard versions
registry plugin add https://github.com/user/plugin-name \
    --trust community \
    --refs 'main:4.0,picard-v3:3.0-3.99'

# With semantic versioning (auto-discovers version tags)
registry plugin add https://github.com/user/plugin-name \
    --trust community \
    --versioning-scheme semver

# With custom version pattern
registry plugin add https://github.com/user/plugin-name \
    --trust community \
    --versioning-scheme 'regex:^version\d+\.\d+\.\d+$'

Update Plugin Metadata

Refresh plugin metadata from MANIFEST.toml:

# Update from default ref (first ref or main)
registry plugin update plugin-id

# Update from specific ref
registry plugin update plugin-id --ref develop

Note: The UUID in MANIFEST.toml must match the registry. If it has changed, the update will fail with an error.

Validate Plugin Manifest

Validate a plugin's MANIFEST.toml without adding it to the registry. Accepts a remote git URL or a local path (directory or file):

# Validate from a remote repository (default ref: main)
registry plugin validate https://github.com/user/plugin-name

# Validate from a specific ref
registry plugin validate https://github.com/user/plugin-name --ref develop

# Validate from a local directory (reads MANIFEST.toml from it)
registry plugin validate /path/to/plugin

# Validate a local MANIFEST.toml file directly
registry plugin validate /path/to/MANIFEST.toml

Edit a Plugin

# Change trust level
registry plugin edit plugin-id --trust official

# Change categories
registry plugin edit plugin-id --categories metadata,ui

# Change git URL (when plugin permanently moves)
registry plugin edit plugin-id --git-url https://github.com/newuser/new-repo

# Add or change versioning scheme
registry plugin edit plugin-id --versioning-scheme semver

# Remove versioning scheme
registry plugin edit plugin-id --versioning-scheme ""

# Change multiple fields
registry plugin edit plugin-id --trust trusted --categories metadata

Add URL Redirect

When a plugin moves to a new repository URL, add a redirect so users with the old URL can still get updates:

# Add redirect
registry plugin redirect plugin-id https://github.com/olduser/old-repo

# List redirects
registry plugin redirect plugin-id --list

# Remove redirect
registry plugin redirect plugin-id https://github.com/olduser/old-repo --remove

Manage Plugin Refs

Refs allow plugins to support multiple git branches for different Picard versions:

# Add a ref
registry ref add plugin-id develop \
    --description "Development branch" \
    --min-api-version "4.0"

# Add ref with version range
registry ref add plugin-id picard-v3 \
    --description "Picard 3.x compatible" \
    --min-api-version "3.0" \
    --max-api-version "3.99"

# Edit ref (update description, API versions, or rename)
registry ref edit plugin-id develop --max-api-version "4.99"
registry ref edit plugin-id develop --name beta

# List refs for a plugin
registry ref list plugin-id

# Remove a ref
registry ref remove plugin-id develop

List Plugins

# Compact list
registry plugin list

# Detailed list (shows all plugin information)
registry plugin list --verbose

# Filter by trust level
registry plugin list --trust official

# Filter by category
registry plugin list --category metadata

# Combine filters
registry plugin list --trust community --category coverart --verbose

Show Plugin Details

registry plugin show plugin-id

Remove a Plugin

registry plugin remove plugin-id

Blacklist a Plugin

# Blacklist by URL
registry blacklist add --url https://github.com/bad/plugin \
    --reason "Contains malicious code"

# Blacklist by UUID (recommended - blocks plugin at all URLs)
registry blacklist add --uuid 12345678-1234-4234-8234-123456789abc \
    --reason "Malicious plugin"

# Blacklist by URL regex (entire organization)
registry blacklist add --url-regex "^https://github\\.com/badorg/.*" \
    --reason "Compromised account"

# Blacklist specific fork (UUID + URL combination)
registry blacklist add \
    --uuid 12345678-1234-4234-8234-123456789abc \
    --url https://github.com/badactor/fork \
    --reason "Malicious fork of legitimate plugin"

Remove from Blacklist

# Remove by URL
registry blacklist remove --url https://github.com/bad/plugin

# Remove by UUID
registry blacklist remove --uuid 12345678-1234-4234-8234-123456789abc

List Blacklist

registry blacklist list

Show Blacklist Entry

# Show details by URL
registry blacklist show --url https://github.com/bad/plugin

# Show details by UUID
registry blacklist show --uuid 12345678-1234-4234-8234-123456789abc

Validate Registry

Check registry integrity (duplicate IDs, UUIDs, URLs):

registry validate

Show Statistics

Display registry statistics by trust level and category:

registry stats

Output Registry

Output the registry in a specific format (useful for conversion or piping):

# Output as TOML (default)
registry output

# Output as JSON
registry output --format json

# Output in human-readable format
registry output --format human

# Convert TOML to JSON
registry output --format json > plugins.json

Display Registry

Shortcut for registry output --format human with colorized output:

registry display

Global Options

# Disable colored output
registry --no-color <command>

Colors are automatically disabled when output is piped or redirected, or when the NO_COLOR environment variable is set.

Trust Levels

• official - Maintained by MusicBrainz Picard team
• trusted - Well-known authors with established reputation
• community - Other plugins (default for new submissions)

Development

Run Tests

# All tests
uv run pytest

# With coverage
uv run pytest --cov=registry_lib

# Specific test file
uv run pytest tests/test_registry.py -v

Code Quality

# Run ruff checks
uv run ruff check .

# Format code
uv run ruff format .

# Type check
uv run ty check

# Run pre-commit on all files
uv run pre-commit run --all-files

Architecture

• registry_lib/ - Main package
  • cli.py - Command-line interface
  • registry.py - Registry file management
  • plugin.py - Plugin operations
  • blacklist.py - Blacklist operations
  • manifest.py - MANIFEST.toml fetching/validation
  • utils.py - Utility functions
  • picard/ - Files copied from Picard (validator, constants)
• tests/ - Unit tests
• plugins.toml - The registry file

Contributing

For registry development (code changes, bug fixes):

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run uv run pytest to verify
5. Submit a pull request

All commits must pass pre-commit hooks (ruff format, ruff check, ty check, pytest).

For plugin developers (submitting, updating, or moving a plugin), see PLUGIN_SUBMISSION.md.

License

GPL-2.0-or-later