Ubuntu Manpage: beet - music tagger and library organizer

NAME

       beet - music tagger and library organizer

SYNOPSIS

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

COMMANDS

import
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"

list
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.

remove
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.

modify
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.

move
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
database.

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.

update
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.

write
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.

stats
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.

fields
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.

config
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.

GLOBAL FLAGS

       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.

SHELL COMPLETION

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.

zsh
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
bashcompinit
_get_comp_words_by_ref() { :; }
compopt() { :; }
_filedir() { :; }
eval "$(beet completion)"

AUTHOR

       Adrian Sampson

COPYRIGHT

       2016, Adrian Sampson