NAME

TagLib::ID3v2::Tag - An ID3v2 implementation

SYNOPSIS

use TagLib::ID3v2::Tag;

my $i = TagLib::ID3v2::Tag->new();
$i->setTitle(TagLib::String->new("sample title"));
print $i->title()->toCString(), "\n"; # got "sample title"

DESCRIPTION

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.

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.

new()

Constructs an empty ID3v2 tag.

NOTE You must create at least one frame for this tag to be valid.

new(PV $file, IV $tagOffset, FrameFactory $factory = FrameFactory::instance())

Constructs an ID3v2 tag read from $file starting from $tagOffset. $factory specifies which FrameFactory will be used for the construction of new frames.

NOTE You should be able to ignore the $factory parameter in almost all situations. You would want to specify your own FrameFactory subclass in the case that you are extending TagLib to support additional frame types, which would be incorperated into your factory.

see FrameFactory

DESTROY()

Destroys this Tag instance.

String title()

String artist()

String album()

String comment()

String genre()

UV year()

UV track()

void setTitle(String $s)

void setArtist(String $s)

void setAlbum(String $s)

void setComment(String $s)

void setGenre(String $s)

void setYear(UV $i)

void setTrack(UV $i)

BOOL isEmpty()

see Tag

Header header()

Returns the tag's header.

ExtendedHeader extendedHeader()

Returns teh tag's extended header or undef if there is no extended header.

Footer footer()

Returns the tag's footer or undef if there is no footer.

deprecated I don't see any reason to keep this around since there's nothing useful to be retrieved from the footer, but well, again, I'm prone to change my mind, so this gets to stay around until near a release.

FrameListMap frameListMap()

Returns a reference to the frame list map. This is an FrameListMap of all of the frames in the tag.

This is the most convenient structure for accessing the tag's frames. Many frame types allow multiple instances of the same frame type so this is a map of lists. In most cases however there will only be a single frame of a certain type.

WARNING You should not modify this data structure directly, instead use addFrame() and removeFrame().

see frameList()

FrameList frameList()

Returns a reference to the frame list. This is an FrameList of all of the frames in the tag in the order that they were parsed.

This can be useful if for example you want iterate over the tag's frames in the order that they occur in the tag.

WARNING You should not modify this data structure directly, instead use addFrame() and removeFrame().

FrameList frameList(ByteVector $frameID)

Returns the frame list for frames with the id $frameID or an empty list if there are no frames of that type.

see frameListMap()

void addFrame(Frame $frame)

Add a frame to the tag. At this point the tag takes ownership of the frame and will handle freeing its memory.

NOTE Using this method will invalidate any pointers on the list returned by frameList()

void removeFrame(Frame $frame, BOOL $del = TRUE)

Remove a frame from the tag. If $del is true the frame's memory will be freed; if it is false, it must be deleted by the user.

NOTE Using this method will invalidate any pointers on the list returned by frameList()

void removeFrames(ByteVector $id)

Remove all frames of type $id from the tag and free their memory.

NOTE Using this method will invalidate any pointers on the list returned by frameList()

ByteVector render()

Render the tag back to binary data, suitable to be written to disk.

EXPORT

None by default.

SEE ALSO

TagLib Tag

AUTHOR

Dongxu Ma, <dongxu.ma@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Dongxu Ma

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.