Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/faraasaaay/innertube-v1/llms.txt

Use this file to discover all available pages before exploring further.

YTItem is the sealed class at the heart of InnerTube’s content model. Every piece of content returned by search, browse, library, or related-content endpoints is a subclass of YTItem. Because YTItem is sealed, the Kotlin compiler guarantees exhaustive when expressions — you can never forget to handle a content type. The sealed class itself declares five abstract properties that every subtype must implement:
​
id
String
The canonical unique identifier for this content item. For songs and episodes this is a YouTube video ID. For albums it is the browseId. For playlists it is the playlist ID.
​
title
String
The human-readable display title of the item.
​
thumbnail
String?
A URL pointing to the item’s cover art or thumbnail image. May be null for certain artist or playlist results that lack artwork.
​
explicit
Boolean
true when the item carries an explicit content badge from YouTube Music.
​
shareLink
String
A fully-qualified https://music.youtube.com/… URL that can be shared directly with users or opened in a browser.

​
Subclasses

Represents an audio track — either an official song recording (MUSIC_VIDEO_TYPE_ATV) or a music video. The isVideoSong computed property distinguishes between the two.
​
id
String
YouTube video ID (e.g. dQw4w9WgXcQ).
​
title
String
Track title.
​
artists
List<Artist>
One or more contributing artists. See the Artist data class below.
​
album
Album?
The album this song belongs to, or null if unavailable. See the Album data class below.
​
duration
Int?
Track duration in seconds, or null if not present in the response.
​
musicVideoType
String?
Raw musicVideoType string from InnerTube (e.g. MUSIC_VIDEO_TYPE_ATV, MUSIC_VIDEO_TYPE_OMV). null for user-uploaded videos.
​
chartPosition
Int?
Chart ranking position, present when this song was returned as part of a charts page result.
​
chartChange
String?
Direction string indicating chart movement (e.g. "up", "down", "same"), or null when not in a chart context.
​
thumbnail
String
Thumbnail URL. Non-nullable for songs.
​
explicit
Boolean
true if the track carries an explicit badge.
​
endpoint
WatchEndpoint?
The playback endpoint to use when starting this track. May carry playlist context.
​
setVideoId
String?
Used when reordering or removing a song from a playlist. This is the unique position handle in the playlist, not the video ID.
​
libraryAddToken
String?
Feedback token to add this song to the YouTube Music library (Like).
​
libraryRemoveToken
String?
Feedback token to remove this song from the library (Unlike).
​
historyRemoveToken
String?
Feedback token to remove this song from playback history.
​
isEpisode
Boolean
true when this SongItem was created by converting an EpisodeItem via .asSongItem().
​
uploadEntityId
String?
Present for privately-uploaded songs. Used with YouTube.deleteUploadedSong().
Computed property:
PropertyTypeDescription
isVideoSongBooleantrue when musicVideoType is non-null and is not MUSIC_VIDEO_TYPE_ATV. Indicates the result is a music video rather than an audio-only track.
val song: SongItem = ...
if (song.isVideoSong) {
    // Show a video player UI
} else {
    // Show audio player UI with album art
}

​
Artist and Album

Two small data classes appear as nested properties throughout the model:

​
Utility Extension Functions

Three extension functions on List<T : YTItem> let you filter content lists before displaying them, based on user preferences. 
// Remove explicit tracks (pass enabled = true to activate the filter)
val cleanSongs = results.filterExplicit(enabled = userPrefs.filterExplicit)

// Remove music video results, keeping only audio-only songs
val audioOnly = results.filterVideoSongs(disableVideos = userPrefs.audioOnlyMode)

// Remove YouTube Shorts playlists (id prefix "SS")
val noShorts = results.filterYoutubeShorts(enabled = userPrefs.hideShorts)

// Chain them together
val filtered = results
    .filterExplicit(enabled = true)
    .filterVideoSongs(disableVideos = true)
    .filterYoutubeShorts(enabled = true)
filterExplicit(enabled = false) and filterVideoSongs(disableVideos = false) and filterYoutubeShorts(enabled = false) all return the original list unchanged, so you can always pass a boolean preference flag without needing an if check at the call site.

​
Pattern-Matching on YTItem

Because YTItem is a sealed class, when expressions on it are exhaustive. The compiler will warn you if you add a new subtype in the future and forget to handle it. 
fun displayItem(item: YTItem) {
    when (item) {
        is SongItem -> {
            val label = if (item.isVideoSong) "Video" else "Song"
            println("[$label] ${item.title} – ${item.artists.joinToString { it.name }}")
            item.album?.let { println("  Album: ${it.name}") }
        }
        is AlbumItem -> {
            val year = item.year?.let { " ($it)" } ?: ""
            println("[Album] ${item.title}$year – ${item.artists?.firstOrNull()?.name}")
        }
        is ArtistItem -> {
            val type = if (item.isProfile) "Profile" else "Artist"
            println("[$type] ${item.title}")
        }
        is PlaylistItem -> {
            val type = if (item.isPodcast) "Podcast" else "Playlist"
            println("[$type] ${item.title} by ${item.author?.name ?: "Unknown"}")
        }
        is PodcastItem -> {
            println("[Podcast] ${item.title} – ${item.episodeCountText ?: "?"}")
        }
        is EpisodeItem -> {
            println("[Episode] ${item.title} – ${item.publishDateText ?: "Unknown date"}")
        }
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us