File Coverage

blib/lib/AudioFile/Info.pm
Criterion Covered Total %
statement 26 31 83.9
branch 5 8 62.5
condition 1 2 50.0
subroutine 6 6 100.0
pod 1 1 100.0
total 39 48 81.2


line stmt bran cond sub pod time code
1             #
2             # $Id$
3             #
4              
5             =head1 NAME
6            
7             AudioFile::Info - Perl extension to get info from audio files.
8            
9             =head1 SYNOPSIS
10            
11             use AudioFile::Info;
12            
13             my $song = AudioFile::Info->new($some_mp3_or_ogg_vorbis_file);
14            
15             print 'Title: ', $song->title, "\n",
16             'Artist: ', $song->artist, "\n".
17             'Album: ', $song->album, "\n",
18             'Track: ', $song->track, "\n";
19             'Year: ', $song->year, "\n",
20             'Genre: ', $song->genre, "\n";
21            
22             $song->title('something else'); # Changes the title
23            
24             =head1 ABSTRACT
25            
26             AudioFile::Info is a simple way to get track information out of an audio
27             file. It gives a unified interface for extracting information from both
28             MP3 and Ogg Vorbis files.
29            
30             Some AudioFile::Info plugins also have the ability to write data back
31             to the file.
32            
33             =head1 DESCRIPTION
34            
35             =head2 What is AudioFile::Info
36            
37             I rip all of my audio files into Ogg Vorbis files. But some of my older
38             rips are in MP3 format. If I'm writing a program to access information
39             from my audio files it's annoying when I have to handle MP3 and Ogg
40             Vorbis files completely separately.
41            
42             AudioFile::Info is my solution to that problem. It works on both MP3
43             and Ogg Vorbis files and gives an identical interface for dealing with
44             both of them.
45            
46             =head2 Using AudioFile::Info
47            
48             To use AudioFile::Info in your programs you simply load the module
49             as normal.
50            
51             use AudioFile::Info;
52            
53             You then create an object using the C<new> method and passing it the
54             pathname of an audio file.
55            
56             my $song = AudioFile::Info->new($some_mp3_or_ogg_vorbis_file);
57            
58             The module works out whether the file is in MP3 or Ogg Vorbis format and
59             creates an object which can extract the information from the correct
60             type of file. You can then use this object to access the various pieces
61             of information about the file.
62            
63             print 'Title: ', $song->title, "\n",
64             'Artist: ', $song->artist, "\n".
65             'Album: ', $song->album, "\n",
66             'Track: ', $song->track, "\n";
67             'Year: ', $song->year, "\n",
68             'Genre: ', $song->genre, "\n";
69            
70             Currently you can access the title, artist, album, track number, year
71             and genre of the file.
72            
73             With certain plugins (see below for a description of plugins) you can
74             now write data back to the file. This is as simple as passing a new string
75             to the accessor function.
76            
77             $song->title('something new');
78            
79             =head2 AudioFile::Info Plugins
80            
81             AudioFile::Info is simply a wrapper around various other modules which
82             read and write MP3 and Ogg Vorbis files. It makes use of these modules
83             by using plugin modules which act as an interface between
84             AudioFile::Info and the other modules. AudioFile::Info is pretty much
85             useless without at least one these plugins installed.
86            
87             Each time you install a plugin, AudioFile::Info notes how it compares
88             with other installed plugins. It then works out how which of your
89             installed plugins is best for handling the various types of audio
90             files. When you use the module to read a file it will use the
91             "best" plugin for the file type.
92            
93             You can override this behaviour and tell it to use a particular
94             plugin by using an extended version of the C<new> method.
95            
96             C<new> takes an optional argument which is a reference to a hash
97             that contains details of which plugin to use for each file type.
98             You use it like this.
99            
100             my $song = AudioFile::Info->new($file,
101             { mp3 => 'AudioFile::Info::MP3::Info' });
102            
103             In this case, if C<$file> is the name of an MP3 file then
104             AudioFile::Info will use C<AudioFile::Info::MP3::Info> to handle it
105             rather than the default MP3 plugin. If C<$file> contains the name
106             of an Ogg Vorbis file then the default Ogg Vorbis plugin will still
107             be used. You can change the Ogg Vorbis plugin by using the C<ogg>
108             key in the optional hash.
109            
110             Currently plugins are available for the following modules.
111            
112             =over 4
113            
114             =item *
115            
116             MP3::ID3Lib
117            
118             =item *
119            
120             MP3::Info
121            
122             =item *
123            
124             MP3::Tag
125            
126             =item *
127            
128             Ogg::Vorbis::Header
129            
130             =item *
131            
132             Ogg::Vorbis::Header::PurePerl
133            
134             =back
135            
136             Plugins for other modules may appear in the future. Let me know if you
137             want a plugin that doesn't already exist.
138            
139             =cut
140              
141             package AudioFile::Info;
142              
143 2     2   122562 use 5.006;
  2         6  
  2         30  
144 2     2   4 use strict;
  2         2  
  2         34  
145 2     2   6 use warnings;
  2         2  
  2         43  
146 2     2   7 use Carp;
  2         2  
  2         73  
147              
148 2     2   396 use YAML 'LoadFile';
  2         7260  
  2         345  
149              
150             our $VERSION = 1.09;
151              
152             =head1 METHODS
153            
154             =head2 AudioFile::Info->new(FILE, [\%OPTIONS])
155            
156             Constructor method which returns a new Audio::File::Info object. Well,
157             actually it returns an instance of one of the AudioFile::Info plugin
158             objects, but for the average user the difference is largely academic.
159            
160             Takes one mandatory argument, which is a full local path to an audio
161             file, and an optional reference to a hash containing options.
162            
163             Currently the only options the method understands are 'mp3' or 'ogg'.
164             The corresponding values for these keys is the name of a plugin module
165             to use to process files of that type. This will override the default
166             plugin which AudioFile::Info will choose for itself from the installed
167             plugins.
168            
169             =cut
170              
171             sub new {
172 3     3 1 91288   my $class = shift;
173 3 100       15   my $file = shift or die "No music file given.";
174              
175 2   50     9   my $param = shift || {};
176              
177 2         3   my $path = $INC{'AudioFile/Info.pm'};
178              
179 2         8   $path =~ s/Info.pm$/plugins.yaml/;
180              
181 2         5   my ($ext) = $file =~ /\.(\w+)$/;
182 2 100       10   die "Can't work out the type of the file $file\n"
183                 unless defined $ext;
184              
185 1         2   $ext = lc $ext;
186              
187 1         2   my $pkg = $param->{$ext};
188              
189 1 50       2   unless (defined $pkg) {
190 1         5     my $config = LoadFile($path);
191              
192 0 0             die "No default $ext file handler\n"
193                     unless exists $config->{default}{$ext};
194              
195 0               $pkg = $config->{default}{$ext}{name};
196               }
197              
198 0             eval "require $pkg";
199 0             $pkg->import;
200              
201 0             return $pkg->new($file);
202             }
203              
204              
205             1;
206             __END__
207            
208             =head2 EXPORT
209            
210             None.
211            
212             =head1 SEE ALSO
213            
214             The various plugin modules.
215            
216             =head1 TO DO
217            
218             =over 4
219            
220             =item *
221            
222             Make more data available.
223            
224             =item *
225            
226             Changing and writing data.
227            
228             =back
229            
230             =head1 AUTHOR
231            
232             Dave Cross, E<lt>dave@mag-sol.comE<gt>
233            
234             =head1 COPYRIGHT AND LICENSE
235            
236             Copyright 2003-2007 by Magnum Solutions Ltd. All rights reserved.
237            
238             This library is free software; you can redistribute it and/or modify it
239             under the same terms as Perl itself.
240            
241             =cut
242