Format support

edit

Fields by format

FieldMP3OGG / OpusFLACMP4WAV / AIFFAPE / WavPack / MusepackASF
Title, Artist, Album, AlbumArtist, Genre, Yearyesyesyesyesyesyesyes
TrackNumber, TrackTotal, DiscNumber, DiscTotalyesyesyesyes 1yesyesyes
Comment, Lyrics, Composer, Conductor, Copyright, Isrcyesyesyesyesyesyesyes
Bpm, IsCompilationyesyesyesyes 1yesyesyes
Durationread and written 2read onlyread onlyread onlyread and written 2read onlyread only
Picturesyesyesyesfront cover onlyyesone per typeyes
ReplayGainyesyesyesyesyesyesyes
MusicBrainz*yesyesyesyesyesyesyes
MediaKind, Description, LongDescription, Tv*nononoyesnonono
VideoWidth, VideoHeightnononoread onlynonoread only
CustomFieldsyesyesyesyesyes 3yesyes
NativeFieldsID3v2 framesnonenoneitemsID3v2 framesbinary itemsother attributes

1 MP4 stores these values in 16 bits. A value above 65535 is refused with MediaTagError.InvalidTagData rather than wrapped.

2 Stored in a TLEN frame. A duration computed from the audio is not written; see Change some fields. A TLEN of 0 means the duration is unknown, so the duration is computed from the audio instead.

3 Stored in the embedded ID3v2 tag, not as native chunks.

MP3

  • Tags are written as an ID3v2 tag, and an ID3v1 tag at the end of the file unless WriteId3v1Tag is false. ID3v1 truncates each field to 30 Latin-1 characters.
  • The ID3v2 frames this library does not read, such as the publisher, the sort names, ratings, UFID, PRIV or the COMM frames of iTunes, are native fields. The frames of an ID3v2.3 tag are converted to ID3v2.4, and an ID3v2.2 tag has none. RemoveTags removes them too.
  • A native frame has a four-character identifier of upper-case letters and digits. A frame a property represents (TIT2, TXXX, APIC, COMM and USLT without a description…) and the tag alter preservation flag (0x4000) are refused.
  • An APEv2 tag at the end of the file, as foobar2000 writes, is read: its values fill the fields the ID3v2 tag does not set, before the ID3v1 tag does. Writing replaces it with the ID3v2 tag: its values are in MediaTagInfo, but its binary items are not kept.
  • A file with only an ID3v1 tag is read. "TAG" in the last 128 bytes of the file is not an ID3v1 tag when the ID3v2 tag covers it, as when a text frame holds it and less than 128 bytes of audio follow the ID3v2 tag.

OGG Vorbis, OGG Opus and FLAC

  • Tags are Vorbis comments. A comment name cannot contain =: writing a custom field with such a name fails with InvalidTagData.
  • A comment whose value cannot be parsed, such as TRACKNUMBER=A1, is read into CustomFields, so writing the tags back keeps it.
  • Every comment is a property or a custom field, so these formats have no native fields.
  • Multiplexed and chained OGG streams, such as a video stream next to the audio or several concatenated streams, are refused rather than rewritten.

MP4, M4A, M4V and MOV

  • Tags are iTunes-style metadata items, in audio and video files alike. The items this library does not read, such as the encoder or the gapless playback flag, are native fields: they are kept when the tags are written, and RemoveTags removes them.
  • A native item has a type of four Latin-1 characters and no flags. The type of an item a property represents (©nam, trkn, covr, ----, tvsh…) or of a box of the movie structure (moov, meta, stco…) is refused.
  • Only one picture is stored: the front cover.
  • The video items are MediaKind (stik), Description (desc), LongDescription (ldes), TvShow (tvsh), TvNetwork (tvnn), TvEpisodeId (tven), TvSeason (tvsn) and TvEpisode (tves). The video size is read from the header of the first video track.
  • QuickTime files store the title, the artist, the album, the year, the comment, the genre, the composer, the copyright and the description as text records of the udta atom (©nam, ©ART…). They are read when the metadata items do not set the field, and writing moves them to the metadata items. A record that holds the text in several languages is kept as it is, and is not read.

WAV and AIFF

  • Tags are written as an embedded ID3v2 chunk, whose native fields are the ones of MP3.
  • Writing removes the existing LIST/INFO chunks of a WAV file and the NAME, AUTH, ANNO, (c) and ISRC chunks of an AIFF file: other programs would otherwise read them instead of the tag just written.

Monkey's Audio, WavPack and Musepack

  • Tags are an APEv2 tag at the end of the file. An APEv1 tag is read too, and written as APEv2. An ID3v1 tag that older taggers added is read for the fields the APE tag does not set; writing removes it, and the APE tags that taggers stacked, so their values are only in the new APE tag.
  • Item keys are case-insensitive: Title, Artist, Album, Album Artist, Year, Track and Disc (as "number/total"), Genre, Comment, Lyrics, Composer, Conductor, Copyright, ISRC, BPM, Compilation, and the ReplayGain and MusicBrainz names of Vorbis comments. Text is UTF-8.
  • A picture is a binary item named after its type, such as Cover Art (Front), so there is one per type: writing two of the same type fails with InvalidTagData. Its file name is the Description. The format stores no MIME type: it is read from the first bytes of the image (PNG, GIF, BMP, WebP), and is image/jpeg for another image.
  • A custom field name, and the key of a native item, has 2 to 255 printable ASCII characters, and cannot be ID3, TAG, OggS or MP+; another one is refused. A custom field named like a field that is set is not written.
  • The native fields are the binary items and the external links (flags 2 and 4, optionally with the read-only flag 1). A binary item named after a picture type is a picture. Items of the reserved type (flags 6) are not read, and writing removes them.
  • The duration is read from the stream header. Musepack files of stream versions 7 and 8 are supported.

ASF (WMA and WMV)

  • The title, the artist, the copyright and the comment are stored in the content description object, as Windows Media Player expects. A value too long for it is stored as an attribute of the same name (Title, Author…).
  • The other fields are attributes: WM/AlbumTitle, WM/AlbumArtist, WM/Genre, WM/Year, WM/TrackNumber (a 32-bit integer) and TotalTracks, WM/PartOfSet (the disc, as "number/total"), WM/Composer, WM/Conductor, WM/Lyrics, WM/ISRC, WM/BeatsPerMinute, WM/IsCompilation, WM/Picture, the ReplayGain names and MusicBrainz/Track Id… The 0-based WM/Track of older files, and the date attribute ffmpeg writes, are read too.
  • Every text attribute that no property represents is a custom field, as is the rating of the content description, which is written back as a Rating attribute. A custom field named like a field that is set is not written.
  • Every other attribute (byte arrays, numbers, booleans, GUIDs) is a native field. The data type of a native field must not be text, and its data must have the size of its type. Native fields and pictures are written in the metadata library object, which every recent reader reads; the other attributes in the extended content description object, or in the metadata library object when they are larger than 64 KB.
  • Attributes that describe a single stream or a single language are kept as they are, and are not read.
  • The size of the file stored in the file properties object is updated. The data packets and the indexes are copied unchanged.

ID3v2 tags in front of other formats

Some taggers add an ID3v2 tag at the start of a FLAC, OGG, MP4, WAV, AIFF, Monkey's Audio, WavPack or Musepack file. It is skipped when reading, and copied unchanged when writing.