NAME
   Audio::Ofa::Util - Retrieve audio fingerprints and metadata for unknown
   audio files

SYNOPSIS
   This module tries to make retrieving audio fingerprints and metadata for
   unknown audio files as easy as possible. It interfaces with the modules
   Audio::Ofa and WebService::MusicBrainz, provides a simple LWP based
   interface to the MusicDNS library, and can make use of
   Audio::Extract::PCM to read some popular music formats.

   The most comprehensive way to use this is to start with a (possibly
   untagged) file name and get full metadata:

       my $util = Audio::Ofa::Util->new(filename => 'song.ogg');
       my @tracks = $util->musicbrainz_lookup or die $util->error;
       for (@tracks) {
           print 'Artist: ', $_->artist, "\n";
           print 'Title:  ', $_->title, "\n";
           print 'Track:  ', $_->track, "\n";
           print 'Album:  ', $_->album, "\n\n";
       }

   To create an audio fingerprint:

       my $util = Audio::Ofa::Util->new(filename => 'song.ogg');
       $util->analyze_file or die $util->error;
       print $util->fingerprint, "\n";

   To create a fingerprint and look it up at MusicDNS:

       my $util = Audio::Ofa::Util->new(filename => 'song.ogg');
       $util->musicdns_lookup or die $util->error; # calls analyze_file implicitly
       print $util->artist, ' - ', $util->title, "\n";

   To look up a known fingerprint at MusicDNS (you need the length of the
   song, too):

       my $util = Audio::Ofa::Util->new(fingerprint => $fp, duration => $millisecs);

   The overall process goes like this:

   *       We create an audio fingerprint, which stores some
           characteristics of a recording in a rather small amount of data.
           This is what libofa (and the Perl binding in Audio::Ofa) does.
           This module (Audio::Ofa::Util) faciliates this with
           "analyze_file" by allowing to fingerprint some widely used music
           formats and storing the results so they can be used for the next
           steps:

   *       The audio fingerprint is submitted to the MusicDNS web service.
           Using a proprietary fuzzy algorithm and their database, they
           determine which song we have at hand. MusicDNS returns some
           metadeta: The artist, the song title, and a PUID. This "portable
           unique identifier" is an arbitrary index into their database and
           is unique for every recording of a given song.

           Note that while libofa's audio fingerprints may change after
           transformations of a recording (such as lossy audio compression
           or radio transmission), the fuzzy algorithm will (ideally) still
           find the same PUID.

   *       Because we usually want to know more than the artist and title,
           we look up the PUID in a second Web Database called MusicBrainz.
           It provides us with all desired metadata such as all the albums
           the song has appeared on in this particular version, and the
           respective track numbers.

           This module provides a basic MusicBrainz PUID lookup through
           "musicbrainz_lookup". If you want to know even more (such as
           members of the band and the previous bands of those members),
           you can use WebService::MusicBrainz, to which this module
           provides an easy frontend.

ACCESSORS
 filename
   See "analyze_file".

 fingerprint, duration
   See "analyze_file" and "musicdns_lookup".

 client_id, client_version, metadata, bitrate, extension, artist, title,
album, track, genre, year, puids
   See "musicdns_lookup".

   Note that puids accesses an array reference. If it is not defined or not
   set, it means that no PUID has been looked up yet. If it is an empty
   array, it means that no PUIDs were found.

 error
   Description of the last error that happened.

METHODS
 new
   Constructor. Accepts key-value pairs as initializers for all of the
   fields, c.f. "ACCESSORS", but currently only the following calls make
   sense:

       Audio::Ofa::Util->new(filename => $filename);
       Audio::Ofa::Util->new(fingerprint => $fp, duration => $dur);
       Audio::Ofa::Util->new(puid => $puid);

 analyze_file
   This creates an Audio Fingerprint of a sound file. The audio file is
   read using Audio::Extract::PCM, which currently uses the extarnal "sox"
   program and supports encodings such as MP3, Ogg/Vorbis and many others.

   You must set "filename" before calling this method.

   The fingerprint is calculated by "ofa_create_print" in Audio::Ofa, and
   the "fingerprint" field of the object will be set. Additionally, the
   "duration" (in milliseconds) and the "extension" will be set to the
   values provided by the file name.

   In case of an error, an empty list is returned and the error message can
   be retrieved via "error". Otherwise, a true value will be returned.

 musicdns_lookup
   This looks up a track at the MusicDNS web service.

   To do a fingerprint lookup, the keys "fingerprint" and "duration" must
   be present, where duration is the length of the song in milli seconds.
   Additionally, the following fields (defaults in parentheses) will be
   sent to the MusicDNS service:

   client_id (hardcoded client id), client_version (module name and
   version), fingerprint, metadata (1), bitrate (0), extension ("unknown"),
   duration, artist ("unknown"), title ("unknown"), album ("unknown"),
   track (0), genre ("unknown"), year (0).

   To do a fingerprint lookup, "fingerprint" and "duration" must have been
   set (can be given to "new"), where "duration" is the song length in
   milli seconds.

   If "fingerprint" hasn't been set, "analyze_file" is called implicitly.

   client_id defaults to a hard-coded Client ID. You can get your own from
   http://www.musicip.com.

   You should set as much of the above-mentioned metadata (like artist,
   etc.) as you have available, because the MusicDNS terms of service
   require this in order to help clean errors in their database.

   In the case of an error, "musicdns_lookup" returns an empty list and the
   error message can be retrieved with the "error" method.

   In the case of success, "musicdns_lookup" sets the fields "puids" to the
   found PUIDs, and sets the fields "artist" and "title" to the first of
   the found values, and returns a true value. In list context, it returns
   a list of objects which have "artist", "title" and "puid" methods.

 musicbrainz_lookup
   This looks up a PUID at MusicBrainz. The PUID can come from a call to
   "musicdns_lookup". In fact this is implicitly done if there is no PUID
   stored in the object (cf. "SYNOPSIS").

   This returns a list of WebService::MusicBrainz::Response::Track objects
   on success, or the first of them in scalar context. Otherwise it returns
   an empty list and the error message can be retrieved via the "error"
   method.

   This method returns a list of tracks or the first track in scalar
   context. The tracks are represented as objects that are guaranteed to
   have the methods "artist", "title", "album", "track" and "wsres", where
   the latter is an WebService::MusicBrainz::Response::Track object, and
   the four former return values that have been retrieved from that object
   for your convenience.

   In the case of an error, an empty list is returned and the error can be
   returned via the "error" method.

SEE ALSO
   *       MusicBrainz::Client - A client for the old MusicBrainz web
           service

   *       MusicBrainz::TRM - Obsolete TRM-based audio fingerprinting
           library

   *       tunepimp - C library which does pretty much everything that this
           module does. It even includes Perl bindings, but as of this
           writing, they don't compile in the current tunepimp version and
           only support the old TRM fingerprints.

   *       <http://www.musicdns.org> - Web site of the MusicDNS web service
           as provided by MusicIP

   *       <http://www.musicbrainz.org> - Web site of MusicBrainz

   *       <http://wiki.musicbrainz.org/HowPUIDsWork> - How PUIDs work

LICENSE
   This module is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License (GPL) as published by
   the Free Software Foundation (http://www.fsf.org/); either version 2 of
   the License, or (at your option) any later version.

   The GPL, which is quite restrictive (when compared to LGPL or Artistic),
   seems to be necessary because of libofa's licenses, but IANAL and if you
   need a license change please contact me.

   Please note that in addition to the license which allows you to use this
   software, the MusicDNS web service has its own terms of service. The
   most important fact is that you can use it for free unless you use it
   commercially. See <http://www.musicdns.org> for more information. You
   are encouraged to register your own client id (for free) if you build a
   client on top of this module.

AUTHOR
   Christoph Bussenius (pepe at cpan.org)

   Please mention the module's name in the subject of your mails so that
   they will not be lost in the spam.

   If you find this module useful I'll be glad if you drop me a note.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.