This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: MP3/Napster/Base, Next: MP3/Napster/Channel, Prev: MP3/Napster, Up: Module List Autoload object accessors ************************* NAME ==== MP3::Napster::Base - Autoload object accessors SYNOPSIS ======== None DESCRIPTION =========== This class is used internally by MP3::Napster as a base class for MP3::Napster::Song, MP3::Napster::Channel, MP3::Napster::Transfer, and MP3::Napster itself. It provides autoloading facilities for accessors. Documentation will be added if and when it becomes useful to application developers. AUTHOR ====== Lincoln Stein . COPYRIGHT ========= Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== *Note MP3/Napster: MP3/Napster,, *Note MP3/Napster/Song: MP3/Napster/Song,, *Note MP3/Napster/Channel: MP3/Napster/Channel,, and `MPEG::Napster::Transfer' in this node  File: pm.info, Node: MP3/Napster/Channel, Next: MP3/Napster/IOEvent, Prev: MP3/Napster/Base, Up: Module List Object-oriented access to Napster channels ****************************************** NAME ==== MP3::Napster::Channel - Object-oriented access to Napster channels SYNOPSIS ======== @channels = $nap->channels; foreach $chan (@channels) { print $chan->name,"\n"; print $chan->topic,"\n"; print $chan->user_count,"\n"; print $chan->server,"\n"; @users = $chan->users,"\n"; } $chan->join && print "Welcome to $chan!\n"; $chan->part && print "Goodbye!\n"; DESCRIPTION =========== MP3::Napster::Channel provides object-oriented access to discussion channels on the Napster service. OBJECT CONSTRUCTION ------------------- Channel objects are normally not constructed from scratch but are returned by the MPEG::Napster channels() method. OBJECT METHODS -------------- Methods provide access to various attributes of the Channel object and allow you to join and depart the channel. Accessors The accessors provide read-only access to the following Channel attributes. Accessor Description -------- ----------- $channel->name Channel name $channel->user_count Number of users enrolled in channel $channel->topic Channel's topic (welcome banner) $channel->server MP3::Napster object from which channel was derived *@users = $channel->users* This method returns the current list of users subscribed to the channel. The return value is an array of MP3::Napster::User objects. *$result = $channel->join* Attempt to join the channel, and return a true result if successful. *$result = $channel->join* Attempt to join the channel, returning a true result if successful. *$result = $channel->part* Attempt to depart from the channel, returning a true result if successful. *String Overloading* If used in a string context, MPEG::Napster::Channel objects will invoke the name() method, allowing the objects to be directly interpolated into strings, printed, and pattern matched. AUTHOR ====== Lincoln Stein . COPYRIGHT ========= Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== *Note MP3/Napster: MP3/Napster,, *Note MP3/Napster/Song: MP3/Napster/Song,, *Note MP3/Napster/User: MP3/Napster/User,, and `MPEG::Napster::Transfer' in this node  File: pm.info, Node: MP3/Napster/IOEvent, Next: MP3/Napster/Registry, Prev: MP3/Napster/Channel, Up: Module List MP3::Napster::IOEvent ********************* NAME ==== MP3::Napster::IOEvent SYNOPSIS ======== DESCRIPTION =========== AUTHOR ====== Lincoln Stein . COPYRIGHT ========= Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ========  File: pm.info, Node: MP3/Napster/Registry, Next: MP3/Napster/Server, Prev: MP3/Napster/IOEvent, Up: Module List Manage local songs shared by MP3::Napster ***************************************** NAME ==== MP3::Napster::Registry - Manage local songs shared by MP3::Napster SYNOPSIS ======== None DESCRIPTION =========== This class is used internally by MP3::Napster to manage the list of local MP3 files that are shared with other users. Documentation will be added if and when it becomes useful to application developers. AUTHOR ====== Lincoln Stein . COPYRIGHT ========= Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== *Note MP3/Napster: MP3/Napster,, *Note MP3/Napster/Song: MP3/Napster/Song,, and `MPEG::Napster::Transfer' in this node  File: pm.info, Node: MP3/Napster/Server, Next: MP3/Napster/Song, Prev: MP3/Napster/Registry, Up: Module List MP3::Napster::Echo ****************** NAME ==== MP3::Napster::Echo SYNOPSIS ======== DESCRIPTION =========== AUTHOR ====== Lincoln Stein . COPYRIGHT ========= Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ========  File: pm.info, Node: MP3/Napster/Song, Next: MP3/Napster/User, Prev: MP3/Napster/Server, Up: Module List Object-oriented access to Napster shared songs ********************************************** NAME ==== MP3::Napster::Song - Object-oriented access to Napster shared songs SYNOPSIS ======== @songs = $nap->browse('sexybabe'); foreach $song (@songs) { print $song->name,"\n"; print $song->size,"\n"; print $song->bitrate,"\n"; print $song->freq,"\n"; print $song->owner,"\n"; print $song->length,"\n"; print $song->hash,"\n"; print $song->address,"\n"; print $song->link,"\n"; } $songs[0]->download; # download to local disk DESCRIPTION =========== MP3::Napster::Song provides object-oriented access to shared MP3 files that can be retrieved via the Napster network protocol. OBJECT CONSTRUCTION ------------------- Song objects are normally not constructed *de novo*, but are returned by search() and browse() calls to MPEG::Napster objects. OBJECT METHODS -------------- Object methods provide access to various attributes of the sound file, and allow you to download the file to disk or pass its data to a pipe. Accessors The accessors provide read-only access to the Song object's attributes. Accessor Description -------- ----------- $song->name Title of the song, often including artist $song->title Same as above $song->size Physical size of file, in bytes $song->bitrate Bit rate of MP3 data, in kilobits/sec $song->freq Sampling frequency, in Hz $song->length Duration of song, in seconds $song->owner Owner of the song, as an MP3::Napster::User object $song->path Physical path of the song, at the remote end $song->hash MD5 hash of the first 300K of the song, for identification $song->address IP address of the client that holds the song $song->link The link speed of the owner, as a string (e.g. LINK_DSL) $song->link_code The link speed of the owner, as a numeric code (e.g. 3) $song->server The MP3::Napster object from which this song was retrieved *$transfer = $song->download( [$path | $fh] )* The download() method will initiate a download on the song. The method behaves like the MP3::Napster->download() method. If no argument is provided, the method will open up a file in the location specified by the MP3::Napster object's download_dir() method. Otherwise the song data will be written to the indicated path or filehandle. If successful, the method will return a MP3::Napster::Transfer object, which can be used to monitor and control the download process. *String Overloading* If used in a string context, MPEG::Napster::Song objects will invoke the name() method. This allows the objects to be directly interpolated into strings, printed, and pattern matched. AUTHOR ====== Lincoln Stein . COPYRIGHT ========= Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== *Note MP3/Napster: MP3/Napster,, *Note MP3/Napster/User: MP3/Napster/User,, *Note MP3/Napster/Channel: MP3/Napster/Channel,, and `MPEG::Napster::Transfer' in this node  File: pm.info, Node: MP3/Napster/User, Next: MP3/Napster/UserCommand, Prev: MP3/Napster/Song, Up: Module List Object-oriented access to Napster users *************************************** NAME ==== MP3::Napster::User - Object-oriented access to Napster users SYNOPSIS ======== $user = $nap->whois('glimitz'); print $user->name,"\n"; print $user->sharing,"\n"; print $user->link,"\n"; print $user->link_code,"\n"; print $user->server,"\n"; print $user->current_channel,"\n"; print join ' ',$user->channels,"\n"; print $user->login_time,"\n"; print $user->time,"\n"; print $user->channels,"\n"; print $user->uploads,"\n"; print $user->downloads,"\n"; print $user->level,"\n"; print $user->last_seen,"\n"; print $user->profile,"\n"; $user->ping || warn "$user is unreachable"; $user->msg('Hello there!'); DESCRIPTION =========== MP3::Napster::User provides object-oriented access to other users on the Napster service. OBJECT CONSTRUCTION ------------------- User objects are normally not constructed *de novo*, but are returned by the MPEG::Napster whois() and users() methods, as well as by several of the callbacks involving the Napster chat channels, specifically USER_JOINS and USER_DEPARTS. OBJECT METHODS -------------- Object methods provide access to various attributes of the User object, allow you to send private messages to users, to browse their files, and to ping them to determine if they are online. Accessors The accessors provide read-only access to the following User attributes. Accessor Description -------- ----------- $user->name User's (nick)name $user->link User's link speed as a string $user->link_code User's link speed as a numeric code $user->sharing Number of files user is sharing $user->current_channel User's current channel $user->channels List of channels that user is subscribed to $user->uploads Number of uploads the user is currently performing $user->downloads Number of downloads the user is currently performing $user->level The user's "level", one of "User" or "Admin" $user->status One of "Offline", "Active" or "Inactive" $user->last_seen The time the user was last seen, in seconds since the epoch $user->time The number of seconds that the user has been logged in $user->login_time The same, in a nice human-readable form $user->client The version of the user's Napster client $user->server The MP3::Napster that this User is attached to *$result = $user->ping([$timeout])* The ping() method returns true if the user is reachable by a PING command. The default timeout for a positive response is defined by MP3::Napster, currently 5 seconds by default. *@songs = $user->browse* Browse the user's shared files, returning an array of MP3::Napster::Song objects. *$user->update* Update the user's attributes from the most current versions on the server. Withoug calling update() the values are always those present when the object was first created. *$user->msg("text")* Send a private message to the user. *$profile = $user->profile* Return a human readable profile like this one: Name: OddBall187 Status: Active Sharing: 62 Link: CABLE Level: User Time: 53.5 min Channels: Themes,Alternative,Rap,Rock Uploads: 5 Downloads: 1 Client: v2.0 *String Overloading* If used in a string context, MPEG::Napster::User objects will invoke the name() method, allowing the objects to be directly interpolated into strings, printed, and pattern matched. AUTHOR ====== Lincoln Stein . COPYRIGHT ========= Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== *Note MP3/Napster: MP3/Napster,, *Note MP3/Napster/Song: MP3/Napster/Song,, *Note MP3/Napster/Channel: MP3/Napster/Channel,, and `MPEG::Napster::Transfer' in this node  File: pm.info, Node: MP3/Napster/UserCommand, Next: MP3/TAG/ID3v1, Prev: MP3/Napster/User, Up: Module List MP3::Napster::Echo ****************** NAME ==== MP3::Napster::Echo SYNOPSIS ======== DESCRIPTION =========== AUTHOR ====== Lincoln Stein . COPYRIGHT ========= Copyright (c) 2000 Cold Spring Harbor Laboratory. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ========  File: pm.info, Node: MP3/TAG/ID3v1, Next: MP3/TAG/ID3v2, Prev: MP3/Napster/UserCommand, Up: Module List Perl extension for reading / writing ID3v1 tags of mp3-files ************************************************************ NAME ==== MP3::TAG::ID3v1 - Perl extension for reading / writing ID3v1 tags of mp3-files 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. use MP3::TAG::ID3v1; $id3v1 = MP3::TAG::ID3v1->new($mp3obj); `$mp3obj' is a object from MP3::Tag. See according documentation. $tag is undef when no tag is found in the `$mp3obj'. * Reading the tag print " Song: " .$id3v1->song . "\n"; print " Artist: " .$id3v1->artist . "\n"; print " Album: " .$id3v1->album . "\n"; print "Comment: " .$id3v1->comment . "\n"; print " Year: " .$id3v1->year . "\n"; print " Genre: " .$id3v1->genre . "\n"; print " Track: " .$id3v1->track . "\n"; @tagdata = $mp3->all(); foreach (@tagdata) { print $_; } * Changing / Writing the tag $id3v1->comment("This is only a Test Tag"); $id3v1->song("testing"); $id3v1->artist("Artest"); $id3v1->album("Test it"); $id3v1->year("1965"); $id3v1->track("5"); $id3v1->genre("Blues"); # or at once $id3v1->all("song title","artist","album","1900","comment",10,"Ska");# $id3v1->writeTag; AUTHOR ====== Thomas Geffert, thg@users.sourceforge.net DESCRIPTION =========== new() $id3v1 = MP3::TAG::ID3v1->new($mp3obj[, $create]); Generally called from MP3::TAG, because a $mp3obj is needed. If $create is true, a new tag is created. Otherwise undef is returned, if now ID3v1 tag is found in the $mp3obj. song(), artist(), album(), year(), comment(), track(), genre() $artist = $id3v1->artist; $artist = $id3v1->artist($artist); $album = $id3v1->album; $album = $id3v1->album($album); $year = $id3v1->year; $year = $id3v1->year($year); $comment = $id3v1->comment; $comment = $id3v1->comment($comment); $track = $id3v1->track; $track = $id3v1->track($track); $genre = $id3v1->genre; $genre = $id3v1->genre($genre); Use these functions to retrieve the date of these fields, or to set the data. $genre can be a string with the name of the genre, or a number describing the genre. all() @tagdata = $id3v1->all; @tagdata = $id3v1->all($song, $artist, $album, $year, $comment, $track, $genre); Returns all information of the tag in a list. You can use this sub also to set the data of the complete tag. The order of the data is always song, artist, album, year, comment, track, and genre. genre has to be a string with the name of the genre, or a number identifying the genre. writeTag() $id3v1->writeTag; Writes the ID3v1 tag to the file. removeTag() $id3v1->removeTag; Removes the ID3v1 tag from the file. genres() @allgenres = $id3v1->genres; $genreName = $id3v1->genres($genreID); $genreID = $id3v1->genres($genreName); Returns a list of all genres, or the according name or id to a given id or name. SEE ALSO ======== MP3::Tag, MP3::TAG::ID3v2 ID3v1 standard - http://www.id3.org  File: pm.info, Node: MP3/TAG/ID3v2, Next: MP3/Tag, Prev: MP3/TAG/ID3v1, Up: Module List Read / Write ID3v2.3 tags from MP3 audio files ********************************************** 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. It then returns a ID3v2-tag-object, which can be used in a users program. $id3v2 = MP3::TAG::ID3v2->new($mp3obj); `$mp3obj' is a object from MP3::Tag. See according documentation. $tag is undef when no tag is found in the `$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"; } AUTHOR ====== Thomas Geffert, thg@users.sourceforge.net DESCRIPTION =========== new() $tag = new($mp3obj); new() needs as parameter a mp3obj, as created by `MP3::Tag' (see documentation of MP3::Tag). 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. 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), the internal names of the frames. 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 expanded names can then used with `getFrame' to get the information of these frames. getFrame() ($info, $name) = getFrame($ID); ($info, $name) = getFrame($ID, 'raw'); getFrame gets the contents of a specific frame, which must be specified by the 4-character-ID (aka short name). You can use `getFrameIDs' to get the IDs of the tag, or use IDs which you hope to find in the tag. If the ID is not found, getFrame 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 getFrame 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. ! 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 a frame to the file. It tries to update the file in place, when the space of the old tag is big enoug for the new tag. Otherwise it creates a temp file (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() $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. Examples: add_frame("TIT2", 0, "Abba"); # both the same, but add_frame("TIT2", "Abba"); # this one with implicit encoding add_frame("COMM", "ENG", "Short text", "This is a comment"); 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; remove_frame() $id3v2->remove_frame($fname); Remove an existing frame. $fname is the short name of a frame, eg as returned by `getFrameIDs'. supported_frames() %frames = $id3v2->supported_frames(); Returns a hash 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 = $id3v2->what_data($fname); Returns for a frame the needed data fields to write this tag. 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. This will change hopefully later on... SEE ALSO ======== MP3::Tag, MP3::TAG::ID3v1 ID3v2 standard - http://www.id3.org  File: pm.info, Node: MP3/Tag, Next: MP3/Tag/File, Prev: MP3/TAG/ID3v2, Up: Module List Module for reading tags of MP3 audio files ****************************************** NAME ==== Tag - Module for reading tags of MP3 audio files SYNOPSIS ======== use Tag; $mp3 = MP3::Tag->new($filename); $mp3->getTags; if (exists $mp3->{ID3v1}) { $id3v1 = $mp3->{ID3v1}; print $id3v1->song; ... } if (exists $mp3->{ID3v2}) { ($name, $info) = $mp3->{ID3v2}->getFrame("TIT2"); ... } $mp3->close(); AUTHOR ====== Thomas Geffert, thg@users.sourceforge.net DESCRIPTION =========== Tag is a wrapper module to read different tags of mp3 files. It provides an easy way to access the functions of seperate moduls which do the handling of reading/writing the tags itself. At the moment MP3::Tag::ID3v1 and MP3::Tag::ID3v2 are supported. !! As this is only a beta version, it is very likely that the design !! of this wrapper module will change soon !! new() $mp3 = MP3::Tag->new($filename); Creates a mp3-object, which can be used to retrieve/set different tags. getTags() @tags = $mp3->getTags; Checks which tags can be found in the mp3-object. It returns a list @tags which contains strings identifying the found tags. Each found tag can be accessed then with $mp3->{tagname} . Use the information found in MP3::Tag::ID3v1 and MP3::Tag::ID3v2 to see what you can do with the tags. newTag() $tag = $mp3->newTag($tagname); Creates a new tag of the given type $tagname. You can access it then with $mp3->{$tagname}. At the moment ID3v1 and ID3v2 are supported as tagname. Returns an tag-object: $mp3->{$tagname}. close() $mp3->close; You can use close() to explicitly close a file. Normally this is done automatically by the module, so that you don't need to do this. genres() $allgenres = $mp3->genres; $genreName = $mp3->genres($genreID); $genreID = $mp3->genres($genreName); Returns a list of all genres (reference to an array), or the according name or id to a given id or name. This function is only a shortcut to MP3::Tag::ID3v1->genres. This can be also called as MP3::Tag->genres; =cut sub genres { # returns all genres, or if a parameter is given, the according genre my $self=shift; return MP3::Tag::ID3v1::genres(shift); } autoinfo() ($song, $track, $artist, $album) = $mp3->autoinfo(); $info_hashref = $mp3->autoinfo(); autoinfo() returns information about the song name, song number, artist number and album name. It can get this information from an ID3v1-tag, an ID3v2-tag and from the filename itself. It will as default first try to find a ID3v2-tag to get this information. If this cannot be found it tries to find a ID3v1-tag and if this is not present either, it will use the filename to retrieve the information. You can change the order of this with the config() command. autoinfo() returns an array with the information or a hashref. The hash then has the keys song, track, artist, album where the information is stored. config MP3::Tag->config("item", options, ...); Possible items are: * autoinfo Configure the order in which ID3v1-, ID3v2-tag and filename are used by autoinfo. options can be "ID3v1","ID3v2","filename". The order in which they are given to config also sets the order how they are used by autoinfo. If an option is not present, it will not be used by auotinfo. $mp3->config("autoinfo","ID3v1","ID3v2","filename"); sets the order to check first ID3v1, then ID3v2 and last the Filename $mp3->config("autoinfo","ID3v1","filename","ID3v2"); sets the order to check first ID3v1, then the Filename and last ID3v2. As the filename will be always present ID3v2 will be checked never. $mp3->config("autoinfo","ID3v1","ID3v2"); sets the order to check first ID3v1, then ID3v2. The filename will be never used. * Later this will be used probably to configure more things. SEE ALSO ======== *Note MP3/Tag/ID3v1: MP3/Tag/ID3v1,, *Note MP3/Tag/ID3v2: MP3/Tag/ID3v2,, *Note MP3/Tag/File: MP3/Tag/File,  File: pm.info, Node: MP3/Tag/File, Next: MP3/Tag/ID3v1, Prev: MP3/Tag, Up: Module List Module for reading / writing files ********************************** NAME ==== MP3::Tag::File - Module for reading / writing files SYNOPSIS ======== MP3::Tag::File is designed to be called from the MP3::Tag module. It offers possibilities to read/write data from files. read_filename($what, $filename) read_filename() tries to extract information about artist, song, song number and album from the filename. This is likely to fail for a lot of filenames, especially the album will be often wrongly guessed, as the name of the parent directory is taken as album name. $what and $filename are optional. $what maybe song, track, artist or album. If $what is defined read_filename will return only this element. If $filename is defined this filename will be used and not the real filename. Following formats will be hopefully recognized: album name/artist name - song name.mp3 album_name/artist_name-song_name.mp3 album.name/artist.name_song.name.mp3 album name/(artist name) song name.mp3 album name/01. artist name - song name.mp3 album name/artist name - 01 - song.name.mp3 song($filename) Returns the song name, guessed from the filename. See also read_filename() $filename is optional and if defined will be used instead of the real filename. artist($filename) Returns the artist name, guessed from the filename. See also read_filename() $filename is optional and if defined will be used instead of the real filename. track($filename) Returns the track number, guessed from the filename. See also read_filename() $filename is optional and if defined will be used instead of the real filename. album($filename) Returns the album name, guessed from the filename. See also read_filename() The album name is guessed from the parent directory so be careful with this! $filename is optional and if defined will be used instead of the real filename.  File: pm.info, Node: MP3/Tag/ID3v1, Next: MP3/Tag/ID3v2, Prev: MP3/Tag/File, Up: Module List Module for reading / writing ID3v1 tags of MP3 audio files ********************************************************** NAME ==== MP3::Tag::ID3v1 - Module for reading / writing ID3v1 tags of MP3 audio files SYNOPSIS ======== MP3::Tag::ID3v1 is designed to be called from the MP3::Tag module. It then returns a ID3v1-tag-object, which can be used in a users program. use MP3::Tag::ID3v1; $id3v1 = MP3::Tag::ID3v1->new($mp3obj); `$mp3obj' is a object from MP3::Tag. See `MP3::Tag|according documentation' in this node. $tag is undef when no tag is found in the `$mp3obj'. * Reading the tag print " Song: " .$id3v1->song . "\n"; print " Artist: " .$id3v1->artist . "\n"; print " Album: " .$id3v1->album . "\n"; print "Comment: " .$id3v1->comment . "\n"; print " Year: " .$id3v1->year . "\n"; print " Genre: " .$id3v1->genre . "\n"; print " Track: " .$id3v1->track . "\n"; @tagdata = $mp3->all(); foreach (@tagdata) { print $_; } * Changing / Writing the tag $id3v1->comment("This is only a Test Tag"); $id3v1->song("testing"); $id3v1->artist("Artest"); $id3v1->album("Test it"); $id3v1->year("1965"); $id3v1->track("5"); $id3v1->genre("Blues"); # or at once $id3v1->all("song title","artist","album","1900","comment",10,"Ska");# $id3v1->writeTag; AUTHOR ====== Thomas Geffert, thg@users.sourceforge.net DESCRIPTION =========== new() $id3v1 = MP3::Tag::ID3v1->new($mp3obj[, $create]); Generally called from MP3::Tag, because a $mp3obj is needed. If $create is true, a new tag is created. Otherwise undef is returned, if now ID3v1 tag is found in the $mp3obj. song(), artist(), album(), year(), comment(), track(), genre() $artist = $id3v1->artist; $artist = $id3v1->artist($artist); $album = $id3v1->album; $album = $id3v1->album($album); $year = $id3v1->year; $year = $id3v1->year($year); $comment = $id3v1->comment; $comment = $id3v1->comment($comment); $track = $id3v1->track; $track = $id3v1->track($track); $genre = $id3v1->genre; $genre = $id3v1->genre($genre); Use these functions to retrieve the date of these fields, or to set the data. $genre can be a string with the name of the genre, or a number describing the genre. all() @tagdata = $id3v1->all; @tagdata = $id3v1->all($song, $artist, $album, $year, $comment, $track, $genre); Returns all information of the tag in a list. You can use this sub also to set the data of the complete tag. The order of the data is always song, artist, album, year, comment, track, and genre. genre has to be a string with the name of the genre, or a number identifying the genre. writeTag() $id3v1->writeTag; Writes the ID3v1 tag to the file. removeTag() $id3v1->removeTag; Removes the ID3v1 tag from the file. genres() @allgenres = $id3v1->genres; $genreName = $id3v1->genres($genreID); $genreID = $id3v1->genres($genreName); Returns a list of all genres, or the according name or id to a given id or name. SEE ALSO ======== *Note MP3/Tag: MP3/Tag,, *Note MP3/Tag/ID3v2: MP3/Tag/ID3v2, ID3v1 standard - http://www.id3.org  File: pm.info, Node: MP3/Tag/ID3v2, Next: MPEG/ID3v1Tag, Prev: MP3/Tag/ID3v1, Up: Module List Read / Write ID3v2.3 tags from mp3 audio files ********************************************** 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. It then returns a ID3v2-tag-object, which can be used in a users program. $id3v2 = MP3::Tag::ID3v2->new($mp3obj); `$mp3obj' is a object from MP3::Tag. See according documentation. $tag is undef when no tag is found in the `$mp3obj'. * Reading a tag $frameIDs_hash = $id3v2->getFrameIDS; foreach my $frame (keys %$frameIDs_hash) { 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"; } AUTHOR ====== Thomas Geffert, thg@users.sourceforge.net DESCRIPTION =========== new() $tag = new($mp3obj); new() needs as parameter a mp3obj, as created by `MP3::Tag' (see documentation of MP3::Tag). 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. getFrameIDs() $frameIDs = $tag->getFrameIDs; getFrameIDs 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 `getFrame' to get the information of these frames. getFrame() ($info, $name) = getFrame($ID); ($info, $name) = getFrame($ID, 'raw'); getFrame gets the contents of a specific frame, which must be specified by the 4-character-ID (aka short name). You can use `getFrameIDs' to get the IDs of the tag, or use IDs which you hope to find in the tag. If the ID is not found, getFrame 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 getFrame 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' in this node 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 a frame to the file. It tries to update the file in place, when the space of the old tag is big enoug for the new tag. Otherwise it creates a temp file (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 equal to the number of fields of the tag. Examples: $f = add_frame("TIT2", 0, "Abba"); # $f="TIT2" $f = add_frame("TIT2", "Abba"); # $f="TIT201", encoding=0 implicit add_frame("COMM", "ENG", "Short text", "This is a comment"); 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; remove_frame() $id3v2->remove_frame($fname); Remove an existing frame. $fname is the short name of a frame, eg as returned by `getFrameIDs'. 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 doesn't exist)) from the tag. album() Returns the album name (TALB) form the tag. SEE ALSO ======== *Note MP3/Tag: MP3/Tag,, *Note MP3/Tag/ID3v1: MP3/Tag/ID3v1,, `MP3::Tag::ID3v2-Data' in this node ID3v2 standard - http://www.id3.org  File: pm.info, Node: MPEG/ID3v1Tag, Next: MPEG/ID3v2Tag, Prev: MP3/Tag/ID3v2, Up: Module List Edit ID3v1 Tags from an Audio MPEG Layer 3. ******************************************* NAME ==== MPEG::ID3v1Tag - Edit ID3v1 Tags from an Audio MPEG Layer 3. SYNOPSIS ======== use MP3::ID3v1Tag; DESCRIPTION =========== This module is provided for backwards compatibility. Please migrate to use MP3::ID3v1Tag AUTHOR ====== Sander van Zoest THANKS ====== Matt Plummer , Mike Oliphant , Matt DiMeo , Olaf Maetzner, Jason Bodnar and Peter Johansson COPYRIGHT ========= Copyright 1999-2000, Sander van Zoest, MP3.com, Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. REFERENCES ========== For general overview of MPEG 1, Layer 3 (MP3) Audio visit http://www.mp3.com/ For more specific references to the MP3 Audio ID3 Tags visit http://www.id3.org/ For information about ID3v2 and a perl implementation see MPEG::ID3v2Tag written by Matt DiMeo .  File: pm.info, Node: MPEG/ID3v2Tag, Next: MPEG/MP3Info, Prev: MPEG/ID3v1Tag, Up: Module List Parses and creates ID3v2 Tags for MPEG audio files. *************************************************** NAME ==== *MPEG::ID3v2Tag* - Parses and creates ID3v2 Tags for MPEG audio files. 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("parse($fh) ; foreach $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->frame_id =~ /^T.../) { print " frame text is ", $frame->text(), "\n" ; } if ($frame->fully_parsed() && $frame->frame_id =~ /^W.../) { print " url is ", $frame->url(), "\n" ; } } DESCRIPTION =========== 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. 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:: 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(frame_id) 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. 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 ============= 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. $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. Support for specific frame types -------------------------------- 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(, ), but remember you can call MPEG::ID3Frame::TALB->new() and pass the return value to add_frame. TALB TBPM TCOM .... and so on T??? All these text information frames are supported: 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. WCOM WCOP .... and so on (W???) All url link frames are supported: WCOM WCOP WOAF WOAR WOAS WORS WPAY WPUB 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(). UFID Call the constructor like this: [$frame = ]$tag->add_frame(UFID, $owner_idstring, $id) ; There is currently no parsing support. USLT Call the constructor like this: $tag->add_frame(USLT, $encoding, $language, $content_descriptor, $lyrics) ; also supports parsing, and these access methods: encoding(), language(), content_descriptor(), and lyrics() ; APIC This is one of the more complicated frames. 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. USER The constructor for the Terms of Use frame is called as $tag->add_frame("USER", $encoding, $language, $text) ; There is no parsing support. COMM The constructor for the Comments frame is called as $tag->add_frame("COMM", $encoding, $language, $description, $text) ; There is no parsing support. SUPPORTING NEW FRAMES ===================== 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. BUGS ==== 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.