NAME

MP3::M3U::Parser - MP3 playlist parser.

SYNOPSIS

   use MP3::M3U::Parser;
   my $parser = MP3::M3U::Parser->new(%options);

   $parser->parse(\*FILEHANDLE, \$scalar, "/path/to/playlist.m3u");
   my $result = $parser->result;
   my %info   = $parser->info;

   $parser->export(-format   => 'xml',
                   -file     => "/path/mp3.xml",
                   -encoding => 'ISO-8859-9');

   $parser->export(-format   => 'html',
                   -file     => "/path/mp3.html",
                   -drives   => 'off');

   # convert all m3u files to individual html files.
   foreach (<*.m3u>) {
      $parser->parse($_)->export->reset;
   }

   # convert all m3u files to one big html file.
   foreach (<*.m3u>) {
      $parser->parse($_);
   }
   $parser->export;

DESCRIPTION

MP3::M3U::Parser is a parser for M3U mp3 playlist files. It also parses the EXTINF lines (which contains id3 song name and time) if possible. You can get a parsed object or specify a format and export the parsed data to it. The format can be xml or html.

Methods

new

The object constructor. Takes several arguments like:

-seconds

Format the seconds returned from parsed file? if you set this to the value format, it will convert the seconds to a format like MM:SS or H:MM:SS. Else: you get the time in seconds like; 256 (if formatted: 04:15).

-search

If you don't want to get a list of every song in the m3u list, but want to get a specific group's/singer's songs from the list, set this to the string you want to search. Think this "search" as a parser filter.

Note that, the module will do a *very* basic case-insensitive search. It does dot accept multiple words (if you pass a string like "michael beat it", it will not search every word seperated by space, it will search the string "michael beat it" and probably does not return any results -- it will not match "michael jackson - beat it"), it does not have a boolean search support, etc. If you want to do something more complex, get the parsed tree and use it in your own search function, or subclass this module and write your own _search method (notice the underscore in the method name). See the tests for a subclassing example.

-parse_path

The module assumes that all of the songs in your M3U lists are (or were: the module does not check the existence of them) on the same drive. And it builds a seperate data table for drive names and removes that drive letter (if there is a drive letter) from the real file path. If there is no drive letter (eg: under linux there is no such thing, or you saved m3u file into the same volume as your mp3s), then the drive value is 'CDROM:'.

So, if you have a mixed list like:

   G:\a.mp3
   F:\b.mp3
   Z:\xyz.mp3

set this parameter to 'asis' to not to remove the drive letter from the real path. Also, you "must" ignore the drive table contents which will still contain a possibly wrong value; export does take the drive letters from the drive tables. So, you can not use the drive area in the exported xml (for example).

-overwrite

Same as the -overwrite option in export but new sets this export option globally.

-encoding

Same as the -encoding option in export but new sets this export option globally.

-expformat

Same as the -format option in export but new sets this export option globally.

-expdrives

Same as the -drives option in export but new sets this export option globally.

parse

It takes a list of arguments. The list can include file paths, scalar references or filehandle references. You can mix these types. Module interface can handle them correctly.

   open FILEHANDLE, ...
   $parser->parse(\*FILEHANDLE);

or with new versions of perl:

   open my $fh, ...
   $parser->parse($fh);

   my $scalar = "#EXTM3U\nFoo - bar.mp3";
   $parser->parse(\$scalar);

or

   $parser->parse("/path/to/some/playlist.m3u");

or

   $parser->parse("/path/to/some/playlist.m3u",\*FILEHANDLE,\$scalar);

Note that globs and scalars are passed as references.

Returns the object itself.

result

Must be called after parse. Returns the result set created from the parsed data(s). Returns the data as an array or arrayref.

   $result = $parser->result;
   @result = $parser->result;

Data structure is like this:

   $VAR1 = [
             {
               'drive' => 'G:',
               'file' => '/path/to/mylist.m3u',
               'data' => [
                           [
                             'mp3\Singer - Song.mp3',
                             'Singer - Song',
                             232,
                             'Singer',
                             'Song'
                           ],
                           # other songs in the list
                         ],
               'total' => '3',
               'list' => 'mylist'
             },
             # other m3u list
           ];

Each playlist is added as a hashref:

   $pls = {
           drive => "Drive letter if available",
           file  => "Path to the parsed m3u file or generic name if GLOB/SCALAR",
           data  => "Songs in the playlist",
           total => "Total number of songs in the playlist",
           list  => "name of the list",
   }

And the data key is an AoA:

   data => [
            ["MP3 PATH INFO", "ID3 INFO","TIME","ARTIST","SONG"],
            # other entries...
            ]

You can use the Data::Dumper module to see the structure yourself:

   use Data::Dumper;
   print Dumper $result;

info

You must call this after calling parse. It returns an info hash about the parsed data.

   my %info = $parser->info;

The keys of the %info hash are:

   songs   => Total number of songs
   files   => Total number of lists parsed
   ttime   => Total time of the songs 
   average => Average time of the songs
   drive   => Drive names for parsed lists

Note that the 'drive' key is an arrayref, while others are strings.

   printf "Drive letter for first list is %s\n", $info{drive}->[0];

But, maybe you do not want to use the $info{drive} table; see -parse_path option in new.

export

Exports the parsed data to a format. The format can be xml or html. The HTML File' s style is based on the popular mp3 player WinAmp' s HTML List file. Takes several arguments:

-file

The full path to the file you want to write the resulting data. If you do not set this parameter, a generic name will be used.

-format

Can be xml or html. Default is html.

-encoding

The exported xml file's encoding. Default is ISO-8859-1. See http://www.iana.org/assignments/character-sets for a list. If you don't define the correct encoding for xml, you can get "not well-formed" errors from the xml parsers. This value is also used in the meta tag section of the html file.

-drives

Only required for the html format. If set to off, you will not see the drive information in the resulting html file. Default is on. Also see -parse_path option in new.

-overwrite

If the file to export exists on the disk and you didn't set this parameter to a true value, export will die with an error.

If you set this parameter to a true value, the named file will be overwritten if already exists. Use carefully.

Has no effect if you use -toscalar option.

-toscalar

With the default configuration, export method will dump the exported data to a disk file, but you can alter this behaviour if you pass this parameter with a reference to a scalar.

   $parser->export(-toscalar => \$dumpvar);
   # then do something with $dumpvar

Returns the object itself.

reset

Resets the parser object and returns the object itself. Can be usefull when exporting to html.

   $parser->parse($fh       )->export->reset;
   $parser->parse(\$scalar  )->export->reset;
   $parser->parse("file.m3u")->export->reset;

Will create individual files while this code

   $parser->parse($fh       )->export;
   $parser->parse(\$scalar  )->export;
   $parser->parse("file.m3u")->export;

creates also individual files but, file2 content will include $fh + $scalar data and file3 will include $fh + $scalar + file.m3u data.

Subclassing

You may want to subclass the module to implement a more advanced search or to change the HTML template.

To override the default search method create a _search method in your class and to override the default template create a _template method in your class.

See the tests in the distribution for examples.

Error handling

Note that, if there is an error, the module will die with that error. So, using eval for all method calls can be helpful if you don't want to die:

   eval {$parser->parse(@list)}
   die "Parser error: $@" if $@;

As you can see, if there is an error, you can catch this with eval and access the error message with the special Perl variable $@.

EXAMPLES

See the tests in the distribution for example codes. If you don't have the distro, you can download it from CPAN.

TIPS

WinAmp

(For v2.80. I don't use Winamp v3 series.) If you don't see any EXTINF lines in your saved M3U lists, open preferences, go to "Options", set "Read titles on" to "Display", add songs to your playlist and scroll down/up in the playlist window until you see all songs' time infos. If you don't do this, you'll get only the file names or only the time infos for the songs you have played. Because, to get the time info, winamp must read/scan the file first.

Naming M3U Files

Give your M3U files unique names and put them into the same directory. This way, you can have an easy maintained archive.

CAVEATS

v2 is not compatible with v1x. v2 of this module breaks old code. See the Changes file for details.

BUGS

• HTML and XML escaping is limited to these characters: & " < >.

Contact the author if you find any other bugs.

SEE ALSO

MP3::M3U.

AUTHOR

Burak Gürsoy, <burak@cpan.org>

COPYRIGHT

Copyright 2003-2006 Burak Gürsoy. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm MP3::M3U::Parser

perl -MCPAN -e shell
install MP3::M3U::Parser