|
B |
MPEG::ID3v2Tag - Parses and creates ID3v2 Tags for MPEG audio files.
use MPEG::ID3v2Tag; use IO::File;
# create a tag
$tag = MPEG::ID3v2Tag->new();
$tag->add_frame( "TIT2", "Happy Little Song" ); # one step
$frame = MPEG::ID3Frame::TALB->new("Happy little album");
$tag->add_frame($frame); # two steps
$tag->add_frame( "WCOM", "http://www.mp3.com"; );
$tag->add_frame(
"APIC",
-picture_type => 0,
-file => "happy_little_song.gif"
);
.....
$tag->set_padding_size(256);
print OUTFILE $tag->as_string();
# read a tag from a file and dump out some data.
$fh = IO::File->new("<happysong.mp3");
binmode $fh;
$tag = MPEG::ID3v2Tag->parse($fh);
for $frame ( $tag->frames() ) {
print $frame->frameid(), "\n"; # prints TALB, TIT2, WCOM, etc.
if ( $frame->flag_read_only() ) {
print " read only\n";
}
if ( $frame->fully_parsed() && $frame->frameid =~ /^T.../ ) {
print " frame text is ", $frame->text(), "\n";
}
if ( $frame->fully_parsed() && $frame->frameid =~ /^W.../ ) {
print " url is ", $frame->url(), "\n";
}
}
MPEG::ID3v2Tag is a class capable of parsing and creating ID3v2 revision 3 tags. While not all frames are fully supported, it's easy to add support for more.
The object doesn't (currently) support modification of .mp3 files; the caller has to handle the mechanics of prepending the tag to the file.
new()MPEG::ID3v2Tag. Takes no parameters.
frames()frames()set_padding_size($bytes)add_frame($frame)new() method of
the class MPEG::ID3Frame::<frameid> to create the frame to be added.
The arguments to the constructor will be those passed to ->add_frame(),
minus the frame id. If there is no new method, it will die.
For details on the arguments for supported frames, see the FRAME SUPPORT section.
get_frame(frameid)flag_unsynchronization([1|0])flag_extended_header([1|0])flag_experimental([1|0])If flag_unsynchronization is set when as_string() is called, the
unsynchronization scheme will be applied to the data portion of the
tag.
If flag_extended_header is set when as_string() is called, an
ID3v2 Extended Header will be added. This flag is set automatically
when set_padding_size() is set to a non-zero value.
parse($filehandle)The filehandle should be in binary mode. This is not necesary on some platforms, but it is on others, so it's a good habit to get into.
Frame types for which a parse_data method has been written will be parsed individually, and (should) provide appropriate access methods to retrieve the data contained in the frame.
All frame types, whether supported by a MPEG::ID3Frame subclass or not, will be read in and will be formatted appropriately when output with $tag->as_string(). You just won't be able to do anything with the data inside the tag unless a parser has been written.
This method will read the tag and leave the filehandle's file pointer at the byte immediately following the tag.
See FRAME SUPPORT for details about frames and their parsers.
dump()
Each ID3v2 frame type is implemented by its own class. TALB is implemented by MPEG::ID3Frame::TALB, OWNE is implemented by MPEG::ID3Frame::OWNE, etc.
Not all frames are currently implemented for writing, and not all frames that are implemented for writing have parsers for reading.
All frames support the following public methods, which they get from a base class called MPEG::ID3Frame.
frameid()fully_parsed()This method can be used to determine whether the tag was parsed into its component bits.
If this routine returns a false value, the reason the tag could not be parsed may be found in the $frame->{UNSUPPORTED_REASON} private variable.
Note that even if a frame can't be parsed, it can still be
retained in the tag when it is output with the $tag->as_string()
method. It will be output exactly as it appeared in the data
stream when it was read in.
flag_tag_alter([1|0])flag_file_alter([1|0])flag_read_only([1|0])flag_compression([1|0])flag_encryption([1|0])flag_grouping_identity([1|0])Note that encryption is not currently supported, and that attempting to create frames with these bits turned on may create bad headers.
If you set the compression flag on a frame, this module will attempt to load the Compress::Zlib module to compress the frame, dying if the module can't be found. When parsing a compressed frame, Compress::Zlib will be used if available. If not, the frame will not be parsed (the fully_parsed method will tell you if a frame was successfully parsed, and $frame->{UNSUPPORTED_REASON} will give you a string telling you why), but no fatal errors will be generated.
dump()
In addition to the above methods, each individual supported frame will
have a new() constructor (which can be called directly, or implicitly by
$tag->add_frame()) and possibly access methods for the data contained
in the frame. In the list below, the constructor is shown as a call
to $tag->add_frame(<tagname>, <arguments>), but remember you can
call MPEG::ID3Frame::TALB->new(<arguments>) and pass the return
value to add_frame.
TALB TBPM TCOM TCON TCOP TDAT TDLY TENC TEXT TFLT TIME TIT1 TIT2 TIT3 TKEY TLAN TLEN TMED TOAL TOFN TOLY TOPE TORY TOWN TPE1 TPE2 TPE3 TPE4 TPOS TPUB TRCK TRDA TRSN TRSO TSIZ TSRC TSSE TYER
The constructor is generally called like this:
[$frame = ]$tag->add_frame(TALB, ``text string'', [optional_encoding]) ;
You can get the encoding value with $frame->encoding() and the
text string value with $frame->text().
Parsing is implemented for these frames.
The constructor is generally called like this:
[$frame = ]$tag->add_frame(WCOM, ``text string'', [optional_encoding]) ;
You can read back the url with $frame->url().
[$frame = ]$tag->add_frame(UFID, $owner_idstring, $id) ;
There is currently no parsing support.
$tag->add_frame(USLT, $encoding, $language, $content_descriptor, $lyrics) ;
also supports parsing, and these access methods: encoding(), language(), content_descriptor(), and lyrics() ;
The constructor is called as
$tag->add_frame(APIC, [switches])
where switches can be:
-encoding => $encoding
-mime[type] => $mime_type
-picture_type => $picture_type
-desc[ription] => $description
-fh => $filehandle
-fn[ame] => $filename
-data => $data
At least one of -fh, -fn, or -data must be provided. -data takes the images as a binary string. -fh provides an open filehandle on the image file, and -fn provides a file for reading.
-mimetype must be provided also. However, if -fname is used, and the filename ends in '.gif' or '.jpg', the mime type will be assumed 'image/gif' or 'image/jpg'.
There is currently no parsing support.
$tag->add_frame(``USER'', $encoding, $language, $text) ;
There is no parsing support.
$tag->add_frame(``COMM'', $encoding, $language, $description, $text) ;
There is no parsing support.
$tag->add_frame(``WXXX'', $encoding, $description, $url) ;
Parsing support exists. As well as the following accessor methods: encoding, description, url
$tag->add_frame(``TXXX'', $encoding, $description, $text) ;
Parsing support exists. As well as the following accessor methods: encoding, description, text
Adding support for more frames is very simple. In general, all you need to do is copy and tweak one of the supported frames (USER is a nice simple one to start from).
Suppose we're adding support for frame XXXX. Read the section about XXXX in the ID3v2.3.0 spec, then...
Create a new package MPEG::ID3Frame::XXXX.
Derive it from MPEG::ID3Frame (put ``MPEG::ID3Frame'' in its @ISA array).
create a subroutine/method called frameid() that just returns ``XXXX''.
create a constructor called new(), which takes whatever arguments you will need.
create a data_as_string method to construct the frame based on
the ID3v2.3.0 spec. pack() is helpful, here.
Optionally, create access methods for the data you passed in in your constructor.
Optionally, create a parse_data method which takes the data portion of the frame and parses out the data so your access methods can access them. If your parser finds it can't parse the body data, it should set $self->{UNSUPPORTED_BODY} to the string passed in, and $self->{UNSUPPORTED_REASON} to a short string giving the reason it failed.
Optionally, create a dump() method.
Make sure that you get the same answer if you write out the frame, read it in, and write it out again.
Creating tags with encryption will probably explode.
Encrypted tags can't be parsed. They can be read in and written back out, however.
UNICODE character encodings will currently fail on input or output.
No support for modifying .mp3 files.
Many frame types unimplemented.
Most frame types don't have parsers.
|
B |