tunepimp

NAME

MusicBrainz::Tunepimp::tunepimp - Perl binding for the tunepimp library

SYNOPSIS

        use MusicBrainz::Tunepimp::tunepimp;
        my $tp = MusicBrainz::Tunepimp::tunepimp->new("My App", "1.0");

ABSTRACT

  MusicBrainz (musicbrainz.org) is a free, community music metadatabase.
  The MusicBrainz Tunepimp library enables applications to fingerprint,
  identify, tag, and rename audio files based on the corresponding MusicBrainz
  data.  See http://www.musicbrainz.org/tagger/index.html for more
  information.

DESCRIPTION

First, please read the Tunepimp documentation.

This module is built on the C wrapper interface to Tunepimp; all of the functions such as "tp_GetStatus" have been transformed into Perl methods by removing the ``tp_'' (or ``tr_'', or ``md_'' etc) prefix, placing the method into the appropriate Perl class, and changing the first character of the method name to lower case (except for ``TRM...'' which remains in upper case). Hence, if you understand the Tunepimp documentation and know about "tr_GetFileName", you'll know it's now in the ``track'' class and is called "getFileName".

Hence here I'll just describe how this Perl module differs from the C wrapper interface.

MusicBrainz::Tunepimp::tunepimp

This class corresponds to a "tunepimp_t" object.

new

This method blesses the returned object into any appropriate subclass. In other words, you can subclass this module.

as_hashref

Additional convenience method: retrieve all the fields of this object into a hash (good for debugging).

getVersion

As a Perl nicety, in scalar context, the version is returned in dotted form (e.g. ``0.2.1'')

getTrack

Tracks ("track_t") are blessed into the class given by "$tunepimp->track_class". Hence, if you want to subclass track objects, you should first subclass "MusicBrainz::Tunepimp::tunepimp", and override "track_class" to return the name of your track class.

track_class

This method returns the class into which tracks (returned by "getTrack" and "getTracks") should be blessed.

getTracks

Additional convenience method: retrieve all tracks.

writeTags

The C function ("tp_WriteTags") accepts a list of integers (file IDs) via an "int *" and an "int" argument; we just accept a Perl list of integers.

addFiles

Additional convenience method: multiple calls to addFile. e.g. "$tp->addFiles(glob("*.mp3"))"

getRecognizedFileList

This method returns the number of recognized files below the given threshold, and a reference to the list of recognized file IDs. The threshold is given as an integer percentage, e.g. ``30'' for 30%. For example:

        ($num_below_threshold, $recognized)
                = $tp->getRecognizedFileList($threshold);

        printf "%d of %d recognized files are below %d%% similarity\n",
                $num_below_threshold, scalar(@$recognized),
                $threshold;

        print "The IDs of the recognized files are @$recognized\n";

getServer, getProxy

Perl nicety: in scalar context, return the host name and port number joined by a colon. If they have not been set, return the empty list (or "undef").

getUserInfo

Perl nicety: in scalar context, return only the user name, instead of only the password.

Combined get / set methods

Additional methods. As a Perl nicety, we provide combined get / set methods for various things. e.g.

        # This calls $tunepimp->getDestDir
        $dir = $tunepimp->destDir;

        # This calls both getDestDir and setDestDir; it
        # both sets a new value and returns the old one.
        $olddir = $tunepimp->destDir($newdir);

Any pair of get / set methods are implemented as a combined method here. The name of the combined method is that of the get / set, with ``Get'' or ``Set'' removed, and the first character then changed to lower case (except for ``TRM...'').

All the getters and setters handle a single value at a time, except for ``proxy'', ``server'' and ``userInfo'', which all deal with a pair of values.

MusicBrainz::Tunepimp::track

This class corresponds to a "track_t" object. You should never need to use the name of this class unless you're planning to subclass it (or one of the other Tunepimp classes).

as_hashref

Additional convenience method: retrieve all the fields of this object into a hash (good for debugging).

getLocalMetadata, getServerMetadata

For convenience, if no metadata argument is supplied, make a new one and return that. The class used to construct a new "metadata_t" object is given by "$track->metadata_class".

metadata_class

This method returns the class into which automatically created metadata objects (returned by "getLocalMetadata" and "getServerMetadata") should be blessed.

getResults

This method returns the type of results (see ":TPResultType") and a reference to the list of results. For example:

        ($type, $results) = $track->getResults;

        for my $result (@$results)
        {
                ...;
        }

Each element of $results is a plain hash reference containing the relevant fields. Some of the fields may themselves be hash references, e.g. for a "eTrackList" result you can do $$result{album}{artist}{name}.

MusicBrainz::Tunepimp::metadata

This class corresponds to a "metadata_t" object. You should never need to use the name of this class unless you're planning to subclass it (or one of the other Tunepimp classes).

new

This method blesses its return value into the appropriate subclass.

member access

In the C interface the caller is expected to just read and write the member fields directly. (Side note: that means they're expected to know to deal with "malloc()" and "free()" too. This is probably a bad idea).

For the Perl interface however we'll provide separate ``get'' and ``set'' methods, then add combined get/set methods over the top of those.

as_hashref

Additional convenience method: retrieve all the fields of this object into a hash (good for debugging, and maybe in real life use).

getAlbumTypeNameFromNumber, getAlbumStatusNameFromNumber

Minor convenience: this can be called either as a class or an object method, with an optional numeric argument. The number defaults to that retrieved from $self if we were called as an object method.

In other words, these all work:

        # Uses $number
        $name = MusicBrainz::Tunepimp::metadata->getAlbumTypeNameFromNumber($number);

        # Uses $metadata->getAlbumType
        $name = $metadata->getAlbumTypeNameFromNumber;

        # Uses $number
        $name = $metadata->getAlbumTypeNameFromNumber($number);

The same applies to "getAlbumStatusNameFromNumber" / "getAlbumStatus".

EXPORT TAGS

The only things which may be exported are the "enum" values from tunepimp/defs.h.

:TPError: tpOk, tpTooManyTRMs, tpNoUserInfo etc
These correspond to the value returned by "$tunepimp->getError" or "$track->getError".
:TPCallbackEnum: tpFileAdded, tpFileChanged, tpFileRemoved.
These are the values returned by the ``status'' callback (see getStatus, setStatusCallback, getStatusCallback).
:TPFileStatus: eUnrecognized, eRecognized, ePending etc
These correspond to the value returned by "$track->getStatus".
:TPResultType: eNone, eArtistList, eAlbumList etc.
These correspond to the ``type'' value returned by "$track->getResults".
:TPAlbumType
:TPAlbumStatus: These correspond to the values returned by "$metadata->getAlbumType" and "$metadata->getAlbumStatus".

Use the export tag ``:all'' to export everything.

Nothing is exported by default.

BUGS

At the time of writing, there is no Tunepimp documentation yet - just the source code.

The following methods are out of bounds: "setStatusCallback", "getStatusCallback", "setNotifyCallback", "getNotifyCallback". Don't use them. They don't work. They probably never will. Instead, please use only the ``polling'' version to retrieve callback information, like so:

        while (my ($type, $fileid) = $tunepimp->getNotification)
        {
                ...;
        }

        while (defined (my $status = $tunepimp->getStatus))
        {
                ...;
        }

AUTHOR

Dave Evans, <djce@musicbrainz.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

tunepimp

NAME

SYNOPSIS

ABSTRACT

DESCRIPTION

MusicBrainz::Tunepimp::tunepimp

MusicBrainz::Tunepimp::track

MusicBrainz::Tunepimp::metadata

EXPORT TAGS

SEE ALSO

BUGS

AUTHOR

COPYRIGHT AND LICENSE

Index