DOCSEARCHbyAlgolia
Submit Docs

beets

repository·master·Indexed 12 days ago

https://github.com/beetbox/beets

A media library management system for music that catalogs collections and automatically improves metadata. It features a robust plugin ecosystem for manipulating, transcoding, and accessing music libraries, including specialized APIs for metadata source plugins and a custom logging system.

Tokens
98.5K
Snippets
404
Records
548
Agent score
92%

What's inside beets

  1. Overview of beets capabilities and plugins

    master

    Beets is a media library management system designed to catalog and improve music metadata. Its core functionality is extended via a plugin system, allowing for a wide range of operations:

    • Metadata Fetching: Retrieve album art, lyrics, genres, tempos, ReplayGain levels, or acoustic fingerprints from sources like MusicBrainz, Discogs, and Beatport.
    • Audio Manipulation: Transcode audio to various formats.
    • Library Maintenance: Identify duplicate tracks and albums or albums that are missing tracks.
    • File Management: Embed/extract album art, clean up crufty tags, and manage file organization.
    • Access & Playback: Browse the library via a Web browser (HTML5 Audio) or use a music player supporting the MPD protocol.

    If a specific feature is missing, users can write custom plugins using Python.

  2. What is Beets

    master

    Beets is a media library management system designed for obsessive music listeners. Its primary purpose is to catalog music collections and automatically improve metadata. It provides tools to access and manipulate music files, acting as a 'brainy tag corrector'.

    Key capabilities include:

    • Metadata Improvement: Fetching data from MusicBrainz, Discogs, or Beatport, and correcting song titles or acoustic features.
    • Extensibility: Almost all functionality is implemented via a plugin system.
    • Audio Processing: Transcoding audio to different formats and handling album art (embedding/extracting).
    • Library Maintenance: Detecting duplicate tracks/albums or missing tracks.
    • Advanced Features: Calculating ReplayGain levels, acoustic fingerprints, genres, and tempos.
    • Compatibility: Supporting MPD protocol for music players and ensuring compatibility with HTML5 Audio for web browsers.

  3. Explore advanced beets workflows and plugins

    master

    Once you have mastered the basics, you can extend beets' functionality through several advanced avenues:

    • Advanced Techniques: Implement sophisticated tagging strategies, manage complex import scenarios, and automate workflows.
    • Plugin Ecosystem: Enhance beets with plugins for metadata fetching from multiple sources, audio analysis, streaming service integration, and custom export formats.
    • Command Reference: For a complete list of command syntax, options, and usage examples (including critical operations like deleting music), consult the CLI reference.
    • Illustrated Walkthroughs: For visual, step-by-step guides covering real-world import examples and interactive tagging, visit the official walkthroughs.

  4. Overview of the beets CLI architecture

    master
    The beets command-line interface is managed by the beets.ui module. When a user executes beet in the terminal, the main function within this module is invoked. The CLI is structured into commands, which can be either built-in or provided by plugins. Built-in commands are implemented within the beets.ui.commands submodule.

  5. Available types for flexible fields

    master

    Flexible field types are used to define the data schema for non-string fields in Beets plugins. You can use built-in types provided by the core library or implement custom types.

    Built-in Types: Available in the beets.dbcore.types and beets.library modules.

    Custom Types: To create a custom type, inherit from the Type class.

  7. Understand the side effects of advancedrewrite on metadata

    master
    While advancedrewrite is intended to apply to templates and path formats, it rewrites all field lookups. This means it effectively modifies the file's metadata during lookups, even if it doesn't explicitly modify the library database or the file's physical tags directly.

  8. How to modify metadata during the write process

    master
    To intercept and potentially modify metadata before it is written to a file, listen for the write event. The handler receives the item, the target path, and a tags dictionary. You can modify the tags dictionary directly or raise library.FileOperationError to abort the write operation.

  9. Configure beets using YAML syntax

    master

    The config.yaml file uses standard YAML syntax. Most options are defined as simple key/value pairs, but you can also use nested structures for complex options.

    Important: Always use spaces for indentation; do not use tabs, as they are invalid in YAML.

    option: value
another_option: foo
bigger_option:
    key: value
    foo: bar

  10. How the lastgenre plugin works

    master

    The lastgenre plugin fetches tags from Last.fm and assigns them as genres to your albums and items. It uses a whitelist-based approach by default to ensure only relevant tags are used as genres.

    Key mechanisms include:

    • Whitelisting: Only tags present in a whitelist are considered genres. You can use the internal whitelist, provide your own list, or set whitelist: no to disable it.
    • Canonicalization: Uses a nested YAML tree to map specific sub-genres to broader, whitelisted categories (e.g., viking metal → heavy metal).
    • Normalization (Aliases): Uses regex to map spelling variants (e.g., dnb → drum and bass) before filtering.
    • Ignorelist: Allows you to reject specific genres globally or per-artist using regex or plain names.

  11. Configure CORS for the web plugin

    master

    If you are using an in-browser client hosted on a different origin (protocol, host, and optional port), you must configure the cors option in the web: section of your config.

    • Set cors to the specific origin (e.g., 'http://example.com').
    • Set cors to '*' to allow all origins (use with caution due to security implications).
    • If the server is behind a proxy using credentials, set cors_supports_credentials: true to allow in-browser clients to log in.
    web:
    host: 0.0.0.0
    cors: 'http://example.com'

  12. How to handle paths in Beets (Legacy vs. New style)

    master

    Beets has transitioned from custom path utilities to using the standard Python pathlib library.

    New Style (Recommended)

    Use pathlib.Path for all new development. To normalize a path (expand ~ and resolve symlinks), use .expanduser().resolve().

    Legacy Utilities

    If you are maintaining older code, you may encounter these functions. While still safe to use, they should be replaced by pathlib where possible:

    • syspath(): Handles Windows Unicode and long-path limitations (adds \?\ prefix).
    • normpath(): Normalizes slashes and removes . or .. (does not expand ~).
    • bytestring_path(): Converts paths to bytes for database storage.
    • displayable_path(): Converts byte paths to Unicode for display/logging.
    # New style (Recommended)
item.filepath
Path("~/Music/../Artist").expanduser().resolve()

# Old style (Legacy)
displayable_path(item.path)
normpath("~/Music/../Artist")
syspath(path)