1BEET(1)                              beets                             BEET(1)
2
3
4

NAME

6       beet - music tagger and library organizer
7

SYNOPSIS

9       beet [args...] command [args...]
10       beet help command
11
12

COMMANDS

14   import
15          beet import [-CWAPRqst] [-l LOGPATH] PATH...
16          beet import [options] -L QUERY
17
18       Add  music  to your library, attempting to get correct tags for it from
19       MusicBrainz.
20
21       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
28       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
36       Optional command flags:
37
38       • 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
45       • 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
49       • 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
55       • 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
61       • 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
68       • 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
78       • 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
85       • 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
89       • 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
93       • 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
99       • 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
103       • 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
107       • 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
113       • 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
118            beet import --set genre="Alternative Rock" --set mood="emotional"
119
120   list
121          beet list [-apf] QUERY
122
123       Queries the database for music.
124
125       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
130       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
136       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
145   remove
146          beet remove [-adf] QUERY
147
148       Remove music from your library.
149
150       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
156       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
167   modify
168          beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...]
169
170       Change the metadata for items or albums in the database.
171
172       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
178       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
185       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
191       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
201   move
202          beet move [-capt] [-d DIR] QUERY
203
204       Move or copy items in your library.
205
206       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
214       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
219   update
220          beet update [-F] FIELD [-aM] QUERY
221
222       Update the library (and, by default, move files) to reflect out-of-band
223       metadata changes and file deletions.
224
225       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
232       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
236       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
241       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
250   write
251          beet write [-pf] [QUERY]
252
253       Write metadata from the database into files' tags.
254
255       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
263       You can think of this command as the opposite of update.
264
265       The -p option previews metadata changes without actually applying them.
266
267       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
271   stats
272          beet stats [-e] [QUERY]
273
274       Show some statistics on your entire library (if  you  don't  provide  a
275       query) or the matched items (if you do).
276
277       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
282   fields
283          beet fields
284
285       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
290   config
291          beet config [-pdc]
292          beet config -e
293
294       Show  or  edit  the  user configuration. This command does one of three
295       things:
296
297       • 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
301       • 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
305       • By default, sensitive information  like  passwords  is  removed  when
306         dumping the configuration. The --clear option includes this sensitive
307         data.
308
309       • 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

GLOBAL FLAGS

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
319-l LIBPATH: specify the library database file to use.
320
321-d DIRECTORY: specify the library root directory.
322
323-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
327-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
333-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
338       Beets also uses the BEETSDIR environment variable to look for  configu‐
339       ration and data.
340

SHELL COMPLETION

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
346          eval "$(beet completion)"
347
348       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
351       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
356       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
360          beet list ar[TAB]
361          # artist:  artist_credit:  artist_sort:  artpath:
362          beet list artp[TAB]
363          beet list artpath\:
364
365       (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
368       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
372   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
378       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
382          autoload bashcompinit
383          bashcompinit
384          _get_comp_words_by_ref() { :; }
385          compopt() { :; }
386          _filedir() { :; }
387          eval "$(beet completion)"
388

SEE ALSO

390       https://beets.readthedocs.org/
391
392       beetsconfig(5)
393

AUTHOR

395       Adrian Sampson
396
398       2023, Adrian Sampson
399
400
401
402
4031.6                              Jul 19, 2023                          BEET(1)
Impressum