Provided by: beets_1.6.0-1_all bug


       beet - music tagger and library organizer


       beet [args…] command [args…]
       beet help command


          beet import [-CWAPRqst] [-l LOGPATH] PATH...
          beet import [options] -L QUERY

       Add music to your library, attempting to get correct tags for it from MusicBrainz.

       Point  the  command  at some music: directories, single files, or compressed archives. The
       music will be copied to  a  configurable  directory  structure  and  added  to  a  library
       database.  The  command  is interactive and will try to get you to verify MusicBrainz tags
       that it thinks are suspect. See the autotagging  guide  for  detail  on  how  to  use  the
       interactive tag-correction flow.

       Directories  passed  to  the  import command can contain either a single album or many, in
       which case the leaf directories will be considered albums (the  latter  case  is  true  of
       typical  Artist/Album  organizations  and many people’s “downloads” folders). The path can
       also be a single song or an archive. Beets supports zip and tar archives out of  the  box.
       To  extract  rar  files,  install the rarfile package and the unrar command. To extract 7z
       files, install the py7zr package.

       Optional command flags:

       • By default, the command copies files to your library directory and updates the ID3  tags
         on your music. In order to move the files, instead of copying, use the -m (move) option.
         If you’d like to leave your music files untouched, try the -C (don’t copy) and -W (don’t
         write  tags) options. You can also disable this behavior by default in the configuration
         file (below).

       • Also, you can disable the autotagging behavior entirely using  -A  (don’t  autotag)—then
         your music will be imported with its existing metadata.

       • During  a  long  tagging  import,  it can be useful to keep track of albums that weren’t
         tagged successfully—either because they’re not in the MusicBrainz  database  or  because
         something’s  wrong  with the files. Use the -l option to specify a filename to log every
         time you skip an album or import it “as-is” or an album gets skipped as a duplicate.

       • Relatedly, the -q (quiet) option can help with large imports by autotagging without ever
         bothering  to  ask  for  user  input.  Whenever the normal autotagger mode would ask for
         confirmation, the quiet mode pessimistically  skips  the  album.  The  quiet  mode  also
         disables the tagger’s ability to resume interrupted imports.

       • Speaking  of  resuming  interrupted imports, the tagger will prompt you if it seems like
         the last import of the directory was interrupted (by you or by a crash). If you want  to
         skip  this prompt, you can say “yes” automatically by providing -p or “no” using -P. The
         resuming feature can be disabled by default using a configuration option (see below).

       • If you want to import only the new stuff from a directory, use the -i option to  run  an
         incremental  import.  With  this  flag, beets will keep track of every directory it ever
         imports and avoid importing them again.  This  is  useful  if  you  have  an  “incoming”
         directory  that  you  periodically add things to.  To get this to work correctly, you’ll
         need to use an incremental import every time you run  an  import  on  the  directory  in
         question—including  the  first time, when no subdirectories will be skipped. So consider
         enabling the incremental configuration option.

       • When beets applies metadata to your music, it will retain the value of any existing tags
         that  weren’t overwritten, and import them into the database. You may prefer to only use
         existing metadata for finding matches, and to erase it completely when new  metadata  is
         applied.  You  can  enforce  this  behavior  with  the  --from-scratch  option,  or  the
         from_scratch configuration option.

       • By default, beets will proceed without asking if it finds a very close  metadata  match.
         To disable this and have the importer ask you every time, use the -t (for timid) option.

       • The  importer  typically  works  in a whole-album-at-a-time mode. If you instead want to
         import individual, non-album tracks, use the singleton mode by supplying the -s option.

       • If you have an album  that’s  split  across  several  directories  under  a  common  top
         directory,  use  the  --flat  option. This takes all the music files under the directory
         (recursively) and treats them as a single large  album  instead  of  as  one  album  per
         directory. This can help with your more stubborn multi-disc albums.

       • Similarly,   if   you  have  one  directory  that  contains  multiple  albums,  use  the
         --group-albums option to split the files based on their metadata before matching them as
         separate albums.

       • If  you want to preview which files would be imported, use the --pretend option. If set,
         beets will just print a list of files that it would otherwise import.

       • If you already have a metadata backend ID that matches the items to be imported, you can
         instruct  beets  to  restrict  the  search  to  that  ID  instead of searching for other
         candidates by using the --search-id SEARCH_ID option.  Multiple IDs can be specified  by
         simply repeating the option several times.

       • You  can supply --set field=value to assign field to value on import.  These assignments
         will merge with (and possibly override) the set_fields configuration dictionary. You can
         use the option multiple times on the command line, like so:

            beet import --set genre="Alternative Rock" --set mood="emotional"

          beet list [-apf] QUERY

       Queries the database for music.

       Want  to search for “Gronlandic Edit” by of Montreal? Try beet list gronlandic.  Maybe you
       want to see everything released in 2009 with “vegetables” in  the  title?  Try  beet  list
       year:2009 title:vegetables. You can also specify the sort order. (Read more in query.)

       You can use the -a switch to search for albums instead of individual items.  In this case,
       the queries you use are restricted to album-level fields: for example, you can search  for
       year:1969  but  query parts for item-level fields like title:foo will be ignored. Remember
       that artist is an item-level field; albumartist is the corresponding album field.

       The -p option makes beets print out filenames of matched items, which might be useful  for
       piping into other Unix commands (such as xargs). Similarly, the -f option lets you specify
       a specific format with which to print every album or track. This uses  the  same  template
       syntax  as beets’ path formats. For example, the command beet ls -af '$album: $albumtotal'
       beatles prints out the number of tracks on each Beatles album. In Unix shells, remember to
       enclose the template argument in single quotes to avoid environment variable expansion.

          beet remove [-adf] QUERY

       Remove music from your library.

       This  command uses the same query syntax as the list command.  By default, it just removes
       entries from the library database; it doesn’t touch the files on disk. To actually  delete
       the  files,  use  the  -d flag.  When the -a flag is given, the command operates on albums
       instead of individual tracks.

       When you run the remove command, it prints a list of all affected items in the library and
       asks  for  your  permission  before  removing them. You can then choose to abort (type n),
       confirm (y), or interactively choose some of the  items  (s).  In  the  latter  case,  the
       command  will  prompt  you  for  every  matching item or album and invite you to type y to
       remove the item/album, n to keep it or q to exit and only remove the items/albums selected
       up  to  this  point.   This option lets you choose precisely which tracks/albums to remove
       without spending too much time to carefully craft a query.  If  you  do  not  want  to  be
       prompted at all, use the -f option.

          beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...]

       Change the metadata for items or albums in the database.

       Supply  a  query matching the things you want to change and a series of field=value pairs.
       For example, beet modify genius of love artist="Tom Tom Club" will change the  artist  for
       the  track  “Genius  of  Love.”   To  remove  fields  (which is only possible for flexible
       attributes), follow a field name with an exclamation point: field!.

       The -a switch operates on albums instead of individual  tracks.  Without  this  flag,  the
       command  will  only  change  track-level  data,  even if all the tracks belong to the same
       album. If you want to change an album-level field, such as  year  or  albumartist,  you’ll
       want  to  use  the  -a  flag  to avoid a confusing situation where the data for individual
       tracks conflicts with the data for the whole album.

       Items will automatically be moved  around  when  necessary  if  they’re  in  your  library
       directory,  but you can disable that with  -M. Tags will be written to the files according
       to the settings you have for imports, but these can be overridden with -w (write tags, the
       default) and -W (don’t write tags).

       When you run the modify command, it prints a list of all affected items in the library and
       asks for your permission before making any changes. You  can  then  choose  to  abort  the
       change (type n), confirm (y), or interactively choose some of the items (s). In the latter
       case, the command will prompt you for every matching item or album and invite you to  type
       y  to  apply  the  changes, n to discard them or q to exit and apply the selected changes.
       This option lets you choose precisely which data to change without spending too much  time
       to carefully craft a query. To skip the prompts entirely, use the -y option.

          beet move [-capt] [-d DIR] QUERY

       Move or copy items in your library.

       This  command,  by  default,  acts as a library consolidator: items matching the query are
       renamed into your library directory structure. By specifying a destination directory  with
       -d  manually,  you  can  move  items  matching a query anywhere in your filesystem. The -c
       option copies files instead of moving them. As with other commands, the -a option  matches
       albums  instead  of  items.   The -e flag (for “export”) copies files without changing the

       To perform a “dry run”, just use the -p (for “pretend”) flag. This will show you a list of
       files  that  would be moved but won’t actually change anything on disk. The -t option sets
       the timid mode which will ask again before really moving or copying the files.

          beet update [-F] FIELD [-aM] QUERY

       Update the library (and, by default, move files) to reflect out-of-band  metadata  changes
       and file deletions.

       This will scan all the matched files and read their tags, populating the database with the
       new values. By default, files will be renamed according to  their  new  metadata;  disable
       this  with  -M. Beets will skip files if their modification times have not changed, so any
       out-of-band metadata changes must also update these for beet update to recognise that  the
       files have been edited.

       To perform a “dry run” of an update, just use the -p (for “pretend”) flag.  This will show
       you all the proposed changes but won’t actually change anything on disk.

       By default, all the changed metadata will be populated back to the database.  If you  only
       want  certain  fields  to  be written, specify them with the `-F` flags (which can be used
       multiple times). For the list of supported fields, please see `beet fields`.

       When an updated track is part of an album, the album-level fields of all tracks  from  the
       album  are also updated. (Specifically, the command copies album-level data from the first
       track on the album and applies it to  the  rest  of  the  tracks.)  This  means  that,  if
       album-level  fields  aren’t  identical  within  an album, some changes shown by the update
       command may be overridden by data from other tracks on the same  album.  This  means  that
       running the update command multiple times may show the same changes being applied.

          beet write [-pf] [QUERY]

       Write metadata from the database into files’ tags.

       When  you make changes to the metadata stored in beets’ library database (during import or
       with the modify command, for example), you often have the option of storing  changes  only
       in  the  database,  leaving  your files untouched. The write command lets you later change
       your mind and write the contents of the database into the files. By default,  this  writes
       the changes only if there is a difference between the database and the tags in the file.

       You can think of this command as the opposite of update.

       The -p option previews metadata changes without actually applying them.

       The  -f  option forces a write to the file, even if the file tags match the database. This
       is useful for making sure that enabled plugins that run on write (e.g., the Scrub and Zero
       plugins) are run on the file.

          beet stats [-e] [QUERY]

       Show  some statistics on your entire library (if you don’t provide a query) or the matched
       items (if you do).

       By default, the command calculates file sizes using their bitrate  and  duration.  The  -e
       (--exact)  option  reads the exact sizes of each file (but is slower). The exact mode also
       outputs the exact duration in seconds.

          beet fields

       Show the item and album metadata fields available for use in  query  and  pathformat.  The
       listing  includes  any  template  fields  provided  by plugins and any flexible attributes
       you’ve manually assigned to your items and albums.

          beet config [-pdc]
          beet config -e

       Show or edit the user configuration. This command does one of three things:

       • With no options, print a YAML representation of the current user configuration. With the
         --default option, beets’ default options are also included in the dump.

       • The  --path  option  instead  shows  the  path  to your configuration file.  This can be
         combined with the --default flag to show where beets keeps its internal defaults.

       • By  default,  sensitive  information  like  passwords  is  removed  when   dumping   the
         configuration. The --clear option includes this sensitive data.

       • With  the  --edit  option, beets attempts to open your config file for editing. It first
         tries the $EDITOR environment variable and then a  fallback  option  depending  on  your
         platform: open on OS X, xdg-open on Unix, and direct invocation on Windows.


       Beets  has  a  few  “global” flags that affect all commands. These must appear between the
       executable name (beet) and the command—for example, beet -v import ....

       • -l LIBPATH: specify the library database file to use.

       • -d DIRECTORY: specify the library root directory.

       • -v: verbose mode; prints out a deluge of debugging information.  Please  use  this  flag
         when reporting bugs. You can use it twice, as in -vv, to make beets even more verbose.

       • -c  FILE:  read  a  specified  YAML  configuration  file. This configuration works as an
         overlay: rather than replacing your normal configuration options entirely, the  two  are
         merged.  Any  individual options set in this config file will override the corresponding
         settings in your base configuration.

       • -p plugins: specify a comma-separated list of  plugins  to  enable.  If  specified,  the
         plugin list in your configuration is ignored. The long form of this argument also allows
         specifying no plugins, effectively disabling all plugins: --plugins=.

       Beets also uses the BEETSDIR environment variable to look for configuration and data.


       Beets includes support for shell command completion. The command  beet  completion  prints
       out  a  bash  3.2  script;  to enable completion put a line like this into your .bashrc or
       similar file:

          eval "$(beet completion)"

       Or, to avoid slowing down your shell startup time, you can pipe the beet completion output
       to a file and source that instead.

       You  will  also need to source the bash-completion script, which is probably available via
       your package manager. On OS  X,  you  can  install  it  via  Homebrew  with  brew  install
       bash-completion; Homebrew will give you instructions for sourcing the script.

       The  completion  script  suggests names of subcommands and (after typing -) options of the
       given command. If you are using a command that accepts  a  query,  the  script  will  also
       complete field names.

          beet list ar[TAB]
          # artist:  artist_credit:  artist_sort:  artpath:
          beet list artp[TAB]
          beet list artpath\:

       (Don’t  worry  about  the  slash  in front of the colon: this is a escape sequence for the
       shell and won’t be seen by beets.)

       Completion of plugin commands only works for those plugins that were enabled when  running
       beet completion. If you add a plugin later on you will want to re-generate the script.

       If you use zsh, take a look at the included completion script. The script should be placed
       in a directory that is part of your fpath, and not sourced in your  .zshrc.  Running  echo
       $fpath will give you a list of valid directories.

       Another  approach is to use zsh’s bash completion compatibility. This snippet defines some
       bash-specific functions to make this work without errors:

          autoload bashcompinit
          _get_comp_words_by_ref() { :; }
          compopt() { :; }
          _filedir() { :; }
          eval "$(beet completion)"




       Adrian Sampson


       2016, Adrian Sampson