1BEET(1) beets BEET(1)
2
6 beet - music tagger and library organizer
7
9 beet [args...] command [args...]
10 beet help command
11
14 import
15 beet import [-CWAPRqst] [-l LOGPATH] PATH...
16 beet import [options] -L QUERY
17 Add music to your library, attempting to get correct tags for it from
19 MusicBrainz.
20 Point the command at some music: directories, single files, or com‐
22 pressed archives. The music will be copied to a configurable directory
23 structure and added to a library database. The command is interactive
24 and will try to get you to verify MusicBrainz tags that it thinks are
25 suspect. See the autotagging guide for detail on how to use the inter‐
26 active tag-correction flow.
27 Directories passed to the import command can contain either a single
29 album or many, in which case the leaf directories will be considered
30 albums (the latter case is true of typical Artist/Album organizations
31 and many people's "downloads" folders). The path can also be a single
32 song or an archive. Beets supports zip and tar archives out of the box.
33 To extract rar files, install the rarfile package and the unrar com‐
34 mand. To extract 7z files, install the py7zr package.
35 Optional command flags:
37 • By default, the command copies files to your library directory and
39 updates the ID3 tags on your music. In order to move the files, in‐
40 stead of copying, use the -m (move) option. If you'd like to leave
41 your music files untouched, try the -C (don't copy) and -W (don't
42 write tags) options. You can also disable this behavior by default in
43 the configuration file (below).
44 • Also, you can disable the autotagging behavior entirely using -A
46 (don't autotag)---then your music will be imported with its existing
47 metadata.
48 • During a long tagging import, it can be useful to keep track of al‐
50 bums that weren't tagged successfully---either because they're not in
51 the MusicBrainz database or because something's wrong with the files.
52 Use the -l option to specify a filename to log every time you skip an
53 album or import it "as-is" or an album gets skipped as a duplicate.
54 • Relatedly, the -q (quiet) option can help with large imports by auto‐
56 tagging without ever bothering to ask for user input. Whenever the
57 normal autotagger mode would ask for confirmation, the quiet mode
58 pessimistically skips the album. The quiet mode also disables the
59 tagger's ability to resume interrupted imports.
60 • Speaking of resuming interrupted imports, the tagger will prompt you
62 if it seems like the last import of the directory was interrupted (by
63 you or by a crash). If you want to skip this prompt, you can say
64 "yes" automatically by providing -p or "no" using -P. The resuming
65 feature can be disabled by default using a configuration option (see
66 below).
67 • If you want to import only the new stuff from a directory, use the -i
69 option to run an incremental import. With this flag, beets will keep
70 track of every directory it ever imports and avoid importing them
71 again. This is useful if you have an "incoming" directory that you
72 periodically add things to. To get this to work correctly, you'll
73 need to use an incremental import every time you run an import on the
74 directory in question---including the first time, when no subdirecto‐
75 ries will be skipped. So consider enabling the incremental configura‐
76 tion option.
77 • When beets applies metadata to your music, it will retain the value
79 of any existing tags that weren't overwritten, and import them into
80 the database. You may prefer to only use existing metadata for find‐
81 ing matches, and to erase it completely when new metadata is applied.
82 You can enforce this behavior with the --from-scratch option, or the
83 from_scratch configuration option.
84 • By default, beets will proceed without asking if it finds a very
86 close metadata match. To disable this and have the importer ask you
87 every time, use the -t (for timid) option.
88 • The importer typically works in a whole-album-at-a-time mode. If you
90 instead want to import individual, non-album tracks, use the single‐
91 ton mode by supplying the -s option.
92 • If you have an album that's split across several directories under a
94 common top directory, use the --flat option. This takes all the music
95 files under the directory (recursively) and treats them as a single
96 large album instead of as one album per directory. This can help with
97 your more stubborn multi-disc albums.
98 • Similarly, if you have one directory that contains multiple albums,
100 use the --group-albums option to split the files based on their meta‐
101 data before matching them as separate albums.
102 • If you want to preview which files would be imported, use the --pre‐
104 tend option. If set, beets will just print a list of files that it
105 would otherwise import.
106 • If you already have a metadata backend ID that matches the items to
108 be imported, you can instruct beets to restrict the search to that ID
109 instead of searching for other candidates by using the --search-id
110 SEARCH_ID option. Multiple IDs can be specified by simply repeating
111 the option several times.
112 • You can supply --set field=value to assign field to value on import.
114 These assignments will merge with (and possibly override) the
115 set_fields configuration dictionary. You can use the option multiple
116 times on the command line, like so:
117 beet import --set genre="Alternative Rock" --set mood="emotional"
119 list
121 beet list [-apf] QUERY
122 Queries the database for music.
124 Want to search for "Gronlandic Edit" by of Montreal? Try beet list
126 gronlandic. Maybe you want to see everything released in 2009 with
127 "vegetables" in the title? Try beet list year:2009 title:vegetables.
128 You can also specify the sort order. (Read more in Queries.)
129 You can use the -a switch to search for albums instead of individual
131 items. In this case, the queries you use are restricted to album-level
132 fields: for example, you can search for year:1969 but query parts for
133 item-level fields like title:foo will be ignored. Remember that artist
134 is an item-level field; albumartist is the corresponding album field.
135 The -p option makes beets print out filenames of matched items, which
137 might be useful for piping into other Unix commands (such as xargs).
138 Similarly, the -f option lets you specify a specific format with which
139 to print every album or track. This uses the same template syntax as
140 beets' path formats. For example, the command beet ls -af '$album: $al‐
141 bumtotal' beatles prints out the number of tracks on each Beatles al‐
142 bum. In Unix shells, remember to enclose the template argument in sin‐
143 gle quotes to avoid environment variable expansion.
144 remove
146 beet remove [-adf] QUERY
147 Remove music from your library.
149 This command uses the same query syntax as the list command. By de‐
151 fault, it just removes entries from the library database; it doesn't
152 touch the files on disk. To actually delete the files, use the -d flag.
153 When the -a flag is given, the command operates on albums instead of
154 individual tracks.
155 When you run the remove command, it prints a list of all affected items
157 in the library and asks for your permission before removing them. You
158 can then choose to abort (type n), confirm (y), or interactively choose
159 some of the items (s). In the latter case, the command will prompt you
160 for every matching item or album and invite you to type y to remove the
161 item/album, n to keep it or q to exit and only remove the items/albums
162 selected up to this point. This option lets you choose precisely which
163 tracks/albums to remove without spending too much time to carefully
164 craft a query. If you do not want to be prompted at all, use the -f
165 option.
166 modify
168 beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...]
169 Change the metadata for items or albums in the database.
171 Supply a query matching the things you want to change and a series of
173 field=value pairs. For example, beet modify genius of love artist="Tom
174 Tom Club" will change the artist for the track "Genius of Love." To re‐
175 move fields (which is only possible for flexible attributes), follow a
176 field name with an exclamation point: field!.
177 The -a switch operates on albums instead of individual tracks. Without
179 this flag, the command will only change track-level data, even if all
180 the tracks belong to the same album. If you want to change an al‐
181 bum-level field, such as year or albumartist, you'll want to use the -a
182 flag to avoid a confusing situation where the data for individual
183 tracks conflicts with the data for the whole album.
184 Items will automatically be moved around when necessary if they're in
186 your library directory, but you can disable that with -M. Tags will be
187 written to the files according to the settings you have for imports,
188 but these can be overridden with -w (write tags, the default) and -W
189 (don't write tags).
190 When you run the modify command, it prints a list of all affected items
192 in the library and asks for your permission before making any changes.
193 You can then choose to abort the change (type n), confirm (y), or in‐
194 teractively choose some of the items (s). In the latter case, the com‐
195 mand will prompt you for every matching item or album and invite you to
196 type y to apply the changes, n to discard them or q to exit and apply
197 the selected changes. This option lets you choose precisely which data
198 to change without spending too much time to carefully craft a query. To
199 skip the prompts entirely, use the -y option.
200 move
202 beet move [-capt] [-d DIR] QUERY
203 Move or copy items in your library.
205 This command, by default, acts as a library consolidator: items match‐
207 ing the query are renamed into your library directory structure. By
208 specifying a destination directory with -d manually, you can move items
209 matching a query anywhere in your filesystem. The -c option copies
210 files instead of moving them. As with other commands, the -a option
211 matches albums instead of items. The -e flag (for "export") copies
212 files without changing the database.
213 To perform a "dry run", just use the -p (for "pretend") flag. This will
215 show you a list of files that would be moved but won't actually change
216 anything on disk. The -t option sets the timid mode which will ask
217 again before really moving or copying the files.
218 update
220 beet update [-F] FIELD [-aM] QUERY
221 Update the library (and, by default, move files) to reflect out-of-band
223 metadata changes and file deletions.
224 This will scan all the matched files and read their tags, populating
226 the database with the new values. By default, files will be renamed ac‐
227 cording to their new metadata; disable this with -M. Beets will skip
228 files if their modification times have not changed, so any out-of-band
229 metadata changes must also update these for beet update to recognise
230 that the files have been edited.
231 To perform a "dry run" of an update, just use the -p (for "pretend")
233 flag. This will show you all the proposed changes but won't actually
234 change anything on disk.
235 By default, all the changed metadata will be populated back to the
237 database. If you only want certain fields to be written, specify them
238 with the `-F` flags (which can be used multiple times). For the list of
239 supported fields, please see `beet fields`.
240 When an updated track is part of an album, the album-level fields of
242 all tracks from the album are also updated. (Specifically, the command
243 copies album-level data from the first track on the album and applies
244 it to the rest of the tracks.) This means that, if album-level fields
245 aren't identical within an album, some changes shown by the update com‐
246 mand may be overridden by data from other tracks on the same album.
247 This means that running the update command multiple times may show the
248 same changes being applied.
249 write
251 beet write [-pf] [QUERY]
252 Write metadata from the database into files' tags.
254 When you make changes to the metadata stored in beets' library database
256 (during import or with the modify command, for example), you often have
257 the option of storing changes only in the database, leaving your files
258 untouched. The write command lets you later change your mind and write
259 the contents of the database into the files. By default, this writes
260 the changes only if there is a difference between the database and the
261 tags in the file.
262 You can think of this command as the opposite of update.
264 The -p option previews metadata changes without actually applying them.
266 The -f option forces a write to the file, even if the file tags match
268 the database. This is useful for making sure that enabled plugins that
269 run on write (e.g., the Scrub and Zero plugins) are run on the file.
270 stats
272 beet stats [-e] [QUERY]
273 Show some statistics on your entire library (if you don't provide a
275 query) or the matched items (if you do).
276 By default, the command calculates file sizes using their bitrate and
278 duration. The -e (--exact) option reads the exact sizes of each file
279 (but is slower). The exact mode also outputs the exact duration in sec‐
280 onds.
281 fields
283 beet fields
284 Show the item and album metadata fields available for use in Queries
286 and Path Formats. The listing includes any template fields provided by
287 plugins and any flexible attributes you've manually assigned to your
288 items and albums.
289 config
291 beet config [-pdc]
292 beet config -e
293 Show or edit the user configuration. This command does one of three
295 things:
296 • With no options, print a YAML representation of the current user con‐
298 figuration. With the --default option, beets' default options are
299 also included in the dump.
300 • The --path option instead shows the path to your configuration file.
302 This can be combined with the --default flag to show where beets
303 keeps its internal defaults.
304 • By default, sensitive information like passwords is removed when
306 dumping the configuration. The --clear option includes this sensitive
307 data.
308 • With the --edit option, beets attempts to open your config file for
310 editing. It first tries the $EDITOR environment variable and then a
311 fallback option depending on your platform: open on OS X, xdg-open on
312 Unix, and direct invocation on Windows.
313
315 Beets has a few "global" flags that affect all commands. These must ap‐
316 pear between the executable name (beet) and the command---for example,
317 beet -v import ....
318 • -l LIBPATH: specify the library database file to use.
320 • -d DIRECTORY: specify the library root directory.
322 • -v: verbose mode; prints out a deluge of debugging information.
324 Please use this flag when reporting bugs. You can use it twice, as in
325 -vv, to make beets even more verbose.
326 • -c FILE: read a specified YAML configuration file. This configuration
328 works as an overlay: rather than replacing your normal configuration
329 options entirely, the two are merged. Any individual options set in
330 this config file will override the corresponding settings in your
331 base configuration.
332 • -p plugins: specify a comma-separated list of plugins to enable. If
334 specified, the plugin list in your configuration is ignored. The long
335 form of this argument also allows specifying no plugins, effectively
336 disabling all plugins: --plugins=.
337 Beets also uses the BEETSDIR environment variable to look for configu‐
339 ration and data.
340
342 Beets includes support for shell command completion. The command beet
343 completion prints out a bash 3.2 script; to enable completion put a
344 line like this into your .bashrc or similar file:
345 eval "$(beet completion)"
347 Or, to avoid slowing down your shell startup time, you can pipe the
349 beet completion output to a file and source that instead.
350 You will also need to source the bash-completion script, which is prob‐
352 ably available via your package manager. On OS X, you can install it
353 via Homebrew with brew install bash-completion; Homebrew will give you
354 instructions for sourcing the script.
355 The completion script suggests names of subcommands and (after typing
357 -) options of the given command. If you are using a command that ac‐
358 cepts a query, the script will also complete field names.
359 beet list ar[TAB]
361 # artist: artist_credit: artist_sort: artpath:
362 beet list artp[TAB]
363 beet list artpath\:
364 (Don't worry about the slash in front of the colon: this is a escape
366 sequence for the shell and won't be seen by beets.)
367 Completion of plugin commands only works for those plugins that were
369 enabled when running beet completion. If you add a plugin later on you
370 will want to re-generate the script.
371 zsh
373 If you use zsh, take a look at the included completion script. The
374 script should be placed in a directory that is part of your fpath, and
375 not sourced in your .zshrc. Running echo $fpath will give you a list of
376 valid directories.
377 Another approach is to use zsh's bash completion compatibility. This
379 snippet defines some bash-specific functions to make this work without
380 errors:
381 autoload bashcompinit
383 bashcompinit
384 _get_comp_words_by_ref() { :; }
385 compopt() { :; }
386 _filedir() { :; }
387 eval "$(beet completion)"
388
390 https://beets.readthedocs.org/
391 beetsconfig(5)
393
395 Adrian Sampson
396
398 2023, Adrian Sampson
3991.6 Jan 18, 2023 BEET(1)