Recursive AI

Tag mapping

All onemedia docs

How the common tag view picks values from the native tag systems. The table is the one the code reads (TagMappingTable.Rows); this page is generated from it, and a test fails when they differ.

  • Rows of one field are tried in table order, and within a row the keys in the order listed. The first value is the field's value; the others stay reachable through CommonTags.Values.
  • Native keys are spelled as the system spells them: four-character atom codes for ilst and udta (©nam), reverse-DNS names for key-table metadata (com.apple.quicktime.title), namespace#property for XMP, upper-case names for Matroska (nested SimpleTags as PARENT/CHILD). Matroska names are matched case-insensitively.
  • Matroska: only tags that target the file (no track, edition, chapter or attachment UID) feed the view, plus the tags of the only track of a single-track file (except ENCODER, which names the stream's encoder). Within a key the lowest target level of 30 or above comes first, then levels below 30; tags with no language or und come before language-specific ones; tags of the file itself come before tags of the only track.
  • 3GPP boxes and QuickTime user-data atoms share four-character codes with different layouts; the reader tells them apart as described in docs/tags.md.
  • Sources: the MusicBrainz Picard tag-mapping table (CC0), the ExifTool QuickTime tag documentation (read as tables of facts), the Matroska tag-name list, Apple's QuickTime File Format specification and 3GPP TS 26.244 §8.
FieldSystemKeys (in precedence order)DocumentNote
Titleilst©namPicard tag map, iTunes MP4
Titlemdtacom.apple.quicktime.title, com.apple.quicktime.displaynameExifTool QuickTime Keys tags
Titleudta©namExifTool QuickTime UserData tags
Title3gpptitl3GPP TS 26.244 §8
Artistilst©ARTPicard tag map, iTunes MP4
Artistmdtacom.apple.quicktime.artistExifTool QuickTime Keys tags
Artistudta©ART, ©prfExifTool QuickTime UserData tags©prf is QuickTime's performer
Artist3gppperf3GPP TS 26.244 §8performer
AlbumArtistilstaARTPicard tag map, iTunes MP4
Albumilst©albPicard tag map, iTunes MP4
Albummdtacom.apple.quicktime.albumExifTool QuickTime Keys tags
Albumudta©albExifTool QuickTime UserData tags
Album3gppalbm3GPP TS 26.244 §8album title; the optional track number feeds TrackNumber
Composerilst©wrtPicard tag map, iTunes MP4
Composerudta©wrt, ©comExifTool QuickTime UserData tags©com is QuickTime's composer
Authormdtacom.apple.quicktime.authorExifTool QuickTime Keys tags
Authorudta©autExifTool QuickTime UserData tags
Author3gppauth3GPP TS 26.244 §8author
Directorilst©dirPicard tag map, iTunes MP4
Directormdtacom.apple.quicktime.directorExifTool QuickTime Keys tags
Directorudta©dirExifTool QuickTime UserData tags
Genreilst©gen, gnrePicard tag map, iTunes MP4gnre holds the ID3v1 genre number plus one
Genremdtacom.apple.quicktime.genreExifTool QuickTime Keys tags
Genreudta©genExifTool QuickTime UserData tags
Genre3gppgnre3GPP TS 26.244 §8
Commentilst©cmtPicard tag map, iTunes MP4
Commentmdtacom.apple.quicktime.commentExifTool QuickTime Keys tags
Commentudta©cmtExifTool QuickTime UserData tags
Descriptionilstdesc, ldesExifTool QuickTime UserData tagsdesc is the short description, ldes the long one
Descriptionmdtacom.apple.quicktime.descriptionExifTool QuickTime Keys tags
Descriptionudta©infExifTool QuickTime UserData tags©inf is QuickTime's information text
Description3gppdscp3GPP TS 26.244 §8
Dateilst©dayPicard tag map, iTunes MP4stored as written, usually a year or an ISO 8601 date
Datemdtacom.apple.quicktime.yearExifTool QuickTime Keys tags
Dateudta©dayExifTool QuickTime UserData tags
Date3gppyrrc3GPP TS 26.244 §8recording year
CopyrightilstcprtPicard tag map, iTunes MP4
Copyrightmdtacom.apple.quicktime.copyrightExifTool QuickTime Keys tags
Copyrightudta©cpy, cprtExifTool QuickTime UserData tags
Copyright3gppcprt3GPP TS 26.244 §8
Encoderilst©tooExifTool QuickTime UserData tagsPicard files ©too under Encoded By; the atom names the writing tool, so it is the encoder here
Encodermdtaencoder, com.apple.quicktime.encoderExifTool QuickTime Keys tagsffmpeg writes the bare key encoder
Encoderudta©tooExifTool QuickTime UserData tags
EncodedByudta©encExifTool QuickTime UserData tags
Groupingilst©grpPicard tag map, iTunes MP4
Lyricsilst©lyrPicard tag map, iTunes MP4
Ratingmdtacom.apple.quicktime.rating.userExifTool QuickTime Keys tagsuser rating as a number
Rating3gpprtng3GPP TS 26.244 §8rating text
Keywordsmdtacom.apple.quicktime.keywordsExifTool QuickTime Keys tags
Keywordsudta©keyExifTool QuickTime UserData tags
Keywords3gppkywd3GPP TS 26.244 §8one value per keyword
TrackNumberilsttrknPicard tag map, iTunes MP4trkn: 16-bit number at byte 2
TrackNumber3gppalbm:track3GPP TS 26.244 §8optional last byte of albm
TrackTotalilsttrknPicard tag map, iTunes MP4trkn: 16-bit total at byte 4
DiscNumberilstdiskPicard tag map, iTunes MP4disk: 16-bit number at byte 2
DiscTotalilstdiskPicard tag map, iTunes MP4disk: 16-bit total at byte 4
Titlexmphttp://purl.org/dc/elements/1.1/#titleXMP specification part 1 and 2 (Dublin Core and XMP basic properties)language alternative: the x-default item
Artistxmphttp://purl.org/dc/elements/1.1/#creatorXMP specification part 1 and 2 (Dublin Core and XMP basic properties)first creator
Descriptionxmphttp://purl.org/dc/elements/1.1/#descriptionXMP specification part 1 and 2 (Dublin Core and XMP basic properties)
Copyrightxmphttp://purl.org/dc/elements/1.1/#rightsXMP specification part 1 and 2 (Dublin Core and XMP basic properties)
Keywordsxmphttp://purl.org/dc/elements/1.1/#subjectXMP specification part 1 and 2 (Dublin Core and XMP basic properties)
Datexmphttp://ns.adobe.com/xap/1.0/#CreateDateXMP specification part 1 and 2 (Dublin Core and XMP basic properties)
TitlemkvTITLEMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8lowest level of 30 or above first (track before album)
Titlemkv-infoTitleMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8Segment Info Title, after the tags
ArtistmkvARTIST, LEAD_PERFORMERMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
AlbumArtistmkvALBUM_ARTISTMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8not in the tag list; ffmpeg and others write it
AlbummkvALBUMMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8not in the tag list (an album title is TITLE at level 50); ffmpeg and others write ALBUM
ComposermkvCOMPOSERMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
AuthormkvWRITTEN_BYMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
DirectormkvDIRECTORMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
GenremkvGENREMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
CommentmkvCOMMENTMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
DescriptionmkvDESCRIPTION, SUMMARY, SYNOPSISMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
DatemkvDATE_RELEASED, DATE_RECORDED, DATEMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8DATE is written by ffmpeg and others
CopyrightmkvCOPYRIGHTMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
EncodermkvENCODERMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8Info WritingApp last
Encodermkv-infoWritingAppMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
EncodedBymkvENCODED_BYMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
LyricsmkvLYRICSMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
RatingmkvRATINGMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
KeywordsmkvKEYWORDSMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8
TrackNumbermkvPART_NUMBER, TRACKMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8part number at the lowest level of 30 or above; ffmpeg writes TRACK, optionally as number/total
DiscNumbermkvDISCMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8ffmpeg writes DISC, optionally as number/total
DiscTotalmkvDISCMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8the part after the slash of DISC
TrackTotalmkvTOTAL_PARTS, TRACKMatroska tag names (matroska.org/technical/tagging.html), RFC 9559 §5.1.8the part after the slash of TRACK when TOTAL_PARTS is absent