The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Audio-TagLib-1.59
River stage zero No dependents
/ Audio::TagLib::ID3v2

NAME

Audio::TagLib::ID3v2 - Classes in this namespace

SYNOPSIS

  use Audio::TagLib::ID3v2;

DESCRIPTION

There is no C++ imlementation corresponding to this file. Rather, there is a collection of classes, linked to below. A careful study of the taglib documentation is reccomended.

AttachedPictureFrame

This is an implementation of ID3v2 attached pictures. Pictures may be included in tags, one per APIC frame (but there may be multiple APIC frames in a single tag). These pictures are usually in either JPEG or PNG format.

CommentsFrame

This implements the ID3v2 comment format. An ID3v2 comment concists of a language encoding, a description and a single text field.

ExtendedHeader

This class implements ID3v2 extended headers. It attempts to follow, both semantically and programatically, the structure specified in the ID3v2 standard. The API is based on the properties of ID3v2 extended headers specified there. If any of the terms used in this documentation are unclear please check the specification in the linked section. (Structure, 3.2)

Per the ID3v2 specification, the tag's footer is just a copy of the information in the header. As such there is no API for reading the data from the header, it can just as easily be done from the header.

In fact, at this point, TagLib does not even parse the footer since it is not useful internally. However, if the flag to include a footer has been set in the ID3v2::Tag, TagLib will render a footer.

FrameFactoryactory

A factory for creating ID3v2 frames during parsing.

This factory abstracts away the frame creation process and instantiates the appropriate ID3v2::Frame subclasses based on the contents of the data.

Reimplementing this factory is the key to adding support for frame types not directly supported by TagLib to your application. To do so you would subclass this factory reimplement createFrame(). Then by setting your factory to be the default factory in ID3v2::Tag constructor or with MPEG::File::setID3v2FrameFactory() you can implement behavior that will allow for new ID3v2::Frame subclasses (also provided by you) to be used.

This implements both abstract factory and singleton patterns of which more information is available on the web and in software design textbooks (Notably Design Patters).

Note: You do not need to use this factory to create new frames to add to an ID3v2::Tag. You can instantiate frame subclasses directly (with new) and add them to a tag using ID3v2::Tag::addFrame()

See also: ID3v2::Tag::addFrame()

FrameListMap

FrameList

Frame

ID3v2 frame implementation.

ID3v2 frame header implementation.

This class is the main ID3v2 frame implementation. In ID3v2, a tag is split between a collection of frames (which are in turn split into fields (Structure, 4) (Frames). This class provides an API for gathering information about and modifying ID3v2 frames. Funtionallity specific to a given frame type is handed in one of the many subclasses.

The ID3v2 Frame Header (Structure, 4)

Every ID3v2::Frame has an associated header that gives some general properties of the frame and also makes it possible to identify the frame type.

As such when reading an ID3v2 tag ID3v2::FrameFactory first creates the frame headers and then creates the appropriate Frame subclass based on the type and attaches the header.

An implementation of ID3v2 headers.

This class implements ID3v2 headers. It attempts to follow, both semantically and programatically, the structure specified in the ID3v2 standard. The API is based on the properties of ID3v2 headers specified there. If any of the terms used in this documentation are unclear please check the specification in the linked section. (Structure, 3.1)

RelativeVolumeFrame

An ID3v2 relative volume adjustment frame implementation.

This is an implementation of ID3v2 relative volume adjustment. The presence of this frame makes it possible to specify an increase in volume for an audio file or specific audio tracks in that file.

Multiple relative volume adjustment frames may be present in the tag each with a unique identification and describing volume adjustment for different channel types.

SynchData

A few functions for ID3v2 synch safe integer conversion

Tag

The main class in the ID3v2 implementation.

This is the main class in the ID3v2 implementation. It serves two functions. This first, as is obvious from the public API, is to provide a container for the other ID3v2 related classes. In addition, through the read() and parse() protected methods, it provides the most basic level of parsing. In these methods the ID3v2 tag is extracted from the file and split into data components.

ID3v2 tags have several parts, TagLib attempts to provide an interface for them all. header(), footer() and extendedHeader() corespond to those data structures in the ID3v2 standard and the APIs for the classes that they return attempt to reflect this.

Also ID3v2 tags are built up from a list of frames, which are in turn have a header and a list of fields. TagLib provides two ways of accessing the list of frames that are in a given ID3v2 tag. The first is simply via the frameList() method. This is just a list of pointers to the frames. The second is a map from the frame type -- i.e. "COMM" for comments -- and a list of frames of that type. (In some cases ID3v2 allows for multiple frames of the same type, hence this being a map to a list rather than just a map to an individual frame.)

More information on the structure of frames can be found in the ID3v2::Frame class.

read() and parse() pass binary data to the other ID3v2 class structures, they do not handle parsing of flags or fields, for instace. Those are handled by similar functions within those classes.

This is one way to create a ID3V2 Tag object. If you wan't to fool with tags, this will work However, if you're looking to fool with tags in a file, how do you get to the file? One way is with a FileRef object (which see), but working with a File object is difficult, because its new() is hard to find. Try this:

     $file = "sample/guitar.mp3";
 $tagOffset = 0;
 $file_object = Audio::TagLib::MPEG::File->new($file, $tagOffset);
 $file_tag_object = $file_object->ID3v2Tag();

Note: All pointers to data structures within the tag will become invalid when the tag is destroyed.

Warning: Dealing with the nasty details of ID3v2 is not for the faint of heart and should not be done without much meditation on the spec. It's rather long, but if you're planning on messing with this class and others that deal with the details of ID3v2 (rather than the nice, safe, abstract TagLib::Tag and friends), it's worth your time to familiarize yourself with said spec (which is distrubuted with the TagLib sources). TagLib tries to do most of the work, but with a little luck, you can still convince it to generate invalid ID3v2 tags. The APIs for ID3v2 assume a working knowledge of ID3v2 structure. You're been warned.

TextIdentificationFrame

An ID3v2 text identification frame implementation.

This is an implementation of the most common type of ID3v2 frame -- text identification frames. There are a number of variations on this. Those enumerated in the ID3v2.4 standard are:

TALB Album/Movie/Show title
TBPM BPM (beats per minute)
TCOM Composer
TCON Content type
TDEN Encoding time
TDLY Playlist delay
TDOR Original release time
TDRC Recording time
TDRL Release time
TDTG Tagging time
TENC Encoded by
TEXT Lyricist/Text writer
TFLT File type
TIPL Involved people list
TIT1 Content group description
TIT2 Title/songname/content description
TIT3 Subtitle/Description refinement
TKEY Initial key
TLAN Language(s)
TLEN Length
TMCL Musician credits list
TMED Media type
TMOO Mood
TOAL Original album/movie/show title
TOFN Original filename
TOLY Original lyricist(s)/text writer(s)
TOPE Original artist(s)/performer(s)
TOWN File owner/licensee
TPE1 Lead performer(s)/Soloist(s)
TPE2 Band/orchestra/accompaniment
TPE3 Conductor/performer refinement
TPE4 Interpreted, remixed, or otherwise modified by
TPOS Part of a set
TPRO Produced notice
TPUB Publisher
TRCK Track number/Position in set
TRSN Internet radio station name
TRSO Internet radio station owner
TSOA Album sort order
TSOP Performer sort order
TSOT Title sort order
TSRC ISRC (international standard recording code)
TSSE Software/Hardware and settings used for encoding
TSST Set subtitle

The ID3v2 Frames document gives a description of each of these formats and the expected order of strings in each. ID3v2::Header::frameID() can be used to determine the frame type.

Note: If non-Latin1 compatible strings are used with this class, even if the text encoding is set to Latin1, the frame will be written using UTF8 (with the encoding flag appropriately set in the output).

UniqueFileIdentifierFrame

An implementation of ID3v2 unique identifier frames.

This is an implementation of ID3v2 unique file identifier frames. This frame is used to identify the file in an arbitrary database identified by the owner field.

UnknownFrame

A frame type unknown to TagLib.

This class represents a frame type not known (or more often simply unimplemented) in TagLib. This is here provide a basic API for manipulating the binary data of unknown frames and to provide a means of rendering such unknown frames.

Please note that a cleaner way of handling frame types that TagLib does not understand is to subclass ID3v2::Frame and ID3v2::FrameFactory to have your frame type supported through the standard ID3v2 mechanism.

UserTextIdentificationFrame

An ID3v2 custom text identification frame implementationx.

This is a specialization of text identification frames that allows for user defined entries. Each entry has a description in addition to the normal list of fields that a text identification frame has.

This description identifies the frame and must be unique.

EXPORT

None by default.

SEE ALSO

Audio::TagLib

AUTHOR

Dongxu Ma, <dongxu@cpan.org>

MAINTAINER

Geoffrey Leach GLEACH@cpan.org

COPYRIGHT AND LICENSE

Copyright (C) 2005-2010 by Dongxu Ma

Copyright (C) 2011 - 2012 Geoffrey Leach

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.