Skip to main content
`Ctrl`+`K`

# 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`(event, func) | 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: EventType, func: Listener) → 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.