or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdimport-autotag.mdindex.mdlibrary-management.mdplugin-system.mdquery-system.mduser-interface.mdutilities-templates.md
tile.json

tessl/pypi-beets

A comprehensive music library management system and command-line application for organizing and maintaining digital music collections

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/beets@2.3.x

To install, run

npx @tessl/cli install tessl/pypi-beets@2.3.0

index.mddocs/

Beets

A comprehensive music library management system and command-line application designed for music enthusiasts who want to organize and maintain their digital music collections. Beets provides automated metadata correction and tagging using various sources including MusicBrainz, Discogs, and Beatport, with intelligent tag correction that can fix inconsistencies and improve music metadata.

Package Information

  • Package Name: beets
  • Package Type: pypi
  • Language: Python
  • Installation: pip install beets
  • Version: 2.3.1

Core Imports

import beets
from beets.library import Library, Item, Album
from beets import config
from beets.ui import main

For autotag and import functionality:

from beets.autotag import AlbumInfo, TrackInfo, Distance
from beets.importer import ImportSession

For plugin development:

from beets.plugins import BeetsPlugin
from beets.ui import Subcommand

Basic Usage

Library Management

from beets.library import Library, Item, Album

# Create or open a music library
lib = Library('/path/to/library.db', '/path/to/music/directory')

# Query for items (tracks)
all_items = lib.items()
beatles_items = lib.items('artist:Beatles')
recent_items = lib.items('added:2024..')

# Query for albums
all_albums = lib.albums()
rock_albums = lib.albums('genre:Rock')

# Add new music to library
item = Item.from_path('/path/to/song.mp3')
lib.add(item)

# Access item metadata
for item in lib.items('artist:Beatles'):
    print(f"{item.artist} - {item.title} ({item.year})")
    print(f"Path: {item.path}")
    print(f"Duration: {item.length} seconds")

Command-Line Usage

# Import music into library
beet import /path/to/music/directory

# Search and list items
beet list artist:Beatles
beet list year:1960..1970 genre:Rock

# Update metadata from sources
beet update artist:Beatles

# Move files according to path formats
beet move artist:Beatles

# Show library statistics
beet stats

Programmatic CLI Access

from beets.ui import main

# Run beets CLI programmatically
main(['import', '/path/to/music'])
main(['list', 'artist:Beatles'])
main(['stats'])

Architecture

Beets is built around several core architectural components:

  • Library: Central database interface managing Items and Albums with SQLite backend
  • Item/Album Models: Database models representing individual tracks and album collections
  • Query System: Flexible query language for filtering and searching library content
  • Import System: Automated music import with metadata matching and user interaction
  • Autotag System: Metadata source integration (MusicBrainz, Discogs, etc.) with matching algorithms
  • Plugin System: Extensible architecture with 78+ plugins for additional functionality
  • Template System: Customizable path formatting and field templating
  • UI System: Command-line interface with user interaction utilities

This modular design enables both CLI-based music management workflows and programmatic library access for custom applications.

Capabilities

Library Management

Core database operations for managing music collections including item and album CRUD operations, query execution, and metadata management.

class Library:
    def __init__(self, path: str, directory: str, path_formats=None, replacements=None): ...
    def items(self, query: str = None) -> Results: ...
    def albums(self, query: str = None) -> Results: ...
    def add(self, obj: Union[Item, Album]) -> None: ...
    def get_item(self, id: int) -> Item: ...
    def get_album(self, id: int) -> Album: ...

class Item:
    @classmethod
    def from_path(cls, path: str) -> 'Item': ...
    def store(self) -> None: ...
    def load(self) -> None: ...
    def write(self) -> None: ...
    def move(self, library: Library, operation: str, basedir: str = None) -> None: ...

class Album:
    def items(self) -> Results: ...
    def store(self) -> None: ...
    def remove(self, delete_items: bool = False) -> None: ...

Library Management

Query System

Sophisticated query language and parsing system for filtering library content with support for field matching, regular expressions, numeric comparisons, and boolean logic.

def query_from_strings(strings: List[str], model_cls: Type) -> Query: ...
def parse_sorted_query(query_string: str, model_cls: Type) -> Tuple[Query, Sort]: ...

class StringQuery(FieldQuery):
    def __init__(self, field: str, pattern: str, fast: bool = True): ...

class NumericQuery(FieldQuery):
    def __init__(self, field: str, point: float, interval: float = 0): ...

class RegexpQuery(FieldQuery):
    def __init__(self, field: str, pattern: str): ...

Query System

Import and Autotag System

Automated music import with metadata matching, user interaction for ambiguous matches, and integration with multiple metadata sources for comprehensive tagging.

class ImportSession:
    def __init__(self, lib: Library, loghandler: logging.Handler = None, config: dict = None): ...
    def run(self) -> None: ...
    def choose_match(self, task: ImportTask) -> action: ...

def tag_album(items: List[Item], search_artist: str = None, search_album: str = None) -> Tuple[List[AlbumInfo], List[TrackInfo]]: ...
def tag_item(item: Item, search_artist: str = None, search_title: str = None) -> Tuple[List[TrackInfo], Distance]: ...

class AlbumInfo:
    album: str
    artist: str
    tracks: List[TrackInfo]
    year: int
    # ... additional metadata fields

Import and Autotag

Plugin System

Extensible plugin architecture with base classes, event system, and plugin management for extending beets functionality through custom commands, metadata sources, and processing hooks.

class BeetsPlugin:
    def __init__(self, name: str): ...
    def commands(self) -> List[Subcommand]: ...
    def template_funcs(self) -> Dict[str, Callable]: ...
    def item_types(self) -> Dict[str, Type]: ...
    def album_types(self) -> Dict[str, Type]: ...

def load_plugins(names: List[str]) -> None: ...
def send(event: str, **kwargs) -> None: ...

class MetadataSourcePlugin(BeetsPlugin):
    def get_albums(self, query: str) -> Iterator[AlbumInfo]: ...
    def get_tracks(self, query: str) -> Iterator[TrackInfo]: ...

Plugin System

User Interface and CLI

Command-line interface utilities, user interaction functions, output formatting, and command infrastructure for building interactive music management tools.

def main(args: List[str] = None) -> None: ...
def input_(prompt: str = None) -> str: ...
def input_options(options: List[str], require: bool = False, prompt: str = None) -> str: ...
def input_yn(prompt: str, require: bool = False) -> bool: ...
def print_(*strings: List[str], **kwargs) -> None: ...
def colorize(color_name: str, text: str) -> str: ...

class Subcommand:
    def __init__(self, name: str, parser: OptionParser = None, help: str = ""): ...
    def func(self, lib: Library, opts: optparse.Values, args: List[str]) -> None: ...

class UserError(Exception): ...

User Interface

Utilities and Templates

File operations, path manipulation, template formatting, and various utility functions for safe file handling and flexible path generation.

def normpath(path: str) -> bytes: ...
def syspath(path: Union[str, bytes]) -> str: ...
def move(src: str, dest: str) -> None: ...
def copy(src: str, dest: str) -> None: ...
def samefile(p1: str, p2: str) -> bool: ...

class Template:
    def __init__(self, template_string: str): ...
    def substitute(self, values: Dict[str, Any], functions: Dict[str, Callable] = None) -> str: ...

def template(template_string: str) -> Template: ...

Utilities and Templates

Configuration System

Global configuration management with YAML-based settings, environment variable support, and plugin configuration integration.

config: IncludeLazyConfig  # Global configuration object

class IncludeLazyConfig:
    def read(self, user: bool = True, defaults: bool = True) -> None: ...
    def set_file(self, filename: str) -> None: ...
    def set_args(self, args: argparse.Namespace) -> None: ...
    def __getitem__(self, key: str) -> ConfigView: ...

class ConfigView:
    def get(self, typ: Type = None) -> Any: ...
    def as_str(self) -> str: ...
    def as_filename(self) -> str: ...

Configuration

Plugin Ecosystem

Beets includes 78+ plugins providing extended functionality:

Metadata Sources

  • fetchart: Album art fetching from online sources
  • lyrics: Lyrics fetching and management
  • discogs: Discogs metadata integration
  • spotify: Spotify metadata integration
  • lastgenre: Genre tagging via Last.fm

Audio Processing

  • replaygain: ReplayGain audio normalization
  • convert: Audio format conversion
  • chroma: Chromaprint acoustic fingerprinting
  • bpm: BPM detection

File Management

  • duplicates: Duplicate detection and removal
  • missing: Find missing files
  • badfiles: Validate audio file integrity

External Integration

  • web: Web interface for library browsing
  • mpdupdate: MPD database synchronization
  • plexupdate: Plex library updates

See individual plugin documentation for detailed API and configuration options.