|
|
|
id3_util - ID3 Tag UtilitiesThe ID3_UTIL functions ... are used by tag311!
An ID3 tag contains identifying information about an MP3 audio track. Such information may include the track's song title, the artist's name, the album name, the publication/recording date, etc.
The obsolete, but still frequently seen, version 1 (ID3v1) tag is a 128-byte block with a fixed set of these fields. The ID3v1 tag is stored at the end of the audio file.
The newer version 2 (ID3v2) tags are stored at the beginning of the file. ID3v2.3 tags are the most commonly seen version. ID3v2.4 tags provide some additional frame types and additional methods for encoding Unicode characters, but don't differ significantly from ID3v2.3 tags.
An ID3v2 tag consists of:
Separate frame types are defined for the song title, artist's name, etc. An ID3v2 frame more generally consists of:
ID3v2 data values (my term) include (i) ancillary data supporting a frame's key value or values and (ii) the key value or values in the frame's unit of ID information. I think an example will make this clearer. ID3 attached picture frames have a 4-character ID of 'APIC' and the key value in their unit of information is an image. Each APIC frame has a number of supporting data values and the key value:
Explicit data values:
Implicit data value:
There may be multiple APIC frames with the same picture type, but they must have different descriptions. For example, the tag for a Beatles song may have 4 "artist/performer" (0x08) pictures, one for each band member, but the descriptions in each of the 4 APIC frames must be different (perhaps "John", "Paul", "George", and "Ringo"!).
An example of a frame with multiple, key data values is the ID3v2.4 Musician credits list frame, the 'TMCL' frame:
The contents of the strings are not standardized. An instrument string could be a comma-separated list of instruments coupled with a single musician's name. Or a single instrument coupled with a comma-separated list of musicians who played that instrument on the recording.
Regarding the ID3v2.4 TMCL example, I should note an important difference between ID3v2.4 and ID3v2.3 frames. ID3v2.4 allows a variable number of NUL-terminated strings at the end of a text information frame such as the TMCL frame. ID3v2.3 doesn't. However, ID3v2.3's comparable 'IPLS' (involved people list) frame, which looks like but is not a text information frame, does support a sequence of NUL-terminated strings in the frame. Things I learned when I dug around while writing this paragraph!
I went back and added support for the IPLS frame to ID3_UTIL. The convention for the display and entry format of IPLS information among other programs seems to be as shown in this example:
Guitar:John;Bass:Paul;Guitar:George;Drums:Ringo
That's the display and entry format; the actual on-disk format is a sequence of NUL-terminated strings (ISO-8859-1 encoding for the example's sake):
Guitar\0John\0Bass\0Paul\0Guitar\0George\0Drums\0Ringo\0
The ID3_UTIL package internally represents all ID3 tags (ID3v1, ID3v2.3, and ID3v2.4) as generalized ID3v2 tags using 3 object types consistent with the description above:
Id3Tag - has the tag header information and
a list of frames.
Id3Frame - has the frame header information and
a list of values.
Id3Value - is an atomic bit of information; e.g., a string.
The ID3 standard speaks of tags and frames, but not of data values at a
third level in the hierarchy. They seemed like an obvious abstraction
to me and I began implementing ID3v2 frames with separate value objects
for each data item (both supporting and key values) in a frame. Accessing
these items proved awkward and tedious, so I quickly switched to an
"fdata" union of type-specific, frame data structures.
A frame type's key value and supporting data are stored in its structure
and are easily accessed. Additional key values allowed in ID3v2.4 and
IPLS frames are stored in a list of value objects. These additional
values are all strings, but the Id3Value code still retains support for
numbers and binary blobs as well, in line with my original intentions
for these objects.
... STILL TO BE WRITTEN! ...
(In "id3_util.c")
id3CRC32() - computes the CRC-32 for a buffer of data.id3DecodeSSI() - decodes a synchsafe integer.id3DeUnsync() - de-unsynchronizes a data buffer.id3Dump() - dumps the contents of an ID3 tag.id3DumpGenres() - lists the ID3v1 music genres.id3DumpLUT() - lists the entries in the frame information table.id3DumpPicTypes() - lists the ID3v2 picture types.id3EncodeSSI() - encodes a synchsafe integer.id3IsEmpty() - checks if an ID3 tag is empty.id3IsFrame() - checks if a buffer begins contains an ID3 frame.id3IsTag() - checks if a buffer contains an ID3 tag.id3ReadHeaders() - reads the ID3 tag headers from a named file.id3ReadHeadersF() - reads the ID3 tag headers from an open file.id3ReadTags() - reads the ID3 tags from a named file.id3ReadTagsF() - reads the ID3 tags from an open file.id3ReadV1() - reads the ID3v1 tag from an open file.id3ReadV2() - reads the ID3v2 tag from an open file.id3Strip() - strips the ID3 tag from a named file.id3StripF() - strips the ID3 tag from an open file.id3Unsync() - unsynchronizes a data buffer.id3WriteTags() - writes ID3v1 and ID3v2 tags to a file.id3GetAlbum() - gets an ID3 tag's album field.id3GetArtist() - gets an ID3 tag's artist field.id3GetComment() - gets an ID3 tag's comment field.id3GetCover() - gets an ID3 tag's cover picture.id3GetGenre() - gets an ID3 tag's genre field.id3GetList() - gets an "involved people list" from an ID3 tag.id3GetObject() - gets an ID3 tag's general object.id3GetPlayCount() - gets a popularimeter/play-count field from an ID3 tag.id3GetPrivate() - gets a private data field from an ID3 tag.id3GetRegistration() - gets an ENCR/GRID registration field from an ID3 tag.id3GetSong() - gets an ID3 tag's song title.id3GetText() - gets a text information field from an ID3 tag.id3GetTrack() - gets/sets an ID3 tag's track field.id3GetUFID() - gets a unique file ID from an ID3 tag.id3GetUnsyncLyrics() - gets unsynchronized lyrics from an ID3 tag.id3GetURL() - gets a URL link from an ID3 tag.id3GetVersion() - gets an ID3 tag's version.id3GetYear() - gets an ID3 tag's year field.id3SetAlbum() - sets an ID3 tag's album field.id3SetArtist() - sets an ID3 tag's artist field.id3SetComment() - sets an ID3 tag's comment field.id3SetCover() - sets an ID3 tag's cover picture.id3SetGenre() - sets an ID3 tag's genre field.id3SetList() - sets an "involved people list" in an ID3 tag.id3SetObject() - sets a general object in an ID3 tag.id3SetPlayCount() - sets a popularimeter/play-count field in an ID3 tag.id3SetPrivate() - sets a private data field in an ID3 tag.id3SetRegistration() - sets an ENCR/GRID registration field in an ID3 tag.id3SetSong() - sets an ID3 tag's song title.id3SetText() - sets a text information field in an ID3 tag.id3SetTrack() - sets/sets an ID3 tag's track field.id3SetURL() - sets a URL in an ID3 tag.id3SetUFID() - sets a unique file ID in an ID3 tag.id3SetUnsyncLyrics() - sets unsynchronized lyrics in an ID3 tag.id3SetVersion() - sets an ID3 tag's version.id3SetYear() - sets an ID3 tag's year field.id3Flags() - gets an ID3v2 tag's header flags.id3Size() - gets an ID3v2 tag's size.id3FromGenre() - translates a genre number to its name.id3ToGenre() - translates a genre name to its number.id3FromPictureType() - translates a picture type to its name.id3ToPictureType() - translates a picture-type name to its number.
(In "id3_tag.c")
id3TagAddFrame() - adds/replaces an ID3 frame to/in an ID3 tag.id3TagCreate() - creates an empty ID3 tag.id3TagDecodeV1() - decodes an ID3v1 tag.id3TagDecodeV2() - decodes an ID3v2 tag.id3TagDeleteFrame() - deletes an ID3 frame from an ID3 tag.id3TagDeletePicture() - deletes an APIC frame from an ID3 tag.id3TagDestroy() - destroys an ID3 tag.id3TagDump() - formats and dumps an ID3 tag for debug purposes.id3TagEncodeV1() - encodes an ID3v1 tag into its file format.id3TagEncodeV2() - encodes an ID3v2 tag into its file format.id3TagErase() - erases the contents of an ID3 tag.id3TagFindFrame() - finds a specified frame in an ID3 tag.id3TagFrameCount() - gets the number of frames in an ID3 tag.id3TagGetFrame() - gets an indexed frame from an ID3 tag.id3TagMerge() - merges the contents of two ID3 tags into a third tag.id3TagSortFrames() - sorts the frames in an ID3 tag.
(In "id3_frame.c")
id3FrameAddStringV() - adds a string value to an ID3 frame.id3FrameAddValue() - adds a value to an ID3 frame.id3FrameCopy() - duplicates an ID3 frame.id3FrameCreate() - creates an empty ID3 frame.id3FrameDataCopy() - copies type-specific frame data.id3FrameDataErase() - erases type-specific frame data.id3FrameDataInit() - initializes type-specific frame data.id3FrameDecode() - decodes an ID3 frame.id3FrameDestroy() - destroys an ID3 frame.id3FrameDump() - formats and dumps an ID3 frame for debug purposes.id3FrameDumpLUT() - dumps the frame information lookup table.id3FrameEncode() - encodes an ID3v2 frame into its file format.id3FrameErase() - erases the contents of an ID3 frame.id3FrameGetValue() - gets the i-th value in an ID3 frame.id3FrameInfoByID() - looks up frame information by ID.id3FrameInfoByName() - looks up frame information by type name.id3FrameInfoByType() - looks up frame information by type.id3FrameParsePair() - parses the next pair of values in a string.id3FramePVLfromS() - constructs a paired-values list from a string.id3FramePVLtoS() - formats a paired-values list as a string.id3FrameTypeName() - returns text name for type.id3FrameUDDescOf() - looks up the description for a user-defined type.id3FrameUDTypeOf() - looks up a user-defined type.id3FrameUDUpgrade() - upgrades a frame to a predefined, user-defined type.id3FrameValueCount() - returns the number of values in an ID3 frame.
(In "id3_value.c")
id3FrameAddStringV() - adds a string value to an ID3 frame.id3ValueCopy() - duplicates an ID3 value.id3ValueCreate() - creates an empty ID3 value.id3ValueDestroy() - destroys an ID3 value.id3ValueDump() - dumps an ID3 value.id3ValueErase() - erases the contents of an ID3 value.id3_util.c
id3_tag.c
id3_frame.c
id3_value.c
id3_util.h
id3_internals.h