Difference between revisions of "MusicBrainz Picard/Plugins/API"

From MusicBrainz Wiki
(Add itemviews action plugins.)
(Redirect to new API docs home on Picard website)
(Tag: New redirect)
 
Line 1: Line 1:
API documentation for [[MusicBrainz Picard]] plugins.
+
#REDIRECT [[picard:docs/plugin-api/]]
 
 
==Metadata Processors==
 
 
 
MusicBrainz metadata can be post-processed at two levels, album and track.
 
 
 
Album metadata example:
 
 
 
<pre>
 
    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)
 
</pre>
 
 
 
Track metadata example:
 
 
 
<pre>
 
    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)
 
</pre>
 
 
 
==File Formats==
 
 
 
Example:
 
 
 
<pre>
 
    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)
 
</pre>
 
 
 
==Tagger Script Functions==
 
 
 
To define new [[Picard Qt/Scripting|tagger script]] function use <code><nowiki>register_script_function(function, name=None)</nowiki></code> from module <code><nowiki>picard.script</nowiki></code>.
 
 
 
Example:
 
 
 
<pre>
 
    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)
 
</pre>
 
 
 
<code><nowiki>register_script_function</nowiki></code> 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:
 
 
 
<pre>
 
    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())
 
</pre>
 
 
 
Use register_x_action where x is album, track, file, cluster or clusterlist.
 
 
 
[[Category:MusicBrainz Picard]]
 

Latest revision as of 17:40, 8 July 2019