NAME

MP3::InfoTag - functions working on ID3 tags

SYNOPSIS

  use MP3::Info;
  use MP3::InfoTag ':typical';

  my $tag = get_mp3tag($file, 1) || createNewTag();
  print("file '$file': current ID3 tag: ".printTag($tag));

  # write tag fields based on a given string; for better understanding
  # a specific string is used here instead of a variable.  All of these
  # tag fields will be lower case because of the `case => 0' argument.
  my $changed = string2tag(
                  { name => '[02] Iron Maiden - Rainmaker',
                    pattern => '[((TRACKNUM))] ((ARTIST)) - ((TITLE))',
                    tag => $tag,
                    case => 0
                  } );

  # let's be control freaks and look for warnings
  if (my @warnings = MP3::InfoTag::flushWarnings()) {
    print("Warning for file '$file': ".join('; ', @warnings));
  }

  # write changes to file if necessary
  if (!defined $changed) {
    print("file '$file': string2tag failed: ".MP3::InfoTag::getError());
  } elsif ($changed > 0) {
    set_mp3tag($file, $tag);
  }

DESCRIPTION

This module contains functions for several tasks that occur while working with ID3 tags of MP3 files.

The functions of this module work with a hash representing the ID3 tag, they do not manipulate any files. This module has a tight relationship to the MP3::Info module which uses the same hash structure. You'll need to read tags from files and write them to files; for these tasks MP3::Info provides the necessary operations.

Thus you should regard this module as an extension that provides some functions which might be useful when working with ID3 tags.

EXPORT

By default this module does not export any functions into the caller's namespace. Anyway, you can export all functions on demand. For convenience, you may use the keyword ':typical' (see SYNOPSIS) to export he most important functions, i.e. all functions except of flushWarnings and getError.

LIMITATIONS

There are two major types of MPEG Layer 3 tag formats, ID3v1 and ID3v2. Whenever the `ID3 tag' is mentioned in this manual you can substitute this with ID3v1 or more specifically ID3v1.1 if the TRACKNUM field is used. ID3v2 tags are not supported.

FUNCTIONS

flushWarnings: Returns an array containing the warnings produced by functions of this module. These warnings do not indicate that something is wrong with the program but rather are informative messages that something happended that the user might not have expected. The internal list of warnings will be erased (`flushed') after calling this function.
getError: Returns the string description of the last error that occured. Errors are typically indicated by an `undef' return value of one of the functions in this module. The internal string variable will not be reset by calling this function.
getTagFields: Returns a reference to a hash containing all valid names for tag fields as keys and their maximum number of characters as values.
getTagFieldNames: Returns a reference to an array containing all valid names for tag fields.
createNewTag: Returns a reference to a hash representing an empty tag, i.e. all keys' values are still empty strings.
printTag(<hashRef> tag [,<boolean> showEmpty]): Creates a string representation for the given tag. Empty fields will be suppressed unless showEmpty is set to a true value.; Returns the string representation.
setTagField(<hashRef> tag, <string> field, <string> value): Sets the field of the given tag to value. Given values are thoroughly checked for validity and, if necessary, warning or error messages are produced.; Returns undef if an error occured, true otherwise.
string2tag(<hashRef> args): Sets the fields of an ID3 tag based upon the information contained in the given string, which will probably be a filename without extension.; Returns the number of changed tag fields or undef if an error occured.; These are the valid hash entries of args:
tag2string(<hashRef> args): Generates a string from the information of an ID3 tag. The format of the string is based upon a given pattern.; Returns undef if an error occured, true otherwise.; These are the valid hash entries of args:

AUTHOR

Joachim Jautz

http://www.jay-jay.net/contact.html