Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tag::ID3v2(3)	      User Contributed Perl Documentation	 Tag::ID3v2(3)

NAME
       MP3::Tag::ID3v2 - Read /	Write ID3v2.3 tags from	mp3 audio files

SYNOPSIS
       MP3::Tag::ID3v2 is designed to be called	from the MP3::Tag module.

	 use MP3::Tag;
	 $mp3 =	MP3::Tag->new($filename);

	 # read	an existing tag
	 $mp3->get_tags();
	 $id3v2	= $mp3->{ID3v2}	if exists $mp3->{ID3v2};

	 # or create a new tag
	 $id3v2	= $mp3->new_tag("ID3v2");

       See MP3::Tag for	information on the above used functions.

       * Reading a tag

	 $frameIDs_hash	= $id3v2->get_frame_ids;

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

       * Adding	/ Changing / Removing /	Writing	a tag

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

       * Removing the whole tag

	 $id3v2->remove_tag();

       * Get information about supported frames

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

AUTHOR
       Thomas Geffert, thg@users.sourceforge.net

DESCRIPTION
	   get_frame_ids()

	     $frameIDs = $tag->get_frame_ids;

	     [old name:	getFrameIDs() .	The old	name is	still available, but you should	use the	new name]

	   get_frame_ids loops through all frames, which exist in the tag. It
	   returns a hash reference with a list	of all available Frame IDs.
	   The keys of the returned hash are 4-character-codes (short names),
	   the internal	names of the frames, the according value is the
	   english (long) name of the frame.

	   You can use this list to iterate over all frames to get their data,
	   or to check if a specific frame is included in the tag.

	   If there are	multiple occurences of a frame in one tag, the first
	   frame is returned with its normal short name, following frames of
	   this	type get a '00', '01', '02', ... appended to this name.	These
	   names can then used with "get_frame"	to get the information of
	   these frames.

	   get_frame()

	     ($info, $name) = get_frame($ID);
	     ($info, $name) = get_frame($ID, 'raw');

	     [old name:	getFrame() . The old name is still available, but you should use the new name]

	   get_frame gets the contents of a specific frame, which must be
	   specified by	the 4-character-ID (aka	short name). You can use
	   "get_frame_ids" to get the IDs of the tag, or use IDs which you
	   hope	to find	in the tag. If the ID is not found, "get_frame"
	   returns (undef, undef).

	   Otherwise it	extracts the contents of the frame. Frames in ID3v2
	   tags	can be very small, or complex and huge.	That is	the reason,
	   that	"get_frame" returns the	frame data in two ways,	depending on
	   the tag.

	   If it is a simple tag, with only one	piece of data, this date is
	   returned directly as	($info,	$name),	where $info is the text
	   string, and $name is	the long (english) name	of the frame.

	   If the frame	consist	of different pieces of data, $info is a	hash
	   reference, $name is again the long name of the frame.

	   The hash, to	which $info points, contains key/value pairs, where
	   the key is always the name of the data, and the value is the	data
	   itself.

	   If the name starts with a underscore	(as eg '_code'), the data is
	   probably binary data	and not	printable. If the name starts without
	   an underscore, it should be a text string and printable.

	   If there exists a second parameter like raw,	the whole frame	data
	   is returned,	but not	the frame header. If the data was stored
	   compressed, it is also in raw mode uncompressed before it is
	   returned. Then $info	contains a string with all data	(which might
	   be binary), and $name against the long frame	name.

	   See also MP3::Tag::ID3v2-Data for a list of all supported frames,
	   and some other explanations of the returned data structure.

	   ! Encrypted frames are not supported	yet !

	   ! Some frames are not supported yet,	but the	most common ones are
	   supported !

	   write_tag()

	     $id3v2->write_tag;

	   Saves all frames to the file. It tries to update the	file in	place,
	   when	the space of the old tag is big	enough for the new tag.
	   Otherwise it	creates	a temp file with a new tag (i.e. copies	the
	   whole mp3 file) and renames/moves it	to the original	file name.

	   An extended header with CRC checksum	is not supported yet.

	   At the moment the tag is automatically unsynchronized.

	   remove_tag()

	     $id3v2->remove_tag();

	   Removes the whole tag from the file by copying the whole mp3-file
	   to a	temp-file and renaming/moving that to the original filename.

	   add_frame()

	     $fn = $id3v2->add_frame($fname, @data);

	   Add a new frame, identified by the short name $fname.  The $data
	   must	consist	from so	much elements, as described in the ID3v2.3
	   standard. If	there is need to give an encoding parameter and	you
	   would like standard ascii encoding, you can omit the	parameter or
	   set it to 0.	Any other encoding is not supported yet, and thus
	   ignored.

	   It returns the the short name $fn, which can	differ from $fname,
	   when	there existed already such a frame. If no other	frame of this
	   kind	is allowed, an empty string is returned. Otherwise the name of
	   the newly created frame is returned (which can have a 01 or 02 or
	   ... appended).

	   @data must be undef or the number of	elements of @data must be
	   equal to the	number of fields of the	tag. See also
	   MP3::Tag::ID3v2-Data.

	   You have to call write_tag()	to save	the changes to the file.

	   Examples:

	    $f = add_frame("TIT2", 0, "Abba");	 # $f="TIT2"
	    $f = add_frame("TIT2", "Abba");	 # $f="TIT201",	encoding=0 implicit

	    $f = add_frame("COMM", "ENG", "Short text",	"This is a comment");

	    $f = add_frame("COMM");		 # creates an empty frame

	    $f = add_frame("COMM", "ENG");	 # ! wrong ! $f=undef, becaues number
						 # of arguments	is wrong

	   change_frame()

	     $id3v2->change_frame($fname, @data);

	   Change an existing frame, which is identified by its	short name
	   $fname. @data must be same as in add_frame;

	   If the frame	$fname doesn't exist, undef is returned.

	   You have to call write_tag()	to save	the changes to the file.

	   remove_frame()

	     $id3v2->remove_frame($fname);

	   Remove an existing frame. $fname is the short name of a frame, eg
	   as returned by "get_frame_ids".

	   You have to call write_tag()	to save	the changes to the file.

	   supported_frames()

	     $frames = $id3v2->supported_frames();

	   Returns a hash reference with all supported frames. The keys	of the
	   hash	are the	short names of the supported frames, the according
	   values are the long (english) names of the frames.

	   what_data()

	     ($data, $res_inp) = $id3v2->what_data($fname);

	   Returns an array reference with the needed data fields for a	given
	   frame.  At this moment only the internal field names	are returned,
	   without any additional information about the	data format of this
	   field. Names	beginning with an underscore (normally '_data')	can
	   contain binary data.

	   $resp_inp is	a reference to an array, which contains	information
	   about a restriction for the content of the data field (
	   coresspodending to the same array field in the @$data array).  If
	   the entry is	undef, no restriction exists. Otherwise	it is a	hash.
	   The keys of the hash	are the	allowed	input, the correspodending
	   value is the	value which should stored later	in that	field. If the
	   value is undef then the key itself is valid for saving.  If the
	   hash	contains an entry with "_FREE",	the hash contains only
	   suggestions for the input, but other	input is also allowed.

	   Example for picture types of	the APIC frame:

	   "  {"Other" =" "\x00",
	      "32x32 pixels 'file icon'	(PNG only)" => "\x01",
	      "Other file icon"	=> "\x02",
	      ...}>

	   song()

	   Returns the song title (TIT2) from the tag.

	   track()

	   Returns the track number (TRCK) from	the tag.

	   artist()

	   Returns the artist name (TPE1 (or TPE2 if TPE1 does not exist))
	   from	the tag.

	   album()

	   Returns the album name (TALB) form the tag.

	   new()

	     $tag = new($mp3fileobj);

	   "new()" needs as parameter a	mp3fileobj, as created by
	   "MP3::Tag::File".  "new" tries to find a ID3v2 tag in the
	   mp3fileobj. If it does not find a tag it returns undef.  Otherwise
	   it reads the	tag header, as well as 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 no CRC check is done at the moment.  The
	   ID3v2-object	can be used to extract information from	the tag.

	   Please use

	      $mp3 = MP3::Tag->new($filename);
	      $mp3->get_tags();			## to find an existing tag, or
	      $id3v2 = $mp3->new_tag("ID3v2");	## to create a new tag

	   instead of using this function directly

SEE ALSO
       MP3::Tag, MP3::Tag::ID3v1, MP3::Tag::ID3v2-Data

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

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 75:
	   You can't have =items (as at	line 79) unless	the first thing	after
	   the =over is	an =item

       Around line 1251:
	   You forgot a	'=back'	before '=head1'

perl v5.32.0			  2001-08-06			 Tag::ID3v2(3)

NAME | SYNOPSIS | AUTHOR | DESCRIPTION | SEE ALSO | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MP3::Tag::ID3v2&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help