From 02ebda090b60f4b68ba75349a5ad63d3878b44ca Mon Sep 17 00:00:00 2001 From: Bob Swift Date: Fri, 29 Sep 2023 10:33:41 -0600 Subject: [PATCH 1/5] Move recording variables to Advanced Variables. --- variables/variables_advanced.rst | 22 +++++++++++++++++++++- variables/variables_basic.rst | 24 ------------------------ 2 files changed, 21 insertions(+), 25 deletions(-) diff --git a/variables/variables_advanced.rst b/variables/variables_advanced.rst index 4aa2e716e..d51512661 100644 --- a/variables/variables_advanced.rst +++ b/variables/variables_advanced.rst @@ -24,12 +24,32 @@ If you enable tagging with :doc:`Use track relationships Date: Sun, 15 Oct 2023 11:03:24 -0600 Subject: [PATCH 2/5] Categorize tags and variables into groups depending on options selected --- variables/tags_advanced.rst | 101 ++++++++----- variables/tags_basic.rst | 251 ++++++++++++++++++------------- variables/variables_advanced.rst | 85 ++++++++--- variables/variables_basic.rst | 101 ++++++------- 4 files changed, 322 insertions(+), 216 deletions(-) diff --git a/variables/tags_advanced.rst b/variables/tags_advanced.rst index 703654c13..5fe50f79b 100644 --- a/variables/tags_advanced.rst +++ b/variables/tags_advanced.rst @@ -4,106 +4,137 @@ .. TODO: Note which tags are not provided by Picard + +.. Test Release 1 + +.. No extra relationships specified +.. https://musicbrainz.org/ws/2/release/8c759d7a-2ade-4201-abc2-a2a7c1a6ad6c?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups&fmt=json + +.. Release extra relationships specified +.. https://musicbrainz.org/ws/2/release/8c759d7a-2ade-4201-abc2-a2a7c1a6ad6c?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups+artist-rels+recording-rels+release-group-level-rels+release-rels+series-rels+url-rels+work-rels&fmt=json + +.. Track extra relationships specified +.. https://musicbrainz.org/ws/2/release/8c759d7a-2ade-4201-abc2-a2a7c1a6ad6c?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups+artist-rels+recording-rels+release-group-level-rels+release-rels+series-rels+url-rels+work-rels+recording-level-rels+work-level-rels&fmt=json + + +.. Test Release 2 + +.. No extra relationships specified +.. https://musicbrainz.org/ws/2/release/59f6dc82-6e05-4d58-8fae-d93c55a250ef?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups&fmt=json + +.. Release extra relationships specified +.. https://musicbrainz.org/ws/2/release/59f6dc82-6e05-4d58-8fae-d93c55a250ef?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups+artist-rels+recording-rels+release-group-level-rels+release-rels+series-rels+url-rels+work-rels&fmt=json + +.. Track extra relationships specified +.. https://musicbrainz.org/ws/2/release/59f6dc82-6e05-4d58-8fae-d93c55a250ef?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups+artist-rels+recording-rels+release-group-level-rels+release-rels+series-rels+url-rels+work-rels+recording-level-rels+work-level-rels&fmt=json + + :index:`Advanced Tags ` ======================================== -You can make additional tags available by enabling the :doc:`Use track relationships ` and the -:doc:`Use genres from MusicBrainz ` settings in Picard. +You can make additional tags available by enabling the :doc:`Use track relationships ` and/or the :doc:`Use genres from MusicBrainz ` settings in Picard. + +Some tags provide the :index:`MusicBrainz Identifier (MBID) ` of the entity. The MBID is a 32-character identifier assigned to an entity (e.g.: artist, album, track or work) to uniquely identify the entity. For more information about MBIDs, please see the `MusicBrainz Identifier `_ page in the MusicBrainz documentation. .. note:: - Tags will not be created and will not be available as variables if there was no value retrieved for the tag - from the MusicBrainz database. + Tags will not be created and will not be available as variables if there was no value retrieved for the tag from the MusicBrainz database. .. note:: - Some of these tags are only supported for certain file types or tag formats. Please see the :doc:`Picard Tag Mapping - ` section for details. + Some of these tags are only supported for certain file types or tag formats. Please see the :doc:`Picard Tag Mapping ` section for details. + .. _advanced_relationships: + Track Relationship Tags --------------------------- -If you enable tagging with "Use track relationships", you get these extra tags: +----------------------- + +If you enable "Use track relationships" in the Option settings, you get these extra tags: **arranger** - The names of the arrangers associated with the track. These can include the instrument and orchestra arrangers, - and could be associated with the release, recording or work. (*since Picard 0.10*) + The names of the arrangers associated with the track. These can include the instrument and orchestra arrangers, and could be associated with the release, recording or work. (*since Picard 0.10*) **composer** - The names of the composers for the associated work. + The names of the composers for the associated work. **composersort** - The sort names of the composers for the associated work. + The sort names of the composers for the associated work. **conductor** - Tha names of the conductors associated with the track. These can include the conductor and chorus master, and could - be associated with the release or recording. + The names of the conductors associated with the track. These can include the conductor and chorus master, and could be associated with the release or recording. **director** - The director of a track as provided by the Video Director or Audio Director relationship in MusicBrainz. (*Since Picard 2.6, updated in Picard 2.9*) + The director of a track as provided by the *Video Director* or *Audio Director* relationship in MusicBrainz. (*Since Picard 2.6, updated in Picard 2.9*) **djmixer** - The names of the DJ mixers for the track. (*since Picard 0.9*) + The names of the DJ mixers for the track. (*since Picard 0.9*) **engineer** - The names of the engineers associated with the track. + The names of the engineers associated with the track. + +**language** + + Work lyric language as per `ISO 639-3 `_ if a related work exists. (*since Picard 0.10*) **license** - The licenses associated with the track, either through the release or recording relationships. (*since Picard 1.0*) + The licenses associated with the track, either through the release or recording relationships. (*since Picard 1.0*) **lyricist** - The names of the lyricists for the associated work. + The names of the lyricists for the associated work. **mixer** - The names of the "Mixed By" engineers associated with the track. (*since Picard 0.9*) + The names of the "*Mixed By*" engineers associated with the track. (*since Picard 0.9*) + +**musicbrainz_workid** + + The MBID for the Work if a related work exists. **performer:** - The names of the performers for the specified type. These types include: + The names of the performers for the specified type. These types include: - - vocals or instruments for the associated release or recording, where can be "vocal", "guest guitar", "solo violin", etc. + - vocals or instruments for the associated release or recording, where can be "*vocal*", "*guest guitar*", "*solo violin*", etc. - - the orchestra for the associated release or recording, where is "orchestra" + - the orchestra for the associated release or recording, where is "*orchestra*" - - the concert master for the associated release or recording, where is "concertmaster" + - the concert master for the associated release or recording, where is "*concertmaster*" **producer** - The names of the producers for the associated release or recording. + The names of the producers for the associated release or recording. **releasedate** - Explicit tag for the release date (*since Picard 2.9*). This tag exists for specific use in scripts and plugins, - but is not filled by default. In most cases it is recommended to use the ``date`` tag instead for compatibility - with existing software. + Explicit tag for the release date (*since Picard 2.9*). This tag exists for specific use in scripts and plugins, but is not filled by default. In most cases it is recommended to use the ``date`` tag instead for compatibility with existing software. **remixer** - The names of the remixer engineers associated with the track. + The names of the remixer engineers associated with the track. **work** - The name of the work associated with the track. (*since Picard 1.3*) + The name of the work associated with the track. (*since Picard 1.3*) **writer** - The names of the writers associated with the related work. (*since Picard 1.0*). This is not written to most file formats automatically. - You can merge this with composers with a script like: + A multi-value tag containing the names of the writers associated with the related work. (*since Picard 1.0*). This is not written to most file formats automatically. You can merge this with composers with a script like: + + .. code-block:: taggerscript - .. code-block:: taggerscript + $copymerge(composer, writer) - $copymerge(composer, writer) .. _genre_settings: @@ -114,4 +145,4 @@ If you enable "Use genres from MusicBrainz", you get: **genre** - Genre information from MusicBrainz (*since Picard 2.1, earlier versions used folksonomy tags*) + A multi-value tag containing the specified genre information from MusicBrainz (*since Picard 2.1, earlier versions used folksonomy tags*) diff --git a/variables/tags_basic.rst b/variables/tags_basic.rst index 3981560b2..d3e00172a 100644 --- a/variables/tags_basic.rst +++ b/variables/tags_basic.rst @@ -21,13 +21,13 @@ :index:`Basic Tags ` -================================== +================================= -The following tags are supported and are written in the standard format that can be read by other software. The information is populated from MusicBrainz data for most releases, without any special Picard settings. Note that some of the information such as 'lyrics' is not contained within the MusicBrainz database, and will not be provided automatically. +The following tags are supported and are written in the standard format that can be read by other software. The information is populated from MusicBrainz data for most releases, without any special Picard settings. Note that some of the information such as 'lyrics' is not contained within the MusicBrainz database, and will not be provided automatically. All of these are also available as variables for use in Picard Scripts (for tagging, for file renaming and in several other more minor settings) by wrapping them between percent '%' symbols (e.g. ``%title%``). -Most tags beginning with ``musicbrainz_`` provide the :index:`MusicBrainz Identifier (MBID) ` of the entity. The MBID is a 32-character identifier assigned to an entity (e.g.: artist, album, track or work) to uniquely identify the entity. For more information about MBIDs, please see the `MusicBrainz Identifier `_ page in the MusicBrainz documentation. +Some tags provide the :index:`MusicBrainz Identifier (MBID) ` of the entity. The MBID is a 32-character identifier assigned to an entity (e.g.: artist, album, track or work) to uniquely identify the entity. For more information about MBIDs, please see the `MusicBrainz Identifier `_ page in the MusicBrainz documentation. .. note:: @@ -35,230 +35,267 @@ Most tags beginning with ``musicbrainz_`` provide the :index:`MusicBrainz Identi .. note:: - Some of these tags are only supported for certain file types or tag formats. Please see the :doc:`Picard Tag Mapping ` section for details. + Some of these tags are only supported for certain file types or tag formats. Please see the :doc:`Picard Tag Mapping ` section for details. -**acoustid_fingerprint** - - AcoustID Fingerprint for the track. The fingerprint is based on the audio information found in a file, and is calculated using the `Chromaprint `_ software. -**acoustid_id** +Tags Provided from MusicBrainz Data +----------------------------------- - AcoustID associated with the track. The AcoustID is the identifier assigned to an audio file based on its 'acoustid_fingerprint'. Multiple fingerprints may be assigned the same AcoustID if the fingerprints are similar enough. +These tags will be provided based on the information from the MusicBrainz database and will be populated automatically by Picard if the information is available. **album** - Title of the release. + The title of the release. **albumartist** - Artist(s) primarily credited on the release. + The artists primarily credited on the release, separated by the specified join phrases. These could be either "standardized" or "as credited" depending on whether the "Use standardized artist names" metadata option is enabled. **albumartistsort** - Release Artist's Sort Name (e.g.: "Beatles, The"). - -**albumsort** - - Release Title's Sort Name. + The release artists sort names, separated by the specified join phrases. (e.g.: "Beatles, The") **artist** - Track Artist Name(s). (string) + The track artist names, separated by the specified join phrases. These could be either "standardized" or "as credited" depending on whether the "Use standardized artist names" metadata option is enabled. **artists** - Track Artist Name(s). (multi-value) (*since Picard 1.3*) + A multi-value tag containing the track artist names. These could be either "standardized" or "as credited" depending on whether the "Use standardized artist names" metadata option is enabled. (*since Picard 1.3*) **artistsort** - Track Artist Sort Name. + The track artists sort names, separated by the specified join phrases. **asin** - Amazon Standard Identification Number - the number identifying the item on Amazon. + The Amazon Standard Identification Number - the number identifying the item on Amazon. **barcode** - Release Barcode - the barcode assigned to the release. - -**bpm** - - Beats per minute of the track. Only available to the file naming script. + The barcode assigned to the release. **catalognumber** - The number(s) assigned to the release by the label(s), which can often be found on the spine or near the barcode. There may be more than one, especially when multiple labels are involved. + A multi-value tag contining the numbers assigned to the release by the labels, which can often be found on the spine or near the barcode. There may be more than one, especially when multiple labels are involved. **comment** - Disambiguation Comment - the comment entered to help distinguish one release from another (e.g.: Deluxe version with 2 bonus tracks). + The disambiguation comment entered to help distinguish one release from another (e.g.: Deluxe version with 2 bonus tracks). **compilation** - | (*since Picard 1.3, compatible with iTunes*) 1 for Various Artist albums, otherwise 0. - | (*Picard 1.2 or previous*) 1 if multiple track artists (including featured artists), otherwise 0. - -**copyright** - - Contains the copyright message for the copyright holder of the original sound, beginning with a year and a space character. + | 1 for Various Artist albums, otherwise empty. (*since Picard 1.3, compatible with iTunes*) + | 1 if multiple track artists (including featured artists), otherwise 0. (*Picard 1.2 or previous*) **date** - Release Date (YYYY-MM-DD) - the date that the release (album) was issued. + The date that the release (album) was issued, in the format YYYY-MM-DD. **discnumber** - Number of the disc in this release that contains this track. + The number of the disc in the release that contains this track. **discsubtitle** - The Media Title given to a specific disc. - -**encodedby** - - Encoded by (person or organization). Only available to the file naming script. - -**encodersettings** - - Encoder Settings used. Only available to the file naming script. + The media title given to a specific disc in the release. **isrc** - International Standard Recording Code - an international standard code for uniquely identifying sound recordings and music video recordings. See `Wikipedia `_ for more information. (*since Picard 0.12*) - -**key** - - Key of the music. + The International Standard Recording Code - an international standard code for uniquely identifying sound recordings and music video recordings. See `Wikipedia `_ for more information. (*since Picard 0.12*) **label** - Release Label Name(s). - -**language** - - Work lyric language as per `ISO 639-3 `_ if track relationships are enabled in Options and a related work exists. (*since Picard 0.10*) - -**lyrics** - - Lyrics for the track. Not provided by MusicBrainz. + A multi-value tag containing the names of the labels associated with the release. **media** - Release Format (e.g.: CD). See the `Release Format `_ page on the MusicBrainz website for more information. + The media on which the release was distributed (e.g.: CD). See the `Release Format `_ page on the MusicBrainz website for more information. **musicbrainz_albumartistid** - Release Artist's MusicBrainz Identifier (MBID). + A multi-value tag containing the MBIDs for the release artists. **musicbrainz_albumid** - Release MusicBrainz Identifier (MBID). + The MBID for the release. **musicbrainz_artistid** - Track Artist's MusicBrainz Identifier (MBID). + A multi-value tag containing the MBIDs for the track artists. **musicbrainz_discid** - Disc ID is the code number which MusicBrainz uses to link a physical CD to a release listing. This is based on the table of contents (TOC) information read from the disc. This tag contains the Disc ID if the album information was retrieved using :menuselection:`"Tools --> Lookup CD"`. (*since Picard 0.12*) + The Disc ID is the code number which MusicBrainz uses to link a physical CD to a release listing. This is based on the table of contents (TOC) information read from the disc. This tag contains the Disc ID if the album information was retrieved using :menuselection:`"Tools --> Lookup CD"`. (*since Picard 0.12*) **musicbrainz_originalalbumid** - Original Release's MusicBrainz Identifier (MBID). + The MBID for the original release. This is only available if the release has been merged with another release. **musicbrainz_originalartistid** - Original Track Artist's MusicBrainz Identifier (MBID). + A multi-value tag containing the MBIDs for the track artists of the original recording. This is only available if the recording has been merged with another recording. **musicbrainz_recordingid** - Recording's MusicBrainz Identifier (MBID). + The MBID for the recording. **musicbrainz_releasegroupid** - Release Group's MusicBrainz Identifier (MBID). + The MBID for the release group. **musicbrainz_trackid** - Release Track MusicBrainz Identifier (MBID). + The MBID for the track. -**musicbrainz_workid** +**originaldate** - MusicBrainz Identifier for the work (MBID). + The original release date in the format YYYY-MM-DD. By default this is set to the earliest release in the release group. This can provide, for example, the release date of the vinyl version of what you have on CD. (*Included as standard from Picard 0.15, and using the Original Release Date plugin if you are still using a non-NGS version earlier than Picard 0.15*) -.. **musicip_fingerprint** + .. note:: -.. MusicIP's Fingerprint. + This is the same information provided in the ``_releasegroup_firstreleasedate`` variable, and is consistent across all tracks in the release. If you prefer to have this tag populated with the date of the earliest recording of the track in the database, which will likely be different for each track in the release, this can be achieved by enabling a one-line tagging script as ``$set(originaldate,%_recording_firstreleasedate%)``. Be aware that setting this can cause a release to be scattered across multiple directories if you use ``%originaldate%`` as part of the path portion of your file naming script. -.. **musicip_puid** + .. note:: -.. MusicIP PUID’s associated with the track. + If you are storing tags in MP3 files as ID3v2.3 then the original date can only be stored as a year. -**originalalbum** +**originalyear** - Release Title of the earliest release in the Release Group intended for the title of the original recording. + The year of the original release date in the format YYYY. By default this is set to the earliest release in the release group. This can provide, for example, the release year of the vinyl version of what you have on CD. -**originalartist** +**releasecountry** - Track Artist of the earliest release in the Release Group intended for the performer(s) of the original recording. + The two-character code for the country in which the release was issued. If more than one release country was specified, this tag will contain the first one in the list. -**originaldate** +**releasestatus** - The original release date in the format YYYY-MM-DD. By default this is set to the earliest release in the Release Group. This can provide, for example, the release date of the vinyl version of what you have on CD. (*Included as standard from Picard 0.15, and using the Original Release Date plugin if you are still using a non-NGS version earlier than Picard 0.15*) + An indicator of the "official" status of the release. Possible values include *official*, *promotional*, *bootleg*, and *pseudo-release*. - .. note:: +**releasetype** - This is the same information provided in the ``_releasegroup_firstreleasedate`` variable, and is consistent across all tracks in the release. If you prefer to have this tag populated with the date of the earliest recording of the track in the database, which will likely be different for each track in the release, this can be achieved by enabling a one-line tagging script as ``$set(originaldate,%_recording_firstreleasedate%)``. Be aware that setting this can cause a release to be scattered across multiple directories if you use ``%originaldate%`` as part of the path portion of your file naming script. + A multi-value tag containing the types of release assigned to the release group. See also :ref:`_primaryreleasetype ` and :ref:`_secondaryreleasetype `. +**script** - .. note:: + The script used to write the release's track list. The possible values are taken from the `ISO 15924 `_ standard. (*since Picard 0.10*) - If you are storing tags in MP3 files as ID3v2.3 then the original date can only be stored as a year. +**title** -**originalyear** + The title of the track. - The year of the original release date in the format YYYY. By default this is set to the earliest release in the Release Group. This can provide, for example, the release year of the vinyl version of what you have on CD. +**totaldiscs** -**releasecountry** + The total number of discs in this release. - Country in which the release was issued. +**totaltracks** -**releasestatus** + The total number of tracks on this disc. - Release Status indicating the "official" status of the release. Possible values include official, promotional, bootleg, and pseudo-release. +**tracknumber** -**releasetype** + The number of the track on the disc. - Release Group Type (see also :ref:`_primaryreleasetype ` and :ref:`_secondaryreleasetype `) +**website** -**script** + The official website for the artist. - The script used to write the release's track list. The possible values are taken from the `ISO 15924 `_ standard. (*since Picard 0.10*) -**subtitle** +Tags Not Provided from MusicBrainz Data +--------------------------------------- - Used for information directly related to the contents title. +These tags are not able to be populated by stock Picard, however they may be used and populated by certain plugins. -**title** +**acoustid_fingerprint** + + The Acoustic Fingerprint for the track. The fingerprint is based on the audio information found in a file, and is calculated using the `Chromaprint `_ software. + +**acoustid_id** + + The AcoustID associated with the track. The AcoustID is the identifier assigned to an audio file based on its acoustic fingerprint. Multiple fingerprints may be assigned the same AcoustID if the fingerprints are similar enough. See the section on :doc:`Understanding Acoustic Fingerprinting and AcoustIDs ` for more information. + +**albumsort** + + The sort name of the title of the release. + +**bpm** + + The number of beats per minute of the track. + +**copyright** + + The copyright message for the copyright holder of the original sound, beginning with a year and a space character. + +**encodedby** + + The person or organization that encoded the track. + +**encodersettings** + + The settings used when encoding the track. + +**key** + + The key of the music. + +**lyrics** - Track Title. + The lyrics for the track. + +**musicip_fingerprint** + + The MusicIP Fingerprint for the track. + +**musicip_puid** + + The MusicIP PUIDs associated with the track. + +**originalalbum** + + The release title of the earliest release in the release group intended for the title of the original recording. + +**originalartist** + + The track artist of the earliest release in the release group intended for the performers of the original recording. + +**originalfilename** + + The original name of the audio file. + +**showmovement** + + The work and movement of the track. + +**subtitle** + + This is used for information directly related to the contents title. **titlesort** - Track Title's Sort Name. + The sort name of the track title. -**totaldiscs** - Total number of discs in this release +iTunes-Specific Tags +-------------------- -**totaltracks** +These tags are only available in iTunes files and are not able to be populated by stock Picard, however they may be used and populated by certain plugins. - Total tracks on this disc. +**gapless** -**tracknumber** + Indicates whether or not there are gaps between the recordings on the release. - Track number on the disc. +**podcast** -**website** + Indicates whether or not the recording is a podcast. + +**podcasturl** + + The associated url if the recording is a podcast. + +**show** + + The name of the show if the recording is associated with a television program. + +**showsort** - Used for official artist website. + The sort name of the show if the recording is associated with a television program. diff --git a/variables/variables_advanced.rst b/variables/variables_advanced.rst index d51512661..dbf4e867f 100644 --- a/variables/variables_advanced.rst +++ b/variables/variables_advanced.rst @@ -4,56 +4,103 @@ .. TODO: Note which tags are not provided by Picard + +.. Test Release 1 + +.. No extra relationships specified +.. https://musicbrainz.org/ws/2/release/8c759d7a-2ade-4201-abc2-a2a7c1a6ad6c?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups&fmt=json + +.. Release extra relationships specified +.. https://musicbrainz.org/ws/2/release/8c759d7a-2ade-4201-abc2-a2a7c1a6ad6c?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups+artist-rels+recording-rels+release-group-level-rels+release-rels+series-rels+url-rels+work-rels&fmt=json + +.. Track extra relationships specified +.. https://musicbrainz.org/ws/2/release/8c759d7a-2ade-4201-abc2-a2a7c1a6ad6c?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups+artist-rels+recording-rels+release-group-level-rels+release-rels+series-rels+url-rels+work-rels+recording-level-rels+work-level-rels&fmt=json + + +.. Test Release 2 + +.. No extra relationships specified +.. https://musicbrainz.org/ws/2/release/59f6dc82-6e05-4d58-8fae-d93c55a250ef?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups&fmt=json + +.. Release extra relationships specified +.. https://musicbrainz.org/ws/2/release/59f6dc82-6e05-4d58-8fae-d93c55a250ef?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups+artist-rels+recording-rels+release-group-level-rels+release-rels+series-rels+url-rels+work-rels&fmt=json + +.. Track extra relationships specified +.. https://musicbrainz.org/ws/2/release/59f6dc82-6e05-4d58-8fae-d93c55a250ef?inc=aliases+annotation+artist-credits+artists+collections+discids+isrcs+labels+media+recordings+release-groups+artist-rels+recording-rels+release-group-level-rels+release-rels+series-rels+url-rels+work-rels+recording-level-rels+work-level-rels&fmt=json + + :index:`Advanced Variables ` ================================================== -If you enable tagging with :doc:`Use track relationships `, you get these extra variables: +You can make additional tags available by enabling the :doc:`Use track relationships ` and/or the +:doc:`Use release relationships ` settings in Picard. + +Some variables provide the :index:`MusicBrainz Identifier (MBID) ` of the entity. The MBID is a 32-character identifier assigned to an entity (e.g.: artist, album, track or work) to uniquely identify the entity. For more information about MBIDs, please see the `MusicBrainz Identifier `_ page in the MusicBrainz documentation. .. note:: Variables will not be created if there was no value retrieved for the variable from the MusicBrainz database. -**_lyricistsort** - - The sort names of the lyricists for the work. (*since Picard 2.9*) -**_performance_attributes** +Track Relationship Variables +---------------------------- - List of performance attributes for the work (e.g.: "live", "cover", "medley"). Use :ref:`func_inmulti` to check for - a specific type (i.e.: ``$if($inmulti(%_performance_attributes%,medley), (Medley),)``). (*since Picard 1.3*) +If you enable tagging with :doc:`Use track relationships `, you get these extra variables: -**_recordingcomment** +**_lyricistsort** - The disambiguation comment for the recording associated with a track. (*since Picard 0.15*) + The sort names of the lyricists for the work. (*since Picard 2.9*) -**_recordingtitle** +**_performance_attributes** - Recording title - normally the same as the Track title, but can be different. + List of performance attributes for the work (e.g.: "live", "cover", "medley"). Use :ref:`func_inmulti` to check for a specific type (i.e.: ``$if($inmulti(%_performance_attributes%,medley), (Medley),)``). (*since Picard 1.3*) -**_recording_firstreleasedate** +**_recordingtitle** - The date of the earliest recording for a track in the format YYYY-MM-DD. (*Since Picard 2.6*) + Recording title - normally the same as the track title, but can be different. **_recording_series** - The series title(s) associated with the recording (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series titles associated with the recording. (*since Picard 2.9*) **_recording_seriesid** - The series MBID(s) associated with the recording (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series MBIDs associated with the recording. (*since Picard 2.9*) **_recording_seriescomment** - The series disambiguation comment(s) associated with the recording (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series disambiguation comments associated with the recording. (*since Picard 2.9*) **_recording_seriesnumber** - The series number(s) associated with the recording (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series numbers associated with the recording. (*since Picard 2.9*) **_workcomment** - Work disambiguation comment. (*since Picard 2.7*) + The disambiguation comment associated with the work. (*since Picard 2.7*) **_writersort** - The sort names of the writers for the work. (*since Picard 2.9*) + The sort names of the writers for the work. (*since Picard 2.9*) + + +Track or Release Relationship Variables +--------------------------------------- + +If you enable tagging with :doc:`Use track relationships ` or :doc:`Use release relationships `, you get these extra variables: + +**_work_series** + + A multi-value variable containing the series titles associated with the work. (*since Picard 2.9*) + +**_work_seriesid** + + A multi-value variable containing the series MBIDs associated with the work. (*since Picard 2.9*) + +**_work_seriescomment** + + A multi-value variable containing the series disambiguation comments associated with the work. (*since Picard 2.9*) + +**_work_seriesnumber** + + A multi-value variable containing the series numbers associated with the work. (*since Picard 2.9*) diff --git a/variables/variables_basic.rst b/variables/variables_basic.rst index bc392c36e..6494e1eb5 100644 --- a/variables/variables_basic.rst +++ b/variables/variables_basic.rst @@ -9,102 +9,105 @@ These variables are populated from MusicBrainz data for most releases, without any special Picard settings. +Some variables provide the :index:`MusicBrainz Identifier (MBID) ` of the entity. The MBID is a 32-character identifier assigned to an entity (e.g.: artist, album, track or work) to uniquely identify the entity. For more information about MBIDs, please see the `MusicBrainz Identifier `_ page in the MusicBrainz documentation. + .. note:: Variables will not be created if there was no value retrieved for the variable from the MusicBrainz database. **_absolutetracknumber** - The absolute number of this track disregarding the disc number (i.e.: ``%_absolutetracknumber%`` of ``%_totalalbumtracks%``). - For example, this value would be 11 for the second track on disc 2 where disc 1 has 9 tracks. (*since Picard 1.3*) + The absolute number of this track disregarding the disc number (i.e.: ``%_absolutetracknumber%`` of ``%_totalalbumtracks%``). For example, this value would be 11 for the second track on disc 2 where disc 1 has 9 tracks. (*since Picard 1.3*) **_albumartists** - The Album's Artists' Name(s) (multi-value). (*since Picard 1.3*) + A multi-value variable containing the names of the album's artists. These could be either "standardized" or "as credited" depending on whether the "Use standardized artist names" metadata option is enabled. (*since Picard 1.3*) **_albumartists_sort** - The Album Artist's Sort Name(s) (multi-value). (*since Picard 1.3*) + A multi-value variable containing the sort names of the album's artists. (*since Picard 1.3*) **_artists_sort** - The Artist's Sort Name(s) (multi-value). (*since Picard 1.3*) + A multi-value variable containing the sort names of the track's artists. (*since Picard 1.3*) **_datatrack** - Set to 1 if the track is a "`data track `_". (*since Picard 1.3.1*) + Set to 1 if the track is a "`data track `_", otherwise empty. (*since Picard 1.3.1*) **_discpregap** - Set to 1 if the disc the track is on has a "`pregap track `_". (*since Picard 1.4*) + Set to 1 if the disc the track is on has a "`pregap track `_", otherwise empty. (*since Picard 1.4*) **_multiartist** - Set to 1 if not all of the tracks on the album have the same primary artist, otherwise empty. (*since Picard 1.3*) + Set to 1 if not all of the tracks on the album have the same primary artist, otherwise empty. (*since Picard 1.3*) **_musicbrainz_discids** - This multi-value variable contains a list of all of the disc ids attached to the selected release. The list provided for each medium only includes - the disc ids attached to that medium. For example, the list provided for Disc 1 of a three CD set will not include the disc ids attached to discs 2 - and 3 of the set. + A multi-value variable containing a list of all of the disc ids attached to the selected release. The list provided for each medium only includes the disc ids attached to that medium. For example, the list provided for Disc 1 of a three CD set will not include the disc ids attached to discs 2 and 3 of the set. **_musicbrainz_tracknumber** - The track number written as on the MusicBrainz release, such as vinyl numbering (A1, A2...). + The track number written as on the MusicBrainz release, such as vinyl numbering (A1, A2…). **_pregap** - Set to 1 if the track is a "`pregap track `_". (*since Picard 1.3.1*) + Set to 1 if the track is a "`pregap track `_", otherwise empty. (*since Picard 1.3.1*) .. _ref_primaryreleasetype: **_primaryreleasetype** - Release Group Primary type (i.e.: album, single, ep, broadcast, or other). + The primary type of the release group (i.e.: *album*, *single*, *ep*, *broadcast*, or *other*). **_rating** - Rating 0-5 by MusicBrainz users. - -**_releaseannotation** - - The annotation comment for the release. (*since Picard 2.6*) + The rating of the track from 0-5 by MusicBrainz users. -**_releasecomment** +**_recordingcomment** - Release disambiguation comment. (*since Picard 0.15*) + The disambiguation comment for the recording associated with a track. (*since Picard 0.15*) -**_releasecountries** +**_recording_firstreleasedate** - This provides the complete list of release countries for the release as a multi-value variable. (*since Picard 2.3.1*) + The date of the earliest recording for a track in the format YYYY-MM-DD. (*Since Picard 2.6*) **_release_series** - The series title(s) associated with the release (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series titles associated with the release. (*since Picard 2.9*) **_release_seriesid** - The series MBID(s) associated with the release (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series MBIDs associated with the release. (*since Picard 2.9*) **_release_seriescomment** - The series disambiguation comment(s) associated with the release (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series disambiguation comments associated with the release. (*since Picard 2.9*) **_release_seriesnumber** - The series number(s) associated with the release (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series numbers associated with the release. (*since Picard 2.9*) -**_releasegroup** +**_releaseannotation** - Release Group Title which is typically the same as the Album Title, but can be different. + The annotation comment for the release. (*since Picard 2.6*) -**_releasegroupcomment** +**_releasecomment** + + The disambiguation comment for the release. (*since Picard 0.15*) + +**_releasecountries** - Release Group disambiguation comment. + A multi-value variable containing the complete list of release countries for the release. (*since Picard 2.3.1*) + +**_releasegroup** + + The title of the release group. This is typically the same as the album title, but can be different. **_releasegroup_firstreleasedate** - The date of the earliest release in the Release Group in the format YYYY-MM-DD. This is intended to provide, for example, the release date of the vinyl version of what you have on CD. (*Since Picard 2.6*) + The date of the earliest release in the release group in the format YYYY-MM-DD. This is intended to provide, for example, the release date of the vinyl version of what you have on CD. (*Since Picard 2.6*) .. note:: @@ -112,46 +115,34 @@ These variables are populated from MusicBrainz data for most releases, without a **_releasegroup_series** - The series title(s) associated with the release group (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series titles associated with the release group. (*since Picard 2.9*) **_releasegroup_seriesid** - The series MBID(s) associated with the release group (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series MBIDs associated with the release group. (*since Picard 2.9*) **_releasegroup_seriescomment** - The series disambiguation comment(s) associated with the release group (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series disambiguation comments associated with the release group. (*since Picard 2.9*) **_releasegroup_seriesnumber** - The series number(s) associated with the release group (multi-value). (*since Picard 2.9*) + A multi-value variable containing the series numbers associated with the release group. (*since Picard 2.9*) + +**_releasegroupcomment** + + The disambiguation comment for the release group. **_releaselanguage** - Release Language as per `ISO 639-3 `_. (*since Picard 0.10*) + The language of the release as per `ISO 639-3 `_. (*since Picard 0.10*) .. _ref_secondaryreleasetype: **_secondaryreleasetype** - Zero or more Release Group Secondary types (i.e.: audiobook, compilation, dj-mix, interview, live, mixtape/street, remix, soundtrack, or spokenword). + Zero or more secondary types (i.e.: *audiobook*, *compilation*, *dj-mix*, *interview*, *live*, *mixtape/street*, *remix*, *soundtrack*, or *spokenword*) for the release group. **_totalalbumtracks** - The total number of tracks across all discs of this release. - -**_work_series** - - The series title(s) associated with the work (multi-value). (*since Picard 2.9*) - -**_work_seriesid** - - The series MBID(s) associated with the work (multi-value). (*since Picard 2.9*) - -**_work_seriescomment** - - The series disambiguation comment(s) associated with the work (multi-value). (*since Picard 2.9*) - -**_work_seriesnumber** - - The series number(s) associated with the work (multi-value). (*since Picard 2.9*) + The total number of tracks across all discs of this release. From c01f1e253c4756045251539a7ebaae2dc5b04fe0 Mon Sep 17 00:00:00 2001 From: Bob Swift Date: Tue, 17 Oct 2023 14:09:53 -0600 Subject: [PATCH 3/5] More fine tuning of tag and variable categorization --- variables/tags_advanced.rst | 8 +++---- variables/tags_basic.rst | 8 +++++-- variables/variables_advanced.rst | 37 +++++++++++++++++++++++--------- variables/variables_basic.rst | 16 -------------- 4 files changed, 37 insertions(+), 32 deletions(-) diff --git a/variables/tags_advanced.rst b/variables/tags_advanced.rst index 5fe50f79b..1e1c73944 100644 --- a/variables/tags_advanced.rst +++ b/variables/tags_advanced.rst @@ -111,10 +111,6 @@ If you enable "Use track relationships" in the Option settings, you get these ex - the concert master for the associated release or recording, where is "*concertmaster*" -**producer** - - The names of the producers for the associated release or recording. - **releasedate** Explicit tag for the release date (*since Picard 2.9*). This tag exists for specific use in scripts and plugins, but is not filled by default. In most cases it is recommended to use the ``date`` tag instead for compatibility with existing software. @@ -135,6 +131,10 @@ If you enable "Use track relationships" in the Option settings, you get these ex $copymerge(composer, writer) +.. note:: + + Some tags such as **performer** are available as both track and release level relationships, and the values may be different depending on which relationship options are enabled. + .. _genre_settings: diff --git a/variables/tags_basic.rst b/variables/tags_basic.rst index d3e00172a..c1dcdb6f9 100644 --- a/variables/tags_basic.rst +++ b/variables/tags_basic.rst @@ -204,7 +204,7 @@ These tags will be provided based on the information from the MusicBrainz databa Tags Not Provided from MusicBrainz Data --------------------------------------- -These tags are not able to be populated by stock Picard, however they may be used and populated by certain plugins. +These tags are not able to be populated by stock Picard, however they may be used and populated by certain plugins or scripts. **acoustid_fingerprint** @@ -262,6 +262,10 @@ These tags are not able to be populated by stock Picard, however they may be use The original name of the audio file. +**producer** + + The names of the producers for the associated release or recording. + **showmovement** The work and movement of the track. @@ -278,7 +282,7 @@ These tags are not able to be populated by stock Picard, however they may be use iTunes-Specific Tags -------------------- -These tags are only available in iTunes files and are not able to be populated by stock Picard, however they may be used and populated by certain plugins. +These tags are only available in iTunes files and are not able to be populated by stock Picard, however they may be used and populated by certain plugins or scripts. **gapless** diff --git a/variables/variables_advanced.rst b/variables/variables_advanced.rst index dbf4e867f..49386b31a 100644 --- a/variables/variables_advanced.rst +++ b/variables/variables_advanced.rst @@ -42,6 +42,29 @@ Some variables provide the :index:`MusicBrainz Identifier (MBID) `, you get these extra variables: + +**_release_series** + + A multi-value variable containing the series titles associated with the release. (*since Picard 2.9*) + +**_release_seriesid** + + A multi-value variable containing the series MBIDs associated with the release. (*since Picard 2.9*) + +**_release_seriescomment** + + A multi-value variable containing the series disambiguation comments associated with the release. (*since Picard 2.9*) + +**_release_seriesnumber** + + A multi-value variable containing the series numbers associated with the release. (*since Picard 2.9*) + + + Track Relationship Variables ---------------------------- @@ -79,16 +102,6 @@ If you enable tagging with :doc:`Use track relationships ` or :doc:`Use release relationships `, you get these extra variables: - **_work_series** A multi-value variable containing the series titles associated with the work. (*since Picard 2.9*) @@ -104,3 +117,7 @@ If you enable tagging with :doc:`Use track relationships Date: Tue, 17 Oct 2023 14:22:51 -0600 Subject: [PATCH 4/5] Fix accidentally moving the wrong tag. (Oops...) --- variables/tags_advanced.rst | 4 ++-- variables/tags_basic.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/variables/tags_advanced.rst b/variables/tags_advanced.rst index 1e1c73944..ed0970547 100644 --- a/variables/tags_advanced.rst +++ b/variables/tags_advanced.rst @@ -111,9 +111,9 @@ If you enable "Use track relationships" in the Option settings, you get these ex - the concert master for the associated release or recording, where is "*concertmaster*" -**releasedate** +**producer** - Explicit tag for the release date (*since Picard 2.9*). This tag exists for specific use in scripts and plugins, but is not filled by default. In most cases it is recommended to use the ``date`` tag instead for compatibility with existing software. + The names of the producers for the associated release or recording. **remixer** diff --git a/variables/tags_basic.rst b/variables/tags_basic.rst index c1dcdb6f9..a9c322682 100644 --- a/variables/tags_basic.rst +++ b/variables/tags_basic.rst @@ -262,9 +262,9 @@ These tags are not able to be populated by stock Picard, however they may be use The original name of the audio file. -**producer** +**releasedate** - The names of the producers for the associated release or recording. + Explicit tag for the release date (*since Picard 2.9*). This tag exists for specific use in scripts and plugins, but is not filled by default. In most cases it is recommended to use the ``date`` tag instead for compatibility with existing software. **showmovement** From 331b5bbd647e7a1cad890e7af6be8b5d4200cef5 Mon Sep 17 00:00:00 2001 From: Bob Swift Date: Wed, 18 Oct 2023 09:44:37 -0600 Subject: [PATCH 5/5] Move `_releasegroup_series*` variables to "Use release relationships" --- variables/variables_advanced.rst | 15 +++++++++++++++ variables/variables_basic.rst | 16 ---------------- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/variables/variables_advanced.rst b/variables/variables_advanced.rst index 49386b31a..e7c7df003 100644 --- a/variables/variables_advanced.rst +++ b/variables/variables_advanced.rst @@ -63,6 +63,21 @@ If you enable tagging with :doc:`Use release relationships