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


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)

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.



Project Versions

Table Of Contents

Previous topic

Writing Plugins

Next topic


This Page