Introduction

The TunePimp library serves as a tool to allow developers to create MusicBrainz enabled tagging applications.

The TunePimp library is a full featured tagging library that allows the developer to open music files for identification/lookup. Once files have been identified, it writes new metadata tags to the music files and writes the files to a standardized directory hierarchy. TunePimp includes the following features:

• Create TRM IDs from WAV, MP3, Ogg/Vorbis and FLAC files
• Automatically lookup files by TRM or by metadata
• Read and write metadata from the music files
• Optionally rename files according to a user specified file mask
• Optionally move files to a user specified directory hierarchy

The TunePimp library source distribution comes with two example programs:

• examples/tp_tagger.c: This command line application is a full fledged tagging application that shows how to use the TunePimp library to create a tagging application. If you are considering using the TunePimp library in your application, please make sure to read through the source code of this example application. The documentation in this page is fairly brief and the tp_tagger source code is a great illustration on how to use the TunePimp library.
• perl/tunepimp-perl/examples/tp_tagger.pl: This example implements the tp_tagger using the perl bindings.
• examples/trm.c: This example shows how to use TunePimp to calculate TRM IDs for music files from the command line.
• python/examples/trm.py: The same application, but it uses the python bindings to create TRM IDs.

If you prefer to read code than documentation in order to learn this client library, please check out these code samples.

The client library is released under the GPL. If you wish to use tunepimp in an LGPL project, you will need to use the --enable--lgpl configure flag when building tunepimp. This will disable the mp3 plugin, which contains GPL code that cannot be used in LGPL mode.

Interface Reference

For details on the individual functions mentioned in this page, please refer to the following pages:

version 0.4.0:

• Online Reference
• Function Reference

version 0.3.0:

• Online Reference
• Function Reference

Please note that we do no have seperate documentation sections for the perl and python bindings. We have made every effort to keep perl and python bindings functioning in a similar manner to the original C bindings. If you would like to contribute seperate documentation for these bindings, please let us know!

Overview

Note: This documenation refers to version 0.4.0.

Note: This documenation refers to version 0.4.0. To start using the tunepimp, you need to create a tunepimp_t instance with tp_New() passing it the name and version of the application you are writing. Once you are finished with this object, call tp_Delete() to clean up this object. You will need to pass the tunepimp_t object as the first parameter to all functions with a tp_ prefix. If you need to specify an alternate location where the tunepimp plugins can be found, use tp_NewWithArgs to create the tunepimp object.

To start tagging files, add files with tp_AddFile() or add whole directories and their subdirectories with tp_AddDir(). After files have been added, the metadata read thread will read the metadata from the file and if the file contains MusicBrainz IDs, the file status will be set to eRecognized. If the file does not contain MusicBrainz Ids, it will be set to eUnrecognized. Unlike version 0.3.0 of tunepimp, in version 0.4.0 you need to manually set the status of the file to ePending in order to get tunepimp to generate a TRM id for the file. If the file status is set to ePending, the analyzer starts calculating the TRM acoustic fingerprint for the file. TunePimp will attempt to match the file to a file in MusicBrainz database. During this process, each of the files will be in one of the following states (status):

• eMetadataRead - This track is waiting for TunePimp to read the metadata from the file.
• ePending - This track is waiting for TunePimp to process it.
• eUnrecognized - TunePimp was not able to match this track.
• eRecognized - Tunepimp recognized this track.
• eTRMLookup - TunePimp is performing a TRM lookup on this track.
• eTRMCollision - TunePimp has detected a TRM collision for this track. The user must select which of the matching TRMs to use to finish the recognition process.
• eFileLookup - TunePimp is doing a metadata lookup on this file.
• eUserSelection - The MB server has returned more than one possible match for the track. The user must select a match to continue the lookup process.
• eVerified - The user has verified the matched track and TunePimp is getting ready to save the changes to disk.
• eSaved - The file was saved
• eDeleted - This track has been deleted from TunePimp, but its reference count has not reached zero yet.
• eError - An error occured during the lookup of this track.

To get notified of changes to a track, the TunePimp caller can either choose to install callback functions with tp_SetNotifyCallback and tp_SetStatusCallback, or decide to poll for changes with tp_GetNotification and tp_GetStatus. If you decide to use the callback methods, you need to ensure that your application is multithread safe and that the callbacks, which could be called at at any time, don't interfere with the rest of your application. If you are unfamiliar with multithreaded programming, choose the polling method for getting notifications and status messages.

When your application need to get detailed information about a track from TunePimp, it should call the tp_GetTrack() function to get a track_t object. With the track_t object you can call the tr_ functions to examine and/or change the data in a track. Given that TunePimp is heavily multithreaded, you must call tr_Lock() before you call any of the tr_Get* or tr_Set* functions. Once you are done examining/changing the track, call tr_Unlock(). Make sure that you keep the track locked as little as absolutely necessary, since having a track locked may stall TunePimp and prevent it from doing its job. Once you are done with a track, call tp_ReleaseTrack(). If you made any changes to a track, or changed the status of a track, call tp_Wake() to let TunePimp know that you changed the track.

If a track was wrongly identified, call tp_Misidentifed(), which will cause TunePimp to do a metadata only lookup on the track in hopes of finding the correct track. If you need to analyze a track again, call tp_IdentifyAgain() to start the process over. If the user has reviewed all of the tracks that have a status of eRecognized and would like to save them, call tp_WriteTracks().

During the tagging process TunePimp will automatically collect TRM IDs for each of the tracks that were matched (if you requested TRM calculations). If any of the TRM IDs need to be submitted to the MusicBrainz server, call tp_GetNumUnsubmitted(). If that returns a value greater than 0, you need to call tp_SubmitTRMs() to submit the TRMs to the server. Before your call can succeed, make sure to call tp_SetUserInfo() with the users MusicBrainz login information.

For tracks that end up with the eTRMCollision or eUserSelection status, you must present the lookup results returned from the server to the user. In order to retrieve the results, you must first get the track with tp_GetTrack(), and then call tr_GetResults(). Release the track with tp_ReleaseTrack() and then present the results to the user. Once you are done with the results, call rs_Delete() to delete the results returned from tr_GetResults(). When the user has chosen a set of results and wishes to continue the lookup process for this track, call tp_SelectResult().

There are a great number of tp_Set* and tp_Get* functions to influence the behaviour of TunePimp. Most of these functions are self explanatory, but the tp_SetFileMask() and tp_SetVariousFileMask() functions deserve a mention. These two function define the filename convention used by TunePimp to write the finished files to disk. The first call defines the file mask for normal tracks and the second call defines how tracks that are part of various artist albums get written to disk. The idea is that the file mask is a string of characters that will be used as a template for creating filenames. None of the portions of the file mask will be changed -- only the variables that start with % will be replaced by the metadata looked up from the MusicBrainz server.

The following variables are available for use in the filemasks:

• %artist -- Name of the artist
• %abc -- The first character of the artist's sortname (album name in case of a Various Artist album)
• %abc2 -- The first two character of the artist's sortname (album name in case of a Various Artist album)
• %abc3 -- The first three character of the artist's sortname (album name in case of a Various Artist album)
• %sortname -- Sortname of the artist
• %track -- Title of the song
• %album -- Title of the album
• %num -- Track number on the album
• %0num -- Track number on the album, zero padded to two places
• %format -- The format of the given file e.g. ogg/mp3/wav/flac/ape
• %type -- The release type: single, album, remix, etc
• %status -- The release status: official, bootleg, promo
• %year -- The first release year
• %month -- The first release month
• %day -- The first release day
• %country -- The first release country

So, given this filemask:

%abc2/%sortname/%album/%artist-%album-%0num-%track

a track from The Beatles might be saved to:

Be/Beatles, The/Revolver/The Beatles-Revolver-01-Taxman

Finally a caveat about using TunePimp on Windows. Due to the screwy nature of DLLs you cannot ever free() or delete a piece of memory that was allocated in a DLL. Doing so will cause erratic behaviour in your application and will lead to random crashes. The only time this becomes an issue is if you are setting data into a track using the tr_SetLocalMetadata() or the tr_SetServerMetadata() function. In either case make sure that you never deallocate any data returned from these functions. Therefore, you should not use any of the md_ metadata functions in windows -- if you need to allocate and free your own metadata_t structures, write your own routines to do so.

If you have any questions about the TunePimp library or you are running into trouble using the library, please join the musicbrainz-devel mailing list and post your questions there.

Good luck!