MusicBrainz Picard/Plugins/API

API documentation for MusicBrainz Picard plugins.

Metadata Processors

MusicBrainz metadata can be post-processed at two levels, album and track.

Album metadata example:

    1  PLUGIN_NAME = "Disc Numbers"
    2  PLUGIN_AUTHOR = "Lukas Lalinsky"
    3  PLUGIN_DESCRIPTION = "Moves disc numbers from album titles to tags."
    4  
    5  from picard.metadata import register_album_metadata_processor
    6  import re
    7  
    8  def remove_discnumbers(metadata, release):
    9      matches = re.search(r"\(disc (\d+)\)", metadata["album"])
   10      if matches:
   11          metadata["discnumber"] = matches.group(1)
   12          metadata["album"] = re.sub(r"\(disc \d+\)", "", metadata["album"])
   13  
   14  register_album_metadata_processor(remove_discnumbers)

Track metadata example:

    1  PLUGIN_NAME = "Feat. Artists"
    2  PLUGIN_AUTHOR = "Lukas Lalinsky"
    3  PLUGIN_DESCRIPTION = "Removes feat. artists from track titles."
    4  
    5  from picard.metadata import register_track_metadata_processor
    6  import re
    7  
    8  def remove_featartists(metadata, release, track):
    9      metadata["title"] = re.sub(r"\(feat. [^)]*\)", "", metadata["title"])
   10  
   11  register_track_metadata_processor(remove_featartists)

File Formats

Example:

    1  PLUGIN_NAME = "..."
    2  PLUGIN_AUTHOR = "..."
    3  PLUGIN_DESCRIPTION = "..."
    4  
    5  from picard.file import File
    6  from picard.formats import register_format
    7  
    8  class MyFile(File):
    9      EXTENSIONS = [".foo"]
   10      NAME = "Foo Audio"
   11      def read(self):
   12          ....
   13      def save(self):
   14          ....
   15  
   16  register_format(MyFile)

Tagger Script Functions

To define new tagger script function use register_script_function(function, name=None) from module picard.script.

Example:

    1  PLUGIN_NAME = "Initials"
    2  PLUGIN_AUTHOR = "Lukas Lalinsky"
    3  PLUGIN_DESCRIPTION = "Provides tagger script function $initials(text)."
    4  
    5  from picard.script import register_script_function
    6  
    7  def initials(parser, text):
    8      return "".join(a[:1] for a in text.split(" ") if a[:1].isalpha())
    9  
   10  register_script_function(initials)

register_script_function supports two optional arguments:

• eval_args: If this is False, the arguments will not be evaluated before being passed to function.
• check_argcount: If this is False the number of arguments passed to the function will not be verified.

The default value for both of them is True.

Context Menu Actions

Right-click context menu actions can be added to albums, tracks, files in Unmatched Files, Clusters and the ClusterList (parent folder of Clusters).

Example:

    1  PLUGIN_NAME = u'Remove Perfect Albums'
    2  PLUGIN_AUTHOR = u'ichneumon, hrglgrmpf'
    3  PLUGIN_DESCRIPTION = u'''Remove all perfectly matched albums from the selection.'''
    4  PLUGIN_VERSION = '0.2'
    5  PLUGIN_API_VERSIONS = ['0.15']
    6  
    7  from picard.album import Album
    8  from picard.ui.itemviews import BaseAction, register_album_action
    9  
   10  class RemovePerfectAlbums(BaseAction):
   12      NAME = 'Remove perfect albums'
   13  
   14      def callback(self, objs):
   15          for album in objs:
   16              if isinstance(album, Album) and album.is_complete() and album.get_num_unmatched_files() == 0\
   17                 and album.get_num_matched_tracks() == len(list(album.iterfiles()))\
   18                 and album.get_num_unsaved_files() == 0 and album.loaded == True:
   19                  self.tagger.remove_album(album)
   20  
   21  register_album_action(RemovePerfectAlbums())

Use register_x_action where x is album, track, file, cluster or clusterlist.