tracks(3)
π tracks(3) π
okay bestie sit DOWN because this is the libmtp manual, library-functions-manual edition, and it's literally all about tracks β¨ (tracks(3), if you're being formal about it). No cap, it's giving "everything you ever wanted to know about talking to an MTP device about its music and video tracks." π΅π¬
β¨ NAME β¨
libmtp β tracks π
π¦ SYNOPSIS π¦
π Functions π
LIBMTP_track_t * LIBMTP_new_track_t (void)
void LIBMTP_destroy_track_t (LIBMTP_track_t *)
LIBMTP_track_t * LIBMTP_Get_Tracklisting (LIBMTP_mtpdevice_t *)
LIBMTP_track_t * LIBMTP_Get_Tracklisting_With_Callback
(LIBMTP_mtpdevice_t *, LIBMTP_progressfunc_t const, void const
*const)
LIBMTP_track_t * LIBMTP_Get_Tracklisting_With_Callback_For_Storage
(LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_progressfunc_t const,
void const *const)
LIBMTP_track_t * LIBMTP_Get_Trackmetadata (LIBMTP_mtpdevice_t *,
uint32_t const)
int LIBMTP_Get_Track_To_File (LIBMTP_mtpdevice_t *, uint32_t, char const
*const, LIBMTP_progressfunc_t const, void const *const)
int LIBMTP_Get_Track_To_File_Descriptor (LIBMTP_mtpdevice_t *, uint32_t
const, int const, LIBMTP_progressfunc_t const, void const *const)
int LIBMTP_Get_Track_To_Handler (LIBMTP_mtpdevice_t *, uint32_t const,
MTPDataPutFunc, void *, LIBMTP_progressfunc_t const, void const
*const)
int LIBMTP_Send_Track_From_File (LIBMTP_mtpdevice_t *, char const
*const, LIBMTP_track_t *const, LIBMTP_progressfunc_t const, void
const *const)
int LIBMTP_Send_Track_From_File_Descriptor (LIBMTP_mtpdevice_t *, int
const, LIBMTP_track_t *const, LIBMTP_progressfunc_t const, void
const *const)
int LIBMTP_Send_Track_From_Handler (LIBMTP_mtpdevice_t *,
MTPDataGetFunc, void *, LIBMTP_track_t *const, LIBMTP_progressfunc_t
const, void const *const)
int LIBMTP_Update_Track_Metadata (LIBMTP_mtpdevice_t *, LIBMTP_track_t
const *const)
int LIBMTP_Track_Exists (LIBMTP_mtpdevice_t *, uint32_t const)
int LIBMTP_Set_Track_Name (LIBMTP_mtpdevice_t *, LIBMTP_track_t *, const
char *)
fourteen functions, bestie. count 'em. π₯
πΈ Detailed Description πΈ
no notes, bestie β the original just kindaβ¦ doesn't say anything here. iconic of it honestly. moving on π
π Function Documentation π
π void LIBMTP_destroy_track_t (LIBMTP_track_t * track)
okay so this one destroys a track metadata structure π and deallocates all the memory it was using, including any strings hanging off it.
β οΈ bestie LISTEN β never, ever use a track metadata structure again after you call this function on it. it's done. it's over. it's not coming back. that's undefined-behaviour territory and we do NOT go there. π
Parameters
trackβ the track metadata to destroy.
See also
LIBMTP_new_track_t()
References LIBMTP_track_struct::album, LIBMTP_track_struct::artist, LIBMTP_track_struct::composer, LIBMTP_track_struct::date, LIBMTP_track_struct::filename, LIBMTP_track_struct::genre, and LIBMTP_track_struct::title.
Referenced by LIBMTP_Get_Tracklisting_With_Callback_For_Storage(), and LIBMTP_Get_Trackmetadata().
π int LIBMTP_Get_Track_To_File (LIBMTP_mtpdevice_t * device, uint32_t const id, char const *const path, LIBMTP_progressfunc_t const callback, void const *const data)
this one pulls a track off the device and drops it into a file, identified by a filename β¨. real talk though: this is actually just a wrapper for the LIBMTP_Get_Track_To_File() function. (yes bestie, that's literally what it says. we don't question it, we just report it π
)
Parameters
deviceβ a pointer to the device to get the track from.idβ the track ID of the track to retrieve.pathβ a filename to use for the retrieved track.callbackβ a progress indicator function orNULLto ignore.dataβ a user-defined pointer that is passed along to the progress function in order to pass along some user defined data to the progress updates. If not used, set this toNULL.
Returns
0if the transfer was successful, any other value means failure. π
See also
LIBMTP_Get_Track_To_File_Descriptor()
References LIBMTP_Get_File_To_File().
π int LIBMTP_Get_Track_To_File_Descriptor (LIBMTP_mtpdevice_t * device, uint32_t const id, int const fd, LIBMTP_progressfunc_t const callback, void const *const data)
same vibe as before but the destination is a file descriptor instead of a filename π«Ά. and yeah β this is actually just a wrapper for the LIBMTP_Get_File_To_File_Descriptor() function.
Parameters
deviceβ a pointer to the device to get the track from.idβ the track ID of the track to retrieve.fdβ a file descriptor to write the track to.callbackβ a progress indicator function orNULLto ignore.dataβ a user-defined pointer that is passed along to the progress function in order to pass along some user defined data to the progress updates. If not used, set this toNULL.
Returns
0if the transfer was successful, any other value means failure.
See also
LIBMTP_Get_Track_To_File()
References LIBMTP_Get_File_To_File_Descriptor().
π int LIBMTP_Get_Track_To_Handler (LIBMTP_mtpdevice_t * device, uint32_t const id, MTPDataPutFunc put_func, void * priv, LIBMTP_progressfunc_t const callback, void const *const data)
this one gets a track off the device and hands it straight to a handler function π§. and yes, it's actually just a wrapper for the LIBMTP_Get_File_To_Handler() function.
Parameters
deviceβ a pointer to the device to get the track from.idβ the track ID of the track to retrieve.put_funcβ the function to call when we have data.privβ the user-defined pointer that is passed toput_func.callbackβ a progress indicator function orNULLto ignore.dataβ a user-defined pointer that is passed along to the progress function in order to pass along some user defined data to the progress updates. If not used, set this toNULL.
Returns
0if the transfer was successful, any other value means failure.
References LIBMTP_Get_File_To_Handler().
π LIBMTP_track_t * LIBMTP_Get_Tracklisting (LIBMTP_mtpdevice_t * device)
π¨ THIS FUNCTION IS DEPRECATED. PLEASE UPDATE YOUR CODE IN ORDER NOT TO USE IT. π¨ bestie seriously, update your code. it's giving legacy. it's giving "we love you but please move on." π
See also
LIBMTP_Get_Tracklisting_With_Callback()
References LIBMTP_Get_Tracklisting_With_Callback().
π LIBMTP_track_t * LIBMTP_Get_Tracklisting_With_Callback (LIBMTP_mtpdevice_t * device, LIBMTP_progressfunc_t const callback, void const *const data)
okay this is the main character β¨. it returns a long list of all tracks available on the current MTP device. and when we say tracks, we mean multimedia objects in general β both music tracks and video tracks. π
typical usage, verbatim:
LIBMTP_track_t *tracklist;
tracklist = LIBMTP_Get_Tracklisting_With_Callback(device, callback, data);
while (tracklist != NULL) {
LIBMTP_track_t *tmp;
// Do something on each element in the list here...
tmp = tracklist;
tracklist = tracklist->next;
LIBMTP_destroy_track_t(tmp);
}
now β if you wanna group your track listing by storage (per storage unit) or arrange tracks into folders, you must dereference the storage_id and/or parent_id field of the returned LIBMTP_track_t struct. to arrange by folders or files you typically have to create the proper trees by calls to LIBMTP_Get_Storage() and/or LIBMTP_Get_Folder_List() first. iykyk π«Ά
Parameters
deviceβ a pointer to the device to get the track listing for.callbackβ a function to be called during the tracklisting retrieveal for displaying progress bars etc, orNULLif you don't want any callbacks.dataβ a user-defined pointer that is passed along to the progress function in order to pass along some user defined data to the progress updates. If not used, set this toNULL.
Returns
- a list of tracks that can be followed using the
nextfield of theLIBMTP_track_tdata structure. Each of the metadata tags must be freed after use, and may contain only partial metadata information, i.e. one or several fields may beNULLor0. π
See also
LIBMTP_Get_Trackmetadata()
References LIBMTP_Get_Tracklisting_With_Callback_For_Storage().
Referenced by LIBMTP_Get_Tracklisting().
π LIBMTP_track_t * LIBMTP_Get_Tracklisting_With_Callback_For_Storage (LIBMTP_mtpdevice_t * device, uint32_t const storage_id, LIBMTP_progressfunc_t const callback, void const *const data)
same energy as the last one but β¨storage-awareβ¨ β it returns a long list of all tracks available on the current MTP device, tracks meaning multimedia objects, both music tracks and video tracks.
typical usage, verbatim:
LIBMTP_track_t *tracklist;
tracklist = LIBMTP_Get_Tracklisting_With_Callback_For_Storage(device, storage_id, callback, data);
while (tracklist != NULL) {
LIBMTP_track_t *tmp;
// Do something on each element in the list here...
tmp = tracklist;
tracklist = tracklist->next;
LIBMTP_destroy_track_t(tmp);
}
and again bestie: if you want to group your track listing by storage (per storage unit) or arrange tracks into folders, you must dereference the storage_id and/or parent_id field of the returned LIBMTP_track_t struct. to arrange by folders or files you typically have to create the proper trees by calls to LIBMTP_Get_Storage() and/or LIBMTP_Get_Folder_List() first. πΈ
Parameters
deviceβ a pointer to the device to get the track listing for.storage_idβ ID of device storage (if null, no filter)callbackβ a function to be called during the tracklisting retrieveal for displaying progress bars etc, orNULLif you don't want any callbacks.dataβ a user-defined pointer that is passed along to the progress function in order to pass along some user defined data to the progress updates. If not used, set this toNULL.
Returns
- a list of tracks that can be followed using the
nextfield of theLIBMTP_track_tdata structure. Each of the metadata tags must be freed after use, and may contain only partial metadata information, i.e. one or several fields may beNULLor0.
See also
LIBMTP_Get_Trackmetadata()
References LIBMTP_track_struct::filename, LIBMTP_track_struct::filesize, LIBMTP_track_struct::filetype, LIBMTP_track_struct::item_id, LIBMTP_destroy_track_t(), LIBMTP_FILETYPE_IS_TRACK, LIBMTP_new_track_t(), LIBMTP_track_struct::modificationdate, LIBMTP_track_struct::next, LIBMTP_mtpdevice_struct::params, LIBMTP_track_struct::parent_id, LIBMTP_track_struct::storage_id, and LIBMTP_mtpdevice_struct::usbinfo.
Referenced by LIBMTP_Get_Tracklisting_With_Callback().
π LIBMTP_track_t * LIBMTP_Get_Trackmetadata (LIBMTP_mtpdevice_t * device, uint32_t const trackid)
this one grabs the metadata for a single track off the device. π
π okay bestie, do NOT call this function repeatedly! the track handles are linearly searchedO(n)and the call may involve (slow) USB traffic. so useLIBMTP_Get_Tracklisting()and cache the tracks, preferably as an efficient data structure such as a hash list. fr fr, your USB bus will thank you.
Parameters
deviceβ a pointer to the device to get the track metadata from.trackidβ the object ID of the track that you want the metadata for.
Returns
- a track metadata entry on success or
NULLon failure.
See also
LIBMTP_Get_Tracklisting()LIBMTP_track_struct::filenameLIBMTP_track_struct::filesizeLIBMTP_track_struct::filetypeLIBMTP_track_struct::item_idLIBMTP_destroy_track_t()LIBMTP_FILETYPE_IS_TRACKLIBMTP_new_track_t()LIBMTP_track_struct::modificationdateLIBMTP_mtpdevice_struct::paramsLIBMTP_track_struct::parent_idLIBMTP_track_struct::storage_idLIBMTP_mtpdevice_struct::usbinfo
β¨ LIBMTP_track_t * LIBMTP_new_track_t (void ) β¨
okay so this one is your lil' fresh-out-the-wrapper track metadata struct π it creates a brand new track metadata thingy and allocates memory for it. iconic. no notes.
<talking-headvoice>But bestie, real talk:</talking-headvoice> if you shove strings into this struct, those strings get freed later by the matching LIBMTP_destroy_track_t operation. so like. be SO careful and use strdup() when you assign strings, mkay? for example:
LIBMTP_track_t *track = LIBMTP_new_track_t();
track->title = strdup(titlestr);
....
LIBMTP_destroy_track_t(track);
Returns πΈ
- a pointer to the newly allocated metadata structure. she's here, she's yours π
See also π«Ά
LIBMTP_destroy_track_t()
Referenced by π
LIBMTP_Get_Tracklisting_With_Callback_For_Storage(), andLIBMTP_Get_Trackmetadata().
π₯ int LIBMTP_Send_Track_From_File (LIBMTP_mtpdevice_t * device, char const *const path, LIBMTP_track_t *const metadata, LIBMTP_progressfunc_t const callback, void const *const data) π₯
this is THE function, no cap β it yeets a track from a local file straight onto an MTP device π you gotta hand over a filename and a set of metadata, that's the price of admission.
Parameters π
deviceβ a pointer to the device to send the track to. (<- the destination, obviously)pathβ the filename of a local file which will be sent.metadataβ a track metadata set to be written along with the file. After this call the fieldmetadata->item_idwill contain the new track ID. Other fields such as themetadata->filename,metadata->parent_idormetadata->storage_idmay also change during this operation due to device restrictions, so do not rely on the contents of this struct to be preserved in any way. fr fr, she's a different girl after this call:metadata->parent_idshould be set to the parent (e.g. folder) to store this track in. Since some devices are a bit picky about where files are placed, a default folder will be chosen if libmtp has detected one for the current filetype and this parameter is set to0. If this is0and no default folder can be found, the file will be stored in the root folder. πmetadata->storage_idshould be set to the desired storage (e.g. memory card or whatever your device presents) to store this track in. Setting this to0will store the track on the primary storage. πΎ
callbackβ a progress indicator function orNULLto ignore. (ngl, you want the little progress bar, it's giving serotonin β¨)dataβ a user-defined pointer that is passed along to the progress function in order to pass along some user defined data to the progress updates. If not used, set this toNULL.
Returns π
0if the transfer was successful, any other value means failure. periodt.
See also π
LIBMTP_Send_Track_From_File_Descriptor()LIBMTP_Send_File_From_File()LIBMTP_Delete_Object()
References π¦
LIBMTP_Send_Track_From_File_Descriptor().
π int LIBMTP_Send_Track_From_File_Descriptor (LIBMTP_mtpdevice_t * device, int const fd, LIBMTP_track_t *const metadata, LIBMTP_progressfunc_t const callback, void const *const data) π
same energy as the last one but she takes a file descriptor instead of a path β basically the cool alternative route to get a track onto an MTP device. A filename and a set of metadata must be given as input.
Parameters π
deviceβ a pointer to the device to send the track to.fdβ the filedescriptor for a local file which will be sent.metadataβ a track metadata set to be written along with the file. After this call the fieldmetadata->item_idwill contain the new track ID. Other fields such as themetadata->filename,metadata->parent_idormetadata->storage_idmay also change during this operation due to device restrictions, so do not rely on the contents of this struct to be preserved in any way. like, at all. the struct has main character energy now and she does what she wants:metadata->parent_idshould be set to the parent (e.g. folder) to store this track in. Since some devices are a bit picky about where files are placed, a default folder will be chosen if libmtp has detected one for the current filetype and this parameter is set to0. If this is0and no default folder can be found, the file will be stored in the root folder.metadata->storage_idshould be set to the desired storage (e.g. memory card or whatever your device presents) to store this track in. Setting this to0will store the track on the primary storage.
callbackβ a progress indicator function orNULLto ignore.dataβ a user-defined pointer that is passed along to the progress function in order to pass along some user defined data to the progress updates. If not used, set this toNULL.
Returns π
0if the transfer was successful, any other value means failure.
See also π
LIBMTP_Send_Track_From_File()LIBMTP_Delete_Object()
References π
LIBMTP_file_struct::filenameLIBMTP_track_struct::filenameLIBMTP_file_struct::filesizeLIBMTP_track_struct::filesizeLIBMTP_file_struct::filetypeLIBMTP_track_struct::filetypeLIBMTP_file_struct::item_idLIBMTP_track_struct::item_idLIBMTP_FILETYPE_IS_TRACKLIBMTP_Send_File_From_File_Descriptor()LIBMTP_Update_Track_Metadata()LIBMTP_file_struct::nextLIBMTP_mtpdevice_struct::paramsLIBMTP_file_struct::parent_idLIBMTP_track_struct::parent_idLIBMTP_file_struct::storage_idLIBMTP_track_struct::storage_idLIBMTP_mtpdevice_struct::usbinfo
Referenced by π
LIBMTP_Send_Track_From_File().
π§ int LIBMTP_Send_Track_From_Handler (LIBMTP_mtpdevice_t * device, MTPDataGetFunc get_func, void * priv, LIBMTP_track_t *const metadata, LIBMTP_progressfunc_t const callback, void const *const data) π§
and here's the third sibling in the trio π this one sends a track from a handler function to an MTP device β so instead of pointing at a file or an fd, you're like "hey, call me when you need data, i got you". A filename and a set of metadata must be given as input.
Parameters πΈ
deviceβ a pointer to the device to send the track to.get_funcβ the function to call when we have data.privβ the user-defined pointer that is passed toget_func.metadataβ a track metadata set to be written along with the file. After this call the fieldmetadata->item_idwill contain the new track ID. Other fields such as themetadata->filename,metadata->parent_idormetadata->storage_idmay also change during this operation due to device restrictions, so do not rely on the contents of this struct to be preserved in any way. bestie it is genuinely not the same struct after this, i'm so serious:metadata->parent_idshould be set to the parent (e.g. folder) to store this track in. Since some devices are a bit picky about where files are placed, a default folder will be chosen if libmtp has detected one for the current filetype and this parameter is set to0. If this is0and no default folder can be found, the file will be stored in the root folder.metadata->storage_idshould be set to the desired storage (e.g. memory card or whatever your device presents) to store this track in. Setting this to0will store the track on the primary storage.
callbackβ a progress indicator function orNULLto ignore.dataβ a user-defined pointer that is passed along to the progress function in order to pass along some user defined data to the progress updates. If not used, set this toNULL.
Returns β
0if the transfer was successful, any other value means failure.
See also π«Ά
LIBMTP_Send_Track_From_File()LIBMTP_Delete_Object()
References π
LIBMTP_file_struct::filenameLIBMTP_track_struct::filenameLIBMTP_file_struct::filesizeLIBMTP_track_struct::filesizeLIBMTP_file_struct::filetypeLIBMTP_track_struct::filetypeLIBMTP_file_struct::item_idLIBMTP_track_struct::item_idLIBMTP_FILETYPE_IS_TRACKLIBMTP_Send_File_From_Handler()LIBMTP_Update_Track_Metadata()LIBMTP_file_struct::nextLIBMTP_mtpdevice_struct::paramsLIBMTP_file_struct::parent_idLIBMTP_track_struct::parent_idLIBMTP_file_struct::storage_idLIBMTP_track_struct::storage_idLIBMTP_mtpdevice_struct::usbinfo
π int LIBMTP_Set_Track_Name (LIBMTP_mtpdevice_t * device, LIBMTP_track_t * track, const char * newname) π
glow-up time β¨ this function renames a single track. and honestly? it's lowkey simple β it just means the PTP_OPC_ObjectFileName property gets updated, if this is supported by the device. iykyk.
Parameters π
deviceβ a pointer to the device that contains the file.trackβ the track metadata of the track to rename. On success, thefilenamemember is updated. Be aware, that this name can be different thannewnamedepending of device restrictions. π (/srs, don't come for her about it, the device decided)newnameβ the new filename for this object.
Returns π₯
0on success, any other value means failure.
References π¦
LIBMTP_track_struct::filenameLIBMTP_track_struct::filetypeLIBMTP_track_struct::item_id
π int LIBMTP_Track_Exists (LIBMTP_mtpdevice_t * device, uint32_t const id) π
helper function moment π«Ά she just tells you if a track exists on the device. a lil' vibe check, basically.
Parameters πΈ
deviceβ a pointer to the device to get the track from.idβ the track ID of the track to retrieve.
Returns β
TRUE(!=0) if the track exists,FALSE(0) if not.
References π
LIBMTP_mtpdevice_struct::params
π int LIBMTP_Update_Track_Metadata (LIBMTP_mtpdevice_t * device, LIBMTP_track_t const *const metadata) π
this one updates the MTP track object metadata on a single file identified by an object ID β¨ so like, she's not sending anything new, she's just editing the tags on a file that's already there.
Parameters π§
deviceβ a pointer to the device to update the track metadata on.metadataβ a track metadata set to be written to the file. notice that thetrack_idfield of the metadata structure must be correct so that the function can update the right file. If some properties of this metadata are set toNULL(strings) or0(numerical values) they will be discarded and the track will not be tagged with these blank values. (so no, you can't blank out a tag this way, she's just gonna skip it π)
Returns π
0on success, any other value means failure. If some or all of the properties fail to update we will still return success. On some devices (notablyiRiver T30) properties that exist cannot be updated. π yeah. tragic. that's just how she is.
References π
LIBMTP_track_struct::albumLIBMTP_track_struct::artistLIBMTP_track_struct::bitrateLIBMTP_track_struct::bitratetypeLIBMTP_track_struct::composerLIBMTP_track_struct::dateLIBMTP_track_struct::durationLIBMTP_track_struct::filetypeLIBMTP_track_struct::genreLIBMTP_track_struct::item_idLIBMTP_track_struct::nochannelsLIBMTP_mtpdevice_struct::paramsLIBMTP_track_struct::ratingLIBMTP_track_struct::samplerateLIBMTP_track_struct::titleLIBMTP_track_struct::tracknumberLIBMTP_mtpdevice_struct::usbinfoLIBMTP_track_struct::usecountLIBMTP_track_struct::wavecodec
Referenced by π
LIBMTP_Send_Track_From_File_Descriptor(), andLIBMTP_Send_Track_From_Handler().
π Author π
okay so nobody wrote this by hand bestie, and that's the whole tea π« β this page was generated automatically by Doxygen for libmtp from the source code. so if you're out here looking for a single tired human to @ about a typo, there isn't one, the robot did it and the robot does not read replies πβ¨
and that's the whole page, you made it to the end, so proud of you fr fr π₯Ήπ
quick lil recap of the receipts so you always know where this came from: it's tracks(3), it ships with libmtp, and this version is Version 1.1.23 π keep that in your pocket, it's giving main character energy and it's absolutely slay π
πΈπ¦
now go read some tracks bestie, you've got this ππβ
π¦ where this page comes from
- ubuntu stonking: libmtp-doc 1.1.23-1 Β· LGPL-2.0-or-later
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms