API Documentation

This page describes the internal API of beets’ core. It’s a work in progress—since beets is an application first and a library second, its API has been mainly undocumented until recently. Please file bugs if you run across incomplete or incorrect docs here.

The Library object is the central repository for data in beets. It represents a database containing songs, which are Item instances, and groups of items, which are Album instances.

The Library Class

class beets.library.Library(path, directory[, path_formats[, replacements]])

A database of music containing songs and albums.

items(query=None, sort=None)

Get Item objects matching the query.

albums(query=None, sort=None)

Get Album objects matching the query.


Fetch an Item by its ID. Returns None if no match is found.


Given an album ID or an item associated with an album, return an Album object for the album. If no such album exists, returns None.


Add the Item or Album object to the library database. Return the object’s new id.


Create a new album consisting of a list of items.

The items are added to the database if they don’t yet have an ID. Return a new Album object. The list items must not be empty.


Get a Transaction object for interacting directly with the underlying SQLite database.


The Library class provides the basic methods necessary to access and manipulate its contents. To perform more complicated operations atomically, or to interact directly with the underlying SQLite database, you must use a transaction. For example:

lib = Library()
with lib.transaction() as tx:
    items = lib.items(query)
class beets.dbcore.db.Transaction(db)

A context manager for safe, concurrent access to the database. All SQL commands should be executed through a transaction.

mutate(statement, subvals=())

Execute an SQL statement with substitution values and return the row ID of the last affected row.

query(statement, subvals=())

Execute an SQL statement with substitution values and return a list of rows from the database.


Execute a string containing multiple SQL statements.

Model Classes

The two model entities in beets libraries, Item and Album, share a base class, Model, that provides common functionality and ORM-like abstraction.

The fields model classes can be accessed using attributes (dots, as in item.artist) or items (brackets, as in item['artist']). The Model base class provides some methods that resemble dict objects.

Model base

class beets.dbcore.Model(db=None, **values)

An abstract object representing an object in the database. Model objects act like dictionaries (i.e., the allow subscript access like obj['field']). The same field set is available via attribute access as a shortcut (i.e., obj.field). Three kinds of attributes are available:

  • Fixed attributes come from a predetermined list of field names. These fields correspond to SQLite table columns and are thus fast to read, write, and query.
  • Flexible attributes are free-form and do not need to be listed ahead of time.
  • Computed attributes are read-only fields computed by a getter function provided by a plugin.

Access to all three field types is uniform: obj.field works the same regardless of whether field is fixed, flexible, or computed.

Model objects can optionally be associated with a Library object, in which case they can be loaded and stored from the database. Dirty flags are used to track which fields need to be stored.


Add the object to the library database. This object must be associated with a database; you can provide one via the db parameter or use the currently associated database.

The object’s id and added fields are set along with any current field values.

classmethod all_keys()

Get a list of available keys for objects of this type. Includes fixed and computed fields.


Mark all fields as clean (i.e., not needing to be stored to the database).

evaluate_template(template, for_path=False)

Evaluate a template (a string or a Template object) using the object’s fields. If for_path is true, then no new path separators will be added to the template.


Get a mapping containing all values on this object formatted as human-readable unicode strings.

get(key, default=None)

Get the value for a given key or default if it does not exist.


Iterate over (key, value) pairs that this object contains. Computed fields are not included.


Get a list of available field names for this object. The computed parameter controls whether computed (plugin-provided) fields are included in the key list.


Refresh the object’s metadata from the library database.


Remove the object’s associated rows from the database.

set_parse(key, string)

Set the object’s key to a value represented by a string.


Save the object’s metadata into the library database. :param fields: the fields to be stored. If not specified, all fields will be.


Assign all values in the given dict.


class beets.library.Item(db=None, **values)

Returns the current mtime of the file, rounded to the nearest integer.

destination(fragment=False, basedir=None, platform=None, path_formats=None)

Returns the path in the library directory designated for the item (i.e., where the file ought to be). fragment makes this method return just the path fragment underneath the root library directory; the path is also returned as Unicode instead of encoded as a bytestring. basedir can override the library’s base directory for the destination.

classmethod from_path(path)

Creates a new item from the media file at the specified path.


Get the Album object that this item belongs to, if any, or None if the item is a singleton or is not associated with a library.

move(copy=False, link=False, hardlink=False, basedir=None, with_album=True, store=True)

Move the item to its designated location within the library directory (provided by destination()). Subdirectories are created as needed. If the operation succeeds, the item’s path field is updated to reflect the new location.

If copy is true, moving the file is copied rather than moved. Similarly, link creates a symlink instead, and hardlink creates a hardlink.

basedir overrides the library base directory for the destination.

If the item is in an album, the album is given an opportunity to move its art. (This can be disabled by passing with_album=False.)

By default, the item is stored to the database if it is in the database, so any dirty fields prior to the move() call will be written as a side effect. You probably want to call save() to commit the DB transaction. If store is true however, the item won’t be stored, and you’ll have to manually store it after invoking this method.

move_file(dest, copy=False, link=False, hardlink=False)

Moves or copies the item’s file, updating the path value if the move succeeds. If a file exists at dest, then it is slightly modified to be unique.


Read the metadata from the associated file.

If read_path is specified, read metadata from that file instead. Updates all the properties in _media_fields from the media file.

Raises a ReadError if the file could not be read.

remove(delete=False, with_album=True)

Removes the item. If delete, then the associated file is removed from disk. If with_album, then the item’s album (if any) is removed if it the item was the last in the album.


Get the size of the underlying file in bytes.

If the file is missing, return 0 (and log a warning).

try_sync(write, move, with_album=True)

Synchronize the item with the database and, possibly, updates its tags on disk and its path (by moving the file).

write indicates whether to write new tags into the file. Similarly, move controls whether the path should be updated. In the latter case, files are only moved when they are inside their library’s directory (if any).

Similar to calling write(), move(), and store() (conditionally).

try_write(path=None, tags=None)

Calls write() but catches and logs FileOperationError exceptions.

Returns False an exception was caught and True otherwise.


Set all key/value pairs in the mapping. If mtime is specified, it is not reset (as it might otherwise be).

write(path=None, tags=None)

Write the item’s metadata to a media file.

All fields in _media_fields are written to disk according to the values on this object.

path is the path of the mediafile to write the data to. It defaults to the item’s path.

tags is a dictionary of additional metadata the should be written to the file. (These tags need not be in _media_fields.)

Can raise either a ReadError or a WriteError.


class beets.library.Album(db=None, **values)

Provides access to information about albums stored in a library. Reflects the library’s “albums” table, including album art.

art_destination(image, item_dir=None)

Returns a path to the destination for the album art image for the album. image is the path of the image that will be moved there (used for its extension).

The path construction uses the existing path of the album’s items, so the album must contain at least one item or item_dir must be provided.


Returns the directory containing the album’s first item, provided that such an item exists.

item_keys = ['added', 'albumartist', 'albumartist_sort', 'albumartist_credit', 'album', 'genre', 'year', 'month', 'day', 'disctotal', 'comp', 'mb_albumid', 'mb_albumartistid', 'albumtype', 'label', 'mb_releasegroupid', 'asin', 'catalognum', 'script', 'language', 'country', 'albumstatus', 'albumdisambig', 'rg_album_gain', 'rg_album_peak', 'r128_album_gain', 'original_year', 'original_month', 'original_day']

List of keys that are set on an album’s items.


Returns an iterable over the items associated with this album.

move(copy=False, link=False, hardlink=False, basedir=None, store=True)

Moves (or copies) all items to their destination. Any album art moves along with them. basedir overrides the library base directory for the destination. By default, the album is stored to the database, persisting any modifications to its metadata. If store is true however, the album is not stored automatically, and you’ll have to manually store it after invoking this method.

move_art(copy=False, link=False, hardlink=False)

Move or copy any existing album art so that it remains in the same directory as the items.

remove(delete=False, with_items=True)

Removes this album and all its associated items from the library. If delete, then the items’ files are also deleted from disk, along with any album art. The directories containing the album are also removed (recursively) if empty. Set with_items to False to avoid removing the album’s items.

set_art(path, copy=True)

Sets the album’s cover art to the image at the given path. The image is copied (or moved) into place, replacing any existing art.

Sends an ‘art_set’ event with self as the sole argument.


Update the database with the album information. The album’s tracks are also updated. :param fields: The fields to be stored. If not specified, all fields will be.

try_sync(write, move)

Synchronize the album and its items with the database. Optionally, also write any new tags into the files and update their paths.

write indicates whether to write tags to the item files, and move controls whether files (both audio and album art) are moved.