BEET(1) beets BEET(1)NAMEbeet - music tagger and library organizer
SYNOPSISbeet [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 com‐
pressed 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 inter‐
active 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 com‐
mand.
Optional command flags:
· By default, the command copies files your the library directory and
updates the ID3 tags on your music. 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 config‐
uration 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 auto‐
tagging 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 subdirecto‐
ries will be skipped. So consider enabling the incremental configura‐
tion 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 single‐
ton 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 meta‐
data before matching them as separate albums.
· If you want to preview which files would be imported, use the --pre‐
tend option. If set, beets will just print a list of files that it
would otherwise import.
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:
$tracktotal' 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 [-ad] QUERY
Remove music from your library.
This command uses the same query syntax as the list command. You'll be
shown a list of the files that will be removed and asked to confirm.
By default, this just removes entries from the library database; it
doesn't touch the files on disk. To actually delete the files, use beet
remove -d.
modify
beet modify [-MWay] 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. 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 writ‐
ten 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). Finally, this command politely asks for your permission
before making any changes, but you can skip that prompt with the -y
switch.
move
beet move [-cap] [-d DIR] QUERY
Move or copy items in your library.
This command, by default, acts as a library consolidator: items match‐
ing 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.
To perform a "dry run", just use the -p (for "pretend") flag. This will
show you all how the files would be moved but won't actually change
anything on disk.
update
beet update [-aM] QUERY
Update the library (and, optionally, 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.
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 com‐
mand 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 sec‐
onds.
fields
beet fields
Show the item and album metadata fields available for use in query and
pathformat. Includes any template fields provided by plugins.
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 con‐
figuration. 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 exam‐
ple, 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.
Beets also uses the BEETSDIR environment variable to look for configu‐
ration 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 prob‐
ably 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.
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)"
SEE ALSO
http://beets.readthedocs.org/
beetsconfig(5)AUTHOR
Adrian Sampson
COPYRIGHT
2012, Adrian Sampson
1.3 October 17, 2015 BEET(1)
