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,
40 instead 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
50 albums that weren't tagged successfully---either because they're not
51 in the MusicBrainz database or because something's wrong with the
52 files. Use the -l option to specify a filename to log every time you
53 skip an album or import it "as-is" or an album gets skipped as a
54 duplicate.
55 · Relatedly, the -q (quiet) option can help with large imports by auto‐
57 tagging without ever bothering to ask for user input. Whenever the
58 normal autotagger mode would ask for confirmation, the quiet mode
59 pessimistically skips the album. The quiet mode also disables the
60 tagger's ability to resume interrupted imports.
61 · Speaking of resuming interrupted imports, the tagger will prompt you
63 if it seems like the last import of the directory was interrupted (by
64 you or by a crash). If you want to skip this prompt, you can say
65 "yes" automatically by providing -p or "no" using -P. The resuming
66 feature can be disabled by default using a configuration option (see
67 below).
68 · If you want to import only the new stuff from a directory, use the -i
70 option to run an incremental import. With this flag, beets will keep
71 track of every directory it ever imports and avoid importing them
72 again. This is useful if you have an "incoming" directory that you
73 periodically add things to. To get this to work correctly, you'll
74 need to use an incremental import every time you run an import on the
75 directory in question---including the first time, when no subdirecto‐
76 ries will be skipped. So consider enabling the incremental configura‐
77 tion option.
78 · When beets applies metadata to your music, it will retain the value
80 of any existing tags that weren't overwritten, and import them into
81 the database. You may prefer to only use existing metadata for find‐
82 ing matches, and to erase it completely when new metadata is applied.
83 You can enforce this behavior with the --from-scratch option, or the
84 from_scratch configuration option.
85 · By default, beets will proceed without asking if it finds a very
87 close metadata match. To disable this and have the importer ask you
88 every time, use the -t (for timid) option.
89 · The importer typically works in a whole-album-at-a-time mode. If you
91 instead want to import individual, non-album tracks, use the single‐
92 ton mode by supplying the -s option.
93 · If you have an album that's split across several directories under a
95 common top directory, use the --flat option. This takes all the music
96 files under the directory (recursively) and treats them as a single
97 large album instead of as one album per directory. This can help with
98 your more stubborn multi-disc albums.
99 · Similarly, if you have one directory that contains multiple albums,
101 use the --group-albums option to split the files based on their meta‐
102 data before matching them as separate albums.
103 · If you want to preview which files would be imported, use the --pre‐
105 tend option. If set, beets will just print a list of files that it
106 would otherwise import.
107 · If you already have a metadata backend ID that matches the items to
109 be imported, you can instruct beets to restrict the search to that ID
110 instead of searching for other candidates by using the --search-id
111 SEARCH_ID option. Multiple IDs can be specified by simply repeating
112 the option several times.
113 · You can supply --set field=value to assign field to value on import.
115 These assignments will merge with (and possibly override) the
116 set_fields configuration dictionary. You can use the option multiple
117 times on the command line, like so:
118 beet import --set genre="Alternative Rock" --set mood="emotional"
120 list
122 beet list [-apf] QUERY
123 Queries the database for music.
125 Want to search for "Gronlandic Edit" by of Montreal? Try beet list
127 gronlandic. Maybe you want to see everything released in 2009 with
128 "vegetables" in the title? Try beet list year:2009 title:vegetables.
129 You can also specify the sort order. (Read more in query.)
130 You can use the -a switch to search for albums instead of individual
132 items. In this case, the queries you use are restricted to album-level
133 fields: for example, you can search for year:1969 but query parts for
134 item-level fields like title:foo will be ignored. Remember that artist
135 is an item-level field; albumartist is the corresponding album field.
136 The -p option makes beets print out filenames of matched items, which
138 might be useful for piping into other Unix commands (such as xargs).
139 Similarly, the -f option lets you specify a specific format with which
140 to print every album or track. This uses the same template syntax as
141 beets' path formats. For example, the command beet ls -af '$album:
142 $tracktotal' beatles prints out the number of tracks on each Beatles
143 album. In Unix shells, remember to enclose the template argument in
144 single quotes to avoid environment variable expansion.
145 remove
147 beet remove [-adf] QUERY
148 Remove music from your library.
150 This command uses the same query syntax as the list command. You'll be
152 shown a list of the files that will be removed and asked to confirm.
153 By default, this just removes entries from the library database; it
154 doesn't touch the files on disk. To actually delete the files, use beet
155 remove -d. If you do not want to be prompted to remove the files, use
156 beet remove -f.
157 modify
159 beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...]
160 Change the metadata for items or albums in the database.
162 Supply a query matching the things you want to change and a series of
164 field=value pairs. For example, beet modify genius of love artist="Tom
165 Tom Club" will change the artist for the track "Genius of Love." To
166 remove fields (which is only possible for flexible attributes), follow
167 a field name with an exclamation point: field!.
168 The -a switch operates on albums instead of individual tracks. Without
170 this flag, the command will only change track-level data, even if all
171 the tracks belong to the same album. If you want to change an
172 album-level field, such as year or albumartist, you'll want to use the
173 -a flag to avoid a confusing situation where the data for individual
174 tracks conflicts with the data for the whole album.
175 Items will automatically be moved around when necessary if they're in
177 your library directory, but you can disable that with -M. Tags will be
178 written to the files according to the settings you have for imports,
179 but these can be overridden with -w (write tags, the default) and -W
180 (don't write tags).
181 When you run the modify command, it prints a list of all affected items
183 in the library and asks for your permission before making any changes.
184 You can then choose to abort the change (type n), confirm (y), or
185 interactively choose some of the items (s). In the latter case, the
186 command will prompt you for every matching item or album and invite you
187 to type y to apply the changes, n to discard them or q to exit and
188 apply the selected changes. This option lets you choose precisely which
189 data to change without spending too much time to carefully craft a
190 query. To skip the prompts entirely, use the -y option.
191 move
193 beet move [-capt] [-d DIR] QUERY
194 Move or copy items in your library.
196 This command, by default, acts as a library consolidator: items match‐
198 ing the query are renamed into your library directory structure. By
199 specifying a destination directory with -d manually, you can move items
200 matching a query anywhere in your filesystem. The -c option copies
201 files instead of moving them. As with other commands, the -a option
202 matches albums instead of items. The -e flag (for "export") copies
203 files without changing the database.
204 To perform a "dry run", just use the -p (for "pretend") flag. This will
206 show you a list of files that would be moved but won't actually change
207 anything on disk. The -t option sets the timid mode which will ask
208 again before really moving or copying the files.
209 update
211 beet update [-F] FIELD [-aM] QUERY
212 Update the library (and, optionally, move files) to reflect out-of-band
214 metadata changes and file deletions.
215 This will scan all the matched files and read their tags, populating
217 the database with the new values. By default, files will be renamed
218 according to their new metadata; disable this with -M. Beets will skip
219 files if their modification times have not changed, so any out-of-band
220 metadata changes must also update these for beet update to recognise
221 that the files have been edited.
222 To perform a "dry run" of an update, just use the -p (for "pretend")
224 flag. This will show you all the proposed changes but won't actually
225 change anything on disk.
226 By default, all the changed metadata will be populated back to the
228 database. If you only want certain fields to be written, specify them
229 with the `-F` flags (which can be used multiple times). For the list of
230 supported fields, please see `beet fields`.
231 When an updated track is part of an album, the album-level fields of
233 all tracks from the album are also updated. (Specifically, the command
234 copies album-level data from the first track on the album and applies
235 it to the rest of the tracks.) This means that, if album-level fields
236 aren't identical within an album, some changes shown by the update com‐
237 mand may be overridden by data from other tracks on the same album.
238 This means that running the update command multiple times may show the
239 same changes being applied.
240 write
242 beet write [-pf] [QUERY]
243 Write metadata from the database into files' tags.
245 When you make changes to the metadata stored in beets' library database
247 (during import or with the modify command, for example), you often have
248 the option of storing changes only in the database, leaving your files
249 untouched. The write command lets you later change your mind and write
250 the contents of the database into the files. By default, this writes
251 the changes only if there is a difference between the database and the
252 tags in the file.
253 You can think of this command as the opposite of update.
255 The -p option previews metadata changes without actually applying them.
257 The -f option forces a write to the file, even if the file tags match
259 the database. This is useful for making sure that enabled plugins that
260 run on write (e.g., the Scrub and Zero plugins) are run on the file.
261 stats
263 beet stats [-e] [QUERY]
264 Show some statistics on your entire library (if you don't provide a
266 query) or the matched items (if you do).
267 By default, the command calculates file sizes using their bitrate and
269 duration. The -e (--exact) option reads the exact sizes of each file
270 (but is slower). The exact mode also outputs the exact duration in sec‐
271 onds.
272 fields
274 beet fields
275 Show the item and album metadata fields available for use in query and
277 pathformat. The listing includes any template fields provided by plug‐
278 ins and any flexible attributes you've manually assigned to your items
279 and albums.
280 config
282 beet config [-pdc]
283 beet config -e
284 Show or edit the user configuration. This command does one of three
286 things:
287 · With no options, print a YAML representation of the current user con‐
289 figuration. With the --default option, beets' default options are
290 also included in the dump.
291 · The --path option instead shows the path to your configuration file.
293 This can be combined with the --default flag to show where beets
294 keeps its internal defaults.
295 · By default, sensitive information like passwords is removed when
297 dumping the configuration. The --clear option includes this sensitive
298 data.
299 · With the --edit option, beets attempts to open your config file for
301 editing. It first tries the $EDITOR environment variable and then a
302 fallback option depending on your platform: open on OS X, xdg-open on
303 Unix, and direct invocation on Windows.
304
306 Beets has a few "global" flags that affect all commands. These must
307 appear between the executable name (beet) and the command---for exam‐
308 ple, beet -v import ....
309 · -l LIBPATH: specify the library database file to use.
311 · -d DIRECTORY: specify the library root directory.
313 · -v: verbose mode; prints out a deluge of debugging information.
315 Please use this flag when reporting bugs. You can use it twice, as in
316 -vv, to make beets even more verbose.
317 · -c FILE: read a specified YAML configuration file. This configuration
319 works as an overlay: rather than replacing your normal configuration
320 options entirely, the two are merged. Any individual options set in
321 this config file will override the corresponding settings in your
322 base configuration.
323 Beets also uses the BEETSDIR environment variable to look for configu‐
325 ration and data.
326
328 Beets includes support for shell command completion. The command beet
329 completion prints out a bash 3.2 script; to enable completion put a
330 line like this into your .bashrc or similar file:
331 eval "$(beet completion)"
333 Or, to avoid slowing down your shell startup time, you can pipe the
335 beet completion output to a file and source that instead.
336 You will also need to source the bash-completion script, which is prob‐
338 ably available via your package manager. On OS X, you can install it
339 via Homebrew with brew install bash-completion; Homebrew will give you
340 instructions for sourcing the script.
341 The completion script suggests names of subcommands and (after typing
343 -) options of the given command. If you are using a command that
344 accepts a query, the script will also complete field names.
345 beet list ar[TAB]
347 # artist: artist_credit: artist_sort: artpath:
348 beet list artp[TAB]
349 beet list artpath\:
350 (Don't worry about the slash in front of the colon: this is a escape
352 sequence for the shell and won't be seen by beets.)
353 Completion of plugin commands only works for those plugins that were
355 enabled when running beet completion. If you add a plugin later on you
356 will want to re-generate the script.
357 zsh
359 If you use zsh, take a look at the included completion script. The
360 script should be placed in a directory that is part of your fpath, and
361 not sourced in your .zshrc. Running echo $fpath will give you a list of
362 valid directories.
363 Another approach is to use zsh's bash completion compatibility. This
365 snippet defines some bash-specific functions to make this work without
366 errors:
367 autoload bashcompinit
369 bashcompinit
370 _get_comp_words_by_ref() { :; }
371 compopt() { :; }
372 _filedir() { :; }
373 eval "$(beet completion)"
374
376 http://beets.readthedocs.org/
377 beetsconfig(5)
379
381 Adrian Sampson
382
384 2020, Adrian Sampson
3851.4 Aug 03, 2020 BEET(1)