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 autotaggingguide
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. You can later review the file manually or import
skipped paths from the logfile automatically by using the --from-logfileLOGFILE argument.
• 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
performs a fallback action that can be configured using the quiet_fallback configuration or
--quiet-fallback CLI option. By default it pessimistically skip``sthefile.Alternatively,itcanbeusedasis,byconfiguring``asis.
• 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 everytime 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.
• If you don’t want to record skipped files during an incremental import, use the
--incremental-skip-later flag which corresponds to the incremental_skip_later configuration option.
Setting the flag prevents beets from persisting skip decisions during a non-interactive import so that
a user can make a decision regarding previously skipped files during a subsequent interactive import
run. To record skipped files during incremental import explicitly, use the --noincremental-skip-later
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-idSEARCH_ID option. Multiple IDs can be specified by simply repeating the option several times.
• You can supply --setfield=value to assign field to value on import. Values support the same template
syntax as beets’ pathformats. 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 beetlistgronlandic. Maybe you want to see
everything released in 2009 with “vegetables” in the title? Try beetlistyear:2009title:vegetables. You
can also specify the sort order. (Read more in Queries.)
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’ pathformats. For
example, the command beetls-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 [-IMWay] [-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,
beetmodifygeniusofloveartist="TomTomClub" 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!.
Values can also be templates, using the same syntax as pathformats. For example, beetmodifyartist='$artist_sort' will copy the artist sort name into the artist field for all your tracks, and beetmodifytitle='$track$title' will add track numbers to their title metadata.
The -a option changes to querying album fields instead of track fields and also enables to operate on
albums in addition to the 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.
Modifications issued using -a by default cascade to individual tracks. To prevent this behavior, use
-I/--noinherit.
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 [-e] EXCLUDE_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 beetupdate 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). Alternatively,
specify fields to not write with `-e` flags (which can be used multiple times). For the list of supported
fields, please see `beetfields`.
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 Queries and PathFormats. 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, followed by $EDITOR and then a fallback option depending on your platform: open
on OS X, xdg-open on Unix, and direct invocation on Windows.
Install Now
PNG Icons
