Listen for Events

Event handlers allow plugins to hook into whenever something happens in beets’ operations. For instance, a plugin could write a log message every time an album is successfully autotagged or update MPD’s index whenever the database is changed.

You can “listen” for events using BeetsPlugin.register_listener(). Here’s an example:

from beets.plugins import BeetsPlugin


def loaded():
    print("Plugin loaded!")


class SomePlugin(BeetsPlugin):
    def __init__(self):
        super().__init__()
        self.register_listener("pluginload", loaded)

Note that if you want to access an attribute of your plugin (e.g. config or log) you’ll have to define a method and not a function. Here is the usual registration process in this case:

from beets.plugins import BeetsPlugin


class SomePlugin(BeetsPlugin):
    def __init__(self):
        super().__init__()
        self.register_listener("pluginload", self.loaded)

    def loaded(self):
        self._log.info("Plugin loaded!")

Plugin Events

pluginload

Parameters:

(none)

Description:

Called after all plugins have been loaded after the beet command starts.

import

Parameters:

lib (Library), paths (list of byte paths)

Description:

Called after the import command finishes.

album_imported

Parameters:

lib (Library), album (Album)

Description:

Called every time the importer finishes adding an album to the library.

album_removed

Parameters:

album (Album)

Description:

Called every time an album is removed from the library (even when its files are not deleted from disk).

art_set

Parameters:

album (Album)

Description:

Called after cover art is copied or moved into place for an album.

item_copied

Parameters:

item (Item), source (path), destination (path)

Description:

Called whenever an item file is copied.

item_imported

Parameters:

lib (Library), item (Item)

Description:

Called every time the importer adds a singleton to the library (not called for full-album imports).

before_item_moved

Parameters:

item (Item), source (path), destination (path)

Description:

Called with an Item object immediately before its file is moved.

item_moved

Parameters:

item (Item), source (path), destination (path)

Description:

Called with an Item object whenever its file is moved.

item_linked

Parameters:

item (Item), source (path), destination (path)

Description:

Called with an Item object whenever a symlink is created for a file.

item_hardlinked

Parameters:

item (Item), source (path), destination (path)

Description:

Called with an Item object whenever a hardlink is created for a file.

item_reflinked

Parameters:

item (Item), source (path), destination (path)

Description:

Called with an Item object whenever a reflink is created for a file.

item_removed

Parameters:

item (Item)

Description:

Called with an Item object every time an item (singleton or part of an album) is removed from the library (even when its file is not deleted from disk).

write

Parameters:

item (Item), path (path), tags (dict)

Description:

Called just before a file’s metadata is written to disk. Handlers may modify tags or raise library.FileOperationError to abort.

after_write

Parameters:

item (Item), path (path)

Description:

Called after a file’s metadata is written to disk.

import_task_created

Parameters:

task (ImportTask), session (ImportSession)

Description:

Called immediately after an import task is initialized. May return a list (possibly empty) of replacement tasks.

import_task_start

Parameters:

task (ImportTask), session (ImportSession)

Description:

Called before an import task begins processing.

import_task_apply

Parameters:

task (ImportTask), session (ImportSession)

Description:

Called after metadata changes have been applied in an import task (on the UI thread; keep fast). Prefer a pipeline stage otherwise (see Add Import Pipeline Stages).

import_task_before_choice

Parameters:

task (ImportTask), session (ImportSession)

Description:

Called after candidate search and before deciding how to import. May return an importer action (only one handler may return non-None).

import_task_choice

Parameters:

task (ImportTask), session (ImportSession)

Description:

Called after a decision has been made about an import task. Use task.choice_flag to inspect or change the action.

import_task_files

Parameters:

task (ImportTask), session (ImportSession)

Description:

Called after filesystem manipulation (copy/move/write) for an import task.

library_opened

Parameters:

lib (Library)

Description:

Called after beets starts and initializes the main Library object.

database_change

Parameters:

lib (Library), model (Album or Item)

Description:

A modification has been made to the library database (may not yet be committed).

cli_exit

Parameters:

lib (Library)

Description:

Called just before the beet command-line program exits.

import_begin

Parameters:

session (ImportSession)

Description:

Called just before a beet import session starts.

trackinfo_received

Parameters:

info (beets.autotag.hooks.TrackInfo)

Description:

Called after metadata for a track is fetched (e.g., from MusicBrainz). Handlers can modify the tags seen by later pipeline stages or adjustments (e.g., mbsync).

albuminfo_received

Parameters:

info (beets.autotag.hooks.AlbumInfo)

Description:

Like trackinfo_received but for album-level metadata.

album_matched

Parameters:

match (AlbumMatch)

Description:

Called each time an AlbumMatch candidate is created while importing. This applies to both ID-driven and text-search matching. Missing and extra tracks, if any, are included in the match.

before_choose_candidate

Parameters:

task (ImportTask), session (ImportSession)

Description:

Called before prompting the user during interactive import. May return a list of PromptChoices to append to the prompt (see Append Prompt Choices).

mb_track_extract

Parameters:

data (dict)

Description:

Called after metadata is obtained from MusicBrainz for a track. Must return a (possibly empty) dict of additional field: value pairs to apply (overwriting existing fields).

mb_album_extract

Parameters:

data (dict)

Description:

Like mb_track_extract but for album tags. Overwrites tags set at the track level with the same field.

after_convert

Parameters:

item (Item), dest (path), keepnew (bool)

Description:

Called by the Convert Plugin plugin after it successfully converts or copies an item. When keepnew is false, dest is the converted file. When keepnew is true, dest is where the original file was moved and item.path identifies the converted file retained in the library.

smartplaylist_update

Parameters:

(none)

Description:

Called by the Smart Playlist Plugin plugin after it writes updated playlist files. It is not called in pretend mode.

The included mpdupdate plugin provides an example use case for event listeners.