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,
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
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
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
56       · 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
62       · 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
69       · 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
79       · 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
86       · 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
90       · 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
94       · 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
100       · 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
104       · 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
108       · 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
114       · 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
119            beet import --set genre="Alternative Rock" --set mood="emotional"
120
121   list
122          beet list [-apf] QUERY
123
124       Queries the database for music.
125
126       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
131       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
137       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
146   remove
147          beet remove [-adf] QUERY
148
149       Remove music from your library.
150
151       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
158   modify
159          beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...]
160
161       Change the metadata for items or albums in the database.
162
163       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
169       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
176       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
182       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  or  n. This option lets you choose precisely which data to
188       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
217       according  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
306       appear between the executable name (beet) and the  command---for  exam‐
307       ple, 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
343       accepts 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       2016, Adrian Sampson
384
385
386
387
3881.4                              Jan 31, 2019                          BEET(1)
Impressum