### User Installation with Branch Refs

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Examples of how users can install a plugin, choosing between the latest stable release, the development branch, or a beta branch.

```bash
# Stable release (latest tag)
picard-plugins --install my-plugin

# Development branch
picard-plugins --install my-plugin --ref main

# Beta branch
picard-plugins --install my-plugin --ref beta
```

--------------------------------

### Traditional pip setup for development

Source: https://github.com/metabrainz/picard/blob/master/INSTALL.md

Sets up a virtual environment, installs dependencies from requirement files, builds C extensions in-place for development, and runs Picard.

```bash
# Create virtual environment
python3 -m venv --system-site-packages .venv
source .venv/bin/activate

# Install dependencies manually
pip install -r requirements.txt -r requirements-build.txt -r requirements-dev.txt

# Build and run
python3 setup.py build          # Compiles translations and prepares build files
python3 setup.py build_ext -i   # Builds C extensions in-place for development
python3 tagger.py
```

--------------------------------

### Traditional Pip Setup

Source: https://github.com/metabrainz/picard/blob/master/CONTRIBUTING.md

Set up the project using traditional pip if uv is not preferred. This includes creating a virtual environment, activating it, and installing dependencies from requirement files.

```bash
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-build.txt
pip install -r requirements-dev.txt

# Build and install
python setup.py build          # Compiles translations and prepares build files
python setup.py build_ext -i   # Builds C extensions in-place for development
pip install -e .
```

--------------------------------

### Branch Tracking Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Illustrates registry entry, local installation, and update check for branch tracking.

```text
Registry entry:
  git_url: https://github.com/user/plugin
  refs: [{"name": "main"}]  // or omitted (defaults to main)

Local installation:
  commit: abc123def456
  ref: main

Update check:
  $ git ls-remote https://github.com/user/plugin main
  → returns: def456789abc (different!)
  → Update available: abc123 -> def456 (5 commits ahead)
```

--------------------------------

### Set Up Picard Development Environment

Source: https://github.com/metabrainz/picard/blob/master/CONTRIBUTING.md

Clones the Picard repository, creates and activates a virtual environment using uv, installs dependencies, and builds the project. This is the recommended setup for development.

```bash
# Clone and enter the repository
git clone https://github.com/metabrainz/picard.git
cd picard

# Create virtual environment
uv venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate.bat  # Windows

# Install all dependencies (main, build, dev)
uv sync

# Build the project
python setup.py build          # Compiles translations and prepares build files
python setup.py build_ext -i   # Builds C extensions in-place for development

# Install in editable mode
uv pip install -e .
```

--------------------------------

### Discover and Install Plugin Workflow

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

A common workflow to search for a plugin by name, get more information, and then install it.

```bash
picard-plugins --search "listenbrainz.org"
picard-plugins --info listenbrainz
picard-plugins --install listenbrainz
```

--------------------------------

### Stable Release Workflow Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Demonstrates a typical workflow for releasing stable versions of a plugin using Git tags and how users can install and update them.

```bash
# Plugin repository
git tag v1.0.0
git push --tags

# Users automatically get v1.0.0
picard-plugins --install my-plugin

# Later: release v1.0.1
git tag v1.0.1
git push --tags

# Users get update notification
picard-plugins --update my-plugin
# Updates: v1.0.0 → v1.0.1
```

--------------------------------

### Tag Tracking Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Illustrates registry entry, local installation, and update check for tag tracking.

```text
Registry entry:
  git_url: https://github.com/user/plugin
  refs: [{"name": "v1.8.0"}]

Local installation:
  commit: abc123def456
  ref: v1.8.0

Update check:
  $ git ls-remote --tags https://github.com/user/plugin
  → shows v1.9.0 exists (newer than v1.8.0)
  → Update available: v1.8.0 -> v1.9.0
```

--------------------------------

### Install uv and set up Picard

Source: https://github.com/metabrainz/picard/blob/master/INSTALL.md

This sequence installs the uv package manager, creates a virtual environment, activates it, installs Picard and its dependencies, and finally runs Picard.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

uv venv
source .venv/bin/activate  # macOS/Linux (.venv\Scripts\activate.bat on Windows)
uv sync  # Automatically installs all dependencies from pyproject.toml
python setup.py build && python setup.py build_ext -i
uv pip install -e .

# Run Picard
picard
```

--------------------------------

### Legacy setup.py installation

Source: https://github.com/metabrainz/picard/blob/master/INSTALL.md

Installs Picard using the legacy setup.py script, which also attempts to install dependencies. This method is not recommended.

```bash
sudo python3 setup.py install  # Installs Picard and attempts to install dependencies
```

--------------------------------

### Install and Verify Plugin Locally

Source: https://github.com/metabrainz/picard/blob/master/docs/Plugin2to3MigrationGuide.md

Commands to install a V3 plugin from a local directory and verify its installation.

```bash
# Install from local directory
picard-plugins --install /path/to/my_plugin_v3 --yes

# Verify
picard-plugins --list
```

--------------------------------

### Install Official Plugin

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Demonstrates the command-line installation of an official plugin with a success message.

```bash
$ picard-plugins --install listenbrainz
Installing ListenBrainz (Official)...
✓ Installed successfully
```

--------------------------------

### Install and Test Local Plugin

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MIGRATION.md

Install a plugin from a local directory using 'picard-plugins --install'. After installation, launch Picard to test the plugin and check the log file for errors.

```bash
# Install from local directory
picard-plugins --install ~/dev/picard-plugin-example

# Test in Picard
picard

# Check logs for errors
tail -f ~/.config/MusicBrainz/Picard/picard.log

# Uninstall
picard-plugins --uninstall example
```

--------------------------------

### Example Migration Command

Source: https://github.com/metabrainz/picard/blob/master/docs/Plugin2to3MigrationGuide.md

An example of running the migration script for a specific plugin.

```bash
python scripts/migrate_plugin.py featartist.py featartist_v3
```

--------------------------------

### Install Picard using pip

Source: https://github.com/metabrainz/picard/blob/master/INSTALL.md

Installs Picard using pip after manual dependency installation. To start Picard, run the 'picard' command.

```bash
pip3 install .  # Installs Picard but not dependencies

# To start Picard:
picard

# To uninstall:
pip3 uninstall picard
```

--------------------------------

### Current Plugin Installation

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MONOREPO.md

Illustrates the current method of installing a single plugin from a dedicated repository.

```text
https://github.com/user/plugin.git
→ Installs one plugin
```

--------------------------------

### Async Plugin Installation with Callbacks

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/GUI.md

Demonstrates how to install a plugin asynchronously using `AsyncPluginManager`. It includes callbacks for progress updates and completion, handling various success and error scenarios.

```python
from picard.plugin3.asyncops.manager import AsyncPluginManager

async_manager = AsyncPluginManager(manager)

def on_progress(update):
    # Update progress bar
    progress_bar.setValue(update.percent)
    status_label.setText(update.message)

def on_complete(result):
    if result.success:
        QMessageBox.information(parent, "Success",
                               f"Plugin {result.value} installed successfully")
    else:
        if isinstance(result.error, PluginBlacklistedError):
            QMessageBox.critical(parent, "Blocked",
                                 f"Plugin is blacklisted: {result.error.reason}")
        elif isinstance(result.error, PluginAlreadyInstalledError):
            QMessageBox.information(parent, "Already Installed",
                                   f"Plugin {result.error.plugin_name} is already installed")
        elif isinstance(result.error, PluginManifestInvalidError):
            QMessageBox.critical(parent, "Invalid Plugin",
                                 f"Invalid MANIFEST.toml:\n" + "\n".join(result.error.errors))
        else:
            QMessageBox.critical(parent, "Error", str(result.error))

# Start async installation
async_manager.install_plugin(url, ref=ref, progress_callback=on_progress, callback=on_complete)
```

--------------------------------

### Install Plugin from URL

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Installs a plugin from a given URL, optionally specifying a Git reference. This is useful for installing development versions or specific branches.

```bash
picard-plugins --install <url> --ref dev
```

--------------------------------

### Install Plugin With Versioning Scheme

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Install a plugin when a versioning scheme is defined. The client fetches all tags, filters by the pattern, and installs the latest matching version.

```bash
$ picard-plugins --install my-plugin
# Fetches all tags, filters by pattern, installs latest (e.g., v2.1.4)
```

--------------------------------

### Plugin v3 Code Example

Source: https://github.com/metabrainz/picard/blob/master/AGENTS.md

Example of a v3 plugin's `__init__.py` file, demonstrating how to enable the plugin, register an option, and process track metadata.

```python
from picard.plugin3.api import PluginApi

def enable(api: PluginApi):
    """Called when plugin is enabled."""
    api.plugin_config.register_option("my_option", "default")
    api.register_track_metadata_processor(process_metadata)

def process_metadata(api, album, metadata, track, release):
    metadata['custom'] = api.plugin_config['my_option']
```

--------------------------------

### Standalone CLI Mode Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Illustrates using a CLI command in standalone mode, where changes affect configuration files and plugin directories, taking effect when Picard is next started.

```bash
picard-plugins --enable listenbrainz
```

--------------------------------

### Proposed Monorepo Plugin Installation

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MONOREPO.md

Demonstrates the proposed URL syntax for installing specific plugins from a monorepo.

```text
https://github.com/metabrainz/picard-plugins.git#lastfm
https://github.com/metabrainz/picard-plugins.git#bpm
→ Installs specific plugin from collection
```

--------------------------------

### Install Multiple Plugins

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Installs multiple plugins in a single command, either from URLs/paths or registry IDs. This is useful for setting up multiple plugins at once.

```bash
picard-plugins --install url1 url2 url3
```

--------------------------------

### Install Plugin from URL or Path

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Installs a plugin from a Git repository URL or a local file path. Supports installing from specific Git references (tags, branches, commits).

```bash
# Install from GitHub
picard-plugins --install https://github.com/metabrainz/picard-plugin-listenbrainz
```

```bash
# Install from specific ref
picard-plugins --install https://github.com/user/plugin --ref v1.0.0
```

```bash
# Install from local repository (absolute path)
picard-plugins --install ~/dev/my-plugin
```

```bash
# Install from local repository (relative path - note the ./)
picard-plugins --install ./my-plugin
```

--------------------------------

### Install Plugin with Specific Ref

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Install a plugin from the registry, specifying a particular Git ref (e.g., a beta branch or a specific tag).

```bash
picard-plugins --install my-plugin --ref beta
```

--------------------------------

### Picard Plugin Local Installation

Source: https://github.com/metabrainz/picard/blob/master/docs/Plugin2to3MigrationGuide.md

Install your V3 plugin locally by initializing a git repository, committing, and then using the picard-plugins --install command.

```bash
cd my_plugin_v3
git init && git add . && git commit -m "v3"
picard-plugins --install $(pwd) --yes
```

--------------------------------

### List Installed Plugins

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Lists all installed plugins, their status, and detailed information. Useful for auditing installed plugins and their configurations.

```bash
picard-plugins --list
```

```bash
picard-plugins -l
```

--------------------------------

### Install Community Plugin with Warnings

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Installs a community plugin, showing warnings by default. This is the default behavior when installing plugins not from official or trusted sources.

```bash
picard-plugins --install https://github.com/user/community-plugin
```

--------------------------------

### Install Plugin Locally

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MANIFEST.md

Use this command to install a plugin directly from its local development directory.

```bash
picard-plugins --install ~/dev/my-plugin
```

--------------------------------

### Install Plugin with Progress Updates

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/GUI.md

Use AsyncPluginManager to install a plugin with progress callbacks for GUI feedback. The callback receives the result upon completion.

```python
from picard.plugin3.asyncops.manager import AsyncPluginManager

async_manager = AsyncPluginManager(manager)

# Install with progress updates
async_manager.install_plugin(
    url='https://github.com/user/plugin',
    ref='main',
    progress_callback=lambda update: print(f"{update.percent}%: {update.message}"),
    callback=lambda result: print(f"Installed: {result.value}")
)
```

--------------------------------

### Install Community Plugin with Warning

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Illustrates the installation of a community plugin, featuring a clear warning about trust and security, followed by user confirmation.

```bash
$ picard-plugins --install custom-tagger
Installing Custom Tagger by John Doe (Community)...

⚠️  WARNING: This plugin is not reviewed or endorsed by the Picard team.
   It may contain bugs or security issues.
   Only install if you trust the author.

Continue? [y/N] y
✓ Installed successfully
```

--------------------------------

### Install Trusted Plugin with Warning

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Shows the installation of a trusted plugin, including a minimal warning and user confirmation prompt.

```bash
$ picard-plugins --install discogs
Installing Discogs by Bob Swift (Trusted)...
Note: This plugin is not reviewed by the Picard team.
Continue? [Y/n] y
✓ Installed successfully
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/metabrainz/picard/blob/master/AGENTS.md

Installs the necessary Python packages for the project. Run this command in your terminal.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install Plugin

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Installs a plugin. By default, it installs the latest tag. You can specify a specific version tag or branch using the --ref option.

```bash
picard-plugins --install my-plugin
# Installs latest tag (e.g., v2.1.4)

# Override to install specific version
picard-plugins --install my-plugin --ref v1.0.0

# Override to install branch instead
picard-plugins --install my-plugin --ref main
```

--------------------------------

### Install Plugin from Registry (Auto-Select Ref)

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Install a plugin from the official registry. Picard automatically selects the most appropriate Git reference (branch/tag) based on your Picard version.

```bash
picard-plugins --install my-plugin
```

--------------------------------

### Complete Plugin Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/API.md

A comprehensive example of a Picard plugin, including registering an options page, track processor, file post-save processor, and a file action.

```python
from PyQt6.QtWidgets import QCheckBox
from picard.plugin3.api import PluginApi, BaseAction, OptionsPage, t_


class MyOptionsPage(OptionsPage):
    NAME = "example"
    TITLE = t_("Example Plugin")
    PARENT = "plugins"

    def __init__(self):
        super().__init__()
        self.checkbox = QCheckBox("Enable processing")
        self.layout().addWidget(self.checkbox)

    def load(self):
        enabled = self.api.global_config.setting.get('example_enabled', False)
        self.checkbox.setChecked(enabled)

    def save(self):
        self.api.global_config.setting['example_enabled'] = self.checkbox.isChecked()


def process_track(api, track, metadata, track_node, release=None):
    """Process track metadata."""
    if api.global_config.setting.get('example_enabled', False):
        api.logger.info(f"Processing: {metadata.get('title', 'Unknown')}")
        metadata['example_tag'] = 'processed'


def on_file_saved(api, file):
    """Called after file is saved."""
    api.logger.info(f"Saved: {file.filename}")


class MyAction(BaseAction):
    TITLE = t_("Example Action")

    def callback(self, objs):
        self.api.logger.info(f"Action on {len(objs)} objects")


def enable(api):
    """Plugin entry point."""
    api.logger.info("Example plugin loaded")

    # Register processors
    api.register_track_metadata_processor(process_track)
    api.register_file_post_save_processor(on_file_saved)

    # Register UI
    api.register_options_page(MyOptionsPage)
    api.register_file_action(MyAction)
```

--------------------------------

### Qt Designer UI File Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/TRANSLATIONS.md

An example of a Qt Designer `.ui` file defining a `QTableWidget` with column headers that will be translated.

```xml
<widget class="QTableWidget" name="metadata_table">
  <column>
    <property name="text">
      <string>Variable</string>
    </property>
  </column>
  <column>
    <property name="text">
      <string>Value</string>
    </property>
  </column>
</widget>
```

--------------------------------

### Example Output of Migration Tool

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MIGRATION.md

This is an example of the output you can expect when running the automated migration tool, showing files created, regenerated, and conversions performed.

```text
Migrating plugin: Keep tags
  Author: Wieland Hoffmann
  Version: 1.2.1
  Created: /tmp/keep_v3/MANIFEST.toml
  Created: /tmp/keep_v3/__init__.py
  Regenerated: ui_options.py (from ui_options.ui)

✓ Copied 3 file(s)
✓ Copied 1 directory(ies)

✓ Converted log.* calls to api.logger.*
✓ Converted config.setting to api.global_config.setting
✓ Injected api in MyOptionsPage.__init__

Migration complete! Plugin saved to: /tmp/keep_v3
```

--------------------------------

### Install Plugin from Registry

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Installs a plugin directly from the official plugin registry using its registry ID. This is the simplest method for official plugins.

```bash
# Install by registry ID
picard-plugins --install view-script-variables
```

```bash
# Install multiple from registry
picard-plugins --install listenbrainz discogs acoustid
```

--------------------------------

### Install Plugin from Local Git Repository

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/ROADMAP.md

Installs a plugin directly from a local Git repository path. Requires the `picard-plugins` command-line tool.

```bash
# Install from local git repository
picard-plugins --install ~/dev/my-plugin
```

--------------------------------

### Install Community Plugin Without Warnings

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Installs a community plugin while bypassing the default warnings. Use this when you have already reviewed and trust the plugin.

```bash
picard-plugins --install https://github.com/user/community-plugin --trust-community
```

--------------------------------

### Development Setup with uv

Source: https://github.com/metabrainz/picard/blob/master/AGENTS.md

Steps to set up the Picard development environment using Git clone and `uv sync` for dependency management.

```bash
git clone https://github.com/metabrainz/picard.git
cd picard

# Preferred
uv sync
```

--------------------------------

### UI Action Plugin Example (Export to CSV)

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MANIFEST.md

An example of a plugin that adds a context menu action to export album track data to a CSV file.

```python
# __init__.py
from picard.plugin3.api import PluginApi

def enable(api: PluginApi):
    @api.register_album_action("Export to CSV")
    def export_to_csv(album):
        # Export album data to CSV
        import csv
        with open('export.csv', 'w') as f:
            writer = csv.writer(f)
            for track in album.tracks:
                writer.writerow([track.title, track.artist])
```

--------------------------------

### Display Plugin MANIFEST TOML Content

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Example output of a MANIFEST.toml file for an installed plugin, showing its metadata such as name, version, and description.

```toml
uuid = "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
name = "ListenBrainz Submitter"
version = "2.1.0"
description = "Submit your music to ListenBrainz"
long_description = """
This plugin integrates with ListenBrainz...
"""
api = ["3.0", "3.1"]
authors = ["MusicBrainz Picard Team"]
license = "GPL-2.0-or-later"
license_url = "https://www.gnu.org/licenses/gpl-2.0.html"
homepage = "https://github.com/metabrainz/picard-plugin-listenbrainz"
categories = ["metadata"]

```

--------------------------------

### Get Plugin Information by Registry ID

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Use this command to display detailed information about a plugin installed from the registry, identified by its registry ID.

```bash
picard-plugins --info view-script-variables
```

--------------------------------

### Install Plugin with Local Path Prefix

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Demonstrates the correct way to install a plugin from a local directory when the directory name does not contain path separators. Prefacing with './' ensures it's treated as a local path and not a registry ID.

```bash
# Correct - will use local directory:
picard-plugins --install ./my-plugin
```

--------------------------------

### Get Plugin Information by Git URL

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Fetch information for a plugin directly from its Git repository URL. This is useful for plugins not yet installed or available in the registry.

```bash
picard-plugins --info https://github.com/user/plugin
```

--------------------------------

### Getting Current Locale

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/API.md

Retrieve the current locale string used by Picard, which can be used for internationalization purposes within plugins. Examples include 'en_US', 'de_DE', and 'pt_BR'.

```python
def enable(api):
    locale = api.get_locale()  # e.g., 'en_US', 'de_DE', 'pt_BR'
    api.logger.info(f"Current locale: {locale}")
```

--------------------------------

### Picard v2 Plugin Initialization (__init__.py)

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MIGRATION.md

Example of a v2 Picard plugin's main initialization file, including metadata, registration of options pages, and track processing.

```python
PLUGIN_NAME = "Example Plugin"
PLUGIN_AUTHOR = "John Doe"
PLUGIN_VERSION = "1.0.0"
PLUGIN_API_VERSIONS = ["2.0"]
PLUGIN_LICENSE = "GPL-2.0-or-later"
PLUGIN_LICENSE_URL = "https://www.gnu.org/licenses/gpl-2.0.html"
PLUGIN_DESCRIPTION = "Example plugin"

from picard import log, config
from picard.metadata import register_track_metadata_processor
from picard.ui.options import register_options_page, OptionsPage
from PyQt5.QtWidgets import QCheckBox

class ExampleOptionsPage(OptionsPage):
    NAME = "example"
    TITLE = "Example Plugin"
    PARENT = "plugins"

    def __init__(self, parent=None):
        super().__init__(parent)
        self.checkbox = QCheckBox("Enable processing")
        self.layout().addWidget(self.checkbox)

    def load(self):
        self.checkbox.setChecked(config.setting['example_enabled'])

    def save(self):
        config.setting['example_enabled'] = self.checkbox.isChecked()

def process_track(api, album, metadata, track, release):
    log.info("Processing track: %s", track)
    if config.setting['example_enabled']:
        metadata['example'] = 'processed'

def register():
    log.info("Registering Example Plugin")
    register_track_metadata_processor(process_track)
    register_options_page(ExampleOptionsPage)
```

--------------------------------

### Plugin Identification Examples

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Demonstrates how to use different plugin identifiers (Registry ID, Display Name, Plugin ID, UUID) with the --info command, including exact and prefix matching, and case-insensitivity.

```bash
# Registry ID (exact or prefix)
picard-plugins --info view-script-variables            # Exact registry ID
picard-plugins --info view-script                      # Registry ID prefix
picard-plugins --info VIEW-SCRIPT                      # Case-insensitive

# Display name (exact or prefix)
picard-plugins --info "ListenBrainz Submitter"         # Exact display name
picard-plugins --info "ListenBrainz"                   # Display name prefix
picard-plugins --info listenbrainz                     # Case-insensitive

# Plugin ID (exact or prefix)
picard-plugins --info listenbrainz_a1b2c3d4-e5f6-...
picard-plugins --info listenbrainz_a1b2                # Plugin ID prefix

# UUID (exact or prefix)
picard-plugins --info a1b2c3d4-e5f6-4a5b-8c9d-...
picard-plugins --info a1b2c3d4                         # UUID prefix
```

--------------------------------

### Picard CLI Install Plugin

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/ROADMAP.md

Installs a plugin by its ID from the official registry. This command looks up the plugin ID in the registry before installation.

```bash
picard --install <plugin-id>
```

--------------------------------

### Picard v3 Plugin Initialization (__init__.py)

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MIGRATION.md

Example of a v3 Picard plugin's main initialization file, demonstrating updated API usage for options pages, logging, and track processing.

```python
from picard.plugin3.api import OptionsPage
from PyQt6.QtWidgets import QCheckBox


class ExampleOptionsPage(OptionsPage):
    NAME = "example"
    TITLE = "Example Plugin"
    PARENT = "plugins"

    def __init__(self, api=None, parent=None):
        super().__init__(parent)
        self.api = api
        self.checkbox = QCheckBox("Enable processing")
        self.layout().addWidget(self.checkbox)

    def load(self):
        enabled = self.api.global_config.setting.get('example_enabled', False)
        self.checkbox.setChecked(enabled)

    def save(self):
        self.api.global_config.setting['example_enabled'] = self.checkbox.isChecked()


def process_track(api, track, metadata):
    api.logger.info(f"Processing track: {track}")
    if api.global_config.setting.get('example_enabled', False):
        metadata['example'] = 'processed'


def enable(api):
    """Entry point for the plugin."""
    api.logger.info("Example Plugin loaded")
    api.register_track_metadata_processor(process_track)
    api.register_options_page(ExampleOptionsPage)
```

--------------------------------

### Install libxcb-cursor0 for Qt6 pip issues

Source: https://github.com/metabrainz/picard/blob/master/INSTALL.md

If you encounter 'libxcb' errors when using Qt6 installed via pip, install the 'libxcb-cursor0' package.

```bash
sudo apt install libxcb-cursor0
```

--------------------------------

### Refresh Registry and Install Plugin

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Refreshes the plugin registry cache and then installs a specified plugin. Ensures the latest registry data is used for installation.

```bash
picard-plugins --refresh-registry --install view-script-variables
```

--------------------------------

### Force Reinstall Plugin

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Forces a reinstallation of a plugin, even if it appears to be installed correctly. Use this with the `--install` command to ensure a fresh installation.

```bash
picard-plugins --reinstall
```

--------------------------------

### Registry TOML example with i18n

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/TRANSLATIONS.md

Demonstrates how to include localized names and descriptions for plugins directly within the TOML file for the registry.

```toml
[[plugins]]
id = "listenbrainz"
name = "ListenBrainz Submitter"
description = "Submit your music to ListenBrainz"

[plugins.name_i18n]
de = "ListenBrainz-Submitter"
fr = "Soumetteur ListenBrainz"
ja = "ListenBrainzサブミッター"

[plugins.description_i18n]
de = "Sende deine Musik zu ListenBrainz"
fr = "Soumettez votre musique sur ListenBrainz"
ja = "ListenBrainzに音楽をスクロブルする"
```

--------------------------------

### Install Plugin Without Versioning Scheme

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Install a plugin without specifying a versioning scheme. The client defaults to installing the latest commit on the main branch.

```bash
$ picard-plugins --install my-plugin
# Installs: main branch @ latest commit
```

--------------------------------

### List Installed Plugins

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Displays a list of all currently installed Picard plugins.

```bash
picard-plugins --list
```

--------------------------------

### Compile Resources to Binary

Source: https://github.com/metabrainz/picard/blob/master/resources/README.md

Execute this command to create a binary file of all resources, which will be utilized by Picard.

```bash
python3 compile.py
```

--------------------------------

### V3 Plugin Structure Example

Source: https://github.com/metabrainz/picard/blob/master/docs/Plugin2to3MigrationGuide.md

Illustrates the file structure for a V3 Picard plugin.

```text
my_plugin_v3/
├── MANIFEST.toml
├── __init__.py
└── ui_options.py (if applicable)
```

--------------------------------

### PyQt5 UI Code Example

Source: https://github.com/metabrainz/picard/blob/master/docs/Plugin2to3MigrationGuide.md

Demonstrates V2 PyQt5 usage for setting window modality and executing a dialog. Note the use of Qt.WindowModal and dialog.exec_().

```python
from PyQt5.QtWidgets import QDialog
from PyQt5.QtCore import Qt

dialog.setWindowModality(Qt.WindowModal)
dialog.exec_()
```

--------------------------------

### Switch Plugin to Beta Ref

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Switch an installed registered plugin to its beta Git reference for testing.

```bash
picard-plugins --switch-ref myplugin beta
```

--------------------------------

### Install Plugin from Specific Branch

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Install a plugin from a specific development or feature branch in its Git repository.

```bash
picard-plugins --install https://github.com/user/plugin --ref dev
```

--------------------------------

### MANIFEST.toml example with i18n

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/TRANSLATIONS.md

Shows how to define localized plugin names and descriptions within the MANIFEST.toml file, serving as a single source of truth for translations.

```toml
name = "ListenBrainz Submitter"
description = "Submit your music to ListenBrainz"

[name_i18n]
de = "ListenBrainz-Submitter"
fr = "Soumetteur ListenBrainz"
ja = "ListenBrainzサブミッター"

[description_i18n]
de = "Sende deine Musik zu ListenBrainz"
fr = "Soumettez votre musique sur ListenBrainz"
ja = "ListenBrainzに音楽をスクロブルする"
```

--------------------------------

### Translation File with Qt Keys

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/TRANSLATIONS.md

Example translation file showing keys generated for Qt Designer elements, prefixed with `qt.{ClassName}`.

```toml
"qt.VariablesDialog.Variable" = "Variable"
"qt.VariablesDialog.Value" = "Value"
"dialog.title" = "Script Variables"
```

--------------------------------

### Install Plugin from Specific Tag

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/CLI.md

Install a plugin directly from a specific version tag in its Git repository.

```bash
picard-plugins --install https://github.com/user/plugin --ref v1.0.0
```

--------------------------------

### Install Plugin with Explicit Ref

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Users can override auto-selection by explicitly specifying a ref during plugin installation.

```bash
# Install from specific ref
$ picard-plugins --install my-plugin --ref beta
```

--------------------------------

### V2 Plugin Structure Example

Source: https://github.com/metabrainz/picard/blob/master/docs/Plugin2to3MigrationGuide.md

Illustrates the file structure for a V2 Picard plugin.

```text
my_plugin.py  (or my_plugin/__init__.py)
```

--------------------------------

### Simple Metadata Plugin Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MANIFEST.md

An example of a plugin that adds a custom tag to all tracks when album metadata is loaded.

```python
# __init__.py
from picard.plugin3.api import PluginApi

def enable(api: PluginApi):
    @api.on_album_metadata_loaded
    def add_custom_tag(album, metadata):
        # Add custom tag to all tracks
        metadata['custom_tag'] = 'My Value'
```

--------------------------------

### Initialize Git Repository for Plugin

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MIGRATION.md

Steps to initialize a new Git repository for your plugin, copy existing files, and make an initial commit before migration.

```bash
mkdir picard-plugin-myplugin
cd picard-plugin-myplugin
git init

cp -r ~/old-plugin/* .

cat > .gitignore << EOF
__pycache__/
*.pyc
*.pyo
.DS_Store
EOF

git add .
git commit -m "Initial commit - v2 plugin"
```

--------------------------------

### Registry Redirect Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/MONOREPO.md

Provides a JSON example of how the registry can track plugin redirects when a plugin moves between repositories.

```json
{
  "id": "my-plugin",
  "url": "https://github.com/user/new-repo.git#my-plugin",
  "redirect_from": [
    "https://github.com/user/old-repo.git#my-plugin"
  ]
}
```

--------------------------------

### Force Install Blacklisted Plugin

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/ROADMAP.md

Installs a plugin that has been flagged on the blacklist. Use with extreme caution due to security risks.

```bash
picard-plugins --force-blacklisted myplugin
```

--------------------------------

### Create and upload packages

Source: https://github.com/metabrainz/picard/blob/master/INSTALL.md

Generates a source distribution archive and uploads it to PyPI using twine.

```bash
python3 setup.py sdist
twine upload dist/*
```

--------------------------------

### German Source Locale Example

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/TRANSLATIONS.md

Example of a German developer writing code with German text, which will be used as the source locale.

```python
# German developer
api.tr("ui.button.login", "Bei ListenBrainz anmelden")
```

--------------------------------

### Example Plugin Metadata with Redirect

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Illustrates the structure of local plugin metadata, including original URL and UUID when a redirect has been followed.

```json
{
  "test_plugin_a1b2c3d4": {
    "url": "https://github.com/neworg/plugin",
    "ref": "main",
    "commit": "def456...",
    "uuid": "new-uuid-5678",
    "original_url": "https://github.com/olduser/plugin",
    "original_uuid": "old-uuid-1234"
  }
}
```

--------------------------------

### Blacklist by URL

Source: https://github.com/metabrainz/picard/blob/master/docs/PLUGINSV3/REGISTRY.md

Blacklist a specific repository URL to block installations from a compromised source. This prevents users from installing from a malicious repository.

```toml
# Blacklist the compromised URL
[[blacklist]]
url = "https://github.com/compromised/plugin"
reason = "Repository compromised"
```