I suspect your problem of it not working is because when the tagging script is run automatically, it uses only the tags retrieved from MusicBrainz and not your custom tag (because the files haven’t yet been matched up to the release in the right-hand window). Once you’ve matched the files, you can manually re-run the tagging script and it should then work. The one thing that I’m not sure about is what point in your workflow the user-defined tag is created.
The following is a draft section from the Picard User Manual that I’m (slowly) developing. Much of the information has been extracted from discussion threads in this Community Forum.
Extending MusicBrainz Picard
There are two primary ways that the functionality of MusicBrainz Picard can be extended: plugins and scripts. Plugins can be installed / uninstalled and enabled / disabled from the Options menu. Installed plugins are loaded during the startup of Picard, and are made available to the program. Scripts are stored within the user settings, and are managed from the Options menu.
Plugins
Plugins are written in Python, and are registered to the appropriate hooks. Each plugin has its own version identifier, but also lists the plugin API versions that it supports. When loading a plugin, Picard first compares its list of API versions to the plugin’s supported versions to ensure that the plugin will operate correctly. The Picard API versions indicate the version of the program in which the plugin API was last updated and any plugin APIs with which it is backwards compatible.
Hooks are connections to the various objects in Picard that call a specific type of plugin. During the normal running of Picard, when it encounters a hook it will first retrieve a list of all plugins registered for that specific hook, and then execute them sequentially in order based upon the priority specified when the plugin was registered to the hook.
There are a few different types of plugins, including:
Metadata processors: These plugins can access and modify the metadata when it is loaded from MusicBrainz. They are registered with register_album_metadata_processor() or register_track_metadata_processor(). These are what you might call “automatic” because they operate without any user intervention. An example is the Classical Extras plugin.
Cover art providers: These plugins provide another cover art source, and are registered with register_cover_art_provider(). They are also “automatic” in that they load album art without user intervention, although they must be enabled by the user in the Cover Art options… The Fanart.tv plugin is an example.
Scripting function: Some plugins just provide additional scripting functions for use in Options > Scripting or the renaming script. These are registered with register_script_function(). Keep tag, which provides the $keep() function, is an example.
Context menu actions: Plugins can register actions that can be activated manually via the context menu. This is what the Load as non-album track plugin does. Another example is Generate Cuesheet. These are registered with register_album_action(), register_track_action(), register_file_action(), register_cluster_action() or register_clusterlist_action().
File formats: Plugins can also provide support for new file formats not yet supported by Picard. These are registered with register_format().
Event processors: Plugins can execute automatically based on certain event triggers. These are registered with file_post_load_processor(), file_post_save_processor(), file_post_addition_to_track_processor(), file_post_removal_from_track_processor() or album_post_removal_processor().
Note that plugins are not limited to one of those areas. A single plugin could implement all of the above, but most existing plugins focus on one.
The Plugins API provides information regarding the different plugin hooks available, along with some examples of their use. This is also a list of the available plugins that have been submitted to the MusicBrainz Picard repository.
Scripts
There are two types of scripts used in Picard: the file naming script and tagging scripts. These are managed from the File Naming and Scripting sections of the Options menu. All scripts are written using the Picard scripting language. Scripts are often discussed in the MetaBrainz Community Forum, and there is a thread specific to file naming and script snippets.
File Naming Script
There is only one file naming script defined in a user’s settings, although it can vary from a simple one line script such as %album%/%title% to a very complex script using different file naming formats based on different criteria. In all cases, the files will be saved using the text output by the script. Note that any new tags set or tags modified by the file naming script will not be written to the output files’ metadata.
Tagging Scripts
There can be multiple tagging scripts defined in a user’s settings. Individual scripts can be enabled or disabled, and the order of execution of the scripts can be set. Whenever a script is run automatically (i.e. when an album / release is loaded), it is processed once for each track in the release that triggered the run. For example, if there are two tagging scripts enabled (A and B) and a release with three tracks is loaded, the scripts will be processed in the following order: Script A Track 1; Script A Track 2; Script A Track 3; Script B Track 1; Script B Track 2; Script B Track 3. Metadata updates are not shared between tracks, so you cannot append data from one track to a tag in another track.
Any new tags set or tags modified by the tagging scripts will be written to the output files’ metadata, unless the tag name begins with an underscore. These “hidden” tags are typically used as variables to hold temporary values that are used later in either the tagging or file naming scripts. Tagging scripts are run once for each track in the data, using the metadata for that track.
Tagging scripts can also be run manually by right-clicking either an album or a track in the right-hand pane in Picard. If run from the album entry, the script is run for each track in the album. If run from an individual track, the script is only run for that track.
Processing Order
In order to make effective use of plugins and scripts, it is important to understand when each is processed in relation to the others. As a general statement, plugins are always processed before scripts. Plugins of the same type will be executed in order based upon the priority specified when the plugin was registered.
Startup
During program startup, plugins with the following hooks are processed, and any additional functionality that they provide will be available immediately:
- File Formats
- Cover Art Providers
- Tagger Script Functions
- Context Menu Actions
- Option Pages
Loading an Album / Release
When data gets loaded from MusicBrainz (while the album shows the “loading” status in the right-hand pane), the following are processed:
- Metadata Processor Plugins
- Tagging Scripts
Plugins have access to the raw data loaded from MusicBrainz and are processed before scripts, in the order of priority set when the plugin was registered.
Scripts are processed in the order set in the Options menu. Whenever a script is run automatically (i.e. when an album / release is loaded), it is processed once for each track in the release that triggered the run. For example, if there are two tagging scripts enabled (A and B) and a release with three tracks is loaded, the scripts will be processed in the following order: Script A Track 1; Script A Track 2; Script A Track 3; Script B Track 1; Script B Track 2; Script B Track 3. Metadata updates are not shared between tracks, so you cannot append data from one track to a tag in another track.
Note that tagging scripts are always run against metadata loaded from MusicBrainz, and exactly after the data gets loaded and before files get matched. They are one of the last steps in the loading process. Tagging scripts do not have access to metadata stored in existing files.
Loading Music Files
After a file has been loaded into Picard, plugins registered with file_post_load_processor() are executed. This could, for example, be used to load additional data for a file.
Adding / Removing Files
After a file has been added to a track (on the right-hand pane of Picard), plugins registered with file_post_addition_to_track_processor() are executed.
After a file has been removed from a track (on the right-hand pane of Picard), plugins registered with file_post_removal_from_track_processor() are executed.
Saving Files
When files are saved, for each file / track, the File Naming Script is first executed to determine the destination path and file name. Note that this script has no effect on the tag values written to the output file.
After a file has been saved, plugins registered with file_post_save_processor() are executed. This can, for example, be used to run additional post-processing on the file or write extra data. Note that the file’s metadata is already the newly saved metadata.
Removing Albums
After an album has been removed from Picard, plugins registered with album_post_removal_processor() are executed.
Context Menus
Individual tagging scripts can be executed on-demand from the context menu displayed when right clicking on a file, album, track, cluster or cluster list.