MusicBrainz Pseudo-Release Plugin
=================================

The `mbpseudo` plugin can be used *instead of* the `musicbrainz` plugin to
search for MusicBrainz pseudo-releases_ during the import process, which are
added to the normal candidates from the MusicBrainz search.

.. _pseudo-releases: https://musicbrainz.org/doc/Style/Specific_types_of_releases/Pseudo-Releases

This is useful for releases whose title and track titles are written with a
script_ that can be translated or transliterated into a different one.

.. _script: https://en.wikipedia.org/wiki/ISO_15924

Pseudo-releases will only be included if the initial search in MusicBrainz
returns releases whose script is *not* desired and whose relationships include
pseudo-releases with desired scripts.

Configuration
-------------

Since this plugin first searches for official releases from MusicBrainz, all
options from the `musicbrainz` plugin's :ref:`musicbrainz-config` are supported,
but they must be specified under `mbpseudo` in the configuration file.
Additionally, the configuration expects an array of scripts that are desired for
the pseudo-releases. For ``artist`` in particular, keep in mind that even
pseudo-releases might specify it with the original script, so you should also
configure import :ref:`languages` to give artist aliases more priority.
Therefore, the minimum configuration for this plugin looks like this:

.. code-block:: yaml

    plugins: mbpseudo # remove musicbrainz

    import:
        languages: en

    mbpseudo:
        scripts:
        - Latn

Note that the `search_limit` configuration applies to the initial search for
official releases, and that the `data_source` in the database will be
"MusicBrainz". Nevertheless, `data_source_mismatch_penalty` must also be
specified under `mbpseudo` if desired (see also
:ref:`metadata-source-plugin-configuration`). An example with multiple data
sources may look like this:

.. code-block:: yaml

    plugins: mbpseudo deezer

    import:
        languages: en

    mbpseudo:
        data_source_mismatch_penalty: 0
        scripts:
        - Latn

    deezer:
        data_source_mismatch_penalty: 0.2

By default, the data from the pseudo-release will be used to create a proposal
that is independent from the official release and sets all properties in its
metadata. It's possible to change the configuration so that some information
from the pseudo-release is instead added as custom tags, keeping the metadata
from the official release:

.. code-block:: yaml

    mbpseudo:
        # other config not shown
        custom_tags_only: yes

The default custom tags with this configuration are specified as mappings where
the keys define the tag names and the values define the pseudo-release property
that will be used to set the tag's value:

.. code-block:: yaml

    mbpseudo:
        album_custom_tags:
            album_transl: album
            album_artist_transl: artist
        track_custom_tags:
            title_transl: title
            artist_transl: artist

Note that the information for each set of custom tags corresponds to different
metadata levels (album or track level), which is why ``artist`` appears twice
even though it effectively references album artist and track artist
respectively.

If you want to modify any mapping under ``album_custom_tags`` or
``track_custom_tags``, you must specify *everything* for that set of tags in
your configuration file because any customization replaces the whole dictionary
of mappings for that level.

.. note::

    These custom tags are also added to the music files, not only to the
    database.