playlists(3)

📦
version 1.1.23 · 6 versions
, in ubuntu stonking

💖 NAME 💖

okay bestie, listen up — this is libmtp - playlists 🎧✨ like, everything you need to know about making, grabbing, renaming and yeeting playlists on your MTP device. the manual page is playlists(3), and it ships with libmtp. iykyk 💅

🦋 SYNOPSIS 🦋

✨ Functions ✨

here's the whole squad, fr fr:

LIBMTP_playlist_t * LIBMTP_new_playlist_t (void)
void LIBMTP_destroy_playlist_t (LIBMTP_playlist_t *)
LIBMTP_playlist_t * LIBMTP_Get_Playlist_List (LIBMTP_mtpdevice_t *)
LIBMTP_playlist_t * LIBMTP_Get_Playlist (LIBMTP_mtpdevice_t *, uint32_t const)
int LIBMTP_Create_New_Playlist (LIBMTP_mtpdevice_t *, LIBMTP_playlist_t *const)
int LIBMTP_Update_Playlist (LIBMTP_mtpdevice_t *, LIBMTP_playlist_t *const)
int LIBMTP_Set_Playlist_Name (LIBMTP_mtpdevice_t *, LIBMTP_playlist_t *, const char *)

🌸 Detailed Description 🌸

lowkey this is where all the lore lives. scroll down for the function-by-function breakdown, bestie 🫶

👑 Function Documentation 👑

🎀 int LIBMTP_Create_New_Playlist (LIBMTP_mtpdevice_t * device, LIBMTP_playlist_t *const metadata)

this routine creates a whole new playlist out of the metadata you hand it. and if the tracks field of that metadata has a track listing in it? those tracks get added to the playlist too. slay ✨

Parameters

  • device — a pointer to the device you're creating the new playlist on 💖
  • metadata — the metadata for the new playlist. if this function exits with success, the playlist_id field of this struct will contain the brand new playlist ID of the playlist 👑
    • metadata->parent_id should be set to the parent (e.g. folder) to store this track in. since some devices are a lil picky about where files get placed, a default folder will be chosen if libmtp has detected one for the current filetype and this parameter is set to 0. and if this is 0 and no default folder can be found? the file gets stored in the root folder. periodt.
    • metadata->storage_id should be set to the storage you want (e.g. memory card or whatever your device presents) to store this track in. setting this to 0 will store the track on the primary storage 🧚

Returns

0 on success, any other value means failure. no cap.

See also

LIBMTP_Update_Playlist()

LIBMTP_Delete_Object()

References

LIBMTP_mtpdevice_struct::default_music_folder, LIBMTP_mtpdevice_struct::default_playlist_folder, LIBMTP_playlist_struct::name, LIBMTP_playlist_struct::no_tracks, LIBMTP_playlist_struct::parent_id, LIBMTP_playlist_struct::playlist_id, LIBMTP_playlist_struct::storage_id, LIBMTP_playlist_struct::tracks, and LIBMTP_mtpdevice_struct::usbinfo. 💜

🩰 void LIBMTP_destroy_playlist_t (LIBMTP_playlist_t * playlist)

this one destroys a playlist metadata structure and deallocates the memory it was using, including any strings. it's giving closure 😭

⚠️ never use a track metadata structure again after calling this function on it. literally never. it's gone, bestie, it's in the void 💀

Parameters

  • playlist — the playlist metadata to destroy 🥀

See also

LIBMTP_new_playlist_t()

References

LIBMTP_playlist_struct::name, and LIBMTP_playlist_struct::tracks.

🦄 LIBMTP_playlist_t * LIBMTP_Get_Playlist (LIBMTP_mtpdevice_t * device, uint32_t const plid)

this function retrieves an individual playlist from the device. just the one. your main character playlist 💅

Parameters

  • device — a pointer to the device to get the playlist from 🎧
  • plid — the unique ID of the playlist to retrieve 🔑

Returns

a valid playlist metadata post or NULL on failure.

See also

LIBMTP_Get_Playlist_List()

References

LIBMTP_new_playlist_t(), LIBMTP_playlist_struct::name, LIBMTP_playlist_struct::no_tracks, LIBMTP_mtpdevice_struct::params, LIBMTP_playlist_struct::parent_id, LIBMTP_playlist_struct::playlist_id, LIBMTP_playlist_struct::storage_id, LIBMTP_playlist_struct::tracks, and LIBMTP_mtpdevice_struct::usbinfo. ✨

🌈 LIBMTP_playlist_t * LIBMTP_Get_Playlist_List (LIBMTP_mtpdevice_t * device)

this function returns a list of the playlists available on the device. like, the whole roster 🌟

Typical usage:

Parameters

  • device — a pointer to the device to get the playlist listing from 💖

Returns

a playlist list on success, else NULL. and if there are no playlists on the device, NULL will be returned as well. (yes, same answer, different vibe 🙈)

See also

LIBMTP_Get_Playlist()

References

LIBMTP_new_playlist_t(), LIBMTP_playlist_struct::name, LIBMTP_playlist_struct::next, LIBMTP_playlist_struct::no_tracks, LIBMTP_mtpdevice_struct::params, LIBMTP_playlist_struct::parent_id, LIBMTP_playlist_struct::playlist_id, LIBMTP_playlist_struct::storage_id, LIBMTP_playlist_struct::tracks, and LIBMTP_mtpdevice_struct::usbinfo. 🎀

🧚 LIBMTP_playlist_t * LIBMTP_new_playlist_t (void )

this creates a new playlist metadata structure and allocates memory for it. ✨

⚠️ heads up bestie: if you add strings to this structure, they will be freed by the corresponding LIBMTP_destroy_playlist_t operation later — so be careful and use strdup() when assigning strings, e.g.:
LIBMTP_playlist_t *pl = LIBMTP_new_playlist_t();
pl->name = strdup(str);
....
LIBMTP_destroy_playlist_t(pl);

Returns

a pointer to the newly allocated metadata structure 🫶

See also

LIBMTP_destroy_playlist_t()

Referenced by

LIBMTP_Get_Playlist(), and LIBMTP_Get_Playlist_List().

💜 int LIBMTP_Set_Playlist_Name (LIBMTP_mtpdevice_t * device, LIBMTP_playlist_t * playlist, const char * newname)

this function renames a single playlist object file holder. what that actually means? it just updates the PTP_OPC_ObjectFileName property, if the device supports it. the playlist filename should nominally end with an extension like ".pla" 📁

🚨 NOTE: if you want to change the metadata the device displays about a playlist, you must not use this function — use LIBMTP_Update_Playlist() instead! fr fr, wrong function, wrong energy 💀

Parameters

  • device — a pointer to the device that contains the file 📱
  • playlist — the playlist metadata of the playlist to rename. on success, the name member is updated. be aware that this name can be different from newname depending on device restrictions 🙃
  • newname — the new name for this object ✏️

Returns

0 on success, any other value means failure.

See also

LIBMTP_Update_Playlist()

References

LIBMTP_playlist_struct::name, and LIBMTP_playlist_struct::playlist_id.

🌸 int LIBMTP_Update_Playlist (LIBMTP_mtpdevice_t * device, LIBMTP_playlist_t *const metadata)

this routine updates a playlist based on the metadata supplied. and if the tracks field of the metadata contains a track listing, those tracks get added to the playlist in place of the ones already there — i.e. the previous track listing will be deleted. out with the old, in with the new, periodt 💅

and for Samsung devices? the playlist id (metadata->playlist_id) is likely to change. iconic behavior honestly 😭

Parameters

  • device — a pointer to the device to create the new playlist on 🎧
  • metadata — the metadata for the playlist to be updated. notice that the field playlist_id must contain the appropriate playlist ID. the playlist ID may be modified to a new playlist ID by the time the function returns, since edit-in-place is not always possible 🔄

Returns

0 on success, any other value means failure.

See also

LIBMTP_Create_New_Playlist()

LIBMTP_Delete_Object()

References

LIBMTP_playlist_struct::name, LIBMTP_playlist_struct::no_tracks, LIBMTP_playlist_struct::playlist_id, LIBMTP_playlist_struct::tracks, and LIBMTP_mtpdevice_struct::usbinfo. 🌈

🖋️ Author 🖋️

Generated automatically by Doxygen for libmtp from the source code. (not a human, just a very diligent robot 🫡✨)

and that's the whole page, bestie!! 🎉💖 this was libmtp, Version 1.1.23, chillin' under playlists(3) — go forth and build the most iconic playlists, no cap 👑🎀🦋

📦 where this page comes from