Merge pull request #1499 from m-urban/tag-change-hook

#872: Tag change hooks

beets/autotag/hooks.py

@@ -511,7 +511,10 @@ def album_for_mbid(release_id):
     if the ID is not found.
     """
     try:
-        return mb.album_for_id(release_id)
+        album = mb.album_for_id(release_id)
+        if album:
+            plugins.send('albuminfo_received', info=album)
+        return album
     except mb.MusicBrainzAPIError as exc:
         exc.log(log)
 
@@ -521,22 +524,31 @@ def track_for_mbid(recording_id):
     if the ID is not found.
     """
     try:
-        return mb.track_for_id(recording_id)
+        track = mb.track_for_id(recording_id)
+        if track:
+            plugins.send('trackinfo_received', info=track)
+        return track
     except mb.MusicBrainzAPIError as exc:
         exc.log(log)
 
 
 def albums_for_id(album_id):
     """Get a list of albums for an ID."""
     candidates = [album_for_mbid(album_id)]
-    candidates.extend(plugins.album_for_id(album_id))
+    plugin_albums = plugins.album_for_id(album_id)
+    for a in plugin_albums:
+        plugins.send('albuminfo_received', info=a)
+    candidates.extend(plugin_albums)
     return filter(None, candidates)
 
 
 def tracks_for_id(track_id):
     """Get a list of tracks for an ID."""
     candidates = [track_for_mbid(track_id)]
-    candidates.extend(plugins.track_for_id(track_id))
+    plugin_tracks = plugins.track_for_id(track_id)
+    for t in plugin_tracks:
+        plugins.send('trackinfo_received', info=t)
+    candidates.extend(plugin_tracks)
     return filter(None, candidates)
 
 
@@ -566,6 +578,10 @@ def album_candidates(items, artist, album, va_likely):
     # Candidates from plugins.
     out.extend(plugins.candidates(items, artist, album, va_likely))
 
+    # Notify subscribed plugins about fetched album info
+    for a in out:
+        plugins.send('albuminfo_received', info=a)
+
     return out
 
 
@@ -586,4 +602,8 @@ def item_candidates(item, artist, title):
     # Plugin candidates.
     out.extend(plugins.item_candidates(item, artist, title))
 
+    # Notify subscribed plugins about fetched track info
+    for i in out:
+        plugins.send('trackinfo_received', info=i)
+
     return out

docs/changelog.rst

@@ -128,6 +128,10 @@ The new features:
   :bug:`1104` :bug:`1493`
 * :doc:`/plugins/plexupdate`: A new ``token`` configuration option lets you
   specify a key for Plex Home setups. Thanks to :user:`edcarroll`. :bug:`1494`
+* :doc:`/dev/plugins`: New hooks ``albuminfo_received`` and
+  ``trackinfo_received`` have been added for developers who would like to
+  intercept fetched meta data, before they are applied in tag manipulation
+  operations. :bug:`872`
 
 Fixes:
 

docs/dev/plugins.rst

@@ -214,6 +214,19 @@ The events currently available are:
 * *import_begin*: called just before a ``beet import`` session starts up.
   Parameter: ``session``.
 
+* *trackinfo_received*: called after meta data for a track item has been fetched
+  from disparate sources, such as MusicBrainz. Gives a developer the option to
+  intercept the fetched ``TrackInfo`` object. Can be used to modify tags on a
+  ``beet import`` operation or during later adjustments, such as ``mbsync``.
+  Slow handlers of the event can impact the operation, since the event is fired
+  for any fetched possible match *before* user or autotagger selection was made.
+  Parameter: ``info``.
+
+* *albuminfo_received*: Like *trackinfo_received*, the event indicates new meta
+  data for album items, but supplies an ``AlbumInfo`` object instead of a
+  ``TrackInfo``.
+  Parameter: ``info``.
+
 The included ``mpdupdate`` plugin provides an example use case for event listeners.
 
 Extend the Autotagger