YTItem sealed class and content model reference

Every piece of content returned by InnerTube browse, search, and player endpoints is represented as a subclass of the YTItem sealed class. The sealed hierarchy lets you exhaustively branch on content type at compile time while sharing a common contract — every item has an id, a title, an optional thumbnail, an explicit flag, and a shareLink that deep-links into YouTube Music. Six concrete subclasses cover the full range of YouTube Music content: SongItem, AlbumItem, ArtistItem, PlaylistItem, PodcastItem, and EpisodeItem.

`YTItem` (sealed class)

The abstract base for all InnerTube content items. All fields are abstract and must be implemented by each subclass.

sealed class YTItem {
    abstract val id: String
    abstract val title: String
    abstract val thumbnail: String?
    abstract val explicit: Boolean
    abstract val shareLink: String
}

String

required

Unique identifier for the item. For songs and episodes this is a YouTube video ID; for albums, playlists, artists, and podcasts it is a browse or playlist ID.

title

String

required

Display title of the item as returned by the InnerTube API.

thumbnail

String?

required

URL of the item’s thumbnail image. null when the API does not supply one (for example, some artist results).

explicit

Boolean

required

true when the item carries an explicit content badge (MUSIC_EXPLICIT_BADGE). Always false for types that cannot be explicit (artists, playlists, podcasts).

Canonical music.youtube.com URL for sharing the item. Computed from id without a network call.

`SongItem`

Represents a track — either an audio-only song (MUSIC_VIDEO_TYPE_ATV) or a music video. The computed property isVideoSong distinguishes the two at runtime.

data class SongItem(
    override val id: String,
    override val title: String,
    val artists: List<Artist>,
    val album: Album? = null,
    val duration: Int? = null,
    val musicVideoType: String? = null,
    val chartPosition: Int? = null,
    val chartChange: String? = null,
    override val thumbnail: String,
    override val explicit: Boolean = false,
    val endpoint: WatchEndpoint? = null,
    val setVideoId: String? = null,
    val libraryAddToken: String? = null,
    val libraryRemoveToken: String? = null,
    val historyRemoveToken: String? = null,
    val isEpisode: Boolean = false,
    val uploadEntityId: String? = null,
) : YTItem()

String

required

YouTube video ID.

title

String

required

Track title.

artists

List<Artist>

required

One or more performing artists. Each Artist carries a name and an optional channel id.

album

Album?

Album the track belongs to. null for standalone singles or when the API omits the album link. Each Album carries a name and a browse id.

duration

Int?

Track length in seconds. null when the renderer does not include duration text (e.g., some home-feed cards).

musicVideoType

String?

Raw InnerTube musicVideoType string such as MUSIC_VIDEO_TYPE_ATV (audio) or MUSIC_VIDEO_TYPE_OMV (official music video). null when not present in the renderer.

chartPosition

Int?

Numeric chart rank. Only populated for items sourced from a ChartsPage response.

chartChange

String?

Chart trend indicator string (e.g., "UP", "DOWN", "SAME"). Only populated for items sourced from a ChartsPage response.

thumbnail

String

required

Thumbnail URL. Non-nullable for songs — the parser returns null (drops the item) if the thumbnail is missing.

explicit

Boolean

true when the track carries a MUSIC_EXPLICIT_BADGE. Defaults to false.

endpoint

WatchEndpoint?

Preferred playback endpoint taken from the overlay play button. May differ from the item’s own id in playlist contexts.

setVideoId

String?

Playlist-scoped video ID used when adding or removing the item from a user playlist.

libraryAddToken

String?

Feedback token sent to the feedback endpoint to add this song to the user’s library (Like). Sourced from a toggle menu item in its default state.

libraryRemoveToken

String?

Feedback token sent to the feedback endpoint to remove this song from the user’s library (Unlike). Sourced from a toggle menu item in its toggled state.

historyRemoveToken

String?

Feedback token for REMOVE_FROM_HISTORY. Only present on items returned inside a HistoryPage.

isEpisode

Boolean

true when the song item was created from a podcast episode renderer. Defaults to false.

uploadEntityId

String?

Entity ID for user-uploaded songs, extracted from the musicDeletePrivatelyOwnedEntityCommand in the item menu. null for standard catalogue tracks.

Computed property

isVideoSong

Boolean

true when musicVideoType is non-null and is not MUSIC_VIDEO_TYPE_ATV. Use this to filter or display music-video items differently from audio-only tracks.

`AlbumItem`

Represents a release (album, EP, or single). InnerTube identifies albums by a browseId (for the detail page) and a playlistId (for the track listing).

data class AlbumItem(
    val browseId: String,
    val playlistId: String,
    override val id: String = browseId,
    override val title: String,
    val artists: List<Artist>?,
    val year: Int? = null,
    override val thumbnail: String,
    override val explicit: Boolean = false,
) : YTItem()

browseId

String

required

InnerTube browse ID (e.g., MPREb_…) used to navigate to the album detail page.

playlistId

String

required

Playlist ID (e.g., OLAK5uy_…) used for playback and the AlbumPage track-list fetch.

String

required

Alias for browseId. Set automatically from the primary constructor default.

title

String

required

Album title.

artists

List<Artist>?

Contributing artists. null in some contexts (e.g., LibraryAlbumsPage) where the renderer does not include artist links.

year

Int?

Release year as a four-digit integer. Parsed from the last subtitle run; null when absent.

thumbnail

String

required

Thumbnail URL.

explicit

Boolean

true when the album carries a MUSIC_EXPLICIT_BADGE. Defaults to false.

`PlaylistItem`

Represents a user-created or editorial playlist. The explicit property is always false since playlists themselves are never badged.

data class PlaylistItem(
    override val id: String,
    override val title: String,
    val author: Artist?,
    val songCountText: String?,
    override val thumbnail: String?,
    val playEndpoint: WatchEndpoint?,
    val shuffleEndpoint: WatchEndpoint?,
    val radioEndpoint: WatchEndpoint?,
    val isEditable: Boolean = false,
    val isPodcast: Boolean = false,
    val description: String? = null,
    val authorAvatarUrl: String? = null,
) : YTItem()

String

required

Playlist ID with the VL prefix stripped.

title

String

required

Playlist display title.

author

Artist?

Playlist creator. null when the renderer does not provide an author run.

songCountText

String?

Localised track-count string (e.g., "42 songs"). null in contexts that omit this label.

thumbnail

String?

Thumbnail URL. Can be null for some programmatically created playlists.

playEndpoint

WatchEndpoint?

Endpoint for starting sequential playback from the first track.

shuffleEndpoint

WatchEndpoint?

Endpoint for starting shuffled playback.

radioEndpoint

WatchEndpoint?

Endpoint for starting a radio/mix seeded by this playlist.

isEditable

Boolean

true when the authenticated user owns the playlist and the EDIT menu item is present.

isPodcast

Boolean

true when this PlaylistItem was created by PodcastItem.asPlaylistItem(). Used to distinguish podcast show playlists from regular playlists in the UI.

description

String?

Optional free-text description of the playlist.

authorAvatarUrl

String?

URL of the author’s channel avatar image, when supplied by the renderer.

`ArtistItem`

Represents a music artist channel or user channel (profile). The explicit property is always false.

data class ArtistItem(
    override val id: String,
    override val title: String,
    override val thumbnail: String?,
    val channelId: String? = null,
    val playEndpoint: WatchEndpoint? = null,
    val shuffleEndpoint: WatchEndpoint?,
    val radioEndpoint: WatchEndpoint?,
    val isProfile: Boolean = false,
) : YTItem()

String

required

Browse ID of the artist channel (e.g., UCxxxxxx…).

title

String

required

Artist display name.

thumbnail

String?

Artist profile thumbnail URL. May be null for user-channel results.

channelId

String?

Raw YouTube channel ID extracted from the subscribe endpoint. Used for subscription management.

playEndpoint

WatchEndpoint?

Endpoint for the artist’s top-tracks playlist. Not always present in search results.

shuffleEndpoint

WatchEndpoint?

Endpoint for shuffled playback of the artist’s catalogue.

radioEndpoint

WatchEndpoint?

Endpoint for a radio seeded by this artist.

isProfile

Boolean

true when this item was identified as a MUSIC_PAGE_TYPE_USER_CHANNEL rather than a standard artist page (e.g., a podcast host’s profile).

`PodcastItem`

Represents a podcast show. A PodcastItem can be converted to a PlaylistItem for uniform treatment in list views via .asPlaylistItem().

data class PodcastItem(
    override val id: String,
    override val title: String,
    val author: Artist?,
    val episodeCountText: String?,
    override val thumbnail: String?,
    val playEndpoint: WatchEndpoint?,
    val shuffleEndpoint: WatchEndpoint?,
    val libraryAddToken: String? = null,
    val libraryRemoveToken: String? = null,
    val channelId: String? = null,
) : YTItem()

String

required

Browse ID of the podcast show page.

title

String

required

Podcast show title.

author

Artist?

Show host or publisher. null when the renderer omits the subtitle runs.

episodeCountText

String?

Localised episode-count string (e.g., "120 episodes"). Sourced from the last subtitle run.

thumbnail

String?

Show artwork thumbnail URL.

playEndpoint

WatchEndpoint?

Endpoint for sequential playback of the show’s episode list.

shuffleEndpoint

WatchEndpoint?

Endpoint for shuffled playback of the show’s episodes.

libraryAddToken

String?

Feedback token to add this podcast to the user’s library.

libraryRemoveToken

String?

Feedback token to remove this podcast from the user’s library.

channelId

String?

Optional channel ID of the podcast host.

Method

fun PodcastItem.asPlaylistItem(): PlaylistItem

Converts this podcast show into a PlaylistItem so that generic playlist UI components can display it without special-casing. Sets isPodcast = true and maps episodeCountText to songCountText.

`EpisodeItem`

Represents a single podcast episode. Like PodcastItem, episodes can be surfaced as SongItem instances via .asSongItem() for playback in song-oriented contexts.

data class EpisodeItem(
    override val id: String,
    override val title: String,
    val author: Artist?,
    val podcast: Album? = null,
    val duration: Int? = null,
    val publishDateText: String? = null,
    override val thumbnail: String,
    override val explicit: Boolean = false,
    val endpoint: WatchEndpoint? = null,
    val libraryAddToken: String? = null,
    val libraryRemoveToken: String? = null,
    val markAsPlayedToken: String? = null,
    val markAsUnplayedToken: String? = null,
) : YTItem()

String

required

YouTube video ID of the episode.

title

String

required

Episode title.

author

Artist?

Host or publisher. Often null in search results where the podcast itself is the attribution source.

podcast

Album?

The parent podcast show, represented as an Album (name + browse ID). null when the renderer does not include a podcast link.

duration

Int?

Episode length in seconds. Parsed from the last subtitle group; null when absent.

publishDateText

String?

Localised publication date string (e.g., "Jan 2025"). Sourced from the subtitle section immediately before the podcast link.

thumbnail

String

required

Episode thumbnail URL. The parser discards the item if this is missing.

explicit

Boolean

true when the episode carries a MUSIC_EXPLICIT_BADGE. Defaults to false.

endpoint

WatchEndpoint?

Playback endpoint. Falls back to the item’s own watchEndpoint when the overlay play button is absent (common in filtered search results).

libraryAddToken

String?

Feedback token to add this episode to the user’s library.

libraryRemoveToken

String?

Feedback token to remove this episode from the user’s library.

markAsPlayedToken

String?

Feedback token to mark this episode as played in the podcast progress tracker.

markAsUnplayedToken

String?

Feedback token to mark this episode as unplayed.

Method

fun EpisodeItem.asSongItem(): SongItem

Converts the episode to a SongItem with isEpisode = true, mapping author to the artists list and podcast to album. Preserves duration, thumbnail, explicit, endpoint, libraryAddToken, and libraryRemoveToken.

Helper types

`Artist`

data class Artist(
    val name: String,
    val id: String?,
)

name

String

required

Display name of the artist.

String?

Browse ID of the artist channel (UCxxxxxx…). null when the run carries no navigation endpoint (e.g., plain-text artist names on label-uploaded tracks).

`Album`

data class Album(
    val name: String,
    val id: String,
)

name

String

required

Album display name.

String

required

Browse ID of the album (MPREb_…). Used to navigate to the AlbumPage.

Extension functions

Three list-level filter helpers are defined on List<T : YTItem>. All return a new list — the receiver is never mutated.

`filterExplicit`

fun <T : YTItem> List<T>.filterExplicit(enabled: Boolean = true): List<T>

When enabled is true, removes every item whose explicit property is true. Pass false to return the list unchanged (useful for toggling the filter via a user preference).

`filterVideoSongs`

fun <T : YTItem> List<T>.filterVideoSongs(disableVideos: Boolean = false): List<T>

When disableVideos is true, removes every SongItem where isVideoSong == true. All non-SongItem elements and audio-only tracks are always retained.

`filterYoutubeShorts`

fun <T : YTItem> List<T>.filterYoutubeShorts(enabled: Boolean = false): List<T>

When enabled is true, removes every PlaylistItem whose id starts with "SS" — the prefix used by YouTube Shorts playlists. All other item types are always retained.

YouTube Object

Models

YTItem sealed class and content model reference