Inner YTItem sealed class: SongItem, AlbumItem, and more

YTItem is a sealed class that represents all content types returned by Inner. Every item has a common set of base properties plus type-specific fields. All four concrete subtypes — SongItem, AlbumItem, PlaylistItem, and ArtistItem — are data class implementations, making them safe to use in when expressions, copy() calls, and equality checks.

import com.tamed.music.innertube.models.*

Base properties

All YTItem subtypes share the following abstract properties:

String

Unique content identifier. For songs this is the videoId; for albums and artists it is the browseId; for playlists it is the playlistId (without the VL prefix).

title

String

The display title of the content item.

thumbnail

String?

URL of the highest-quality thumbnail image available. May be null for some artist items.

explicit

Boolean

true if the content is marked with an explicit badge (MUSIC_EXPLICIT_BADGE). Always false for PlaylistItem and ArtistItem.

The full YouTube Music share URL for the item. The format differs by subtype — see each subtype section for the exact pattern.

SongItem

Represents a single track on YouTube Music.

String

The YouTube video ID (e.g. "dQw4w9WgXcQ").

title

String

The track title.

artists

List<Artist>

The list of credited artists. Each Artist has:

Show Artist fields

name

String

The artist’s display name.

String?

The artist’s browse ID (e.g. "UCxxxxxx"). May be null for artists without a YouTube Music page.

album

Album?

The album this song belongs to, or null if not available. Album has:

Show Album fields

name

String

The album title.

String

The album’s browse ID (e.g. "MPREb_xxxx").

duration

Int?

Duration of the track in seconds. May be null when parsed from contexts that do not include duration (e.g. artist page song lists).

chartPosition

Int?

Position in a chart ranking, if the song was returned as part of a charts page. null otherwise.

chartChange

String?

Change indicator for the chart position (e.g. "up", "down"). null when not from a charts context.

thumbnail

String

URL of the track’s thumbnail image. Non-nullable for SongItem.

explicit

Boolean

true if the track has an explicit content badge.

endpoint

WatchEndpoint?

The playback endpoint for this track. Contains videoId and optionally playlistId, params, and index. Pass this to a player to begin playback.

setVideoId

String?

A per-entry playlist operation ID. Only populated when the SongItem was parsed from a playlist (via PlaylistPage). Required for operations like removing a specific entry from a playlist.

Always https://music.youtube.com/watch?v={id}.

val song: SongItem = ...
println("${song.title} by ${song.artists.joinToString { it.name }}")
println("Duration: ${song.duration}s")
println("Album: ${song.album?.name}")
println("Share: ${song.shareLink}")

AlbumItem

Represents a full album (studio album, EP, single, or compilation).

browseId

String

The album’s browse ID (e.g. "MPREb_xxxxxxxxxxxx"). Used to fetch full album data via YouTube.album() or PortableInnertube.album().

playlistId

String

The associated playlist ID (e.g. "OLAK5uy_xxxx"). Used to fetch the album’s track listing.

String

Defaults to browseId. Satisfies the YTItem contract.

title

String

The album title.

artists

List<Artist>?

The credited artists. May be null when the album is parsed from carousel renderers that do not include artist subtitle runs.

year

Int?

The release year, parsed from subtitle text. null if not present.

thumbnail

String

URL of the album artwork thumbnail.

explicit

Boolean

true if the album carries an explicit badge.

Always https://music.youtube.com/playlist?list={playlistId}.

val album: AlbumItem = ...
println("${album.title} (${album.year})")
println("Artists: ${album.artists?.joinToString { it.name } ?: "Unknown"}")

PlaylistItem

Represents a user-created or editorial playlist on YouTube Music.

String

The playlist ID without the VL prefix (e.g. "PLxxxxxxxxxxxxxxxxxx").

title

String

The playlist title.

author

Artist?

The playlist creator. The Artist.id field is populated when the author has a linked browse endpoint; otherwise it is null.

songCountText

String?

A human-readable song count string (e.g. "42"), as returned by the API. May be null.

thumbnail

String?

URL of the playlist thumbnail. May be null for some playlist contexts.

playEndpoint

WatchEndpoint?

The watch endpoint for playing the playlist from the beginning.

shuffleEndpoint

WatchEndpoint?

The watch endpoint for shuffling the playlist.

radioEndpoint

WatchEndpoint?

The watch endpoint for starting a radio based on the playlist.

isEditable

Boolean

true when the authenticated user owns and can edit this playlist. Derived from the presence of a musicEditablePlaylistDetailHeaderRenderer in the browse response.

explicit

Boolean

Always false for PlaylistItem.

Always https://music.youtube.com/playlist?list={id}.

ArtistItem

Represents a music artist or channel on YouTube Music.

String

The artist’s browse ID, which is always a channel ID of the form "UCxxxxxxxxxxxxxxxxxxxxxx".

title

String

The artist’s display name.

thumbnail

String?

URL of the artist’s profile image. May be null.

channelId

String?

The YouTube channel ID for the subscribe button, sourced from the subscribeButtonRenderer. May differ from id in some renderer contexts; usually null when parsed from search or carousel renderers.

playEndpoint

WatchEndpoint?

Endpoint to begin playing the artist’s top songs.

shuffleEndpoint

WatchEndpoint?

Endpoint to shuffle the artist’s songs.

radioEndpoint

WatchEndpoint?

Endpoint to start a radio based on the artist.

explicit

Boolean

Always false for ArtistItem.

Always https://music.youtube.com/channel/{id}.

Utility extensions

Two generic extension functions are available on any List<T : YTItem>:

`filterExplicit`

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

When enabled is true (the default), returns a new list with all items where explicit == true removed. When enabled is false, the original list is returned unchanged. Useful for implementing a user-controlled explicit content filter.

val filtered = songs.filterExplicit(enabled = userPrefs.hideExplicit)

`filterVideo`

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

When enabled is true, removes SongItem entries whose endpoint has a musicVideoType of MUSIC_VIDEO_TYPE_OMV (Official Music Video) or MUSIC_VIDEO_TYPE_UGC (user-generated content). Non-song items are always kept. Use this to restrict results to audio-only tracks.

val audioOnly = results.filterVideo(enabled = userPrefs.hideVideos)

Type-checking pattern

Use a when expression to branch on the concrete YTItem subtype:

import com.tamed.music.innertube.models.*

when (val item: YTItem = someItem) {
    is SongItem     -> println("Song: ${item.title} — ${item.duration}s")
    is AlbumItem    -> println("Album: ${item.title} (${item.year})")
    is PlaylistItem -> println("Playlist: ${item.title} by ${item.author?.name}")
    is ArtistItem   -> println("Artist: ${item.title}")
}

Because YTItem is a sealed class, the Kotlin compiler guarantees exhaustiveness — you will get a compile-time warning if a new subtype is added and your when does not cover it.

YouTube Object

Portable API

Data Models

Inner YTItem sealed class: SongItem, AlbumItem, and more

Base properties

SongItem

AlbumItem

PlaylistItem

ArtistItem

Utility extensions

`filterExplicit`

`filterVideo`

Type-checking pattern

Build docs developers (and LLMs) love

YouTube Object

Portable API

Data Models

Documentation Index

​Base properties

​SongItem

​AlbumItem

​PlaylistItem

​ArtistItem

​Utility extensions

​filterExplicit

​filterVideo

​Type-checking pattern

Build docs developers (and LLMs) love

Base properties

SongItem

AlbumItem

PlaylistItem

ArtistItem

Utility extensions

`filterExplicit`

`filterVideo`

Type-checking pattern