BeetsPlugin

class beets.plugins.BeetsPlugin(name: str | None = None)

Bases: object

The base class for all beets plugins. Plugins provide functionality by defining a subclass of BeetsPlugin and overriding the abstract methods defined here.

__init__(name: str | None = None)

Perform one-time plugin setup.

Public methods summary

add_media_field(name, descriptor)	Add a field that is synchronized between media files and items.
commands()	Should return a list of beets.ui.Subcommand objects for commands that should be added to beets' CLI.
get_early_import_stages()	Return a list of functions that should be called as importer pipelines stages early in the pipeline.
get_import_stages()	Return a list of functions that should be called as importer pipelines stages.
queries()	Return a dict mapping prefixes to Query subclasses.
register_listener()	Add a function as a listener for the specified event.
template_field(name)	Decorator that registers a path template field computation.
template_func(name)	Decorator that registers a path template function.

Methods definition

commands() → Sequence[Subcommand]

Should return a list of beets.ui.Subcommand objects for commands that should be added to beets’ CLI.

get_early_import_stages() → list[ImportStageFunc]

Return a list of functions that should be called as importer pipelines stages early in the pipeline.

The callables are wrapped versions of the functions in self.early_import_stages. Wrapping provides some bookkeeping for the plugin: specifically, the logging level is adjusted to WARNING.

get_import_stages() → list[ImportStageFunc]

Return a list of functions that should be called as importer pipelines stages.

The callables are wrapped versions of the functions in self.import_stages. Wrapping provides some bookkeeping for the plugin: specifically, the logging level is adjusted to WARNING.

queries() → dict[str, FieldQueryType]

Return a dict mapping prefixes to Query subclasses.

add_media_field(name: str, descriptor: MediaField) → None

Add a field that is synchronized between media files and items.

When a media field is added item.write() will set the name property of the item’s MediaFile to item[name] and save the changes. Similarly item.read() will set item[name] to the value of the name property of the media file.

register_listener(event: events.AfterWriteEventType, func: Callable[[Unpack[events.AfterWriteEventArgs]], None]) → None

register_listener(event: events.ItemPathEventType, func: Callable[[Unpack[events.ItemPathEventArgs]], None]) → None

register_listener(event: events.BeforeChooseCandidateEventType, func: Callable[[Unpack[events.ImportTaskEventArgs]], list[PromptChoice]]) → None

register_listener(event: events.ImportTaskBeforeChoiceEventType, func: Callable[[Unpack[events.ImportTaskEventArgs]], Action | None]) → None

register_listener(event: events.ImportTaskCreatedEventType, func: Callable[[Unpack[events.ImportTaskEventArgs]], list[ImportTask] | None]) → None

register_listener(event: events.ImportTaskEventType, func: Callable[[Unpack[events.ImportTaskEventArgs]], None]) → None

register_listener(event: events.ImportEventType, func: Callable[[Unpack[events.ImportEventArgs]], None]) → None

register_listener(event: events.AlbumImportedEventType, func: Callable[[Unpack[events.AlbumImportedEventArgs]], None]) → None

register_listener(event: events.AlbumEventType, func: Callable[[Unpack[events.AlbumEventArgs]], None]) → None

register_listener(event: events.AlbumInfoReceivedEventType, func: Callable[[Unpack[events.AlbumInfoReceivedEventArgs]], None]) → None

register_listener(event: events.TrackInfoReceivedEventType, func: Callable[[Unpack[events.TrackInfoReceivedEventArgs]], None]) → None

register_listener(event: events.AlbumMatchedEventType, func: Callable[[Unpack[events.AlbumMatchedEventArgs]], None]) → None

register_listener(event: events.LibraryEventType, func: Callable[[Unpack[events.LibraryEventArgs]], None]) → None

register_listener(event: events.DatabaseChangeEventType, func: Callable[[Unpack[events.DatabaseChangeEventArgs]], None]) → None

register_listener(event: events.ImportBeginEventType, func: Callable[[Unpack[events.ImportBeginEventArgs]], None]) → None

register_listener(event: events.ItemImportedEventType, func: Callable[[Unpack[events.ItemImportedEventArgs]], None]) → None

register_listener(event: events.ItemEventType, func: Callable[[Unpack[events.ItemEventArgs]], None]) → None

register_listener(event: events.WriteEventType, func: Callable[[Unpack[events.WriteEventArgs]], None]) → None

register_listener(event: events.MusicBrainzExtractEventType, func: Callable[[Unpack[events.MusicBrainzExtractEventArgs]], None]) → None

register_listener(event: events.NoArgsEventType, func: Callable[[], None]) → None

register_listener(event: events.AfterConvertEventType, func: Callable[[Unpack[events.AfterConvertEventArgs]], None]) → None

Add a function as a listener for the specified event.

classmethod template_func(name: str) → Callable[[TFunc[str]], TFunc[str]]

Decorator that registers a path template function. The function will be invoked as %name{} from path format strings.

classmethod template_field(name: str) → Callable[[TFunc[Item]], TFunc[Item]]

Decorator that registers a path template field computation. The value will be referenced as $name from path format strings. The function must accept a single parameter, the Item being formatted.