MP3-Tag
view release on metacpan or search on metacpan
lib/MP3/Tag.pm view on Meta::CPAN
package MP3::Tag;
# Copyright (c) 2000-2004 Thomas Geffert. All rights reserved.
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the Artistic License, distributed
# with Perl.
################
#
# provides a general interface for different modules, which can read tags
#
# at the moment MP3::Tag works with MP3::Tag::ID3v1 and MP3::Tag::ID3v2
use strict;
{
package MP3::Tag::__hasparent;
sub parent_ok {
my $self = shift;
$self->{parent} and $self->{parent}->proxy_ok;
}
sub get_config {
my $self = shift;
return $MP3::Tag::config{shift()} unless $self->parent_ok;
return $self->{parent}->get_config(@_);
}
*get_config1 = \&MP3::Tag::Implemenation::get_config1;
*get_config1 = 0 if 0; # quiet a warning
}
use MP3::Tag::ID3v1;
use MP3::Tag::ID3v2;
use MP3::Tag::File;
use MP3::Tag::Inf;
use MP3::Tag::CDDB_File;
use MP3::Tag::Cue;
use MP3::Tag::ParseData;
use MP3::Tag::ImageSize;
use MP3::Tag::ImageExifTool;
use MP3::Tag::LastResort;
use vars qw/$VERSION @ISA/;
$VERSION="1.16";
@ISA = qw( MP3::Tag::User MP3::Tag::Site MP3::Tag::Vendor
MP3::Tag::Implemenation ); # Make overridable
*config = \%MP3::Tag::Implemenation::config;
package MP3::Tag::Implemenation; # XXXX Old mispring...
use vars qw/%config/;
%config = ( autoinfo => [qw( ParseData ID3v2 ID3v1 ImageExifTool
CDDB_File Inf Cue ImageSize
filename LastResort )],
cddb_files => [qw(audio.cddb cddb.out cddb.in)],
v2title => [qw(TIT1 TIT2 TIT3)],
composer => ['TCOM|a'],
performer => ['TXXX[TPE1]|TPE1|a'],
extension => ['\.(?!\d+\b)\w{1,4}$'],
parse_data => [],
parse_split => ["\n"],
encoded_v1_fits => [0],
parse_filename_ignore_case => [1],
parse_filename_merge_dots => [1],
parse_join => ['; '],
year_is_timestamp => [1],
comment_remove_date => [0],
id3v2_frame_empty_ok => [0],
id3v2_minpadding => [128],
id3v2_sizemult => [512],
id3v2_shrink => [0],
id3v2_mergepadding => [0],
id3v23_unsync_size_w => [0],
id3v23_unsync => [1],
parse_minmatch => [0],
update_length => [1],
default_language => ['XXX'],
default_descr_c => [''],
person_frames => [qw{ TEXT TCOM TXXX[TPE1] TPE1
TPE3 TOPE TOLY TMCL TIPL TENC
TXXX[person-file-by] }],
id3v2_frames_autofill => [qw{ TXXX[MCDI-fulltoc] 1 TXXX[cddb_id] 0
TXXX[cdindex_id] 0 }],
id3v2_set_trusted_encoding0 => [1],
id3v2_fix_encoding_on_edit => [1],
name_for_field_normalization => ['%{composer}'],
local_cfg_file => ['~/.mp3tagprc'],
extra_config_keys => [],
is_writable => ['writable_by_extension'],
# ExifTool says: ID3 may be in MP3/MPEG/AIFF/OGG/FLAC/APE/RealAudio (MPC).
writable_extensions => [qw(mp3 mp2 id3 tag ogg mpg mpeg
mp4 aiff flac ape ram mpc)],
ampersand_joiner => ['; '],
);
sub reset_encode_decode_config ($;$) {
my(undef, $force_enc) = (shift,shift);
my($i_enc, $o_enc) = ($force_enc, $force_enc);
my %e;
$e{FILES} = $i_enc if ($force_enc or (($ENV{LANG}||'') =~ /\.([-\w]+)$/i and $i_enc = $1, 1))
and not (${^UNICODE} & 0x8) and not $ENV{"MP3TAG_DECODE_FILES_DEFAULT_RESET"};
$e{eF} = $o_enc if ($force_enc or (($ENV{LANG}||'') =~ /\.([-\w]+)$/i and $o_enc = $1, 1))
and not (${^UNICODE} & 0x16) and not $ENV{"MP3TAG_ENCODE_FILES_DEFAULT_RESET"};
for my $t (qw(V1 V2 FILENAME FILES INF CDDB_FILE CUE)) {
$e{$t} = $ENV{"MP3TAG_DECODE_${t}_DEFAULT"} unless $t eq 'FILES' and not defined $ENV{"MP3TAG_DECODE_${t}_DEFAULT"};
$e{$t} = $ENV{MP3TAG_DECODE_DEFAULT} unless defined $e{$t};
$config{"decode_encoding_" . lc $t} = [$e{$t}] if $e{$t};
}
$e{eV1} = $ENV{MP3TAG_ENCODE_V1_DEFAULT};
$e{eV1} = $ENV{MP3TAG_ENCODE_DEFAULT} unless defined $e{eV1};
$e{eV1} = $e{V1} unless defined $e{eV1};
$config{encode_encoding_v1} = [$e{eV1}] if $e{eV1};
$e{eF} = $ENV{MP3TAG_ENCODE_FILES_DEFAULT} if defined $ENV{MP3TAG_ENCODE_FILES_DEFAULT};
$e{eF} = $ENV{MP3TAG_ENCODE_DEFAULT} unless defined $e{eF};
$e{eF} = $e{FILES} if not defined $e{eF} and
(defined $ENV{"MP3TAG_DECODE_FILES_DEFAULT"} or defined $ENV{MP3TAG_DECODE_DEFAULT});
$config{encode_encoding_files} = [$e{eF}] if $e{eF};
}
MP3::Tag->reset_encode_decode_config();
=pod
=head1 NAME
MP3::Tag - Module for reading tags of MP3 audio files
=head1 SYNOPSIS
use MP3::Tag;
$mp3 = MP3::Tag->new($filename);
# get some information about the file in the easiest way
($title, $track, $artist, $album, $comment, $year, $genre) = $mp3->autoinfo();
# Or:
$comment = $mp3->comment();
$dedicated_to
= $mp3->select_id3v2_frame_by_descr('COMM(fre,fra,eng,#0)[dedicated to]');
$mp3->title_set('New title'); # Edit in-memory copy
$mp3->select_id3v2_frame_by_descr('TALB', 'New album name'); # Edit in memory
$mp3->select_id3v2_frame_by_descr('RBUF', $n1, $n2, $n3); # Edit in memory
$mp3->update_tags({year => 1866}); # Edit in-memory, and commit to file
$mp3->update_tags(); # Commit to file
The following low-level access code is discouraged; better use title()
etc., title_set() etc., update_tags(), select_id3v2_frame_by_descr()
etc. methods on the wrapper $mp3:
# scan file for existing tags
$mp3->get_tags;
if (exists $mp3->{ID3v1}) {
# read some information from the tag
$id3v1 = $mp3->{ID3v1}; # $id3v1 is only a shortcut for $mp3->{ID3v1}
print $id3v1->title;
# change the tag contents
$id3v1->all("Song","Artist","Album",2001,"Comment",10,"Top 40");
$id3v1->write_tag;
}
if (exists $mp3->{ID3v2}) {
# read some information from the tag
($name, $info) = $mp3->{ID3v2}->get_frame("TIT2");
# delete the tag completely from the file
$mp3->{ID3v2}->remove_tag;
} else {
# create a new tag
$mp3->new_tag("ID3v2");
$mp3->{ID3v2}->add_frame("TALB", "Album title");
$mp3->{ID3v2}->write_tag;
}
$mp3->close();
Please consider using the script F<mp3info2>; it allows simple access
to most features of this module via command-line options; see
L<mp3info2>.
=head1 AUTHORS
Thomas Geffert, thg@users.sourceforge.net
Ilya Zakharevich, ilyaz@cpan.org
=head1 DESCRIPTION
C<MP3::Tag> is a wrapper module to read different tags of mp3 files.
It provides an easy way to access the functions of separate modules which
do the handling of reading/writing the tags itself.
At the moment MP3::Tag::ID3v1 and MP3::Tag::ID3v2 are supported for
read and write; MP3::Tag::ImageExifTool, MP3::Tag::Inf, MP3::Tag::CDDB_File,
MP3::Tag::File, MP3::Tag::Cue, MP3::Tag::ImageSize, MP3::Tag::LastResort
are supported for read access (the information obtained by
L<Image::ExifTool|Image::ExifTool> (if present), parsing CDDB files,
F<.inf> file, the filename, and F<.cue> file, and obtained via
L<Image::Size|Image::Size>) (if present).
=over 4
=item new()
$mp3 = MP3::Tag->new($filename);
Creates a mp3-object, which can be used to retrieve/set
different tags.
=cut
sub rel2abs ($) {
shift;
if (eval {require File::Spec; File::Spec->can('rel2abs')}) {
File::Spec->rel2abs(shift);
} else {
# require Cwd;
# Cwd::abs_path(shift);
shift;
}
}
sub new {
my $class = shift;
my $filename = shift;
my $mp3data;
my $self = {};
bless $self, $class;
my $proxy = MP3::Tag::__proxy->new($self);
if (-f $filename or -c $filename) {
$mp3data = MP3::Tag::File->new_with_parent($filename, $proxy);
}
# later it should hopefully possible to support also http/ftp sources
# with a MP3::Tag::Net module or something like that
if ($mp3data) {
%$self = (filename => $mp3data,
ofilename => $filename,
abs_filename => $class->rel2abs($filename),
__proxy => $proxy);
return $self;
}
return undef;
}
{ # Proxy class: to have only one place where to weaken/localize the reference
# $obj->[0] must be settable to the handle (not needed if weakening succeeds)
package MP3::Tag::__proxy;
use vars qw/$AUTOLOAD/;
my $skip_weaken = $ENV{MP3TAG_SKIP_WEAKEN};
sub new {
my ($class, $handle) = (shift,shift);
my $self = bless [$handle], $class;
#warn("weaken() failed, falling back"),
return bless [], $class if $skip_weaken or not
eval {require Scalar::Util; Scalar::Util::weaken($self->[0]); 1};
$self;
}
sub DESTROY {}
sub proxy_ok { shift->[0] }
sub AUTOLOAD {
my $self = shift;
die "local_proxy not initialized" unless $self->[0];
(my $meth = $AUTOLOAD) =~ s/.*:://;
my $smeth = $self->[0]->can($meth);
die "proxy can't find the method $meth" unless $smeth;
unshift @_, $self->[0];
goto &$smeth;
}
}
sub proxy_ok { 1 } # We can always be a proxy to ourselves... ;-)
=pod
=item get_tags()
[old name: getTags() . The old name is still available, but its use is not advised]
@tags = $mp3->get_tags;
Checks which tags can be found in the mp3-object. It returns
a list @tags which contains strings identifying the found tags, like
"ID3v1", "ID3v2", "Inf", or "CDDB_File" (the last but one if the F<.inf>
information file with the same basename as MP3 file is found).
Each found tag can then be accessed with $mp3->{tagname} , where tagname is
a string returned by get_tags ;
Use the information found in L<MP3::Tag::ID3v1>, L<MP3::Tag::ID3v2> and
L<MP3::Tag::Inf>, L<MP3::Tag::CDDB_File>, L<MP3::Tag::Cue> to see what you can do with the tags.
=cut
################ tag subs
sub get_tags {
my $self = shift;
return @{$self->{gottags}} if exists $self->{gottags};
my (@IDs, $id);
# Will not create a reference loop
local $self->{__proxy}[0] = $self unless $self->{__proxy}[0] or $ENV{MP3TAG_TEST_WEAKEN};
for $id (qw(ParseData ID3v2 ID3v1 ImageExifTool Inf CDDB_File Cue ImageSize LastResort)) {
my $ref = "MP3::Tag::$id"->new_with_parent($self->{filename}, $self->{__proxy});
next unless defined $ref;
$self->{$id} = $ref;
push @IDs, $id;
}
$self->{gottags} = [@IDs];
return @IDs;
}
sub _get_tag {
my $self = shift;
$self->{shift()};
}
# keep old name for a while
*getTags = \&get_tags;
*getTags = 0 if 0; # quiet a warning
=item new_fake
$obj = MP3::Tag->new_fake();
This method produces a "fake" MP3::Tag object which behaves as an MP3
file without tags. Give a TRUE optional argument if you want to set
some properties of this object.
=cut
sub new_fake {
my ($class, $settable) = (shift, shift);
my %h = (gottags => []);
my $self = bless \%h, $class;
if ($settable) {
$h{__proxy} = MP3::Tag::__proxy->new($self);
$h{ParseData} = MP3::Tag::ParseData->new_with_parent(undef, $h{__proxy});
}
\%h;
}
=pod
=item new_tag()
[old name: newTag() . The old name is still available, but its use is not advised]
$tag = $mp3->new_tag($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}.
=cut
sub new_tag {
my $self = shift;
my $whichTag = shift;
if ($whichTag =~ /1/) {
$self->{ID3v1}= MP3::Tag::ID3v1->new($self->{filename},1);
return $self->{ID3v1};
} elsif ($whichTag =~ /2/) {
$self->{ID3v2}= MP3::Tag::ID3v2->new($self->{filename},1);
return $self->{ID3v2};
}
}
# keep old name for a while
*newTag = \&new_tag;
*newTag = 0 if 0; # quiet a warning
#only as a shortcut to {filename}->close to explicitly close a file
=pod
=item close()
$mp3->close;
You can use close() to explicitly close a file. Normally this is done
automatically by the module, so that you do not need to do this.
=cut
sub close {
my $self=shift;
$self->{filename}->close;
}
=pod
=item 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);
}
=pod
=item autoinfo()
($title, $track, $artist, $album, $comment, $year, $genre) = $mp3->autoinfo();
$info_hashref = $mp3->autoinfo();
autoinfo() returns information about the title, track number,
artist, album name, the file comment, the year and genre. It can get this
information from an ID3v1-tag, an ID3v2-tag, from CDDB file, from F<.inf>-file,
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, then
to read an CDDB file, an F<.inf>-file, and
if these are not present either, it will use the filename to retrieve
the title, track number, artist, album name. The comment, year and genre
are found differently, via the C<comment>, C<year> and C<genre> methods.
You can change the order of lookup with the config() command.
autoinfo() returns an array with the information or a hashref. The hash
has four keys 'title', 'track', 'artist' and 'album' where the information is
stored. If comment, year or genre are found, the hash will have keys
'comment' and/or 'year' and/or 'genre' too.
If an optional argument C<'from'> is given, the returned values (title,
track number, artist, album name, the file comment, the year and genre) are
array references with the first element being the value, the second the
tag (C<ID3v2> or C<ID3v1> or C<Inf> or C<CDDB_File> or C<Cue> or C<filename>) from which
it is taken.
(Deprecated name 'song' can be used instead of 'title' as well.)
=cut
sub autoinfo() {
my ($self, $from) = (shift, shift);
my (@out, %out);
for my $elt ( qw( title track artist album comment year genre ) ) {
my $out = $self->$elt($from);
if (wantarray) {
push @out, $out;
} elsif (defined $out and length $out) {
$out{$elt} = $out;
}
}
$out{song} = $out{title} if exists $out{title};
return wantarray ? @out : \%out;
}
=item comment()
$comment = $mp3->comment(); # empty string unless found
comment() returns comment information. It can get this information from an
lib/MP3/Tag.pm view on Meta::CPAN
my $r = track(@_);
return '' unless $r =~ s(^.*?/)()s;
$r;
}
sub track0 ($) {
my $self = shift;
my $d = (@_ ? shift() : 2);
my $r = $self->track();
return '' unless defined $r;
(my $r1 = $r) =~ s(/.*)()s;
$r = 'a' x $d unless $r =~ s(^.*?/)()s;
my $l = length $r;
sprintf "%0${l}d", $r1;
}
sub disk1 ($) {
my $self = shift;
my $r = $self->select_id3v2_frame('TPOS');
return '' unless defined $r;
$r =~ s(/.*)()s;
$r;
}
sub disk2 ($) {
my $self = shift;
my $r = $self->select_id3v2_frame('TPOS');
return '' unless defined $r;
return '' unless $r =~ s(^.*?/)()s;
$r;
}
sub disk_alphanum ($) {
my $self = shift;
my $r = $self->select_id3v2_frame('TPOS');
return '' unless defined $r;
(my $r1 = $r) =~ s(/.*)()s;
$r = $r1 unless $r =~ s(^.*?/)()s; # max(disk2, disk1)
return chr(ord('a') - 1 + $r1) if $r <= 26;
my $l = length $r;
sprintf "%0${l}d", $r1;
}
my %ignore_0length = qw(ID3v1 1 CDDB_File 1 Inf 1 Cue 1 ImageSize 1 ImageExifTool 1);
sub _auto_field_from($$$;$$$$) {
my ($self, $check_only, $packs, $rwhat, $ret_from, $args, $all) = (shift, shift, shift, shift, shift, shift || [], shift);
my @what = ref $rwhat ? @$rwhat : $rwhat;
my @out;
local $self->{__proxy}[0] = $self unless $self->{__proxy}[0] or $ENV{MP3TAG_TEST_WEAKEN};
$self->get_tags;
# ID3v1 has AUTOLOAD
# my $do_can = ($what =~ /^(cd\w+_id|height|width|bit_depth|mime_type|img_type|_duration)$/);
foreach my $pack (@$packs) {
next unless exists $self->{$pack};
my $do_can = $pack ne 'ID3v1';
my $out;
for my $what (@what) {
next if $pack eq 'ID3v1' and not $MP3::Tag::ID3v1::ok_length{$what}; # dup of a warning in AUTOLOAD
next if $do_can and not $self->{$pack}->can($what);
if ($check_only and $self->{$pack}->can(my $m = $what . '_have')) {
next unless $self->{$pack}->$m(@$args);
return $ret_from ? [1, $pack] : 1;
}
next unless defined ($out = $self->{$pack}->$what(@$args));
# Ignore 0-length answers from ID3v1, ImageExifTool, CDDB_File, Cue, ImageSize, and Inf
undef $out, next if not length $out and $ignore_0length{$pack}; # These return ''
}
next unless defined $out;
$out = 1 if $check_only;
if ($all) { # Currently, @out is not used by our callers
push @out, ($ret_from ? [$out, $pack] : $out);
next;
}
return [$out, $pack] if $ret_from;
return $out;
}
return @out if $all;
return;
}
sub auto_field($;$$) {
my ($self, $what, $ret_from) = (shift, shift, shift);
my $packs = $self->get_config($what) || $self->get_config('autoinfo');
my $o = $self->_auto_field_from(!'check_only', $packs, $what, $ret_from);
return '' unless defined $o;
$o;
}
for my $elt ( qw( title track artist album comment year genre ) ) {
no strict 'refs';
*$elt = sub (;$) {
my $self = shift;
my $translate = ($self->get_config("translate_$elt") || [])->[0] || sub {$_[1]};
return &$translate($self, $self->auto_field($elt, @_));
}
}
my %hide_meth = qw(mime_type _mime_type);
for my $elt ( qw( cddb_id cdindex_id height width bit_depth mime_type img_type _duration ) ) {
no strict 'refs';
*{$hide_meth{$elt} || $elt} = sub (;$) {
my $self = shift;
return $self->auto_field($elt, @_);
}
}
for my $elt ( qw( comment_collection comment_track title_track artist_collection ) ) {
no strict 'refs';
my ($tr) = ($elt =~ /^(\w+)_/);
*$elt = sub (;$) {
my $self = shift;
local $self->{__proxy}[0] = $self unless $self->{__proxy}[0] or $ENV{MP3TAG_TEST_WEAKEN};
$self->get_tags;
return unless exists $self->{CDDB_File};
my $v = $self->{CDDB_File}->parse($elt);
return unless defined $v;
my $translate = ($self->get_config("translate_$tr") || [])->[0] || sub {$_[1]};
lib/MP3/Tag.pm view on Meta::CPAN
return((!$lazy && $self->_mime_type()) || 'application/octet-stream');
}
=item genre()
$genre = $mp3->genre(); # empty string unless found
genre() returns the genre string. It can get this information from an
ID3v2-tag or ID3v1-tag.
It will as default first try to find a ID3v2-tag to get this
information. If no genre is found there, it tries to find it in a ID3v1-tag,
if none present, will try F<.inf>-file,
It returns an empty string if no genre is found.
You can change the order of this with the config() command.
If an optional argument C<'from'> is given, returns an array reference with
the first element being the value, the second the tag (ID3v2 or ID3v1 or
filename) from which the value is taken.
=item composer()
$composer = $mp3->composer(); # empty string unless found
composer() returns the composer. By default, it gets from ID3v2 tag,
otherwise returns artist.
You can change the inspected fields with the config() command.
Subject to normalization via C<translate_composer> or
C<translate_person> configuration variables.
=item performer()
$performer = $mp3->performer(); # empty string unless found
performer() returns the main performer. By default, it gets from ID3v2
tag C<TXXX[TPE1]>, otherwise from ID3v2 tag C<TPE1>, otherwise
returns artist.
You can change the inspected fields with the config() command.
Subject to normalization via C<translate_performer> or
C<translate_person> configuration variables.
=cut
for my $elt ( qw( composer performer ) ) {
no strict 'refs';
*$elt = sub (;$) {
my $self = shift;
my $translate = ($self->get_config("translate_$elt")
|| $self->get_config("translate_person")
|| [])->[0] || sub {$_[1]};
my $fields = ($self->get_config($elt))->[0];
return &$translate($self, $self->interpolate("%{$fields}"));
}
}
=item config
MP3::Tag->config(item => value1, value2...); # Set options globally
$mp3->config(item => value1, value2...); # Set object options
When object options are first time set or get, the global options are
propagated into object options. (So if global options are changed later, these
changes are not inherited.)
Possible items are:
=over
=item autoinfo
Configure the order in which ID3v1-, ID3v2-tag and filename are used
by autoinfo. The default is C<ParseData, ID3v2, ID3v1, ImageExifTool,
CDDB_File, Inf, Cue, ImageSize, filename, LastResort>.
Options can be elements of the default list. 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 autoinfo (and other auto-methods if the specific overriding config
command were not issued).
$mp3->config("autoinfo","ID3v1","ID3v2","filename");
sets the order to check first ID3v1, then ID3v2 and at 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 here
never be checked.
$mp3->config("autoinfo","ID3v1","ID3v2");
sets the order to check first ID3v1, then ID3v2. The filename will
never be used.
=item title artist album year comment track genre
Configure the order in which ID3v1- and ID3v2-tag are used
by the corresponding methods (e.g., comment()). Options can be
the same as for C<autoinfo>. The order
in which they are given to config also sets the order how they are
used by comment(). If an option is not present, then C<autoinfo> option
will be used instead.
=item extension
regular expression to match the file extension (including the dot). The
default is to match 1..4 letter extensions which are not numbers.
=item composer
string to put into C<%{}> to interpolate to get the composer. Default
is C<'TCOM|a'>.
=item performer
string to put into C<%{}> to interpolate to get the main performer.
Default is C<'TXXX[TPE1]|TPE1|a'>.
=item parse_data
the data used by L<MP3::Tag::ParseData> handler; each option is an array
reference of the form C<[$flag, $string, $pattern1, ...]>. All the options
are processed in the following way: patterns are matched against $string
until one of them succeeds; the information obtained from later options takes
precedence over the information obtained from earlier ones.
=item parse_split
The regular expression to split the data when parsing with C<n> or C<l> flags.
=item parse_filename_ignore_case
If true (default), calling parse() and parse_rex() with match-filename
escapes (such as C<%=D>) matches case-insensitively.
=item parse_filename_merge_dots
If true (default), calling parse() and parse_rex() with match-filename
escapes (such as C<%=D>) does not distinguish a dot and many consequent
dots.
=item parse_join
string to put between multiple occurences of a tag in a parse pattern;
defaults to C<'; '>. E.g., parsing C<'1988-1992, Homer (LP)'> with pattern
C<'%c, %a (%c)'> results in comment set to C<'1988-1992; LP'> with the
default value of C<parse_join>.
=item v2title
Configure the elements of ID3v2-tag which are used by ID3v2::title().
Options can be "TIT1", "TIT2", "TIT3"; the present values are combined.
If an option is not present, it will not be used by ID3v2::title().
=item cddb_files
List of files to look for in the directory of MP3 file to get CDDB info.
=item year_is_timestamp
If TRUE (default) parse() will match complicated timestamps against C<%y>;
for example, C<2001-10-23--30,2002-02-28> is a range from 23rd to 30th of
October 2001, I<and> 28th of February of 2002. According to ISO, C<--> can
be replaced by C</> as well. For convenience, the leading 0 can be omited
from the fields which ISO requires to be 2-digit.
=item comment_remove_date
When extracting the date from comment fields, remove the recognized portion
even if it is human readable (e.g., C<Recorded on 2014-3-23>) if TRUE.
Current default: FALSE.
=item default_language
The language to use to select ID3v2 frames, and to choose C<COMM>
ID3v2 frame accessed in comment() method (default is 'XXX'; if not
C<XXX>, this should be lowercase 3-letter abbreviation according to
ISO-639-2).
=item default_descr_c
The description field used to choose the C<COMM> ID3v2 frame accessed
in comment() method. Defaults to C<''>.
=item id3v2_frame_empty_ok
When setting the individual id3v2 frames via ParseData, do not
remove the frames set to an empty string. Default 0 (empty means 'remove').
=item id3v2_minpadding
Minimal padding to reserve after ID3v2 tag when writing (default 128),
=item id3v2_sizemult
Additionally to C<id3v2_minpadding>, insert padding to make file size multiple
of this when writing ID3v2 tag (default 512), Should be power of 2.
=item id3v2_shrink
If TRUE, when writing ID3v2 tag, shrink the file if needed (default FALSE).
=item id3v2_mergepadding
If TRUE, when writing ID3v2 tag, consider the 0-bytes following the
ID3v2 header as writable space for the tag (default FALSE).
=item update_length
If TRUE, when writing ID3v2 tag, create a C<TLEN> tag if the duration
is known (as it is after calling methods like C<total_secs>, or
interpolation the duration value). If this field is 2 or more, force
creation of ID3v2 tag by update_tags() if the duration is known.
=item translate_*
FALSE, or a subroutine used to munch a field C<*> (out of C<title
track artist album comment year genre comment_collection comment_track
title_track artist_collection person>) to some "normalized" form.
Takes two arguments: the MP3::Tag object, and the current value of the
field.
The second argument may also have the form C<[value, handler]>, where
C<handler> is the string indentifying the handler which returned the
value.
=item short_person
Similar to C<translate_person>, but the intent is for this subroutine
to translate a personal name field to a shortest "normalized" form.
=item person_frames
list of ID3v2 frames subject to normalization via C<translate_person>
handler; current default is C<TEXT TCOM TXXX[TPE1] TPE1 TPE3 TOPE TOLY
TMCL TIPL TENC TXXX[person-file-by]>.
Used by select_id3v2_frame_by_descr(), frame_translate(),
frames_translate().
=item id3v2_missing_fatal
If TRUE, interpolating ID3v2 frames (e.g., by C<%{TCOM}>) when
the ID3v2 tags is missing is a fatal error. If false (default), in such cases
interpolation results in an empty string.
=item id3v2_recalculate
If TRUE, interpolating the whole ID3v2 tag (by C<%{ID3v2}>) will recalculate
the tag even if its contents is not modified.
=item parse_minmatch
may be 0, 1, or a list of C<%>-escapes (matching any string) which should
matched non-greedily by parse() and friends. E.g., parsing
C<'Adagio - Andante - Piano Sonata'> via C<'%t - %l'> gives different results
for the settings 0 and 1; note that greediness of C<%l> does not matter,
thus the value of 1 is equivalent for the value of C<t> for this particular
pattern.
=item id3v23_unsync_size_w
Old experimental flag to test why ITunes refuses to handle unsyncronized tags
(does not help, see L<id3v23_unsync>). The idea was that
version 2.3 of the standard is not clear about frame size field, whether it
is the size of the frame after unsyncronization, or not. We assume
that this size is one before unsyncronization (as in v2.2).
Setting this value to 1 will assume another interpretation (as in v2.4) for
write.
=item id3v23_unsync
Some broken MP3 players (e.g., ITunes, at least up to v6) refuse to
handle unsyncronized (i.e., written as the standard requires it) tags;
they may need this to be set to FALSE. Default: TRUE.
(Some details: by definition, MP3 files should contain combinations of bytes
C<FF F*> or C<FF E*> only at the start of audio frames ("syncronization" points).
ID3v2 standards take this into account, and supports storing raw tag data
in a format which does not contain these combinations of bytes
[via "unsyncronization"]. Itunes etc do not only emit broken MP3 files
lib/MP3/Tag.pm view on Meta::CPAN
can be idempotent.]
=item id3v2_fix_encoding_on_write
If TRUE and C<decode_encoding_v2> is defined, the ID3v2 frames are converted
to standard-conforming encodings on write. The default is FALSE.
=item id3v2_fix_encoding_on_edit
If TRUE (default) and C<decode_encoding_v2> is defined (and not disabled
via a frame C<TXXX[trusted_encoding0_v2]> and the setting
C<ignore_trusted_encoding0_v2>), a CYA action is performed when an
edit may result in a confusion. More precise, adding an ID3v2 frame which
is I<essentially> affected by C<decode_encoding_v2> would convert other
frames to a standard-conforming encoding (and would set
C<TXXX[trusted_encoding0_v2]> if required by C<id3v2_set_trusted_encoding0>).
Recall that the added frames are always encoded in standard-conformant way;
the action above avoids mixing non-standard-conformant frames with
standard-conformant frames. Such a mix could not be cleared up by setting
C<decode_encoding_v2>! One should also keep in mind that this does not affect
frames which contain characters above C<0x255>; such frames are always written
in Unicode, thus are not affected by C<decode_encoding_v2>.
=item id3v2_frames_autofill
Hash of suggested ID3v2 frames to autogenerate basing on extra information
available; keys are frame descriptors (such as C<TXXX[cddb_id]>), values
indicate whether ID3v2 tag should be created if it was not present.
This variable is inspected by the method C<id3v2_frames_autofill>,
which is not called automatically when the tag is accessed, but may be called
by scripts using the module.
The default is to force creation of tag for C<TXXX[MCDI-fulltoc]> frame, and do not
force creation for C<TXXX[cddb_id]> and C<TXXX[cdindex_id]>.
=item local_cfg_file
Name of configuration file read at startup by the method parse_cfg(); is
C<~>-substituted; defaults to F<~/.mp3tagprc>.
=item prohibit_v24
If FALSE (default), reading of ID3v2.4 is allowed (it is not fully supported,
but most things work acceptably).
=item write_v24
If FALSE (default), writing of ID3v2.4 is prohibited (it is not fully
supported; allow on your own risk).
=item name_for_field_normalization
interpolation of this string is used as a person name to normalize
title-like fields. Defaults to C<%{composer}>.
=item extra_config_keys
List of extra config keys (default is empty); setting these would not cause
warnings, and would not affect operation of C<MP3::Tag>. Applications using
this module may add to this list to allow their configuration by the same
means as configuration of C<MP3::Tag>.
=item is_writable
Contains a boolean value, or a method name and argument list
to call whether the tag may be added to the file. Defaults to
writable_by_extension().
=item writable_extensions
Contains a list of extensions (case insensitive) for which the tag may be
added to the file. Current default is C<mp3 mp2 id3 tag ogg mpg mpeg
mp4 aiff flac ape ram mpc> (extracted from L<ExifTool> docs; may be tuned
later).
=item *
Later there will be probably more things to configure.
=back
=cut
my $conf_rex;
sub config {
my ($self, $item, @options) = @_;
$item = lc $item;
my $config = ref $self ? ($self->{config} ||= {%config}) : \%config;
my @known = qw(autoinfo title artist album year comment track genre
v2title cddb_files force_interpolate parse_data parse_split
composer performer default_language default_descr_c
update_length id3v2_fix_encoding_on_write
id3v2_fix_encoding_on_edit extra_config_keys
parse_join parse_filename_ignore_case encoded_v1_fits
parse_filename_merge_dots year_is_timestamp
comment_remove_date extension id3v2_missing_fatal
id3v2_frame_empty_ok id3v2_minpadding id3v2_sizemult
id3v2_shrink id3v2_mergepadding person_frames short_person
parse_minmatch id3v23_unsync id3v23_unsync_size_w
id3v2_recalculate ignore_trusted_encoding0_v2
id3v2_set_trusted_encoding0 write_v24 prohibit_v24
encode_encoding_files encode_encoding_v1 encode_encoding_cue
decode_encoding_v1 decode_encoding_v2
decode_encoding_filename decode_encoding_files
decode_encoding_inf decode_encoding_cddb_file
name_for_field_normalization is_writable writable_extensions
id3v2_frames_autofill local_cfg_file ampersand_joiner);
my @tr = map "translate_$_", qw( title track artist album comment
year genre comment_collection
comment_track title_track
composer performer
artist_collection person );
my $e_known = $self->get_config('extra_config_keys');
$e_known = [map lc, @$e_known];
$conf_rex = '^(' . join('|', @known, @$e_known, @tr) . ')$' unless $conf_rex;
if ($item =~ /^(force)$/) {
return $config->{$item} = {@options};
} elsif ($item !~ $conf_rex) {
warn "MP3::Tag::config(): Unknown option '$item' found; known options: @known @$e_known @tr\n REX = <<<$conf_rex>>>\n";
return;
}
undef $conf_rex if $item eq 'extra_config_keys';
$config->{$item} = \@options;
}
=item get_config
$opt_array = $mp3->get_config("item");
When object options are first time set or get, the global options are
propagated into object options. (So if global options are changed later, these
changes are not inherited.)
=item get_config1
$opt = $mp3->get_config1("item");
Similar to get_config(), but returns UNDEF if no config array is present, or
the first entry of array otherwise.
=cut
sub get_config ($$) {
my ($self, $item) = @_;
my $config = ref $self ? ($self->{config} ||= {%config}) : \%config;
$config->{lc $item};
}
sub get_config1 {
my $self = shift;
my $c = $self->get_config(@_);
$c and $c->[0];
}
=item name_for_field_normalization
$name = $mp3->name_for_field_normalization;
Returns "person name" to use for normalization of title-like fields;
it is the result of interpolation of the configuration variable
C<name_for_field_normalization> (defaults to C<%{composer}> - which, by
default, expands the same as C<%{TCOM|a}>).
=cut
sub name_for_field_normalization ($) {
my $self = shift;
$self->interpolate( $self->get_config1("name_for_field_normalization") );
}
=item pure_filetags
$data = $mp3->pure_filetags()->autoinfo;
Configures $mp3 to not read anything except the pure ID3v2 or ID3v1 tags, and
do not postprocess them. Returns the object reference itself to simplify
chaining of method calls.
=cut
sub pure_filetags ($) {
my $self = shift;
for my $c (qw(autoinfo title artist album year comment track genre)) {
$self->config($c,"ID3v2","ID3v1");
}
$self->config('comment_remove_date', 0);
for my $k (%{$self->{config}}) {
delete $self->{config}->{$k} if $k =~ /^translate_/;
}
return $self;
}
=item get_user
$data = $mp3->get_user($n); # n-th piece of user scratch space
Queries an entry in a scratch array ($n=3 corresponds to C<%{U3}>).
=item set_user
$mp3->set_user($n, $data); # n-th piece of user scratch space
Sets an entry in a scratch array ($n=3 corresponds to C<%{U3}>).
=cut
sub get_user ($$) {
my ($self, $item) = @_;
unless ($self->{userdata}) {
local $self->{__proxy}[0] = $self unless $self->{__proxy}[0] or $ENV{MP3TAG_TEST_WEAKEN};
$self->{ParseData}->parse('track'); # Populate the hash if possible
$self->{userdata} ||= [];
}
return unless defined (my $d = $self->{userdata}[$item]);
$d;
}
sub set_user ($$$) {
my ($self, $item, $val) = @_;
$self->{userdata} ||= [];
$self->{userdata}[$item] = $val;
}
=item set_id3v2_frame
$mp3->set_id3v2_frame($name, @values);
When called with only $name as the argument, removes the specified
frame (if it existed). Otherwise sets the frame passing the specified
@values to the add_frame() function of MP3::Tag::ID3v2. (The old value is
removed.)
=cut
# With two elements, removes frame
sub set_id3v2_frame ($$;@) {
my ($self, $item) = (shift, shift);
$self->get_tags;
return if not @_ and not exists $self->{ID3v2};
$self->new_tag("ID3v2") unless exists $self->{ID3v2};
$self->{ID3v2}->remove_frame($item)
if defined $self->{ID3v2}->get_frame($item);
return unless @_;
return $self->{ID3v2}->add_frame($item, @_);
}
=item get_id3v2_frames
($descr, @frames) = $mp3->get_id3v2_frames($fname);
Returns the specified frame(s); has the same API as
L<MP3::Tag::ID3v2::get_frames>, but also returns undef if no ID3v2
tag is present.
=cut
sub get_id3v2_frames ($$;$) {
my ($self) = (shift);
$self->get_tags;
return if not exists $self->{ID3v2};
$self->{ID3v2}->get_frames(@_);
}
=item delete_tag
$deleted = $mp3->delete_tag($tag);
$tag should be either C<ID3v1> or C<ID3v2>. Deletes the tag if it is present.
Returns FALSE if the tag is not present.
=cut
sub delete_tag ($$) {
my ($self, $tag) = (shift, shift);
$self->get_tags;
die "Unexpected tag type '$tag'" unless $tag =~ /^ID3v[12]$/;
return unless exists $self->{$tag};
my $res = $self->{$tag}->remove_tag();
$res = ($res >= 0) if $tag eq 'ID3v1'; # -1 on error
$res or die "Error deleting tag `$tag'";
}
=item is_id3v2_modified
$frame = $mp3->is_id3v2_modified();
Returns TRUE if ID3v2 tag exists and was modified after creation.
=cut
sub is_id3v2_modified ($$;@) {
my ($self) = (shift);
return if not exists $self->{ID3v2};
$self->{ID3v2}->is_modified();
}
=item select_id3v2_frame
$frame = $mp3->select_id3v2_frame($fname, $descrs, $langs [, $VALUE]);
Returns the specified frame(s); has the same API as
L<MP3::Tag::ID3v2/frame_select> (args are the frame name, the list of
wanted Descriptors, list of wanted Languages, and possibly the new
contents - with C<undef> meaning deletion). For read-only access it
returns empty if no ID3v2 tag is present, or no frame is found.
If new contents is specified, B<ALL> the existing frames matching the
specification are deleted.
=item have_id3v2_frame
$have_it = $mp3->have_id3v2_frame($fname, $descrs, $langs);
Returns TRUE the specified frame(s) exist; has the same API as
L<MP3::Tag::ID3v2::frame_have> (args are frame name, list of wanted
Descriptors, list of wanted Languages).
=item get_id3v2_frame_ids
$h = $mp3->get_id3v2_frame_ids();
print " $_ => $h{$_}" for keys %$h;
Returns a hash reference with the short names of ID3v2 frames present
in the tag as keys (and long description of the meaning as values), or
FALSE if no ID3v2 tag is present. See
L<MP3::Tags::ID3v2::get_frame_ids> for details.
=item id3v2_frame_descriptors
Returns the list of human-readable "long names" of frames (such as
C<COMM(eng)[lyricist birthdate]>), appropriate for interpolation, or
for select_id3v2_frame_by_descr().
=item select_id3v2_frame_by_descr
=item have_id3v2_frame_by_descr
Similar to select_id3v2_frame(), have_id3v2_frame(), but instead of
arguments $fname, $descrs, $langs take one string of the form
NAME(langs)[descr]
Both C<(langs)> and C<[descr]> parts may be omitted; langs should
contain comma-separated list of needed languages. The semantic is
similar to
L<MP3::Tag::ID3v2::frame_select_by_descr_simpler|MP3::Tag::ID3v2/frame_select_by_descr_simpler>.
It is allowed to have C<NAME> of the form C<FRAMnn>; C<nn>-th frame
with name C<FRAM> is chosen (C<-1>-based: the first frame is C<FRAM>,
the second C<FRAM00>, the third C<FRAM01> etc; for more user-friendly
scheme, use C<langs> of the form C<#NNN>, with C<NNN> 0-based; see
L<MP3::Tag::ID3v2/"get_frame_ids()">).
$frame = $mp3->select_id3v2_frame_by_descr($descr [, $VALUE1, ...]);
$have_it = $mp3->have_id3v2_frame_by_descr($descr);
select_id3v2_frame_by_descr() will also apply the normalizer in config
setting C<translate_person> if the frame name matches one of the
elements of the configuration setting C<person_frames>.
$c = $mp3->select_id3v2_frame_by_descr("COMM(fre,fra,eng,#0)[]");
$t = $mp3->select_id3v2_frame_by_descr("TIT2");
$mp3->select_id3v2_frame_by_descr("TIT2", "MyT"); # Set/Change
$mp3->select_id3v2_frame_by_descr("RBUF", $n1, $n2, $n3); # Set/Change
$mp3->select_id3v2_frame_by_descr("RBUF", "$n1;$n2;$n3"); # Set/Change
$mp3->select_id3v2_frame_by_descr("TIT2", undef); # Remove
Remember that when select_id3v2_frame_by_descr() is used for
modification, B<ALL> found frames are deleted before a new one is
added. For gory details, see L<MP3::Tag::ID3v2/frame_select>.
=item frame_translate
$mp3->frame_translate('TCOM'); # Normalize TCOM ID3v2 frame
assuming that the frame value denotes a person, normalizes the value
using personal name normalization logic (via C<translate_person>
configuration value). Frame is updated, but the tag is not written
back. The frame must be in the list of personal names frames
(C<person_frames> configuration value).
=item frames_translate
Similar to frame_translate(), but updates all the frames in
C<person_frames> configuration value.
=cut
sub select_id3v2_frame ($$;@) {
my ($self) = (shift);
$self->get_tags;
if (not exists $self->{ID3v2}) {
return if @_ <= 3 or not defined $_[3]; # Read access, or deletion
$self->new_tag("ID3v2");
}
$self->{ID3v2}->frame_select(@_);
}
sub _select_id3v2_frame_by_descr ($$$;@) {
my ($self, $update) = (shift, shift);
$self->get_tags;
if (not exists $self->{ID3v2}) {
return if @_ <= 1 or @_ <= 2 and not defined $_[1]; # Read or delete
$self->new_tag("ID3v2");
}
my $fname = $_[0];
$fname =~ s/^(\w{4})\d+/$1/; # if FRAMnn, convert to FRAM
my $tr = ($self->get_config('translate_person') || [])->[0];
if ($tr) {
my $translate = $self->get_config('person_frames');
unless (ref $translate eq 'HASH') { # XXXX Store the hash somewhere???
$translate = {map +($_, 1), @$translate};
#$self->config('person_frames', @translate);
}
my $do = $translate->{$fname};
$do = $translate->{$fname} # Remove language
if not $do and $fname =~ s/^(\w{4})(?:\(([^()]*(?:\([^()]+\)[^()]*)*)\))/$1/;
undef $tr unless $do;
}
return if $update and not $tr;
$tr ||= sub {$_[1]};
return $self->{ID3v2}->frame_select_by_descr_simpler(@_)
if @_ > 2 or @_ == 2 and not defined $_[1]; # Multi-arg write or delete
return $self->{ID3v2}->frame_select_by_descr_simpler(
$_[0], &$tr($self, $_[1])
) if @_ == 2; # Write access with one arg
my $val = $self->{ID3v2}->frame_select_by_descr_simpler(@_);
my $nval;
$nval = &$tr($self, $val) if defined $val;
return $nval unless $update;
# Update logic:
return if not defined $val or $val eq $nval;
$self->{ID3v2}->frame_select_by_descr_simpler($_[0], $nval);
}
sub select_id3v2_frame_by_descr ($$;@) {
my ($self) = (shift);
return $self->_select_id3v2_frame_by_descr(0, @_);
}
sub frame_translate ($@) {
my ($self) = (shift);
return $self->_select_id3v2_frame_by_descr(1, @_);
}
sub frames_translate ($) {
my ($self) = (shift);
for my $f (@{$self->get_config('person_frames') || []}) {
$self->frame_translate($f);
}
}
sub have_id3v2_frame ($$;@) {
my ($self) = (shift);
$self->get_tags;
return if not exists $self->{ID3v2};
$self->{ID3v2}->frame_have(@_);
}
sub have_id3v2_frame_by_descr ($$) {
my ($self) = (shift);
$self->get_tags;
return if not exists $self->{ID3v2};
$self->{ID3v2}->frame_have_by_descr(shift);
}
sub get_id3v2_frame_ids ($$) {
my ($self) = (shift);
$self->get_tags;
return if not exists $self->{ID3v2};
$self->{ID3v2}->get_frame_ids(@_);
}
sub id3v2_frame_descriptors ($) {
my ($self) = (shift);
$self->get_tags;
return if not exists $self->{ID3v2};
$self->{ID3v2}->get_frame_descriptors(@_);
}
=item copy_id3v2_frames($from, $to, $overwrite, [$keep_flags, $f_ids])
Copies specified frames between C<MP3::Tag> objects $from, $to. Unless
$keep_flags, the copied frames have their flags cleared.
If the array reference $f_ids is not specified, all the frames (but C<GRID>
and C<TLEN>) are considered (subject to $overwrite), otherwise $f_ids should
contain short frame ids to consider. Group ID flag is always cleared.
If $overwrite is C<'delete'>, frames with the same descriptors (as
returned by get_frame_descr()) in $to are deleted first, then all the
specified frames are copied. If $overwrite is FALSE, only frames with
descriptors not present in $to are copied. (If one of these two
conditions is not met, the result may be not conformant to standards.)
Returns count of copied frames.
=cut
sub copy_id3v2_frames {
my ($from, $to, $overwrite, $keep_flags, $f_ids) = @_;
$from->get_tags;
return 0 unless $from = $from->{ID3v2}; # No need to create it...
$f_ids ||= [keys %{$from->get_frame_ids}];
return 0 unless @$f_ids;
$to->get_tags;
$to->new_tag("ID3v2") if not exists $to->{ID3v2};
$from->copy_frames($to->{ID3v2}, $overwrite, $keep_flags, $f_ids);
}
sub _Data_to_MIME ($$;$) {
goto &MP3::Tag::ID3v2::_Data_to_MIME
}
=item _Data_to_MIME
Internal method to extract MIME type from a string the image file content.
Returns C<application/octet-stream> for unrecognized data
(unless extra TRUE argument is given).
$format = $id3->_Data_to_MIME($data);
Currently, only the first 4 bytes of the string are inspected.
=cut
=item shorten_person
$string = $mp3->shorten_person($person_name);
shorten $person_name as a personal name (according to C<short_person>
configuration setting).
=cut
sub shorten_person ($$) {
my $self = shift;
my $tr = ($self->get_config('short_person') || [])->[0];
return shift unless $tr;
return &$tr($self, shift);
}
=item normalize_person
$string = $mp3->normalize_person($person_name);
normalize $person_name as a personal name (according to C<translate_person>
configuration setting).
=cut
sub normalize_person ($$) {
my $self = shift;
my $tr = ($self->get_config('translate_person') || [])->[0];
return shift unless $tr;
return &$tr($self, shift);
}
=item id3v2_frames_autofill
$mp3->id3v2_frames_autofill($force);
Generates missing tags from the list specified in C<id3v2_frames_autofill>
configuration variable. The tags should be from a short list this method
knows how to deal with:
TXXX[MCDI-fulltoc]: filled from file audio_cd.toc in directory of the
audio file. [Create this file with
readcd -fulltoc dev=0,1,0 -f=audio_cd >& nul
modifying the dev (and redirection per your shell). ]
lib/MP3/Tag.pm view on Meta::CPAN
(Multi-char escapes must be inclosed in braces, as in C<%{SML}> or C<%.5{aR}>.
Additional multi-char escapes are interpretated is follows:
=over 4
=item *
Names of ID3v2 frames are replaced by their text values (empty for missing
frames).
=item *
Strings C<n1> and C<n2> are replaced by "pure track number" and
"max track number" (this allows for both formats C<N1> and C<N1/N2> of "track",
the latter meaning track N1 of N2); use C<n0> to pad C<n1> with leading 0
to the width of C<n2> (in absense of n2, to 2). Likewise for C<m1>, C<m2>
but with disk (media) number instead of track number; use C<mA> to encode
C<m1> as a letter (see L<disk_alphanum()>).
=item *
Strings C<ID3v1> and C<ID3v2> are replaced by the whole ID3v1/2 tag
(interpolation of C<ID3v2> for an unmodified tag is subject to
C<id3v2_recalculate> configuration variable). (These may work as
conditionals too, with C<:>.)
=item *
Strings of the form C<FRAM(list,of,languages)[description]> are
replaced by the first FRAM frame with the descriptor "description" in
the specified comma-separated list of languages. Instead of a
language (ID3v2 uses lowercase 3-char ISO-639-2 language notations) one can use
a string of the form C<#Number>; e.g., C<#4> means 4th FRAM frame, or
FRAM04. Empty string for the language means any language.) Works as
a condition for conditional interpolation too.
Any one of the list of languages and the disription can be omitted;
this means that either the frame FRAM has no language or descriptor
associated, or no restriction should be applied.
Unknown language should be denoted as C<XXX> (in uppercase!). The language
match is case-insensitive.
=item *
Several descriptors of the form
C<FRAM(list,of,languages)[description]> discussed above may be
combined together with C<&>; the non-empty expansions are joined
together with the value of configuration variable C<ampersand_joiner>
(default C<"; ">). Example:
%{TXXX[pre-title]&TIT1&TIT2&TIT3&TXXX[post-title]}
=item *
Strings of the form C<method(list,of,packages)[arg1][arg2]> are replaced
by the result of C<method> (with the given arguments) in one of the specified
known subpackages (e.g., for C<Inf>, C<MP3::Tag::Inf> is used). Arbitrary number
of arguments is supported. Instead of a long name C<method> one can use its
standard shortcut (e.g., C<t> for C<title>). For example,
$mp3->interpolate('%{t(ID3v1,Cue)}')
returns the title from the ID3v1 tag, or (if not there) from a cue sheet.
One can use this in conditionals etc as well.
=item *
C<d>I<NUMBER> is replaced by I<NUMBER>-th component of the directory name (with
0 corresponding to the last component).
=item *
C<D>I<NUMBER> is replaced by the directory name with NUMBER components stripped.
=item *
C<U>I<NUMBER> is replaced by I<NUMBER>-th component of the user scratch
array.
=item *
If string starts with C<FNAME:>: if frame FNAME does not exists, the escape
is ignored; otherwise the rest of the string is reinterpreted.
=item *
String starting with C<!FNAME:> are treated similarly with inverted test.
=item *
If string starts with C<FNAME||>: if frame FNAME exists, the part
after C<||> is ignored; otherwise the part before C<||> is ignored,
and the rest is reinterpreted.
=item *
If string starts with C<FNAME|>: if frame FNAME exists, the part
after C<|> is ignored; otherwise the part before C<|> is ignored,
and the rest is reinterpreted as if it started with C<%{>.
=item *
String starting with I<LETTER>C<:> or C<!>I<LETTER>C<:> are treated similarly
to ID3v2 conditionals, but the condition is that the corresponding escape
expands to non-empty string. Same applies to non-time related 2-char escapes
and user variables.
=item *
Likewise for string starting with I<LETTER>C<|> or I<LETTER>C<||>.
=item *
For strings of the form C<nmP[VALUE]> or C<shP[VALUE]>, I<VALUE> is
interpolated, then normalized or shortened as a personal name
(according to C<translate_person> or C<short_person> configuration
setting).
lib/MP3/Tag.pm view on Meta::CPAN
}
my @data = $data;
if ($flags =~ /[ln]/) {
my $p = $self->get_config('parse_split')->[0];
@data = split $p, $data, -1;
}
if ($flags =~ /n/) {
my $track = $self->track1 or return;
@data = $data[$track - 1];
}
for my $d (@data) {
$d = $self->interpolate($d) if $flags =~ /I/;
unless ($flags =~ /b/) {
$d =~ s/^\s+//;
$d =~ s/\s+$//;
}
}
@data;
}
=item parse_rex($pattern, $string)
Parse $string according to the regular expression $pattern with
C<%>-escapes C<%%, %a, %t, %l, %y, %g, %c, %n, %e, %E> etc. The meaning
of escapes is the same as for method L<"interpolate">(); but (with
the exception of C<%%>) they are
used not for I<expansion>, but for I<matching> a part of $string
suitable to be a value for these fields. Returns false on failure, a
hash reference with parsed fields otherwise (with C<%a> setting the
field C<author>, etc).
Some more escapes are supported: C<%=a, %=t, %=l, %=y, %=g, %=c, %=n, %=e,
%=E, %=A, %=B, %=D, %=f, %=F, %=N, %={WHATEVER}> I<match>
substrings which are I<current> values of artist/title/etc (C<%=n> also
matches leading 0s; actual file-name matches ignore the difference
between C</> and C<\>, between one and multiple consequent dots (if
configuration variable C<parse_filename_merge_dots> is true (default))
and are case-insensitive if configuration variable
C<parse_filename_ignore_case> is true (default); moreover, C<%n>,
C<%y>, C<%=n>, C<%=y> will not match if the string-to-match is
adjacent to a digit). Double C<=> if you want to match to fail when
the corresponding conditional C<%>-escape would fail (a missing field,
or a zero-length field for required fields).
The escapes C<%{UE<lt>numberE<gt>}> and escapes of the forms
C<%{ABCD}> match any string; the
corresponding hash key in the result hash is what is inside braces;
here C<ABCD> is a 4-letter word possibly followed by 2-digit number
(as in names of ID3v2 tags), or what can be put in
C<'%{FRAM(lang,list)[description]}'>.
$res = $mp3->parse_rex( qr<^%a - %t\.\w{1,4}$>,
$mp3->filename_nodir ) or die;
$author = $res->{author};
2-digit numbers, or I<number1/number2> with number1,2 up to 999 are
allowed for the track number (the leading 0 is stripped); 4-digit
years in the range 1000..2999 are allowed for year. Alternatively, if
option year_is_timestamp is TRUE (default), year may be a range of
timestamps in the format understood by ID3v2 method year() (see
L<MP3::Tag::ID3v2/"year">).
The escape C<%E> matches the REx in the configuration variable C<extension>;
the escape C<%e> matches the part of %E after the leading dot.
In list context, also returns an array reference with %{handler} groups
parsed (if present). Such groups can match everything, and a successful match gives an
array element with C<[$method, $packages, $args, $matched]>.
Currently the regular expressions with capturing parens are not supported.
=item parse_rex_prepare($pattern)
Returns a data structure which later can be used by parse_rex_match().
These two are equivalent:
$mp3->parse_rex($pattern, $data);
$mp3->parse_rex_match($mp3->parse_rex_prepare($pattern), $data);
This call constitutes the "slow part" of the parse_rex() call; it makes sense to
factor out this step if the parse_rex() with the same $pattern is called
against multiple $data.
=item parse_rex_match($prepared, $data)
Matches $data against a data structure returned by parse_rex_prepare().
These two are equivalent:
$mp3->parse_rex($pattern, $data);
$mp3->parse_rex_match($mp3->parse_rex_prepare($pattern), $data);
=cut
sub _rex_protect_filename {
my ($self, $filename, $what) = (shift, quotemeta shift, shift);
$filename =~ s,\\[\\/],[\\\\/],g; # \ and / are interchangeable + backslashitis
if ($self->get_config('parse_filename_merge_dots')->[0]) {
# HPFS doesn't distinguish x..y and x.y
$filename =~ s(\\\.+)(\\.+)g;
$filename =~ s($)(\\.*) if $what =~ /[ABN]/;
}
my $case = $self->get_config('parse_filename_ignore_case')->[0];
return $filename unless $case;
return "(?i:$filename)";
}
sub _parse_rex_anything ($$) {
my $c = shift->get_config('parse_minmatch');
my $min = $c->[0];
if ($min and $min ne '1') {
my $field = shift;
$min = grep $_ eq $field, @$c;
}
return $min ? '(.*?)' : '(.*)';
}
sub __pure_track_rex ($) {
my $t = shift()->track;
$t =~ s/^0+//;
$t =~ s,^(.*?)(/.*),\Q$1\E(?:\Q$2\E)?,;
$t
lib/MP3/Tag.pm view on Meta::CPAN
$out .= "$res$ff";
} else {
$out .= $self->interpolate($what) . $ff;
}
}
$out;
}
my @channel_modes = ('stereo', 'joint stereo', 'dual channel', 'mono');
sub channel_mode { $channel_modes[shift->channel_mode_int] }
=item can_write()
checks permission to write per the configuration variable C<is_writable>.
=item can_write_or_die($mess)
as can_write(), but die()s on non-writable files with meaningful error message
($mess is prepended to the message).
=item die_cant_write($mess)
die() with the same message as can_write_or_die().
=item writable_by_extension()
Checks that extension is (case-insensitively) in the list given by
configuration variable C<writable_extensions>.
=cut
sub can_write ($) {
my $self = shift;
my @wr = @{ $self->get_config('is_writable') }; # Make copy
return $wr[0] if @wr == 1 and not $wr[0] =~ /\D/;
my $meth = shift @wr;
$self->$meth(@wr);
}
sub writable_by_extension ($) {
my $self = shift;
my $wr = $self->get_config('writable_extensions'); # Make copy
$self->extension_is(@$wr);
}
sub die_cant_write ($$) {
my($self, $what) = (shift, shift);
die $what, $self->interpolate("File %F is not writable per `is_writable' confuration variable, current value is `"),
join(', ', @{$self->get_config('is_writable')}), "'";
}
sub can_write_or_die ($$) {
my($self, $what) = (shift, shift);
my $wr = $self->can_write;
return $wr if $wr;
$self->die_cant_write($what);
}
=item update_tags( [ $data, [ $force2 ]] )
$mp3 = MP3::Tag->new($filename);
$mp3->update_tags(); # Fetches the info, and updates tags
$mp3->update_tags({}); # Updates tags if needed/changed
$mp3->update_tags({title => 'This is not a song'}); # Updates tags
This method updates ID3v1 and ID3v2 tags (the latter only if in-memory copy
contains any data, or $data does not fit ID3v1 restrictions, or $force2
argument is given)
with the the information about title, artist, album, year, comment, track,
genre from the hash reference $data. The format of $data is the same as
one returned from autoinfo() (with or without the optional argument 'from').
The fields which are marked as coming from ID3v1 or ID3v2 tags are not updated
when written to the same tag.
If $data is not defined or missing, C<autoinfo('from')> is called to obtain
the data. Returns the object reference itself to simplify chaining of method
calls.
This is probably the simplest way to set data in the tags: populate
$data and call this method - no further tinkering with subtags is
needed.
=cut
sub update_tags {
my ($mp3, $data, $force2, $wr2) = (shift, shift, shift);
$mp3->get_tags;
$data = $mp3->autoinfo('from') unless defined $data;
# $mp3->new_tag("ID3v1") unless $wr1 = exists $mp3->{ID3v1};
unless (exists $mp3->{ID3v1}) {
$mp3->can_write_or_die('update_tags() doing ID3v1: ');
$wr2 = 1;
$mp3->new_tag("ID3v1");
}
my $elt;
for $elt (qw/title artist album year comment track genre/) {
my $d = $data->{$elt};
next unless defined $d;
$d = [$d, ''] unless ref $d;
$mp3->{ID3v1}->$elt( $d->[0] ) if $d->[1] ne 'ID3v1';
} # Skip what is already there...
$mp3->{ID3v1}->write_tag;
my $do_length
= (defined $mp3->{ms}) ? ($mp3->get_config('update_length'))->[0] : 0;
return $mp3
if not $force2 and $mp3->{ID3v1}->fits_tag($data)
and not exists $mp3->{ID3v2} and $do_length < 2;
# $mp3->new_tag("ID3v2") unless exists $mp3->{ID3v2};
unless (exists $mp3->{ID3v2}) {
if (defined $wr2) {
$mp3->die_cant_write('update_tags() doing ID3v2: ') unless $wr2;
} else {
$mp3->can_write_or_die('update_tags() doing ID3v2: ');
}
$mp3->new_tag("ID3v2");
}
for $elt (qw/title artist album year comment track genre/) {
my $d = $data->{$elt};
next unless defined $d;
$d = [$d, ''] unless ref $d;
$mp3->{ID3v2}->$elt( $d->[0] ) if $d->[1] ne 'ID3v2';
} # Skip what is already there...
# $mp3->{ID3v2}->comment($data->{comment}->[0]);
$mp3->set_id3v2_frame('TLEN', $mp3->{ms})
if $do_length and not $mp3->have_id3v2_frame('TLEN');
$mp3->{ID3v2}->write_tag;
return $mp3;
}
sub _massage_genres ($;$) { # Thanks to neil verplank for the prototype
require MP3::Tag::ID3v1;
my($data, $how) = (shift, shift);
my $firstnum = (($how || 0) eq 'num');
my $prefer_num = (($how || 0) eq 'prefer_num');
my (%seen, @genres); # find all genres in incoming data
$data = $data->[0] if ref $data;
# clean and split line on both null and parentheses
$data =~ s/\s+/ /g;
$data =~ s/\s*\0[\0\s]*/\0/g;
$data =~ s/^[\s\0]+//;
$data =~ s/[\s\0]+$//;
my @data = split m<\0|\s+/\s+>, $data;
@data = split /\( ( \d+ | rx | cr ) \)/xi, $data[0] if @data == 1;
# review array, produce a clean, ordered list of unique genres for output
foreach my $genre (@data) {
next if $genre eq ""; # (12)(13) ==> in front, and between
# convert text to number to eliminate collisions, and produce consistent output
if ($genre =~ /\D/) {{ # Not a pure number
# return id number
my $genre_num = MP3::Tag::ID3v1::genres($genre);
# 255 is "non-standard text" in ID3v1; pass the rest through
last if $genre_num eq '255' or $genre_num eq '';
return $genre_num if $firstnum;
$genre = $genre_num, last if $prefer_num;
$genre_num = MP3::Tag::ID3v1::genres($genre_num);
last unless defined $genre_num;
$genre = $genre_num;
}} # Now converted to a number - if possible
unless ($prefer_num or $genre =~ /\D/) {{ # Here $genre is a number
my $genre_str = MP3::Tag::ID3v1::genres($genre) or last;
return $genre if $firstnum;
$genre = $genre_str;
}}
# 2.4 defines these conversions
$genre = "Remix" if lc $genre eq "rx";
$genre = "Cover" if lc $genre eq "cr";
$genre = "($genre)" if length $genre and not $genre =~ /\D/; # Only digits
push @genres, $genre unless $seen{$genre}++;
}
return if $firstnum;
@genres;
}
=item extension_is
$mp3->extension_is(@EXT_LIST)
returns TRUE if the extension of the filename coincides (case-insensitive)
with one of the elements of the list.
=cut
sub extension_is ($@) {
my ($self) = (shift);
my $ext = lc($self->filename_extension_nodot());
return 1 if grep $ext eq lc, @_;
return;
}
sub DESTROY {
my $self=shift;
if (exists $self->{filename} and defined $self->{filename}) {
$self->{filename}->close;
}
}
sub parse_cfg_line ($$$) {
my ($self, $line, $data) = (shift,shift,shift);
return if $line =~ /^\s*(#|$)/;
die "Unrecognized configuration file line: <<<$line>>>"
unless $line =~ /^\s*(\w+)\s*=\s*(.*?)\s*$/;
push @{$data->{$1}}, $2;
}
=item C<parse_cfg( [$filename] )>
Reads configuration information from the specified file (defaults to
the value of configuration variable C<local_cfg_file>, which is
C<~>-substituted). Empty lines and lines starting with C<#> are ignored.
The remaining lines should have format C<varname=value>; leading
and trailing whitespace is stripped; there may be several lines with the same
C<varname>; this sets list-valued variables.
=back
=cut
sub parse_cfg ($;$) {
my ($self, $file) = (shift,shift);
$file = ($self->get_config('local_cfg_file'))->[0] unless defined $file;
return unless defined $file;
$file =~ s,^~(?=[/\\]),$ENV{HOME}, if $ENV{HOME};
return unless -e $file;
open F, "< $file" or die "Can't open `$file' for read: $!";
my $data = {};
while (defined (my $l = <F>)) {
$self->parse_cfg_line($l, $data);
}
CORE::close F or die "Can't close `$file' for read: $!";
for my $k (keys %$data) {
$self->config($k, @{$data->{$k}});
}
}
my @parents = qw(User Site Vendor);
@MP3::Tag::User::ISA = qw( MP3::Tag::Site MP3::Tag::Vendor
MP3::Tag::Implemenation ); # Make overridable
@MP3::Tag::Site::ISA = qw( MP3::Tag::Vendor MP3::Tag::Implemenation );
@MP3::Tag::Vendor::ISA = qw( MP3::Tag::Implemenation );
sub load_parents {
my $par;
while ($par = shift @parents) {
return 1 if eval "require MP3::Tag::$par; 1"
}
return;
}
load_parents() unless $ENV{MP3TAG_SKIP_LOCAL};
MP3::Tag->parse_cfg() unless $ENV{MP3TAG_SKIP_LOCAL};
1;
=pod
=head1 ENVIRONMENT
Some defaults for the operation of this module (and/or scripts distributed
with this module) are set from
environment. Assumed encodings (0 or encoding name): for read access:
MP3TAG_DECODE_V1_DEFAULT MP3TAG_DECODE_V2_DEFAULT
MP3TAG_DECODE_FILENAME_DEFAULT MP3TAG_DECODE_FILES_DEFAULT
MP3TAG_DECODE_INF_DEFAULT MP3TAG_DECODE_CDDB_FILE_DEFAULT
MP3TAG_DECODE_CUE_DEFAULT
for write access:
MP3TAG_ENCODE_V1_DEFAULT MP3TAG_ENCODE_FILES_DEFAULT
(if not set, default to corresponding C<DECODE> options).
Defaults for the above:
MP3TAG_DECODE_DEFAULT MP3TAG_ENCODE_DEFAULT
(if the second one is not set, the value of the first one is used).
Value 0 for more specific variable will cancel the effect of the less
specific variables.
If the C<LANG> environment variable indicates C<UTF-8> encoding, then
the "C<FILES>" flavors default to C<utf8> (unless this effect is already
achieved by the C<${^UNICODE}> variable). This may be disabled by setting
C<MP3TAG_DECODE_FILES_DEFAULT_RESET> true in the environment (likewise for
C<EN>-code flavor).
These variables set default configuration settings for C<MP3::Tag>;
the values are read during the load time of the module. After load,
one can use config()/get_config() methods to change/access these
settings. See C<encode_encoding_*> and C<encode_decoding_*> in
documentation of L<config|config> method. (Note that C<FILES> variant
govern file read/written in non-binary mode by L<MP3/ParseData> module,
as well as reading of control files of some scripts using this module, such as
L<typeset_audio_dir>.)
=over
=item B<EXAMPLE>
Assume that locally present CDDB files and F<.inf> files
are in encoding C<cp1251> (this is not supported by "standard", but since
the standard supports only a handful of languages, this is widely used anyway),
and that one wants C<ID3v1> fields to be in the same encoding, but C<ID3v2>
have an honest (Unicode, if needed) encoding. Then set
MP3TAG_DECODE_INF_DEFAULT=cp1251
MP3TAG_DECODE_CDDB_FILE_DEFAULT=cp1251
MP3TAG_DECODE_V1_DEFAULT=cp1251
Since C<MP3TAG_DECODE_V1_DEFAULT> implies C<MP3TAG_ENCODE_V1_DEFAULT>,
you will get the desired effect both for read and write of MP3 tags.
=back
Additionally, the following (unsupported) variables are currently
recognized by ID3v2 code:
MP3TAG_DECODE_UNICODE MP3TAG_DECODE_UTF8
MP3TAG_DECODE_UNICODE (default 1) enables decoding; the target of
decoding is determined by MP3TAG_DECODE_UTF8: if 0, decoded values are
byte-encoded UTF-8 (every Perl character contains a byte of UTF-8
encoded string); otherwise (default) it is a native Perl Unicode
string.
If C<MP3TAG_SKIP_LOCAL> is true, local customization files are not loaded.
=head1 CUSTOMIZATION
Many aspects of operation of this module are subject to certain subtle
choices. A lot of effort went into making these choices customizable,
by setting global or per-object configuration variables.
A certain degree of customization of global configuration variables is
available via the environment variables. Moreover, at startup the local
customization file F<~/.mp3tagprc> is read, and defaults are set accordingly.
In addition, to make customization as flexible as possible, I<ALL> aspects
of operation of C<MP3::Tag> are subject to local override. Three customization
modules
MP3::Tag::User MP3::Tag::Site MP3::Tag::Vendor
are attempted to be loaded if present. Only the first module (of
those present) is loaded directly; if sequential load is desirable,
the first thing a customization module should do is to call
MP3::Tag->load_parents()
method.
The customization modules have an opportunity to change global
configuration variables on load. To allow more flexibility, they may
override any method defined in C<MP3::Tag>; as usual, the overriden
method may be called using C<SUPER> modifier (see L<perlobj/"Method
invocation">).
E.g., it is recommended to make a local customization file with
eval 'require Normalize::Text::Music_Fields';
for my $elt ( qw( title track artist album comment year genre
title_track artist_collection person ) ) {
no strict 'refs';
MP3::Tag->config("translate_$elt", \&{"Normalize::Text::Music_Fields::normalize_$elt"})
if defined &{"Normalize::Text::Music_Fields::normalize_$elt"};
}
MP3::Tag->config("short_person", \&Normalize::Text::Music_Fields::short_person)
if defined &Normalize::Text::Music_Fields::short_person;
and install the (supplied, in the F<examples/modules>) module
L<Normalize::Text::Music_Fields> which enables normalization of person
names (to a long or a short form), and of music piece names to
canonical forms.
To simplify debugging of local customization, it may be switched off
completely by setting MP3TAG_SKIP_LOCAL to TRUE (in environment).
For example, putting
id3v23_unsync = 0
into F<~/.mp3tagprc> will produce broken ID3v2 tags (but those required
by ITunes).
=head1 EXAMPLE SCRIPTS
Some example scripts come with this module (either installed, or in directory
F<examples> in the distribution); they either use this module, or
provide data understood by this module:
=over
=item mp3info2
perform command line manipulation of audio tags (and more!);
=item audio_rename
rename audio files according to associated tags (and more!);
=item typeset_mp3_dir
write LaTeX files suitable for CD covers and normal-size sheet
descriptions of hierarchy of audio files;
=item mp3_total_time
Calculate total duration of audio files;
=item eat_wav_mp3_header
remove WAV headers from MP3 files in WAV containers.
=item fulltoc_2fake_cddb
converts a CD's "full TOC" to a "fake" CDDB file (header only). Create
this file with something like
readcd -fulltoc dev=0,1,0 -f=audio_cd >& nul
run similar to
fulltoc_2fake_cddb < audio_cd.toc | cddb2cddb > cddb.out
=item dir_mp3_2fake_cddb
tries to convert a directory of MP3 files to a "fake" CDDB file (header only);
assumes that files are a rip from a CD, and that alphabetical sort gives
the track order (works only heuristically, since quantization of duration
of MP3 files and of CD tracks is so different).
Run similar to
dir_mp3_2fake_cddb | cddb2cddb > cddb.out
=item inf_2fake_cddb
tries to convert a directory of F<.inf> files to a "fake" CDDB file (header
only). (Still heuristic, since it can't guess the length of the leader.)
Run similar to
inf_2fake_cddb | cddb2cddb > cddb.out
=item cddb2cddb
Reads a (header of) CDDB file from STDIN, outputs (on STDOUT) the current
version of the database record. Can be used to update a file, and/or to
convert a fake CDDB file to a real one.
=back
(Last four do not use these modules!)
Some more examples:
# Convert from one (non-standard-conforming!) encoding to another
perl -MMP3::Tag -MEncode -wle '
my @fields = qw(artist album title comment);
for my $f (@ARGV) {
print $f;
my $t = MP3::Tag->new($f) or die;
$t->update_tags(
{ map { $_ => encode "cp1251", decode "koi8-r", $t->$_() }, @fields }
);
}' list_of_audio_files
=head1 Problems with ID3 format
The largest problem with ID3 format is that the first versions of these
format were absolutely broken (underspecified). It I<looks> like the newer
versions of this format resolved most of these problems; however, in reality
they did not (due to unspecified backward compatibility, and
grandfathering considerations).
What are the problems with C<ID3v1>? First, one of the fields was C<artist>,
which does not make any sense. In particular, different people/publishers
would put there performer(s), composer, author of text/lyrics, or a combination
of these. The second problem is that the only allowed encoding was
C<iso-8859-1>; since most of languages of the world can't be expressed
in this encoding, this restriction was completely ignored, thus the
encoding is essentially "unknown".
Newer versions of C<ID3> allow specification of encodings; however,
since there is no way to specify that the encoding is "unknown", when a
tag is automatically upgraded from C<ID3v1>, it is most probably assumed to be
in the "standard" C<iso-8859-1> encoding. Thus impossibility to
distinguish "unknown, assumed C<iso-8859-1>" from "known to be C<iso-8859-1>"
in C<ID3v2>, essentially, makes any encoding specified in the tag "unknown"
(or, at least, "untrusted"). (Since the upgrade [or a chain of upgrades]
from the C<ID3v1> tag to the C<ID3v2> tag can result in any encoding of
the "supposedly C<iso-8859-1>" tag, one cannot trust the content of
C<ID3v2> tag even if it stored as Unicode strings.)
This is why this module provides what some may consider only lukewarm support
for encoding field in ID3v2 tags: if done fully automatic, it can allow
instant propagation of wrong information; and this propagation is in a form
which is quite hard to undo (but still possible to do with suitable settings
to this module; see L<mp3info2/"Examples on dealing with broken encodings">).
Likewise, the same happens with the C<artist> field in C<ID3v1>. Since there
is no way to specify just "artist, type unknown" in C<ID3v2> tags, when
C<ID3v1> tag is automatically upgraded to C<ID3v2>, the content would most
probably be put in the "main performer", C<TPE1>, tag. As a result, the
content of C<TPE1> tag is also "untrusted" - it may contain, e.g., the composer.
In my opinion, a different field should be used for "known to be
principal performer"; for example, the method performer() (and the
script F<mp3info2> shipped with this module) uses C<%{TXXX[TPE1]}> in
preference to C<%{TPE1}>.
For example, interpolate C<%{TXXX[TPE1]|TPE1}> or C<%{TXXX[TPE1]|a}> -
this will use the frame C<TXXX> with identifier C<TPE1> if present, if not,
it will use the frame C<TPE1> (the first example), or will try to get I<artist>
by other means (including C<TPE1> frame) (the second example).
=head1 FILES
There are many files with special meaning to this module and its dependent
modules.
=over 4
=item F<*.inf>
Files with extension F<.inf> and the same basename as the audio file are
read by module C<MP3::Tag::Inf>, and the extracted data is merged into the
information flow according to configuration variable C<autoinfo>.
It is assumed that these files are compatible in format to the files written
by the program F<cdda2wav>.
=item F<audio.cddb> F<cddb.out> F<cddb.in>
in the same directory as the audio file are read by module
C<MP3::Tag::CDDB_File>, and the extracted data is merged into the
information flow according to configuration variable C<autoinfo>.
(In fact, the list may be customized by configuration variable C<cddb_files>.)
=item F<audio_cd.toc>
in the same directory as the audio file may be read by the method
id3v2_frames_autofill() (should be called explicitly) to fill the C<TXXX[MCDI-fulltoc]>
frame. Depends on contents of configuration variable C<id3v2_frames_autofill>.
=item F<~/.mp3tagprc>
By default, this file is read on startup (may be customized by overriding
the method parse_cfg()). By default, the name of the file is in the
configuration variable C<local_cfg_file>.
=back
=head1 SEE ALSO
L<MP3::Tag::ID3v1>, L<MP3::Tag::ID3v2>, L<MP3::Tag::File>,
L<MP3::Tag::ParseData>, L<MP3::Tag::Inf>, L<MP3::Tag::CDDB_File>,
L<MP3::Tag::Cue>, L<MP3::Tag::ImageExifTool>, L<MP3::Tag::ImageSize>,
L<MP3::Tag::LastResort>, L<mp3info2>, L<typeset_audio_dir>.
=head1 COPYRIGHT
Copyright (c) 2000-2016 Thomas Geffert, Ilya Zakharevich. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the terms of the Artistic License, distributed
with Perl.
=cut
( run in 0.499 second using v1.01-cache-2.11-cpan-d7a12ab2c7f )