# beetbox/beets architecture

> Architecture diagram of the GitHub repository beetbox/beets, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beetbox/beets
- Repository: https://github.com/beetbox/beets

## Overview

Beets is a music library manager and metadata organizer. The principal workflow is: a user invokes an import command, files become import tasks, autotagging proposes metadata, the user accepts or adjusts the result, and tagged files plus catalog records are stored. The catalog then supports querying and management commands. Plugins extend enrichment, analysis, artwork, transcoding, web access, and playback. Some plugin wiring is inferred from documented capabilities and filenames; sampled excerpts primarily confirm importing, querying, pipeline execution, and integrations.

Main entry points: [`beets/library/library.py`](https://github.com/beetbox/beets/blob/master/beets/library/library.py) (Library Service), [`beets/importer/session.py`](https://github.com/beetbox/beets/blob/master/beets/importer/session.py) (Import Session), [`beets/importer/tasks.py`](https://github.com/beetbox/beets/blob/master/beets/importer/tasks.py) (Import Tasks), [`beets/importer/stages.py`](https://github.com/beetbox/beets/blob/master/beets/importer/stages.py) (Import Stages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_cli["CLI Commands<br/>[__init__.py]"]
  node_import_ui["Import Prompts<br/>[session.py]"]
end

subgraph group_import["Import Workflow"]
  node_import_session["Import Session<br/>[session.py]"]
  node_import_stages["Import Stages<br/>[stages.py]"]
  node_import_tasks["Import Tasks<br/>[tasks.py]"]
  node_pipeline["Pipeline Engine<br/>[pipeline.py]"]
  node_autotag["Autotag Matching<br/>[match.py]"]
end

subgraph group_catalog["Library Catalog"]
  node_mediafile["Media File Tags<br/>[mediafile.py]"]
  node_models["Library Models<br/>[models.py]"]
  node_library["Library Service<br/>[library.py]"]
  node_query_parser["Query Parser<br/>[queryparse.py]"]
  node_query_engine["Query Engine<br/>[query.py]"]
  node_library_db[("SQLite Library<br/>[db.py]")]
end

subgraph group_plugins["Plugin Features"]
  node_plugin_system["Plugin System<br/>[plugins.py]"]
  node_metadata_plugins["Metadata Plugins"]
  node_art_lyrics["Art And Lyrics<br/>[fetchart.py]"]
  node_replaygain["ReplayGain Analysis<br/>[replaygain.py]"]
  node_transcoding["Audio Transcoding<br/>[convert.py]"]
  node_library_checks["Library Checks<br/>[duplicates.py]"]
  node_web["Web Browser<br/>[__init__.py]"]
  node_playback["MPD Playback<br/>[play.py]"]
end

subgraph group_integrations["External Integrations"]
  node_metadata_sources["Metadata Sources<br/>[source.py]"]
end

node_user(("Music User"))
node_musicbrainz["MusicBrainz"]
node_discogs["Discogs"]
node_lastfm["Last.fm"]
node_music_files["Music Files"]

node_user -->|"invokes"| node_cli
node_cli -->|"starts import"| node_import_session
node_import_ui -->|"chooses action"| node_import_stages
node_import_session -->|"builds stages"| node_import_stages
node_import_session -->|"runs pipeline"| node_pipeline
node_import_stages -->|"creates tasks"| node_import_tasks
node_import_tasks -->|"reads files"| node_music_files
node_import_stages -->|"requests matches"| node_autotag
node_autotag -->|"queries sources"| node_metadata_sources
node_metadata_sources -.->|"looks up metadata"| node_musicbrainz
node_metadata_sources -.->|"looks up metadata"| node_discogs
node_import_ui -->|"reviews matches"| node_autotag
node_import_tasks -->|"updates tags"| node_mediafile
node_import_tasks -->|"stores items"| node_models
node_models -->|"manages records"| node_library
node_library -->|"reads and writes"| node_library_db
node_cli -->|"parses queries"| node_query_parser
node_query_parser -->|"builds queries"| node_query_engine
node_query_engine -->|"filters records"| node_library
node_query_engine -->|"reads catalog"| node_library_db
node_import_session -->|"dispatches events"| node_plugin_system
node_plugin_system -->|"loads extensions"| node_metadata_plugins
node_metadata_plugins -.->|"fetches genres"| node_lastfm
node_metadata_plugins -->|"enriches files"| node_art_lyrics
node_replaygain -->|"analyzes audio"| node_music_files
node_transcoding -->|"transcodes audio"| node_music_files
node_library_checks -->|"checks records"| node_library
node_web -->|"browses catalog"| node_library
node_playback -->|"plays audio"| node_music_files

click node_cli "https://github.com/beetbox/beets/blob/master/beets/ui/commands/__init__.py"
click node_import_ui "https://github.com/beetbox/beets/blob/master/beets/ui/commands/import_/session.py"
click node_import_session "https://github.com/beetbox/beets/blob/master/beets/importer/session.py"
click node_import_stages "https://github.com/beetbox/beets/blob/master/beets/importer/stages.py"
click node_import_tasks "https://github.com/beetbox/beets/blob/master/beets/importer/tasks.py"
click node_pipeline "https://github.com/beetbox/beets/blob/master/beets/util/pipeline.py"
click node_autotag "https://github.com/beetbox/beets/blob/master/beets/autotag/match.py"
click node_metadata_sources "https://github.com/beetbox/beets/blob/master/beets/autotag/source.py"
click node_mediafile "https://github.com/beetbox/beets/blob/master/beets/mediafile.py"
click node_models "https://github.com/beetbox/beets/blob/master/beets/library/models.py"
click node_library "https://github.com/beetbox/beets/blob/master/beets/library/library.py"
click node_query_parser "https://github.com/beetbox/beets/blob/master/beets/dbcore/queryparse.py"
click node_query_engine "https://github.com/beetbox/beets/blob/master/beets/dbcore/query.py"
click node_library_db "https://github.com/beetbox/beets/blob/master/beets/dbcore/db.py"
click node_plugin_system "https://github.com/beetbox/beets/blob/master/beets/plugins.py"
click node_metadata_plugins "https://github.com/beetbox/beets/blob/master/beets/metadata_plugins.py"
click node_art_lyrics "https://github.com/beetbox/beets/blob/master/beetsplug/fetchart.py"
click node_replaygain "https://github.com/beetbox/beets/blob/master/beetsplug/replaygain.py"
click node_transcoding "https://github.com/beetbox/beets/blob/master/beetsplug/convert.py"
click node_library_checks "https://github.com/beetbox/beets/blob/master/beetsplug/duplicates.py"
click node_web "https://github.com/beetbox/beets/blob/master/beetsplug/web/__init__.py"
click node_playback "https://github.com/beetbox/beets/blob/master/beetsplug/play.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_import_ui,node_user toneBlue
class node_import_session,node_import_stages,node_import_tasks,node_pipeline,node_autotag toneAmber
class node_mediafile,node_models,node_library,node_query_parser,node_query_engine,node_library_db toneMint
class node_plugin_system,node_metadata_plugins,node_art_lyrics,node_replaygain,node_transcoding,node_library_checks,node_web,node_playback toneRose
class node_metadata_sources,node_musicbrainz,node_discogs,node_lastfm,node_music_files toneIndigo
```

## Components

### User Interface

- [CLI Commands](https://github.com/beetbox/beets/blob/master/beets/ui/commands/__init__.py): `beets/ui/commands/__init__.py`
- [Import Prompts](https://github.com/beetbox/beets/blob/master/beets/ui/commands/import_/session.py): `beets/ui/commands/import_/session.py`

### Import Workflow

- [Import Session](https://github.com/beetbox/beets/blob/master/beets/importer/session.py): `beets/importer/session.py`
- [Import Stages](https://github.com/beetbox/beets/blob/master/beets/importer/stages.py): `beets/importer/stages.py`
- [Import Tasks](https://github.com/beetbox/beets/blob/master/beets/importer/tasks.py): `beets/importer/tasks.py`
- [Pipeline Engine](https://github.com/beetbox/beets/blob/master/beets/util/pipeline.py): `beets/util/pipeline.py`
- [Autotag Matching](https://github.com/beetbox/beets/blob/master/beets/autotag/match.py): `beets/autotag/match.py`

### Library Catalog

- [Media File Tags](https://github.com/beetbox/beets/blob/master/beets/mediafile.py): `beets/mediafile.py`
- [Library Models](https://github.com/beetbox/beets/blob/master/beets/library/models.py): `beets/library/models.py`
- [Library Service](https://github.com/beetbox/beets/blob/master/beets/library/library.py): `beets/library/library.py`
- [Query Parser](https://github.com/beetbox/beets/blob/master/beets/dbcore/queryparse.py): `beets/dbcore/queryparse.py`
- [Query Engine](https://github.com/beetbox/beets/blob/master/beets/dbcore/query.py): `beets/dbcore/query.py`
- [SQLite Library](https://github.com/beetbox/beets/blob/master/beets/dbcore/db.py): `beets/dbcore/db.py`

### Plugin Features

- [Plugin System](https://github.com/beetbox/beets/blob/master/beets/plugins.py): `beets/plugins.py`
- [Metadata Plugins](https://github.com/beetbox/beets/blob/master/beets/metadata_plugins.py): `beets/metadata_plugins.py`
- [Art And Lyrics](https://github.com/beetbox/beets/blob/master/beetsplug/fetchart.py): `beetsplug/fetchart.py`
- [ReplayGain Analysis](https://github.com/beetbox/beets/blob/master/beetsplug/replaygain.py): `beetsplug/replaygain.py`
- [Audio Transcoding](https://github.com/beetbox/beets/blob/master/beetsplug/convert.py): `beetsplug/convert.py`
- [Library Checks](https://github.com/beetbox/beets/blob/master/beetsplug/duplicates.py): `beetsplug/duplicates.py`
- [Web Browser](https://github.com/beetbox/beets/blob/master/beetsplug/web/__init__.py): `beetsplug/web/__init__.py`
- [MPD Playback](https://github.com/beetbox/beets/blob/master/beetsplug/play.py): `beetsplug/play.py`

### External Integrations

- [Metadata Sources](https://github.com/beetbox/beets/blob/master/beets/autotag/source.py): `beets/autotag/source.py`

### Other components

- **Music User**
- **MusicBrainz**
- **Discogs**
- **Last.fm**
- **Music Files**

## Connections

- Music User → CLI Commands: invokes
- CLI Commands → Import Session: starts import
- Import Prompts → Import Stages: chooses action
- Import Session → Import Stages: builds stages
- Import Session → Pipeline Engine: runs pipeline
- Import Stages → Import Tasks: creates tasks
- Import Tasks → Music Files: reads files
- Import Stages → Autotag Matching: requests matches
- Autotag Matching → Metadata Sources: queries sources
- Metadata Sources → MusicBrainz: looks up metadata
- Metadata Sources → Discogs: looks up metadata
- Import Prompts → Autotag Matching: reviews matches
- Import Tasks → Media File Tags: updates tags
- Import Tasks → Library Models: stores items
- Library Models → Library Service: manages records
- Library Service → SQLite Library: reads and writes
- CLI Commands → Query Parser: parses queries
- Query Parser → Query Engine: builds queries
- Query Engine → Library Service: filters records
- Query Engine → SQLite Library: reads catalog
- Import Session → Plugin System: dispatches events
- Plugin System → Metadata Plugins: loads extensions
- Metadata Plugins → Last.fm: fetches genres
- Metadata Plugins → Art And Lyrics: enriches files
- ReplayGain Analysis → Music Files: analyzes audio
- Audio Transcoding → Music Files: transcodes audio
- Library Checks → Library Service: checks records
- Web Browser → Library Service: browses catalog
- MPD Playback → Music Files: plays audio
