#include "defs.h"
Go to the source code of this file.
#define TP_ALBUM_NAME_LEN 255 |
#define TP_ARTIST_NAME_LEN 255 |
This structure holds the meta data of a track.
The meanings of most attributes are pretty straight forward, but a few need additional explanations. Strings like artist, sortName, album etc. are never NULL. If the information isn't available, the attribute is set to the empty string ("").
The duration attribute is in milliseconds. fileFormat is one of the supported file formats (see tp_GetSupportedExtensions()) but without the dot ("mp3", "ogg", "wav" etc.). If there was a TRM collision, numTRMIds is set to a value greater than one. If variousArtist is true, the track is from a various artists release. If nonAlbum is true, the track resides within a special non-album tracklisting.
The memory containing the meta data will be released when calling md_Clear() or md_Delete(), so you have to copy the data if you want to use it.
#define TP_COUNTRY_LEN 3 |
#define TP_EXTENSION_LEN 32 |
This function returns a list of supported audio formats. The elements of the list are the usual filename extensions like ".wav", ".mp3", ".ogg" etc.
The buffer you pass to the function has to be big enough to hold the list. You can use tp_GetNumSupportedExtensions() to get the number of supported extensions.
o | the tunepimp_t object returned from tp_New() | |
extensions | a user supplied buffer for the list of filename extensions |
#define TP_FORMAT_LEN 32 |
#define TP_ID_LEN 40 |
#define TP_TRACK_NAME_LEN 255 |
typedef struct _albumresult_t albumresult_t |
This structure contains information about an album.
As in artistresult_t, a higher relevance value indicates a better match. The artist attribute points to an artistresult_t structure.
typedef struct _albumtrackresult_t albumtrackresult_t |
This structure represents a matched track.
A higher relevance value indicates a better match. Information about the track's artist and the album can be found in the artist and album attributes.
typedef struct _artistresult_t artistresult_t |
This structure contains information about an artist.
The relevance attribute is an indication for the quality of the match. The higher the better.
typedef struct _metadata_t metadata_t |
typedef void* result_t |
The abstraction of a TPResult object. Such objects are returned by tr_GetResults(), but there are no functions that operate on them. You have to cast them to albumresult_t, artistresult_t or albumtrackresult_t, depending on the type of the result (which is also returned by tr_GetResults()).
typedef void(*) tp_notify_callback(tunepimp_t pimp, void *data, TPCallbackEnum type, int fileId, TPFileStatus status) |
This is the signature definition of a function suitable as a notification callback. The data argument is the pointer that the user gave when registering the function using tp_SetNotifyCallback().
pimp | the tunepimp object that invoked the callback function | |
data | a pointer to user data set when registering the callback | |
type | the type of this notification | |
fileId | the Id of the file concerned |
typedef void(*) tp_status_callback(tunepimp_t pimp, void *data, const char *status) |
This is the signature definition of a function suitable as a status callback. The data argument is the pointer that the user gave when registering the function using tp_SetStatusCallback().
pimp | the tunepimp object that invoked the callback function | |
data | a pointer to user data set when registering the callback | |
status | a pointer to a text message |
typedef void* track_t |
The abstraction of a Track object. Functions to manipulate have a prefix of "tr_".
typedef void* tunepimp_t |
tunepimp_t is the basic C abstraction for a TunePimp Object. It is completely transparent for the user. Don't try to manipulate it manually, use one of the functions starting with "tp_".
void md_Clear | ( | metadata_t * | mdata | ) |
Clears a metadata_t object.
All values of the object are set to NULL values. After that the object is in the same state as directly after md_New().
mdata | a valid metadata_t object |
int md_Compare | ( | const metadata_t * | mdataA, | |
const metadata_t * | mdataB | |||
) |
Compare two metadata_t objects and return a similarity value between 0.0 and 1.0, where zero is totally dissimilar and 1.0 is exactly the same.
mdataA | a valid metadata_t object | |
mdataB | a valid metadata_t object |
void md_ConvertFromAlbumStatus | ( | TPAlbumStatus | status, | |
char * | albumStatus, | |||
int | maxLen | |||
) |
Convert the status of an album to its textual representation. The function stores the status string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
status | an album status | |
albumStatus | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
void md_ConvertFromAlbumType | ( | TPAlbumType | type, | |
char * | albumType, | |||
int | maxLen | |||
) |
Convert the type of an album to its textual representation. The function stores the type string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
type | an album type | |
albumType | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
TPAlbumStatus md_ConvertToAlbumStatus | ( | const char * | albumStatus | ) |
Converts a string to TPAlbumStatus. The string's value has to be one of "official", "promotion" or "bootleg". Case doesn't matter.
albumStatus | the string to convert |
TPAlbumType md_ConvertToAlbumType | ( | const char * | albumType | ) |
Converts a string to TPAlbumType. The string's value has to be one of "album", "single", "compilation", "soundtrack", "spokenword", "audiobook", "live" or "other". Case doesn't matter.
albumType | the string to convert |
void md_Delete | ( | metadata_t * | mdata | ) |
metadata_t* md_New | ( | void | ) |
Create a new metadata_t object.
Don't forget to release it using md_Delete() when you don't need it any longer.
float md_Similarity | ( | const char * | a, | |
const char * | b | |||
) |
Does a fuzzy string comparison and returns the similarity value between 0.0 and 1.0
a | the first string | |
b | the second string |
void rs_Delete | ( | TPResultType | type, | |
result_t * | result, | |||
int | numResults | |||
) |
Releases the memory for a result list allocated by tr_GetResults()
type | the type of the result | |
result | the result pointer returned by tr_GetResults() | |
numResults | the number of results |
int tp_AddDir | ( | tunepimp_t | o, | |
const char * | dirPath | |||
) |
This function descends recursively into the specified directory and adds all files to the list that look like they contain music, judging by comparing file extensions. You can get a list of supported file formats using tp_GetSupportedExtensions().
o | the tunepimp_t object returned from tp_New | |
dirPath | a string containing a path |
int tp_AddFile | ( | tunepimp_t | o, | |
const char * | fileName, | |||
int | readMetadataNow | |||
) |
Add a file to the list. The fileId of the added file is returned which is a handle that is valid until the file is removed using tp_Remove() or TunePimp writes new metadata tags and automatically removes the file. Adding a file that is already in the list is a no-op. Initially, the status of a file is ePending.
For each file added, your registered notification callback is invoked. Its parameters are tpFileAdded and the fileId returned by tp_Add().
Please note that tp_AddFile() always succeeds, no matter if the file isn't a recognized audio file, if it isn't readable or doesn't exist at all. However, you can always query the track's status to see if there was an error.
o | the tunepimp_t object returned from tp_New | |
fileName | a string containing a filename | |
readMetadataNow | read the file metadata before returning |
void tp_AddTRMSubmission | ( | tunepimp_t | o, | |
const char * | trackId, | |||
const char * | trmId | |||
) |
Add a (trackId, TRM) pair to the list of unsubmitted TRMs. You have to call tp_SubmitTRMs() to actually send it to the server.
o | the tunepimp_t object returned from tp_New() | |
trackId | a musicbrainz track Id | |
trmId | a TRM Id in its ASCII representation |
void tp_Delete | ( | tunepimp_t | o | ) |
The destructor for the TunePimp class.
o | the handle for the tunepimp_t object to delete |
void tp_DeleteRecognizedFileList | ( | tunepimp_t | o, | |
int * | fileIds | |||
) |
Release the memory allocated by tp_GetRecognizedFileList(). You can use this function even if there were no fileIds returned.
o | the tunepimp_t object returned from tp_New() | |
fileIds | the array returned by tp_GetRecognizedFileList() |
void tp_GetAllowedFileCharacters | ( | tunepimp_t | o, | |
char * | allowedFileCharacters, | |||
int | maxLen | |||
) |
Use this function to get a string containing the characters allowed in a file name. This function stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
If all characters are allowed, the empty string ("") is returned.
o | the tunepimp_t object returned from tp_New() | |
allowedFileCharacters | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
TPThreadPriorityEnum tp_GetAnalyzerPriority | ( | tunepimp_t | o | ) |
This function gets the analyzer thread priority level.
o | the tunepimp_t object returned from tp_New() |
int tp_GetAutoFileLookup | ( | tunepimp_t | o | ) |
Query the status of the AutoFileLookup feature. See tp_SetAutoFileLookup() for further information.
o | the tunepimp_t object returned from tp_New() |
int tp_GetAutoRemovedSavedFiles | ( | tunepimp_t | o | ) |
Use this function to determine if the tunepimp library automatically deletes files after they've been saved or if it moves them to the eSaved status.
o | the tunepimp_t object returned from tp_New() |
int tp_GetAutoSaveThreshold | ( | tunepimp_t | o | ) |
Get the autosave threshold if autosave is enabled or a negative value if the feature is disabled. See tp_SetAutoSaveThreshold() for an explanation of the autosave feature.
o | the tunepimp_t object returned from tp_New() |
int tp_GetClearTags | ( | tunepimp_t | o | ) |
Query the tunepimp object if tag clearing is enabled. See tp_SetClearTags() for more information.
o | the tunepimp_t object returned from tp_New() |
int tp_GetDebug | ( | tunepimp_t | o | ) |
Check if debugging is enabled.
o | the tunepimp_t object returned from tp_New |
void tp_GetDestDir | ( | tunepimp_t | o, | |
char * | destDir, | |||
int | maxLen | |||
) |
Use this function to get a string containing the destination directory. tp_GetDestDir() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
o | the tunepimp_t object returned from tp_New() | |
destDir | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
void tp_GetError | ( | tunepimp_t | o, | |
char * | error, | |||
int | maxLen | |||
) |
Use this function to get a printable error message for the last error that occured in the tunepimp object. tp_GetError() stores the error string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
o | the tunepimp_t object returned from tp_New() | |
error | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
void tp_GetFileIds | ( | tunepimp_t | o, | |
int * | ids, | |||
int | numIds | |||
) |
Returns the fileIds in tunepimp's list. At most numIds are returned.
Use tp_GetNumFileIds to get the number of fileIds in the list. Do not use tp_Add() or tp_AddDir() between calls to tp_GetNumFileIds() and tp_GetFileIds().
o | the tunepimp_t object returned from tp_New() | |
numIds | the number of fileIds the buffer can receive | |
ids | a poiner to the buffer that will receive the fileIds |
void tp_GetFileMask | ( | tunepimp_t | o, | |
char * | fileMask, | |||
int | maxLen | |||
) |
Use this function to get a string containing the file mask. tp_GetFileMask() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
o | the tunepimp_t object returned from tp_New() | |
fileMask | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
void tp_GetFileNameEncoding | ( | tunepimp_t | o, | |
char * | encoding, | |||
int | maxEncodingLen | |||
) |
o | the tunepimp_t object returned from tp_New() | |
encoding | the encoding to use. | |
maxEncodingLen | length of the encoding string |
TPID3Encoding tp_GetID3Encoding | ( | tunepimp_t | o | ) |
Check which encoding is set for writing ID3v2 tags.
o | the tunepimp_t object returned from tp_New() |
int tp_GetMaxFileNameLen | ( | tunepimp_t | o | ) |
Use this function to get the current maximum filename length
o | the tunepimp_t object returned from tp_New() |
int tp_GetMinTRMThreshold | ( | tunepimp_t | o | ) |
Get the minimum TRM match threshold. The returned value is between 0 and 100. See tp_SetMinTRMThreshold() for a discussion.
o | the tunepimp_t object returned from tp_New() |
int tp_GetMoveFiles | ( | tunepimp_t | o | ) |
Check if file moving is enabled. See tp_SetMoveFiles() for more information.
o | the tunepimp_t object returned from tp_New() |
void tp_GetNonAlbumFileMask | ( | tunepimp_t | o, | |
char * | nonAlbumFileMask, | |||
int | maxLen | |||
) |
Use this function to get a string containing the various artists file mask. tp_GetVariousFileMask() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
o | the tunepimp_t object returned from tp_New() | |
nonAlbumFileMask | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
int tp_GetNotification | ( | tunepimp_t | o, | |
TPCallbackEnum * | type, | |||
int * | fileId, | |||
TPFileStatus * | status | |||
) |
Get a notification message from tunepimp's queue. All messages are stored in a queue (FIFO) to make sure you get them in the right order.
Please note that this function only returns notification messages if no notification callback was set.
o | the tunepimp_t object returned from tp_New() | |
type | the address of a variable to receive the notification type | |
fileId | the address of a variable to receive the fileId | |
status | the address of a variable to receive the current status |
tp_notify_callback tp_GetNotifyCallback | ( | tunepimp_t | o | ) |
Get the function registered to receive notification messages. See tp_SetNotifyCallback() for more information.
o | the tunepimp_t object returned from tp_New() |
int tp_GetNumFileIds | ( | tunepimp_t | o | ) |
Get the number of filesIds that a call to tp_GetFileIds() would return.
Do not use tp_Add() or tp_AddDir() between calls to tp_GetNumFileIds() and tp_GetFileIds(). They might increase the number of fileIds.
o | the tunepimp_t object returned from tp_New() |
int tp_GetNumFiles | ( | tunepimp_t | o | ) |
This function returns the number of files that tunepimp has in its list.
o | the tunepimp_t object returned from tp_New() |
int tp_GetNumSupportedExtensions | ( | tunepimp_t | o | ) |
Query the number of audio file formats supported by tunepimp. The number depends on which libraries were present when tunepimp was compiled.
o | the tunepimp_t object returned from tp_New() |
int tp_GetNumUnsavedItems | ( | tunepimp_t | o | ) |
This function returns the number of track that have been recognized and are ready to be saved.
o | the tunepimp_t object returned from tp_New() |
int tp_GetNumUnsubmitted | ( | tunepimp_t | o | ) |
This function returns the number of TRMs that haven't been submitted to the server yet.
o | the tunepimp_t object returned from tp_New() |
void tp_GetProxy | ( | tunepimp_t | o, | |
char * | serverAddr, | |||
int | maxLen, | |||
short * | serverPort | |||
) |
Get the proxy settings. tp_GetProxy() stores the address in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
If no proxy was set, serverAddr is set to the empty string ("").
o | the tunepimp_t object returned from tp_New() | |
serverAddr | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer | |
serverPort | the address of a variable to receive the port |
int tp_GetRecognizedFileList | ( | tunepimp_t | o, | |
int | threshold, | |||
int ** | fileIds, | |||
int * | numIds | |||
) |
Get a list of recognized files (eRecognized) that have a similarity value of less than threshold. If such files were found, the function allocates an array of ints and returns it using the fileIds argument. The number of entries in the array can be found in the numIds argument.
Don't forget to free the allocated memory using tp_DeleteRecognizedFileList().
o | the tunepimp_t object returned from tp_New() | |
threshold | a threshold (between 0 and 100) | |
fileIds | the address of an int pointer | |
numIds | the address of a variable to receive the number of IDs returned |
int tp_GetRenameFiles | ( | tunepimp_t | o | ) |
Query the tunepimp object if file renaming is enabled. See tp_SetRenameFiles() for an explanation.
o | the tunepimp_t object returned from tp_New() |
void tp_GetServer | ( | tunepimp_t | o, | |
char * | serverAddr, | |||
int | maxLen, | |||
short * | serverPort | |||
) |
Get the server settings. tp_GetServer() stores the address in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
If no proxy was set, serverAddr is set to the empty string ("").
o | the tunepimp_t object returned from tp_New() | |
serverAddr | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer | |
serverPort | the address of a variable to receive the port |
int tp_GetStatus | ( | tunepimp_t | o, | |
char * | status, | |||
int | statusLen | |||
) |
Get a status message from tunepimp's queue. All messages are stored in a queue (FIFO) to make sure you get them in the right order.
Please note that this function only returns status messages if no status callback was set.
o | the tunepimp_t object returned from tp_New() | |
status | a user supplied buffer of statusLen characters | |
statusLen | the size of the buffer |
tp_status_callback tp_GetStatusCallback | ( | tunepimp_t | o | ) |
Get the function registered to receive status messages. See tp_SetStatusCallback() for more information.
o | the tunepimp_t object returned from tp_New() |
void tp_GetSupportedExtensions | ( | tunepimp_t | o, | |
char | extensions[][TP_EXTENSION_LEN] | |||
) |
void tp_GetTopSrcDir | ( | tunepimp_t | o, | |
char * | topSrcDir, | |||
int | maxLen | |||
) |
Use this function to get the top source directory. See tp_SetTopSrcDir() for more information.
tp_GetTopSrcDir() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
o | the tunepimp_t object returned from tp_New() | |
topSrcDir | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
track_t tp_GetTrack | ( | tunepimp_t | o, | |
int | fileId | |||
) |
Get a handle for a track object. Don't forget to release the track using tp_ReleaseTrack() when you don't need it any longer. YOU MUST CALL tr_Lock() BEFORE YOU MAKE ANY CHANGES TO THE TRACK. After your changes are complete, call tr_Unlock.
o | the tunepimp_t object returned from tp_New() | |
fileId | a fileId |
int tp_GetTrackCounts | ( | tunepimp_t | o, | |
int * | counts, | |||
int | maxCounts | |||
) |
This function returns the number of tracks in each of the TPFileStatus categories. For example, the count for the number of unrecognized files will be stored in: counts[(int)eUnrecognized]
o | the tunepimp_t object returned from tp_New() | |
counts | a pointer to an array of ints that will receive the counts | |
maxCounts | max number of counts that can be written to the counts array. |
int tp_GetTRMCollisionThreshold | ( | tunepimp_t | o | ) |
Get the TRM collision threshold. The returned value is between 0 and 100. See tp_SetTRMCollisionThreshold() for a discussion.
o | the tunepimp_t object returned from tp_New() |
void tp_GetUserInfo | ( | tunepimp_t | o, | |
char * | userName, | |||
int | maxUserNameLen, | |||
char * | password, | |||
int | maxPasswordLen | |||
) |
Get the user name and password. The data is stored in the user supplied buffers userName and password. Not more than maxUserNameLen and maxPasswordLen characters respectively including the trailing '\0' byte are copied into that buffer.
o | the tunepimp_t object returned from tp_New() | |
userName | a user supplied buffer of maxUserNameLen characters | |
maxUserNameLen | Len the size of the buffer for the user name | |
password | a user supplied buffer of maxPasswordLen characters | |
maxPasswordLen | the size of the buffer for the password |
void tp_GetVariousFileMask | ( | tunepimp_t | o, | |
char * | variousFileMask, | |||
int | maxLen | |||
) |
Use this function to get a string containing the various artists file mask. tp_GetVariousFileMask() stores the string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
o | the tunepimp_t object returned from tp_New() | |
variousFileMask | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
void tp_GetVersion | ( | tunepimp_t | o, | |
int * | major, | |||
int * | minor, | |||
int * | rev | |||
) |
Get the version number of this library.
o | the tunepimp_t object returned from tp_New | |
major | an int pointer that will receive the major number of the version | |
minor | an int pointer that will receive the minor number | |
rev | an int pointer that will receive the rev number |
int tp_GetWriteID3v1 | ( | tunepimp_t | o | ) |
Check if writing ID3v1 tags to MP3 files is enabled.
o | the tunepimp_t object returned from tp_New() |
int tp_GetWriteID3v2_3 | ( | tunepimp_t | o | ) |
Check if writing ID3v2_3 tags to MP3 files is enabled.
o | the tunepimp_t object returned from tp_New() |
void tp_IdentifyAgain | ( | tunepimp_t | o, | |
int | fileId | |||
) |
Mark a file as misidentified. The status is set back to eFileLookup which causes file lookup to be done on the file. Any MusicBrainz ids that have been downloaded for this file are ignored and a lookup from the metadata is done in order to find the right file on the MB server.
o | the tunepimp_t object returned from tp_New() | |
fileId | a fileId |
void tp_Misidentified | ( | tunepimp_t | o, | |
int | fileId | |||
) |
Discard all MusicBrainz idenitifiers and identify this file again. The status is set back to ePending which causes the whole identification process to start again, including TRM generation.
o | the tunepimp_t object returned from tp_New() | |
fileId | a fileId |
tunepimp_t tp_New | ( | const char * | appName, | |
const char * | appVersion | |||
) |
Create a new handle (a C abstraction) to the TunePimp object. Call tp_Delete() when done with the handle.
appName | the name of your application | |
appVersion | the version number of your application |
tunepimp_t tp_NewWithArgs | ( | const char * | appName, | |
const char * | appVersion, | |||
int | startThreads, | |||
const char * | pluginDir | |||
) |
Create a new handle (a C abstraction) to the TunePimp object, specifying which internal threads to start. Call tp_Delete() when done with the handle.
appName | the name of your application | |
appVersion | the version number of your application | |
startThreads | a bit flag that specifies which internal threads to start. Pass in one or more TP_THREAD_XXXX flags that are or'ed together. | |
pluginDir | the directory where tunepimp plugins can be found |
void tp_ReleaseTrack | ( | tunepimp_t | o, | |
track_t | track | |||
) |
Release the specified track object.
o | the tunepimp_t object returned from tp_New() | |
track | the track handle |
void tp_Remove | ( | tunepimp_t | o, | |
int | fileId | |||
) |
Remove a file entry from the list. fileId is the file's handle returned by tp_Add(). The file itself isn't removed from disk.
o | the tunepimp_t object returned from tp_New() | |
fileId | the Id of the file you want to remove. |
TPError tp_SelectResult | ( | tunepimp_t | o, | |
track_t | track, | |||
int | resultIndex | |||
) |
Select one of the results that were returned by tr_GetResults(). resultIndex is the index of an array element and thus starts at 0. The results MUST BE deleted using rs_Delete()
o | the tunepimp_t object returned from tp_New() | |
track | a track object obtained via tp_GetTrack() | |
resultIndex | the array index of the result to select |
void tp_SetAllowedFileCharacters | ( | tunepimp_t | o, | |
const char * | allowedFileCharacters | |||
) |
Use this function to set a white list of characters that are permitted in a filename.
If you set allowedFileCharacters to the empty string, all characters permitted by the underlying file system are regarded as allowed. All other characters are removed from filenames written by tunepimp. Please note, however, that the directory separator ("/" on Unix) is always permitted.
The default is the empty string ("").
o | the tunepimp_t object returned from tp_New() | |
allowedFileCharacters | the list of allowed characters |
void tp_SetAnalyzerPriority | ( | tunepimp_t | o, | |
TPThreadPriorityEnum | priority | |||
) |
This function sets the analyzer thread priority level.
o | the tunepimp_t object returned from tp_New() | |
priority | The priority to set the analyzer to. See include/defs.h for values for this parameter. |
void tp_SetAutoFileLookup | ( | tunepimp_t | o, | |
int | enable | |||
) |
Set enable to a non-zero value to activate AutoFileLookup. If set, tunepimp tries a file lookup (using data found in the file's tag) when the TRM of a track wasn't found in the musicbrainz database.
If enable is set to zero and no TRM is found in the database, the track's status is set to eUnrecognized. You can then manually set the state to eFileLookup using tr_SetState() to initiate a file lookup. A file lookup uses meta data found in the file to query the database.
For tracks that have matching TRMs in the database, AutoFileLookup has no effect.
Defaults to "enabled".
o | the tunepimp_t object returned from tp_New() | |
enable | a non-zero value enables automatic file lookup |
void tp_SetAutoRemovedSavedFiles | ( | tunepimp_t | o, | |
int | autoRemoveSavedFiles | |||
) |
Use this function to control if the tunepimp library automatically deletes files after they've been saved or if they should be moved to the eSaved status.
o | the tunepimp_t object returned from tp_New() | |
autoRemoveSavedFiles | automatically remove the files (true/false) |
void tp_SetAutoSaveThreshold | ( | tunepimp_t | o, | |
int | autoSaveThreshold | |||
) |
Use this function to set the auto save threshold.
When the similarity value (see tp_SetTRMCollision()) is greater or equal the auto save threshold, a recognized file (in state eRecognized) is marked as verified (eVerified). The effect is the same as calling tp_WriteTags() on a recognized file.
The writing is done immediately, without the possibility of user intervention.
Valid values for the threshold are between 0 and 100, including 0 and 100. Set it to a negative value to disable the auto save feature.
Default: 90.
o | the tunepimp_t object returned from tp_New() | |
autoSaveThreshold | the auto save threshold |
void tp_SetClearTags | ( | tunepimp_t | o, | |
int | clearTags | |||
) |
Use this function to enable/disable the clearning of metadata tags before the MusicBrainz data is written to the tag. If the metadata tags have crufty data in them and you want to clean them completely before writing new data to the tag, then enable this option.
Default: false
o | the tunepimp_t object returned from tp_New() | |
clearTags | set a non-zero value to enable tag clearing |
void tp_SetDebug | ( | tunepimp_t | o, | |
int | debug | |||
) |
Enable debugging output to stdout by sending a non-zero value to this function. Whenever the tunepimp library makes a server call, the data sent to the server and the data returned from the server is printed to stdout.
Default: disabled.
o | the tunepimp_t object returned from tp_New | |
debug | whether or not to enable debug (non-zero enables debug output) |
void tp_SetDestDir | ( | tunepimp_t | o, | |
const char * | destDir | |||
) |
This function sets a base directory that is prepended to all files written by tunepimp if the move feature is enabled. The base directory may be absolute or relative. No trailing directory separator ("/" or "\") is required.
Default: "MyMusic" in the current working directory.
o | the tunepimp_t object returned from tp_New() | |
destDir | a directory name |
void tp_SetFileMask | ( | tunepimp_t | o, | |
const char * | fileMask | |||
) |
Set the file mask. The file mask is a format string roughly similar to the one used in printf(3). Whenever a filename has to be created, the escape sequences embedded in the file mask are expanded with meta data from the musicbrainz database.
The following escape sequences are supported:
Please note that you have to use tp_SetVariousFileMask() to set the file mask for tracks from various artists releases.
The default file mask is "%artist/%album/%artist-%album-%0num-%track".
o | the tunepimp_t object returned from tp_New() | |
fileMask | a format string |
void tp_SetFileNameEncoding | ( | tunepimp_t | o, | |
const char * | encoding | |||
) |
Use this function to specify the encoding to be used for writing filenames to the filesystem. Defaults to UTF-8.
UTF-8 and ISO-8859-1 are supported by default and more encodings are supported by ICU is ICU is available to libtp at compilation time.
o | the tunepimp_t object returned from tp_New() | |
encoding | the encoding to use. Must be 'UTF-8', 'ISO-8859-1' or an ICU supported encoding. |
void tp_SetID3Encoding | ( | tunepimp_t | o, | |
TPID3Encoding | encoding | |||
) |
Use this function to set which encoding to write to ID3v2 tags.
Default: utf-8 for ID3v2.4, ISO 8859-1 (latin1) for ID3v2.3
o | the tunepimp_t object returned from tp_New() | |
encoding | set to one of eLatin1, eUTF8 or eUTF16 |
void tp_SetMaxFileNameLen | ( | tunepimp_t | o, | |
int | maxFileNameLen | |||
) |
Use this function to set the maximum filename length
o | the tunepimp_t object returned from tp_New() | |
maxFileNameLen | the maximum filename length |
void tp_SetMinTRMThreshold | ( | tunepimp_t | o, | |
int | minThreshold | |||
) |
Set the minimum recognition threshold for TRM lookups.
If there is a TRM match for a given track, but the similarity between the metadata returned is below the minimum recognition threshold, then the TRM match should not be accepted and the file should be listed as unrecognized.
Valid values for the threshold are between 0 and 100, including 0 and 100.
Default: 50.
o | the tunepimp_t object returned from tp_New() | |
minThreshold | the threshold value to use |
void tp_SetMoveFiles | ( | tunepimp_t | o, | |
int | move | |||
) |
If enabled, files are moved to the destination directory as specified in the file mask or the various artists file mask. Files are only moved to a new directory, but the file name isn't changed.
Default: enabled.
o | the tunepimp_t object returned from tp_New() | |
move | set a non-zero value to enable moving |
void tp_SetNonAlbumFileMask | ( | tunepimp_t | o, | |
const char * | nonAlbumFileMask | |||
) |
Set the file mask for non-album releases. See tp_SetFileMask() for a discussion of file masks.
For regular album releases, tp_SetFileMask() or tp_SetVariousFileMask() has to be used.
The default file mask is "%artist/%album/%artist-%track".
o | the tunepimp_t object returned from tp_New() | |
nonAlbumFileMask | a format string |
void tp_SetNotifyCallback | ( | tunepimp_t | o, | |
tp_notify_callback | callback, | |||
void * | data | |||
) |
Use this function to register a callback function with tunepimp that gets called each time a file is added (using tp_AddFile() or tp_AddDir()), removed (using tp_Remove()) or changed. A change is signalled every time the status of a track changes.
Note that if a callback is provided the tp_GetNotification() function will no longer return notification messages. To unset a callback, pass in NULL to this function. Only one function may be registered at a time.
o | the tunepimp_t object returned from tp_New() | |
callback | a function pointer to set or NULL to unset a callback | |
data | a private data member that will be passed back verbatim to the callback |
void tp_SetProxy | ( | tunepimp_t | o, | |
const char * | serverAddr, | |||
short | serverPort | |||
) |
Set the name of the HTTP Proxy to use. This function must be called anytime the client library must communicate via a proxy firewall. To disable the use of the proxy server, set serverAddr to the empty string ("").
o | the tunepimp_t object returned from tp_New() | |
serverAddr | the name of the proxy server to use e.g. proxy.mydomain.com | |
serverPort | the port number to use. e.g. 8080 |
void tp_SetRenameFiles | ( | tunepimp_t | o, | |
int | rename | |||
) |
If enabled, files are renamed as specified in the file mask or the various artists file mask. Only the file name is changed, this setting doesn't imply moving the file to a new directory.
Default: enabled.
o | the tunepimp_t object returned from tp_New() | |
rename | set a non-zero value to enable renaming |
void tp_SetServer | ( | tunepimp_t | o, | |
const char * | serverAddr, | |||
short | serverPort | |||
) |
Set the name and the port of the MusicBrainz server to use. If this function is not called, the default www.musicbrainz.org server on port 80 will be used.
o | the tunepimp_t object returned from tp_New | |
serverAddr | the name of the musicbrainz server to use e.g. www.musicbrainz.org | |
serverPort | the port number to use. e.g. 80 |
void tp_SetStatusCallback | ( | tunepimp_t | o, | |
tp_status_callback | callback, | |||
void * | data | |||
) |
Use this function to register a callback function to receive textual messages describing tunepimp's current status. The messages are intended for direct output to the user. Don't try to parse the messages. All important information can be retrieved by other means.
Note that if a callback is provided the tp_GetStatusCallback() function will no longer return Status messages. To unset a callback, pass in NULL to this function. Only one function may be registered at a time.
o | the tunepimp_t object returned from tp_New() | |
callback | a function pointer to set or NULL to unset a callback | |
data | a private data member that will be passed back verbatim to the callback |
void tp_SetTopSrcDir | ( | tunepimp_t | o, | |
const char * | topSrcDir | |||
) |
When TunePimp moves a file out of a directory to a new directory, and the old directory is now empty, the old directory is removed. This process is repeated for the old directory's parent, until it reaches the TopSrcDir, where it stops removing directories. Set the TopDrcDir to root of the directory tree where Tunepimp is writing ID3 files to.
Example:
TopSrcDir in this case is set to: /mnt/mp3
/mnt/mp3/dirty_mp3s/Beatles/Yesterday.mp3
The Yesterday song is the only file left in the dirty_mp3s folder. When tunepimp moves this file to its new, clean location, it will remove the Beatles directory, then the dirty_mp3s directory, but it will not remove the /mnt/mp3 directory, since that is the TopSrcDir.
o | the tunepimp_t object returned from tp_New() | |
topSrcDir | the top src directory to use |
void tp_SetTRMCollisionThreshold | ( | tunepimp_t | o, | |
int | trmThreshold | |||
) |
Set the recognition threshold for TRM collisions.
If there is more than one entry matching a TRM in the musicbrainz database, we have a TRM collision. In this case, a similarity value is calculated for each returned database entry using the file's meta data as the reference. The similarity is a percent value describing how good the match is.
If the similarity is greater or equal than the TRMCollisionThreshold, the file is marked as recognized (eRecognized). Otherwise, the track's status is set to eTRMCollision which requires user interaction to select one of the returned results.
Valid values for the threshold are between 0 and 100, including 0 and 100.
Default: 80.
o | the tunepimp_t object returned from tp_New() | |
trmThreshold | the TRM threshold |
void tp_SetUserInfo | ( | tunepimp_t | o, | |
const char * | userName, | |||
const char * | password | |||
) |
This function must be called if you want to submit data to the server. Anonymous TRM submission using tp_SubmitTRMs() is not permitted. If you're looking up data from the server, you do not need to call tp_SetUserInfo.
o | the tunepimp_t object returned from tp_New() | |
userName | the name of the user | |
password | the plaintext password of the user |
void tp_SetVariousFileMask | ( | tunepimp_t | o, | |
const char * | variousFileMask | |||
) |
Set the file mask for various artists releases. See tp_SetFileMask() for a discussion of file masks.
For single artist releases, tp_SetFileMask() has to be used.
The default is "Various Artists/%album/%album-%0num-%artist-%track".
o | the tunepimp_t object returned from tp_New() | |
variousFileMask | a format string |
void tp_SetWriteID3v1 | ( | tunepimp_t | o, | |
int | writeID3v1 | |||
) |
Use this function to enable writing of legacy ID3v1 tags to MP3 files. ID3v1 tags are supported by almost every existing MP3 player.
Default: enabled.
o | the tunepimp_t object returned from tp_New() | |
writeID3v1 | set a non-zero value to enable ID3v1 tags |
void tp_SetWriteID3v2_3 | ( | tunepimp_t | o, | |
int | writeID3v2_3 | |||
) |
Use this function to enable writing of ID3v2.3 tags to MP3 files. ID3v2.4 tags are the default for tunepimp.
Default: disabled
o | the tunepimp_t object returned from tp_New() | |
writeID3v2_3 | set a non-zero value to enable ID3v2_3 tags |
TPError tp_SubmitTRMs | ( | tunepimp_t | o | ) |
Send all unsubmitted TRMs to trackId mappings to the server. Except for TRM and trackId, no further meta data is sent.
To prevent abuse, however, you need to authenticate to the server using tp_SetUserInfo() before calling tp_SubmitTRMs().
o | the tunepimp_t object returned from tp_New() |
void tp_Wake | ( | tunepimp_t | o, | |
track_t | track | |||
) |
Wake up tunepimp to look for work to do.
You have to call this function every time you change a track's status using tr_SetStatus(). This call will wake up the TunePimp internal threads to look for tracks that need to be processed. If you do not call this function after you make a change to a track, the change will be ignored.
o | the tunepimp_t object returned from tp_New() | |
track | the handle of the track that changed |
int tp_WriteTags | ( | tunepimp_t | o, | |
int * | fileIds, | |||
int | numFileIds | |||
) |
Write tags for the specified files. Only files in state eRecognized will be written. If renaming was enabled using tp_SetRenameFiles(), the files are also renamed as specified in the file part of the file mask. Otherwise, the file name stays as it is.
If moving was enabled using tp_SetMoveFiles(), the files are moved to the destination directory (see tp_SetDestDir()) while keeping their original file names. If, additionally, renaming was enabled, the files are moved to a subdirectory of the destination directory depending on the directory part of the file mask.
If fileIds is set to the NULL pointer, all recognized files are written. In this case the numFileIds argument is ignored.
tp_WriteTags() doesn't return an error indicator if there were problems writing the files. You have to check the track status to see if writing was successful. The state is changed to eDeleted on success and deleted as soon as neither tunepimp nor the client have any more references to the track. The status is set to eError if an error occurs. Until writing of a track is done, the track stays in state eVerified.
Please note that files that had a similarity greater or equal to the AutoSaveThreshold are written automatically, right after they have been recognized.
o | the tunepimp_t object returned from tp_New() | |
fileIds | a pointer to an array of fileIds or NULL | |
numFileIds | the number of fileIds in the array |
void tr_GetError | ( | track_t | t, | |
char * | error, | |||
int | maxLen | |||
) |
Use this function to get a printable error message for the last error that occured in the track object. tr_GetError() stores the error string in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
Don't confuse this function with tp_GetError().
t | a track object obtained via tp_GetTrack() | |
error | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
void tr_GetFileName | ( | track_t | t, | |
char * | fileName, | |||
int | maxLen | |||
) |
Get the filename of the specified track. The function stores the filename in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
t | a track object obtained via tp_GetTrack() | |
fileName | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
void tr_GetLocalMetadata | ( | track_t | t, | |
metadata_t * | mdata | |||
) |
Get the track's meta data that was already present in the file. The meta data is saved in a valid metadata_t object passed as an argument. No I/O takes place since the data will have been read during the TRM analisys stage. Files that are still in the ePending stage may not have correct local metadata.
t | a track object obtained via tp_GetTrack() | |
mdata | a meta data object created by md_New() |
int tr_GetNumResults | ( | track_t | t | ) |
Returns the number of results that were retrieved using TRM or file lookup.
t | a track object obtained via tp_GetTrack() |
void tr_GetResults | ( | track_t | t, | |
TPResultType * | type, | |||
result_t * | results, | |||
int * | numResults | |||
) |
Get the results that were returned for a TRM or file lookup.
The results argument has to be a pointer to a result_t. When the function returns, it points to a an array of newly allocated objects, depending on the type argument. If type is eArtistList, results points to an artistresult_t array, for eAlbumList to a albumresult_t array and for eTrackList to a tracklist_t array.
Don't forget to release the memory using rs_Delete() when you're done.
t | a track object obtained via tp_GetTrack() | |
type | the address of a variable to receive the result type | |
results | the address of a result_t variable | |
numResults | the address of a variable to receive the number of results |
void tr_GetServerMetadata | ( | track_t | t, | |
metadata_t * | mdata | |||
) |
Retrieve the meta data we got back from the server. This data will have been downloaded from the server if a track was recognized or it was set by tunepimp when the user selected a Lookup result.
The server meta data is used to construct file and directory names and is written to the tags as soon as the data is verified (eVerified).
t | a track object obtained via tp_GetTrack() | |
mdata | a valid metadata_t object |
int tr_GetSimilarity | ( | track_t | t | ) |
Get the similarity of the local and the server meta data.
The similarity is a percent value between 0 and 100. Before a lookup, the similarity is 0. If no metadata was extracted from the file, the similarity will also be 0.
t | a track object obtained via tp_GetTrack() |
TPFileStatus tr_GetStatus | ( | track_t | t | ) |
Returns the status of a track.
It is also possible to get notifed as soon as the status of a track changes using the notfy callback.
t | a track object obtained via tp_GetTrack() |
void tr_GetTRM | ( | track_t | t, | |
char * | trm, | |||
int | maxLen | |||
) |
Get the TRM of the specified track in an ASCII representation. The TRM is stored in a user supplied buffer. Not more than maxLen characters including the trailing '\0' byte are copied into that buffer.
A TRM is MB_ID_LEN=36 characters long, so you can set maxLen to 37.
t | a track object obtained via tp_GetTrack() | |
trm | a user supplied buffer of maxLen characters | |
maxLen | the size of the buffer |
int tr_HasChanged | ( | track_t | t | ) |
Returns true if local and server meta data differ and false otherwise.
t | a track object obtained via tp_GetTrack() |
void tr_Lock | ( | track_t | t | ) |
Lock a track object to make sure tunepimp doesn't change it while you are working on it. Tunepimp is multithreaded so it is needed to avoid race conditions. Don't forget to release the lock using tr_Unlock() when you're done.
t | a track object obtained via tp_GetTrack() |
void tr_SetChanged | ( | track_t | t | ) |
Mark a track as changed, so that it will be saved even if libtp doesn't think the track changed. (Useful for cases where the encoding changed, which libtp doesn't detect.
t | a track object obtained via tp_GetTrack() |
void tr_SetLocalMetadata | ( | track_t | t, | |
const metadata_t * | mdata | |||
) |
Set the track's local meta data to the specified values. No I/O takes place. The local meta data is sent to the server when doing a TRM or file lookup if there isn't server meta data from a previous lookup.
To avoid race conditions, you have to tr_Lock() the track before using tr_SetLocalMetadata() and tr_Unlock() afterwards.
t | a track object obtained via tp_GetTrack() | |
mdata | a valid metadata_t object |
void tr_SetServerMetadata | ( | track_t | t, | |
const metadata_t * | mdata | |||
) |
Set the server meta data. It is used to write the tag and to construct new file and directory names as soon as the data is verifed (eVerified).
When doing lookups the server meta data is used if it is available. Otherwise, the local meta data is used.
t | a track object obtained via tp_GetTrack() | |
mdata | a valid metadata_t object |
void tr_SetStatus | ( | track_t | t, | |
const TPFileStatus | status | |||
) |
Set a track's status. Setting the status is necessary if a track is in state eTRMCollision, eUserSelection or eUnrecognized. Don't forget to lock the track before using this function and unlocking it afterwards.
t | a track object obtained via tp_GetTrack() | |
status | the new status of the track |
void tr_Unlock | ( | track_t | t | ) |
Unlock a track object previously locked using tr_Lock(). You are not allowed to unlock tracks that were locked by tunepimp itself.
t | a track object obtained via tp_GetTrack() |