NAME

SYNOPSIS

  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";
      }
  }

DESCRIPTION

The object doesn't (currently) support modification of .mp3 files; the caller has to handle the mechanics of prepending the tag to the file.

METHODS

$tag = MPEG::ID3v2Tag->new()

Creates a "MPEG::ID3v2Tag". Takes no parameters.

$arrayref = $tag->frames()

@array = $tag->frames()

Returns an array or arrayref containing all the MPEG::ID3Frame-derived objects from the tag. See FRAME SUPPORT for details on what frames can do.

$tagdata = $tag->as_string

Returns the complete tag, formatted as a binary string, ready to be slapped on the front of an .mp3 file.

$tag->set_padding_size($bytes)

Sets the number of bytes of padding to add at the end of the tag. This will be added as zero bytes. Also sets the extended_header flag if $bytes > 0.

$tag->add_frame($frame)

$tag->add_frame($frameid, [arguments])

Adds a new frame to the end of the tag. The first form takes an object derived from the class MPEG::ID3Frame and simply appends it to the list of frames. The second will take a four-letter frame id code (TALB, RBUF, SYLT, etc.) and attempt to call the 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.

@frames = $tag->get_frame(frameid)

Given a four-letter frame id, this method will search the tag's frames for all that match and return them. If called in scalar context, it will return just the first one found, if any.

$tag->flag_unsynchronization([1|0])

$tag->flag_extended_header([1|0])

$tag->flag_experimental([1|0])

These get and set the flags for the ID3v2 header. If an argument is passed, the flag will be set to that value. The current flag value is returned.

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.

MPEG::ID3v2Tag->parse($filehandle)

This method will construct a new tag by reading from a file containing an ID3v2 tag. If there is no revision 3 tag in the file, undef is returned.

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.

$tag->dump()

Dumps out the tag to the currently selected filehandle, for debugging purposes.

FRAME SUPPORT

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.

$id = $frame->frameid()

Returns the four-letter frame id code for the frame.

$frame->fully_parsed()

When a frame is read from an ID3v2 tag which has been parsed by MPEG::ID3v2Tag->parse(), actually parsing the data into a useful form may turn out to be impossible. For example, the appropriate parser routine may not be implemented, or the tag may contain a flag demanding unimplemented functionality like encryption.

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.

$frame->flag_tag_alter([1|0])

$frame->flag_file_alter([1|0])

$frame->flag_read_only([1|0])

$frame->flag_compression([1|0])

$frame->flag_encryption([1|0])

$frame->flag_grouping_identity([1|0])

These functions get and/or set the flag bits from the frame header. See the ID3v2.3.0 informal standard for semantics.

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.

$frame->dump()

Dumps out some data from this frame. This is generally overridden in subclasses to dump frame-specific data.

SUPPORTING NEW FRAMES

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.

BUGS

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.

POD ERRORS

Around line 1415:

You forgot a '=back' before '=head1'

Around line 1427:

'=item' outside of any '=over'

Around line 1483:

You forgot a '=back' before '=head2'

Around line 1493:

'=item' outside of any '=over'

Around line 1617:

You forgot a '=back' before '=head1'