Library API methods: likes, history, upload, and song management

The library API provides access to the authenticated user’s personal music library, playback history, likes, subscriptions, and uploaded tracks. Every method requires YouTube.cookie to be set with a valid session. All suspend functions return Result<T>.

Library browsing

`YouTube.library`

Fetches the user’s library using a browse ID and optional tab index.

suspend fun library(browseId: String, tabIndex: Int = 0): Result<LibraryPage>

browseId

String

required

The browse ID of the library section, such as "FEmusic_liked_playlists", "FEmusic_library_landing", or a custom library browse ID.

tabIndex

Int

Zero-based tab index for browse responses with multiple tabs. Defaults to 0.

Return type

Result<LibraryPage>

Result

Show LibraryPage fields

items

List<YTItem>

Library items (songs, albums, playlists, artists).

continuation

String?

Token for additional pages.

Example

YouTube.library("FEmusic_liked_playlists").onSuccess { page ->
    page.items.forEach { println(it.title) }
}

`YouTube.libraryContinuation`

Fetches additional library items from a continuation token.

suspend fun libraryContinuation(continuation: String): Result<LibraryContinuationPage>

continuation

String

required

Token from LibraryPage.continuation.

Return type

Result<LibraryContinuationPage>

Result

Show LibraryContinuationPage fields

items

List<YTItem>

Next page of library items.

continuation

String?

Token for yet another page, or null when exhausted.

`YouTube.libraryRecentActivity`

Fetches the “Recent activity” grid from the library landing page using LibraryFilter.FILTER_RECENT_ACTIVITY. For artist items the function additionally calls YouTube.artist() to enrich playEndpoint.

suspend fun libraryRecentActivity(): Result<LibraryPage>

Return type

Result<LibraryPage>

Result

LibraryPage with items and a null continuation (the activity grid is not paginated).

`LibraryFilter`

An inline value class that wraps encoded continuation tokens accepted by the library browse endpoint.

@JvmInline
value class LibraryFilter(val value: String) {
    companion object {
        val FILTER_RECENT_ACTIVITY     = LibraryFilter("4qmFsgIrEhdGRW11c2ljX2xpYnJhcnlfbGFuZGluZxoQZ2dNR0tnUUlCaEFCb0FZQg%3D%3D")
        val FILTER_RECENTLY_PLAYED     = LibraryFilter("4qmFsgIrEhdGRW11c2ljX2xpYnJhcnlfbGFuZGluZxoQZ2dNR0tnUUlCUkFCb0FZQg%3D%3D")
        val FILTER_PLAYLISTS_ALPHABETICAL   = LibraryFilter("4qmFsgIrEhdGRW11c2ljX2xpa2VkX3BsYXlsaXN0cxoQZ2dNR0tnUUlBUkFBb0FZQg%3D%3D")
        val FILTER_PLAYLISTS_RECENTLY_SAVED = LibraryFilter("4qmFsgIrEhdGRW11c2ljX2xpa2VkX3BsYXlsaXN0cxoQZ2dNR0tnUUlBQkFCb0FZQg%3D%3D")
    }
}

Constant	Sort/filter applied
`FILTER_RECENT_ACTIVITY`	Most recently interacted-with items
`FILTER_RECENTLY_PLAYED`	Recently played tracks
`FILTER_PLAYLISTS_ALPHABETICAL`	Liked playlists sorted A–Z
`FILTER_PLAYLISTS_RECENTLY_SAVED`	Liked playlists sorted by save date

History

`YouTube.musicHistory`

Fetches the user’s full playback history, grouped into date sections.

suspend fun musicHistory(): Result<HistoryPage>

Return type

Result<HistoryPage>

Result

HistoryPage with sections: List<HistoryPage.HistorySection>?. Each section has a date label and a list of SongItems. Each SongItem.historyRemoveToken can be passed to removeHistoryItems().

Example

YouTube.musicHistory().onSuccess { page ->
    page.sections?.forEach { section ->
        println("=== ${section.date} ===")
        section.songs.forEach { println("  ${it.title}") }
    }
}

`YouTube.removeHistoryItems`

Removes one or more items from the playback history using their feedback tokens.

suspend fun removeHistoryItems(feedbackTokens: List<String>): Result<Boolean>

feedbackTokens

List<String>

required

List of tokens from SongItem.historyRemoveToken. Delegates to YouTube.feedback().

Return type

Result<Boolean>

Result

true when the feedback endpoint accepted all tokens.

Like / Unlike

`YouTube.likeVideo`

Likes or un-likes a video.

suspend fun likeVideo(videoId: String, like: Boolean): Result<*>

videoId

String

required

The video ID to like or unlike.

Boolean

required

true to like, false to remove the like.

Example

YouTube.likeVideo("dQw4w9WgXcQ", like = true)

`YouTube.likePlaylist`

Likes or un-likes (saves/unsaves) a playlist.

suspend fun likePlaylist(playlistId: String, like: Boolean): Result<*>

playlistId

String

required

The playlist ID to save or unsave.

Boolean

required

true to save, false to unsave.

`YouTube.subscribeChannel`

Subscribes to or unsubscribes from an artist or podcast channel.

suspend fun subscribeChannel(
    channelId: String,
    subscribe: Boolean,
    params: String? = null,
): Result<*>

channelId

String

required

The channel ID. Obtained from ArtistItem.channelId or PodcastItem.channelId.

true to subscribe, false to unsubscribe.

params

String?

Override the default subscribe params ("EgIIAhgA"). Leave null in most cases.

Example

YouTube.artist("UCT9zcQNlyht7fRlcjmflRSA").onSuccess { page ->
    val channelId = page.artist.channelId ?: return@onSuccess
    YouTube.subscribeChannel(channelId, subscribe = true)
}

Song library management

`YouTube.addSongToLibrary`

Adds a song to the user’s liked-songs library. Internally calls next() to fetch fresh feedback tokens and then submits them via feedback().

suspend fun addSongToLibrary(videoId: String): Result<Boolean>

videoId

String

required

The video ID of the song to add.

Return type

Result<Boolean>

Result

true if the feedback endpoint accepted the add-token.

`YouTube.removeSongFromLibrary`

Removes a song from the user’s liked-songs library. Fetches fresh tokens from next() before submitting.

suspend fun removeSongFromLibrary(videoId: String): Result<Boolean>

videoId

String

required

The video ID of the song to remove.

Return type

Result<Boolean>

Result

true if the feedback endpoint accepted the remove-token.

`YouTube.toggleSongLibrary`

Convenience wrapper that calls addSongToLibrary() or removeSongFromLibrary() based on the addToLibrary flag.

suspend fun toggleSongLibrary(videoId: String, addToLibrary: Boolean): Result<Boolean>

videoId

String

required

The video ID to toggle.

addToLibrary

Boolean

required

true to add, false to remove.

Example

// Toggle based on current library state
val inLibrary = song.libraryAddToken == null  // add token absent = already saved
YouTube.toggleSongLibrary(song.id, addToLibrary = !inLibrary)

Upload

`YouTube.uploadSong`

Uploads a local audio file to the user’s YouTube Music library in a two-step process: initialise the upload, then stream the file bytes to the returned upload URL.

suspend fun uploadSong(
    filename: String,
    data: ByteArray,
    onProgress: ((Float) -> Unit)? = null,
): Result<Boolean>

filename

String

required

The filename including extension (e.g. "track.flac"). Must use one of the supported extensions listed in SUPPORTED_UPLOAD_TYPES.

data

ByteArray

required

The raw file bytes. Must not exceed MAX_UPLOAD_SIZE (300 MB).

onProgress

((Float) -> Unit)?

Optional progress callback invoked with a value from 0.0 (started) to 1.0 (complete). The first 5% of progress represents upload initialisation; the remaining 95% tracks actual byte transfer.

Return type

Result<Boolean>

Result

true when the server responds with upload status "final".

Constants

Constant	Value	Description
`YouTube.SUPPORTED_UPLOAD_TYPES`	`["mp3", "m4a", "wma", "flac", "ogg"]`	Accepted file extensions.
`YouTube.MAX_UPLOAD_SIZE`	`314572800L`	Maximum file size in bytes (300 MB).

Example

val file = File("song.flac")
require(file.extension in YouTube.SUPPORTED_UPLOAD_TYPES)
require(file.length() <= YouTube.MAX_UPLOAD_SIZE)

YouTube.uploadSong(
    filename = file.name,
    data = file.readBytes(),
    onProgress = { progress ->
        println("Upload: ${(progress * 100).toInt()}%")
    },
).onSuccess { ok ->
    if (ok) println("Upload complete.")
}

`YouTube.deleteUploadedSong`

Deletes a previously uploaded song from the user’s private library.

suspend fun deleteUploadedSong(entityId: String): Result<Boolean>

entityId

String

required

The upload entity ID of the song. Available as SongItem.uploadEntityId on items returned by library browse responses for privately-owned uploads.

Return type

Result<Boolean>

Result

true when the deletion request was accepted.

Example

uploadedSong.uploadEntityId?.let { entityId ->
    YouTube.deleteUploadedSong(entityId).onSuccess {
        println("Uploaded song deleted.")
    }
}

YouTube Object

Models

Library API methods: likes, history, upload, and song management

Library browsing

`YouTube.library`

`YouTube.libraryContinuation`

`YouTube.libraryRecentActivity`

`LibraryFilter`

History

`YouTube.musicHistory`

`YouTube.removeHistoryItems`

Like / Unlike

`YouTube.likeVideo`

`YouTube.likePlaylist`

`YouTube.subscribeChannel`

Song library management

`YouTube.addSongToLibrary`

`YouTube.removeSongFromLibrary`

`YouTube.toggleSongLibrary`

Upload

`YouTube.uploadSong`

`YouTube.deleteUploadedSong`

Build docs developers (and LLMs) love

YouTube Object

Models

Documentation Index

​Library browsing

​YouTube.library

​YouTube.libraryContinuation

​YouTube.libraryRecentActivity

​LibraryFilter

​History

​YouTube.musicHistory

​YouTube.removeHistoryItems

​Like / Unlike

​YouTube.likeVideo

​YouTube.likePlaylist

​Subscribe / Unsubscribe

​YouTube.subscribeChannel

​Song library management

​YouTube.addSongToLibrary

​YouTube.removeSongFromLibrary

​YouTube.toggleSongLibrary

​Upload

​YouTube.uploadSong

​YouTube.deleteUploadedSong

Build docs developers (and LLMs) love

Library browsing

`YouTube.library`

`YouTube.libraryContinuation`

`YouTube.libraryRecentActivity`

`LibraryFilter`

History

`YouTube.musicHistory`

`YouTube.removeHistoryItems`

Like / Unlike

`YouTube.likeVideo`

`YouTube.likePlaylist`

Subscribe / Unsubscribe

`YouTube.subscribeChannel`

Song library management

`YouTube.addSongToLibrary`

`YouTube.removeSongFromLibrary`

`YouTube.toggleSongLibrary`

Upload

`YouTube.uploadSong`

`YouTube.deleteUploadedSong`