view release on metacpan or  search on metacpan

TAG/ID3v2.pm  view on Meta::CPAN

package MP3::TAG::ID3v2;

use strict;
use MP3::TAG::ID3v1;
use Compress::Zlib;

use vars qw /%format %long_names/;

=pod

=head1 NAME

MP3::TAG::ID3v2 - Read / Write ID3v2.3 tags from MP3 audio files

=head1 SYNOPSIS

MP3::TAG::ID3v2 is designed to be called from the MP3::Tag module.
It then returns a ID3v2-tag-object, which can be used in a users
program.

  $id3v2 = MP3::TAG::ID3v2->new($mp3obj);

C<$mp3obj> is a object from MP3::Tag. See according documentation.
C<$tag> is undef when no tag is found in the C<$mp3obj>.

* Reading a tag

  @frameIDs = $id3v2->getFrameIDS;

  foreach my $frame (@frameIDs) {
    my ($info, $name) = $id3v2->getFrame($frame);
    if (ref $info) {
      print "$name ($frame):\n";
      while(my ($key,$val)=each %$info) {
	print " * $key => $val\n";
      }
    } else {
      print "$name: $info\n";
    }
  }

* Changing / Writing a tag

  $id3v2->add_frame("TIT2", "Title of the song");
  $id3v2->change_frame("TALB","Greatest Album");
  $id3v2->remove_frame("TLAN");

  $id3v2->write_tag();

* Get information about supported frames

  %tags = $id3v2->supported_frames();
  while (($fname, $longname) = each %tags) {
      print "$fname $longname: ", 
            join(", ", @{$id3v2->what_data($fname)}), "\n";
  }

=head1 AUTHOR

Thomas Geffert, thg@users.sourceforge.net

=head1 DESCRIPTION

=over 4

=item new()

  $tag = new($mp3obj);

C<new()> needs as parameter a mp3obj, as created by C<MP3::Tag> (see documentation
of MP3::Tag).
C<new> tries to find a ID3v2 tag in the mp3obj. If it does not find a tag it returns undef.
Otherwise it reads the tag header, as well an extended header, if available. It reads the
rest of the tag in a buffer, does unsynchronizing if neccessary, and returns a ID3v2-object.
At this moment only ID3v2.3 is supported. Any extended header with CRC data is ignored, so
not CRC check is done at the moment.
The ID3v2-object can then be used to extract information from the tag.  

=cut
  
sub new {
  my $class = shift;
  my $mp3obj = shift;
  my $create = shift;
  my $self={mp3=>$mp3obj};
  my $header=0; my @size;
  bless $self, $class;
  
  $mp3obj->seek(0,0);
  $mp3obj->read(\$header, 10);
  $self->{frame_start}=0;

  if ($self->read_header($header)) {
    if (defined $create && $create) {
      $self->{tag_data} = '';
      $self->{data_size} = 0;
    } else {
      $mp3obj->read(\$self->{tag_data}, $self->{tagsize});
      $self->{data_size} = $self->{tagsize};
      # un-unsynchronize
      if ($self->{flags}->{unsync}) {
	my $hits= $self->{tag_data} =~ s/\xFF\x00/\xFF/gs;
	$self->{data_size} -= $hits;
      }
      # read the ext header if it exists
      if ($self->{flags}->{extheader}) {
	unless ($self->read_ext_header(substr ($self->{tag_data}, 0, 14))) {
	  return undef; # ext header not supported
	} 
      }
    }
    return $self;
  } else {
    if (defined $create && $create) {
      $self->{tag_data}='';
      $self->{tagsize} = -10;
      $self->{data_size} = 0;
      return $self;
    } 
  }
  return undef;
}

=pod

=item getFrameIDs()

  @frameIDs = $tag->getFrameIDs;

getFrameIDs loops through all frames, which exist in the tag. It returns a
list of all available Frame IDs. These are 4-character-codes (short names),

TAG/ID3v2.pm  view on Meta::CPAN

		SYLT => "Synchronized lyric/text",
		SYTC => "Synchronized tempo codes",
		TALB => "Album/Movie/Show title",
		TBPM => "BPM (beats per minute)",
		TCOM => "Composer",
		TCON => "Content type",
		TCOP => "Copyright message",
		TDAT => "Date",
		TDLY => "Playlist delay",
		TENC => "Encoded by",
		TEXT => "Lyricist/Text writer",
		TFLT => "File type",
		TIME => "Time",
		TIT1 => "Content group description",
		TIT2 => "Title/songname/content description",
		TIT3 => "Subtitle/Description refinement",
		TKEY => "Initial key",
		TLAN => "Language(s)",
		TLEN => "Length",
		TMED => "Media type",
		TOAL => "Original album/movie/show title",
		TOFN => "Original filename",
		TOLY => "Original lyricist(s)/text writer(s)",
		TOPE => "Original artist(s)/performer(s)",
		TORY => "Original release year",
		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",
		TPUB => "Publisher",
		TRCK => "Track number/Position in set",
		TRDA => "Recording dates",
		TRSN => "Internet radio station name",
		TRSO => "Internet radio station owner",
		TSIZ => "Size",
		TSRC => "ISRC (international standard recording code)",
		TSSE => "Software/Hardware and settings used for encoding",
		TYER => "Year",
		TXXX => "User defined text information frame",
		UFID => "Unique file identifier",
		USER => "Terms of use",
		USLT => "Unsychronized lyric/text transcription",
		WCOM => "Commercial information",
		WCOP => "Copyright/Legal information",
		WOAF => "Official audio file webpage",
		WOAR => "Official artist/performer webpage",
		WOAS => "Official audio source webpage",
		WORS => "Official internet radio station homepage",
		WPAY => "Payment",
		WPUB => "Publishers official webpage",
		WXXX => "User defined URL link frame", 
	       );
}

=pod

=head1 SEE ALSO

MP3::Tag, MP3::TAG::ID3v1

ID3v2 standard - http://www.id3.org

=cut


1;