🎵 Beets Music Library Management Cheat Sheet

🎵 Beets Music Library Management Cheat Sheet #

📖 Overview #

Beets is the media library management system for obsessive music geeks. It catalogs your music collection, automatically improving metadata using the MusicBrainz database, and provides powerful tools for manipulating and accessing your music.

🚀 Installation #

Basic Installation # 

pip install beets

With Additional Dependencies # 

# For audio analysis and ReplayGain
pip install beets[replaygain]

# For web interface
pip install beets[web]

# Full installation with most plugins
pip install beets[fetchart,lyrics,lastgenre,replaygain,web,chroma]

⚙️ Configuration #

Configuration File Location #

  • Linux/macOS: ~/.config/beets/config.yaml
  • Windows: %APPDATA%\beets\config.yaml
  • Custom location: Set BEETSDIR environment variable

Basic Configuration Example # 

directory: ~/Music
library: ~/.config/beets/musiclibrary.db

plugins: fetchart lyrics lastgenre replaygain duplicates

import:
    move: yes
    write: yes
    autotag: yes
    
paths:
    default: $albumartist/$album%aunique{}/$track $title
    singleton: Non-Album/$artist - $title
    comp: Compilations/$album%aunique{}/$track $title

fetchart:
    auto: yes
    
lyrics:
    auto: yes
    
lastgenre:
    auto: yes
    
replaygain:
    auto: yes

🎯 Core Commands #

Import Music # 

# Import and organize music files
beet import /path/to/music

# Import without moving files
beet import -C /path/to/music

# Import as singletons (no album grouping)
beet import -s /path/to/music

# Quiet import (minimal prompts)
beet import -q /path/to/music

# Resume interrupted import
beet import -r /path/to/music

# List all items
beet list

# List albums
beet list -a

# Search by artist
beet list artist:radiohead

# Search by year range
beet list year:2000..2010

# Search by genre
beet list genre:rock

# Complex queries
beet list artist:radiohead album:ok year:1997

# Show file paths
beet list -p artist:radiohead

# Show detailed info
beet list -f '$artist - $album - $title [$format, $bitrate]'

Modify Metadata # 

# Modify single field
beet modify artist:oldname artist=newname

# Modify multiple fields
beet modify album:"OK Computer" year=1997 genre=rock

# Modify albums
beet modify -a album:"OK Computer" albumartist="Radiohead"

# Write changes to files
beet modify -w artist:radiohead genre=rock

Remove Items # 

# Remove from library (keep files)
beet remove artist:badband

# Remove from library and delete files
beet remove -d artist:badband

# Remove albums
beet remove -a album:"Bad Album"

Move and Update # 

# Move files to match current path format
beet move artist:radiohead

# Update metadata from MusicBrainz
beet update artist:radiohead

# Write library metadata to files
beet write artist:radiohead

Statistics # 

# Show library statistics
beet stats

# Show statistics for specific query
beet stats artist:radiohead

🔌 Essential Plugins #

FetchArt Plugin #

Automatically downloads album artwork

fetchart:
    auto: yes
    sources: filesystem coverart itunes amazon albumart
    minwidth: 300
    maxwidth: 1000
    quality: 0
    max_filesize: 0

# Manually fetch art
beet fetchart artist:radiohead

# Fetch art for all albums
beet fetchart -a

Lyrics Plugin #

Fetches song lyrics from various sources

lyrics:
    auto: yes
    sources: genius lyricwiki musixmatch
    fallback: ''

# Manually fetch lyrics
beet lyrics artist:radiohead

# Force re-fetch lyrics
beet lyrics -f artist:radiohead

LastGenre Plugin #

Assigns genres using Last.fm data

lastgenre:
    auto: yes
    source: album
    force: yes
    min_weight: 10
    count: 3
    separator: ', '

# Manually assign genres
beet lastgenre artist:radiohead

# Force genre update
beet lastgenre -f artist:radiohead

ReplayGain Plugin #

Calculates ReplayGain values for volume normalization

replaygain:
    auto: yes
    backend: gstreamer  # or 'command' or 'audiotools'
    overwrite: no
    albumgain: yes

# Calculate ReplayGain
beet replaygain artist:radiohead

# Calculate for albums
beet replaygain -a artist:radiohead

Duplicates Plugin #

Finds duplicate tracks in your library

# Find duplicate tracks
beet duplicates

# Find duplicate albums
beet duplicates -a

# Show checksums
beet duplicates -c

# Delete duplicates (interactive)
beet duplicates -d

Web Plugin #

Provides a web interface for browsing your library

web:
    host: 0.0.0.0
    port: 8337
    cors: ''
    cors_supports_credentials: no
    reverse_proxy: no

# Start web server
beet web

# Start on specific port
beet web -p 8080

🎨 Path Formats #

Template Variables #

  • $artist, $albumartist - Artist names
  • $album - Album title
  • $title - Track title
  • $track, $tracktotal - Track numbers
  • $disc, $disctotal - Disc numbers
  • $year, $month, $day - Date information
  • $genre - Genre
  • $format - File format (MP3, FLAC, etc.)
  • $bitrate - Bitrate

Path Format Examples # 

paths:
    # Standard format
    default: $albumartist/$album%aunique{}/$track $title
    
    # By genre
    genre:classical: Classical/$composer/$album/$track $title
    genre:soundtrack: Soundtracks/$album/$track $title
    
    # Compilations
    comp: Compilations/$album%aunique{}/$track $title
    
    # Singles
    singleton: Singles/$artist - $title
    
    # By year
    default: $albumartist/[$year] $album%aunique{}/$track $title

🔍 Query Syntax #

Basic Queries # 

# Field matching
artist:radiohead
album:"ok computer"
year:1997

# Ranges
year:1990..2000
track:1..5

# Regular expressions
artist::/radio.*/

# Negation
^artist:nickelback

# Boolean operators
artist:radiohead album:kid

Advanced Queries # 

# Multiple conditions
artist:radiohead year:1990..2010

# Path queries
path:/music/rock/

# Numeric comparisons
bitrate:320..
length:..180  # songs under 3 minutes

# Missing fields
^genre:
albumartist:""

🛠️ Best Practices #

Library Organization #

  1. Use consistent path formats - Define clear naming conventions
  2. Enable auto-tagging - Let beets handle metadata automatically
  3. Regular maintenance - Run beet update periodically
  4. Backup your library - Keep backups of your library.db file

Import Workflow #

  1. Test with small batches first
  2. Use -C flag to test without moving files
  3. Review matches carefully during import
  4. Enable logging for troubleshooting

Performance Tips #

  1. Use SSD storage for library database
  2. Enable threading in configuration
  3. Limit concurrent imports for stability
  4. Use incremental imports for large collections

Plugin Management # 

# Essential plugins for most users
plugins: fetchart lyrics lastgenre replaygain duplicates info

# Power user plugins
plugins: fetchart lyrics lastgenre replaygain duplicates info 
         chroma acousticbrainz web smartplaylist convert

🔧 Troubleshooting #

Common Issues # 

# Fix permissions
chmod -R 755 ~/Music
chown -R $USER:$USER ~/.config/beets/

# Rebuild library database
beet import -L /path/to/library.db /path/to/music

# Check configuration
beet config

# Verbose output for debugging
beet -v import /path/to/music

Database Maintenance # 

# Check database integrity
sqlite3 ~/.config/beets/musiclibrary.db "PRAGMA integrity_check;"

# Vacuum database
sqlite3 ~/.config/beets/musiclibrary.db "VACUUM;"

# Export library
beet export > library_backup.json

📚 Useful Commands Reference #

Information Commands # 

beet fields          # List available fields
beet config           # Show current configuration
beet version          # Show version info
beet help <command>   # Get help for specific command

Batch Operations # 

# Update all metadata
beet update

# Write all changes to files
beet write

# Move all files to match paths
beet move

# Re-import with current settings
beet import -L library.db /music/path

Plugin-Specific Commands # 

beet mbsync           # Sync with MusicBrainz
beet acousticbrainz   # Fetch acoustic analysis
beet chroma           # Generate acoustic fingerprints
beet convert          # Convert audio formats
beet smartplaylist    # Generate smart playlists

🎵 Advanced Configuration #

Multiple Libraries # 

# In config.yaml
library: ~/.config/beets/main.db
directory: ~/Music/Main

# Use with -l flag
# beet -l ~/.config/beets/classical.db import /classical/music

Custom Fields # 

item_fields:
    mood: text
    energy: int
    
album_fields:
    purchase_date: date

Hooks and Events # 

# Run commands on import
import:
    post_import_hook: echo "Imported: $album"

This cheat sheet covers the essential aspects of beets for efficient music library management. Start with basic import and configuration, then gradually add plugins and advanced features as needed.