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.
35 Optional command flags:
37 • By default, the command copies files your the 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 query.)
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:
141 $tracktotal' beatles prints out the number of tracks on each Beatles
142 album. In Unix shells, remember to enclose the template argument in
143 single 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. You'll be
151 shown a list of the files that will be removed and asked to confirm.
152 By default, this just removes entries from the library database; it
153 doesn't touch the files on disk. To actually delete the files, use beet
154 remove -d. If you do not want to be prompted to remove the files, use
155 beet remove -f.
156 modify
158 beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...]
159 Change the metadata for items or albums in the database.
161 Supply a query matching the things you want to change and a series of
163 field=value pairs. For example, beet modify genius of love artist="Tom
164 Tom Club" will change the artist for the track "Genius of Love." To
165 remove fields (which is only possible for flexible attributes), follow
166 a field name with an exclamation point: field!.
167 The -a switch operates on albums instead of individual tracks. Without
169 this flag, the command will only change track-level data, even if all
170 the tracks belong to the same album. If you want to change an al‐
171 bum-level field, such as year or albumartist, you'll want to use the -a
172 flag to avoid a confusing situation where the data for individual
173 tracks conflicts with the data for the whole album.
174 Items will automatically be moved around when necessary if they're in
176 your library directory, but you can disable that with -M. Tags will be
177 written to the files according to the settings you have for imports,
178 but these can be overridden with -w (write tags, the default) and -W
179 (don't write tags).
180 When you run the modify command, it prints a list of all affected items
182 in the library and asks for your permission before making any changes.
183 You can then choose to abort the change (type n), confirm (y), or in‐
184 teractively choose some of the items (s). In the latter case, the com‐
185 mand will prompt you for every matching item or album and invite you to
186 type y to apply the changes, n to discard them or q to exit and apply
187 the selected changes. This option lets you choose precisely which data
188 to change without spending too much time to carefully craft a query. To
189 skip the prompts entirely, use the -y option.
190 move
192 beet move [-capt] [-d DIR] QUERY
193 Move or copy items in your library.
195 This command, by default, acts as a library consolidator: items match‐
197 ing the query are renamed into your library directory structure. By
198 specifying a destination directory with -d manually, you can move items
199 matching a query anywhere in your filesystem. The -c option copies
200 files instead of moving them. As with other commands, the -a option
201 matches albums instead of items. The -e flag (for "export") copies
202 files without changing the database.
203 To perform a "dry run", just use the -p (for "pretend") flag. This will
205 show you a list of files that would be moved but won't actually change
206 anything on disk. The -t option sets the timid mode which will ask
207 again before really moving or copying the files.
208 update
210 beet update [-F] FIELD [-aM] QUERY
211 Update the library (and, optionally, move files) to reflect out-of-band
213 metadata changes and file deletions.
214 This will scan all the matched files and read their tags, populating
216 the database with the new values. By default, files will be renamed ac‐
217 cording to their new metadata; disable this with -M. Beets will skip
218 files if their modification times have not changed, so any out-of-band
219 metadata changes must also update these for beet update to recognise
220 that the files have been edited.
221 To perform a "dry run" of an update, just use the -p (for "pretend")
223 flag. This will show you all the proposed changes but won't actually
224 change anything on disk.
225 By default, all the changed metadata will be populated back to the
227 database. If you only want certain fields to be written, specify them
228 with the `-F` flags (which can be used multiple times). For the list of
229 supported fields, please see `beet fields`.
230 When an updated track is part of an album, the album-level fields of
232 all tracks from the album are also updated. (Specifically, the command
233 copies album-level data from the first track on the album and applies
234 it to the rest of the tracks.) This means that, if album-level fields
235 aren't identical within an album, some changes shown by the update com‐
236 mand may be overridden by data from other tracks on the same album.
237 This means that running the update command multiple times may show the
238 same changes being applied.
239 write
241 beet write [-pf] [QUERY]
242 Write metadata from the database into files' tags.
244 When you make changes to the metadata stored in beets' library database
246 (during import or with the modify command, for example), you often have
247 the option of storing changes only in the database, leaving your files
248 untouched. The write command lets you later change your mind and write
249 the contents of the database into the files. By default, this writes
250 the changes only if there is a difference between the database and the
251 tags in the file.
252 You can think of this command as the opposite of update.
254 The -p option previews metadata changes without actually applying them.
256 The -f option forces a write to the file, even if the file tags match
258 the database. This is useful for making sure that enabled plugins that
259 run on write (e.g., the Scrub and Zero plugins) are run on the file.
260 stats
262 beet stats [-e] [QUERY]
263 Show some statistics on your entire library (if you don't provide a
265 query) or the matched items (if you do).
266 By default, the command calculates file sizes using their bitrate and
268 duration. The -e (--exact) option reads the exact sizes of each file
269 (but is slower). The exact mode also outputs the exact duration in sec‐
270 onds.
271 fields
273 beet fields
274 Show the item and album metadata fields available for use in query and
276 pathformat. The listing includes any template fields provided by plug‐
277 ins and any flexible attributes you've manually assigned to your items
278 and albums.
279 config
281 beet config [-pdc]
282 beet config -e
283 Show or edit the user configuration. This command does one of three
285 things:
286 • With no options, print a YAML representation of the current user con‐
288 figuration. With the --default option, beets' default options are
289 also included in the dump.
290 • The --path option instead shows the path to your configuration file.
292 This can be combined with the --default flag to show where beets
293 keeps its internal defaults.
294 • By default, sensitive information like passwords is removed when
296 dumping the configuration. The --clear option includes this sensitive
297 data.
298 • With the --edit option, beets attempts to open your config file for
300 editing. It first tries the $EDITOR environment variable and then a
301 fallback option depending on your platform: open on OS X, xdg-open on
302 Unix, and direct invocation on Windows.
303
305 Beets has a few "global" flags that affect all commands. These must ap‐
306 pear between the executable name (beet) and the command---for example,
307 beet -v import ....
308 • -l LIBPATH: specify the library database file to use.
310 • -d DIRECTORY: specify the library root directory.
312 • -v: verbose mode; prints out a deluge of debugging information.
314 Please use this flag when reporting bugs. You can use it twice, as in
315 -vv, to make beets even more verbose.
316 • -c FILE: read a specified YAML configuration file. This configuration
318 works as an overlay: rather than replacing your normal configuration
319 options entirely, the two are merged. Any individual options set in
320 this config file will override the corresponding settings in your
321 base configuration.
322 Beets also uses the BEETSDIR environment variable to look for configu‐
324 ration and data.
325
327 Beets includes support for shell command completion. The command beet
328 completion prints out a bash 3.2 script; to enable completion put a
329 line like this into your .bashrc or similar file:
330 eval "$(beet completion)"
332 Or, to avoid slowing down your shell startup time, you can pipe the
334 beet completion output to a file and source that instead.
335 You will also need to source the bash-completion script, which is prob‐
337 ably available via your package manager. On OS X, you can install it
338 via Homebrew with brew install bash-completion; Homebrew will give you
339 instructions for sourcing the script.
340 The completion script suggests names of subcommands and (after typing
342 -) options of the given command. If you are using a command that ac‐
343 cepts a query, the script will also complete field names.
344 beet list ar[TAB]
346 # artist: artist_credit: artist_sort: artpath:
347 beet list artp[TAB]
348 beet list artpath\:
349 (Don't worry about the slash in front of the colon: this is a escape
351 sequence for the shell and won't be seen by beets.)
352 Completion of plugin commands only works for those plugins that were
354 enabled when running beet completion. If you add a plugin later on you
355 will want to re-generate the script.
356 zsh
358 If you use zsh, take a look at the included completion script. The
359 script should be placed in a directory that is part of your fpath, and
360 not sourced in your .zshrc. Running echo $fpath will give you a list of
361 valid directories.
362 Another approach is to use zsh's bash completion compatibility. This
364 snippet defines some bash-specific functions to make this work without
365 errors:
366 autoload bashcompinit
368 bashcompinit
369 _get_comp_words_by_ref() { :; }
370 compopt() { :; }
371 _filedir() { :; }
372 eval "$(beet completion)"
373
375 http://beets.readthedocs.org/
376 beetsconfig(5)
378
380 Adrian Sampson
381
383 2022, Adrian Sampson
3841.4 Jan 19, 2022 BEET(1)