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.


Get a sorted list of Item objects matching the given query.


Get a sorted list of Album objects matching the given 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 object to the library database. The item’s id field will be updated; the new id is returned.


Create a new album in the database with metadata derived from its items. The items are added to the database if they don’t yet have an ID. Returns an Album object.


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.library.Transaction(lib)

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 base classes that provide generic data storage. The LibModel class inherits from FlexModel, and both Item and Album inherit from it.

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

class beets.library.FlexModel(**values)

An abstract object that consists of a set of “fast” (fixed) fields and an arbitrary number of flexible fields.

get(key, default=None)

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


Get all the keys (both fixed and flex) on this object.


Assign all values in the given dict.

class beets.library.LibModel(lib=None, **values)

A model base class that includes a reference to a Library object. It knows how to load and store itself from the database.


Refresh the object’s metadata from the library database.


Remove the object’s associated rows from the database.


Save the object’s metadata into the library database.


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

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

destination(pathmod=None, 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.

evaluate_template(template, sanitize=False, pathmod=None)

Evaluates a Template object using the item’s fields. If sanitize, then each value will be sanitized for inclusion in a file path.

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, basedir=None, with_album=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.

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

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.

move_file(dest, copy=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.

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.


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


Writes the item’s metadata to the associated file.


class beets.library.Album(lib=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.


Evaluates a Template object using the album’s fields.


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


Returns an iterable over the items associated with this album.

move(copy=False, basedir=None)

Moves (or copies) all items to their destination. Any album art moves along with them. basedir overrides the library base directory for the destination. The album is stored to the database, persisting any modifications to its metadata.


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.


Update the database with the album information. The album’s tracks are also updated.