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  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
192   move
193          beet move [-capt] [-d DIR] QUERY
194
195       Move or copy items in your library.
196
197       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
205       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
210   update
211          beet update [-F] FIELD [-aM] QUERY
212
213       Update the library (and, optionally, move files) to reflect out-of-band
214       metadata changes and file deletions.
215
216       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
223       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
227       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
232       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
241   write
242          beet write [-pf] [QUERY]
243
244       Write metadata from the database into files' tags.
245
246       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
254       You can think of this command as the opposite of update.
255
256       The -p option previews metadata changes without actually applying them.
257
258       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
262   stats
263          beet stats [-e] [QUERY]
264
265       Show  some  statistics  on  your entire library (if you don't provide a
266       query) or the matched items (if you do).
267
268       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
273   fields
274          beet fields
275
276       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
281   config
282          beet config [-pdc]
283          beet config -e
284
285       Show or edit the user configuration. This command  does  one  of  three
286       things:
287
288       · 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
292       · 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
296       · By  default,  sensitive  information  like  passwords is removed when
297         dumping the configuration. The --clear option includes this sensitive
298         data.
299
300       · 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

GLOBAL FLAGS

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

SHELL COMPLETION

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
332          eval "$(beet completion)"
333
334       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
337       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
342       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
346          beet list ar[TAB]
347          # artist:  artist_credit:  artist_sort:  artpath:
348          beet list artp[TAB]
349          beet list artpath\:
350
351       (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
354       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
358   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
364       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
368          autoload bashcompinit
369          bashcompinit
370          _get_comp_words_by_ref() { :; }
371          compopt() { :; }
372          _filedir() { :; }
373          eval "$(beet completion)"
374

SEE ALSO

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

AUTHOR

381       Adrian Sampson
382
384       2019, Adrian Sampson
385
386
387
388
3891.4                              Jul 24, 2019                          BEET(1)
Impressum