1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
.. _plugin_events:
Listen for Events
=================
.. currentmodule:: beets.plugins
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 :py:meth:`BeetsPlugin.register_listener`.
Here's an example:
.. code-block:: python
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:
.. code-block:: python
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!")
.. rubric:: 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 path strings)
: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: ``lib`` (|Library|), ``album`` (|Album|)
:Description: Called every time an album is removed from the library (even
when its files are not deleted from disk).
``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_imported``
:Parameters: ``item`` (|Item|), ``source`` (path), ``destination`` (path)
:Description: Called with an ``Item`` object immediately before it is
imported.
``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|)
: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 :ref:`plugin-stage`).
``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`` (|Model|)
: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`` (|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`` (|AlbumInfo|)
:Description: Like ``trackinfo_received`` but for album-level metadata.
``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
:ref:`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.
The included ``mpdupdate`` plugin provides an example use case for event
listeners.
|
