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.
35
36       Optional command flags:
37
38       • 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
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 query.)
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:
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
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.  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
157   modify
158          beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...]
159
160       Change the metadata for items or albums in the database.
161
162       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
168       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
175       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
181       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
191   move
192          beet move [-capt] [-d DIR] QUERY
193
194       Move or copy items in your library.
195
196       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
204       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
209   update
210          beet update [-F] FIELD [-aM] QUERY
211
212       Update the library (and, optionally, move files) to reflect out-of-band
213       metadata changes and file deletions.
214
215       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
222       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
226       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
231       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
240   write
241          beet write [-pf] [QUERY]
242
243       Write metadata from the database into files' tags.
244
245       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
253       You can think of this command as the opposite of update.
254
255       The -p option previews metadata changes without actually applying them.
256
257       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
261   stats
262          beet stats [-e] [QUERY]
263
264       Show some statistics on your entire library (if  you  don't  provide  a
265       query) or the matched items (if you do).
266
267       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
272   fields
273          beet fields
274
275       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
280   config
281          beet config [-pdc]
282          beet config -e
283
284       Show  or  edit  the  user configuration. This command does one of three
285       things:
286
287       • 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
291       • 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
295       • By default, sensitive information  like  passwords  is  removed  when
296         dumping the configuration. The --clear option includes this sensitive
297         data.
298
299       • 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

GLOBAL FLAGS

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
309-l LIBPATH: specify the library database file to use.
310
311-d DIRECTORY: specify the library root directory.
312
313-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
317-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
323       Beets  also uses the BEETSDIR environment variable to look for configu‐
324       ration and data.
325

SHELL COMPLETION

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
331          eval "$(beet completion)"
332
333       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
336       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
341       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
345          beet list ar[TAB]
346          # artist:  artist_credit:  artist_sort:  artpath:
347          beet list artp[TAB]
348          beet list artpath\:
349
350       (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
353       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
357   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
363       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
367          autoload bashcompinit
368          bashcompinit
369          _get_comp_words_by_ref() { :; }
370          compopt() { :; }
371          _filedir() { :; }
372          eval "$(beet completion)"
373

SEE ALSO

375       http://beets.readthedocs.org/
376
377       beetsconfig(5)
378

AUTHOR

380       Adrian Sampson
381
383       2021, Adrian Sampson
384
385
386
387
3881.4                              Jan 26, 2021                          BEET(1)
Impressum