0
# Beets
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: beets
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install beets`
10
- **Version**: 2.3.1
11

12
## Core Imports
13

14
```python
15
import beets
16
from beets.library import Library, Item, Album
17
from beets import config
18
from beets.ui import main
19
```
20

21
For autotag and import functionality:
22

23
```python
24
from beets.autotag import AlbumInfo, TrackInfo, Distance
25
from beets.importer import ImportSession
26
```
27

28
For plugin development:
29

30
```python
31
from beets.plugins import BeetsPlugin
32
from beets.ui import Subcommand
33
```
34

35
## Basic Usage
36

37
### Library Management
38

39
```python
40
from beets.library import Library, Item, Album
41

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

45
# Query for items (tracks)
46
all_items = lib.items()
47
beatles_items = lib.items('artist:Beatles')
48
recent_items = lib.items('added:2024..')
49

50
# Query for albums
51
all_albums = lib.albums()
52
rock_albums = lib.albums('genre:Rock')
53

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

58
# Access item metadata
59
for item in lib.items('artist:Beatles'):
60
    print(f"{item.artist} - {item.title} ({item.year})")
61
    print(f"Path: {item.path}")
62
    print(f"Duration: {item.length} seconds")
63
```
64

65
### Command-Line Usage
66

67
```bash
68
# Import music into library
69
beet import /path/to/music/directory
70

71
# Search and list items
72
beet list artist:Beatles
73
beet list year:1960..1970 genre:Rock
74

75
# Update metadata from sources
76
beet update artist:Beatles
77

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

81
# Show library statistics
82
beet stats
83
```
84

85
### Programmatic CLI Access
86

87
```python
88
from beets.ui import main
89

90
# Run beets CLI programmatically
91
main(['import', '/path/to/music'])
92
main(['list', 'artist:Beatles'])
93
main(['stats'])
94
```
95

96
## Architecture
97

98
Beets is built around several core architectural components:
99

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

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

111
## Capabilities
112

113
### Library Management
114

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

117
```python { .api }
118
class Library:
119
    def __init__(self, path: str, directory: str, path_formats=None, replacements=None): ...
120
    def items(self, query: str = None) -> Results: ...
121
    def albums(self, query: str = None) -> Results: ...
122
    def add(self, obj: Union[Item, Album]) -> None: ...
123
    def get_item(self, id: int) -> Item: ...
124
    def get_album(self, id: int) -> Album: ...
125

126
class Item:
127
    @classmethod
128
    def from_path(cls, path: str) -> 'Item': ...
129
    def store(self) -> None: ...
130
    def load(self) -> None: ...
131
    def write(self) -> None: ...
132
    def move(self, library: Library, operation: str, basedir: str = None) -> None: ...
133

134
class Album:
135
    def items(self) -> Results: ...
136
    def store(self) -> None: ...
137
    def remove(self, delete_items: bool = False) -> None: ...
138
```
139

140
[Library Management](./library-management.md)
141

142
### Query System
143

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

146
```python { .api }
147
def query_from_strings(strings: List[str], model_cls: Type) -> Query: ...
148
def parse_sorted_query(query_string: str, model_cls: Type) -> Tuple[Query, Sort]: ...
149

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

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

156
class RegexpQuery(FieldQuery):
157
    def __init__(self, field: str, pattern: str): ...
158
```
159

160
[Query System](./query-system.md)
161

162
### Import and Autotag System
163

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

166
```python { .api }
167
class ImportSession:
168
    def __init__(self, lib: Library, loghandler: logging.Handler = None, config: dict = None): ...
169
    def run(self) -> None: ...
170
    def choose_match(self, task: ImportTask) -> action: ...
171

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

175
class AlbumInfo:
176
    album: str
177
    artist: str
178
    tracks: List[TrackInfo]
179
    year: int
180
    # ... additional metadata fields
181
```
182

183
[Import and Autotag](./import-autotag.md)
184

185
### Plugin System
186

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

189
```python { .api }
190
class BeetsPlugin:
191
    def __init__(self, name: str): ...
192
    def commands(self) -> List[Subcommand]: ...
193
    def template_funcs(self) -> Dict[str, Callable]: ...
194
    def item_types(self) -> Dict[str, Type]: ...
195
    def album_types(self) -> Dict[str, Type]: ...
196

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

200
class MetadataSourcePlugin(BeetsPlugin):
201
    def get_albums(self, query: str) -> Iterator[AlbumInfo]: ...
202
    def get_tracks(self, query: str) -> Iterator[TrackInfo]: ...
203
```
204

205
[Plugin System](./plugin-system.md)
206

207
### User Interface and CLI
208

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

211
```python { .api }
212
def main(args: List[str] = None) -> None: ...
213
def input_(prompt: str = None) -> str: ...
214
def input_options(options: List[str], require: bool = False, prompt: str = None) -> str: ...
215
def input_yn(prompt: str, require: bool = False) -> bool: ...
216
def print_(*strings: List[str], **kwargs) -> None: ...
217
def colorize(color_name: str, text: str) -> str: ...
218

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

223
class UserError(Exception): ...
224
```
225

226
[User Interface](./user-interface.md)
227

228
### Utilities and Templates
229

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

232
```python { .api }
233
def normpath(path: str) -> bytes: ...
234
def syspath(path: Union[str, bytes]) -> str: ...
235
def move(src: str, dest: str) -> None: ...
236
def copy(src: str, dest: str) -> None: ...
237
def samefile(p1: str, p2: str) -> bool: ...
238

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

243
def template(template_string: str) -> Template: ...
244
```
245

246
[Utilities and Templates](./utilities-templates.md)
247

248
### Configuration System
249

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

252
```python { .api }
253
config: IncludeLazyConfig  # Global configuration object
254

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

261
class ConfigView:
262
    def get(self, typ: Type = None) -> Any: ...
263
    def as_str(self) -> str: ...
264
    def as_filename(self) -> str: ...
265
```
266

267
[Configuration](./configuration.md)
268

269
## Plugin Ecosystem
270

271
Beets includes 78+ plugins providing extended functionality:
272

273
### Metadata Sources
274
- **fetchart**: Album art fetching from online sources
275
- **lyrics**: Lyrics fetching and management
276
- **discogs**: Discogs metadata integration
277
- **spotify**: Spotify metadata integration
278
- **lastgenre**: Genre tagging via Last.fm
279

280
### Audio Processing
281
- **replaygain**: ReplayGain audio normalization
282
- **convert**: Audio format conversion
283
- **chroma**: Chromaprint acoustic fingerprinting
284
- **bpm**: BPM detection
285

286
### File Management
287
- **duplicates**: Duplicate detection and removal
288
- **missing**: Find missing files
289
- **badfiles**: Validate audio file integrity
290

291
### External Integration
292
- **web**: Web interface for library browsing
293
- **mpdupdate**: MPD database synchronization
294
- **plexupdate**: Plex library updates
295

296
See individual plugin documentation for detailed API and configuration options.