#include "defs.h"Go to the source code of this file.
|
|
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. |
|
|
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. |
|
|
This structure contains information about an artist. The relevance attribute is an indication for the quality of the match. The higher the better. |
|
|
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. 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.
|
|
|
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()). |
|
|
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().
|
|
|
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().
|
|
|
The abstraction of a Track object. Functions to manipulate have a prefix of "tr_". |
|
|
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_". |
|
|
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().
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
|
Converts a string to TPAlbumStatus. The string's value has to be one of "official", "promotion" or "bootleg". Case doesn't matter.
|
|
|
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.
|
|
|
Delete a metadata_t object.
|
|
|
Create a new metadata_t object. Don't forget to release it using md_Delete() when you don't need it any longer.
|
|
||||||||||||||||
|
Releases the memory for a result list allocated by tr_GetResults()
|
|
||||||||||||
|
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().
|
|
||||||||||||
|
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.
|
|
||||||||||||||||
|
Add a (trackId, TRM) pair to the list of unsubmitted TRMs. You have to call tp_SubmitTRMs() to actually send it to the server.
|
|
|
The destructor for the TunePimp class.
|
|
||||||||||||
|
Release the memory allocated by tp_GetRecognizedFileList(). You can use this function even if there were no fileIds returned.
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer. If all characters are allowed, the empty string ("") is returned.
|
|
|
This function gets the analyzer thread priority level.
|
|
|
Query the status of the AutoFileLookup feature. See tp_SetAutoFileLookup() for further information.
|
|
|
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.
|
|
|
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.
|
|
|
Query the tunepimp object if tag clearing is enabled. See tp_SetClearTags() for more information.
|
|
|
Check if debugging is enabled.
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
||||||||||||||||
|
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().
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
|
Use this function to get the current maximum filename length
|
|
|
Get the minimum TRM match threshold. The returned value is between 0 and 100. See tp_SetMinTRMThreshold() for a discussion.
|
|
|
Check if file moving is enabled. See tp_SetMoveFiles() for more information.
|
|
||||||||||||||||
|
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.
|
|
|
Get the function registered to receive notification messages. See tp_SetNotifyCallback() for more information.
|
|
|
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.
|
|
|
This function returns the number of files that tunepimp has in its list.
|
|
|
Query the number of audio file formats supported by tunepimp. The number depends on which libraries were present when tunepimp was compiled.
|
|
|
This function returns the number of track that have been recognized and are ready to be saved.
|
|
|
This function returns the number of TRMs that haven't been submitted to the server yet.
|
|
||||||||||||||||||||
|
Get the proxy settings. tp_GetProxy() stores the address in a user supplied buffer. Not more than maxLen characters including the trailing '' byte are copied into that buffer. If no proxy was set, serverAddr is set to the empty string ("").
|
|
||||||||||||||||||||
|
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().
|
|
|
Query the tunepimp object if file renaming is enabled. See tp_SetRenameFiles() for an explanation.
|
|
||||||||||||||||||||
|
Get the server settings. tp_GetServer() stores the address in a user supplied buffer. Not more than maxLen characters including the trailing '' byte are copied into that buffer. If no proxy was set, serverAddr is set to the empty string ("").
|
|
||||||||||||||||
|
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.
|
|
|
Get the function registered to receive status messages. See tp_SetStatusCallback() for more information.
|
|
||||||||||||
|
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.
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
||||||||||||
|
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.
|
|
||||||||||||||||
|
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]
|
|
|
Get the TRM collision threshold. The returned value is between 0 and 100. See tp_SetTRMCollisionThreshold() for a discussion.
|
|
||||||||||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
|
Use this function to check if tunepimp returns data in UTF-8 or in ISO-8859-1 (latin1).
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
||||||||||||||||||||
|
Get the version number of this library.
|
|
|
Check if writing ID3v1 tags to MP3 files is enabled.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
Create a new handle (a C abstraction) to the TunePimp object. Call tp_Delete() when done with the handle.
|
|
||||||||||||||||
|
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.
|
|
||||||||||||
|
Release the specified track object.
|
|
||||||||||||
|
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.
|
|
||||||||||||||||
|
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()
|
|
||||||||||||
|
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 ("").
|
|
||||||||||||
|
This function sets the analyzer thread priority level.
|
|
||||||||||||
|
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".
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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".
|
|
||||||||||||
|
Use this function to set the maximum filename length
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||||||
|
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.
|
|
||||||||||||||||
|
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 ("").
|
|
||||||||||||
|
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.
|
|
||||||||||||||||
|
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.
|
|
||||||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||||||
|
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.
|
|
||||||||||||
|
Use this function to select the charset of the data returned by tunepimp. Set it to a non-zero value to select UTF-8. Otherwise, ISO-8859-1 (latin1) will be used.
|
|
||||||||||||
|
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".
|
|
||||||||||||
|
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.
|
|
|
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().
|
|
||||||||||||
|
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.
|
|
||||||||||||||||
|
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.
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer. Don't confuse this function with tp_GetError().
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer.
|
|
||||||||||||
|
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.
|
|
|
Returns the number of results that were retrieved using TRM or file lookup.
|
|
||||||||||||||||||||
|
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.
|
|
||||||||||||
|
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).
|
|
|
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.
|
|
|
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.
|
|
||||||||||||||||
|
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 '' byte are copied into that buffer. A TRM is MB_ID_LEN=36 characters long, so you can set maxLen to 37.
|
|
|
Returns true if local and server meta data differ and false otherwise.
|
|
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
|
Unlock a track object previously locked using tr_Lock(). You are not allowed to unlock tracks that were locked by tunepimp itself.
|
1.3.6-20040222