playlists(3)

📦 version 1.1.23, in arch rolling

💖 playlists(3) — the audio/video playlist management API 💖

okay bestie, so this is the <pink>playlists</pink> page from your fave library functions manual, and it's literally the whole audio/video playlist management API. no cap, this is the group chat where every playlist function gets introduced. 🎀

✨ SYNOPSIS ✨

🦋 Functions

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 🌸

💜 Function Documentation 💜

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

this routine creates a brand new playlist based on the metadata you hand it. and if the tracks field of that metadata has a track listing in it, bestie, 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 the function exits successfully, the playlist_id field of this struct will hold the 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 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 to 0. if this is 0 and no default folder can be found, the file will be stored in the root folder.
    • metadata->storage_id should be set to the desired storage (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. periodt.

🔥 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 destroys a playlist metadata structure and deallocates all the memory it was using, including any strings. 🫶

⚠️ never use a track metadata structure again after calling this function on it. like, ever. it's giving "delete and don't look back" and the memory is gone gone.

🎀 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 one individual playlist from the device. main character playlist energy, honestly. ✨

🎀 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 all the playlists available on the device. typical usage:

🎀 Parameters

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

💀 Returns

a playlist list on success, else NULL. and ngl, if there are no playlists on the device, NULL will be returned as well. 😭

🔥 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. 🎀

notice that 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, like this:

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. which simply means the PTP_OPC_ObjectFileName property gets updated, 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!

🎀 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 than 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. 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. 🔥

💀 for Samsung devices the playlist id (metadata->playlist_id) is likely to change. iykyk.

🎀 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 me being auto-generated by a robot and still serving looks 💅✨

and that's the whole page, bestie — this was <pink>libmtp</pink> Version 1.1.23, and the page is playlists(3). go forth and manage those playlists, you iconic little icon 👑🎀🦋

📦 where this page comes from