YTItem Sealed Class and Content Type Models Reference

YTItem is the sealed base class for every content type returned by InnerTube. All search results, browse items, playlist entries, and artist section contents are one of its four concrete subtypes: SongItem, AlbumItem, PlaylistItem, or ArtistItem.

`sealed class YTItem`

Abstract fields shared by every subtype.

Field	Type	Description
`id`	`String`	Unique identifier for the item (videoId, browseId, or playlistId depending on subtype)
`title`	`String`	Human-readable display name
`thumbnail`	`String?`	URL of the item’s thumbnail image
`explicit`	`Boolean`	Whether the content is marked as explicit
`shareLink`	`String`	Computed shareable URL for the item

`data class SongItem : YTItem`

Represents a single track — either an audio-only song (ATV) or a music video.

Field	Type	Description
`id`	`String`	YouTube video ID (`videoId`)
`title`	`String`	Track title
`artists`	`List<Artist>`	One or more artists credited on this track
`album`	`Album?`	Album the track belongs to, or `null` for singles/orphans
`duration`	`Int?`	Track length in seconds, or `null` if unavailable
`musicVideoType`	`String?`	Raw music video type string from the API (e.g. `"MUSIC_VIDEO_TYPE_ATV"`)
`chartPosition`	`Int?`	Ranking position when returned in a charts context
`chartChange`	`String?`	Chart trend indicator (e.g. `"UP"`, `"DOWN"`, `"SAME"`)
`thumbnail`	`String`	Thumbnail URL (non-null for songs)
`explicit`	`Boolean`	Whether the track is marked explicit (default `false`)
`endpoint`	`WatchEndpoint?`	Watch endpoint for initiating playback
`setVideoId`	`String?`	Playlist-scoped ID used for playlist mutation operations
`libraryAddToken`	`String?`	Opaque token for adding the track to the library
`libraryRemoveToken`	`String?`	Opaque token for removing the track from the library
`historyRemoveToken`	`String?`	Opaque token for removing the track from history
`viewCountText`	`String?`	Formatted view count string (e.g. `"1.2M views"`)

Computed Properties

Property	Type	Description
`isVideoSong`	`Boolean`	`true` when `musicVideoType` is non-null and is not `MUSIC_VIDEO_TYPE_ATV` — i.e. this is a music video, not an audio-only track
`shareLink`	`String`	`https://music.youtube.com/watch?v={id}`

`data class AlbumItem : YTItem`

Represents a full album or EP.

Field	Type	Description
`browseId`	`String`	Browse ID used to fetch the full album page (e.g. `MPREb_…`)
`playlistId`	`String`	Playlist ID used to stream all album tracks
`id`	`String`	Defaults to `browseId`
`title`	`String`	Album title
`artists`	`List<Artist>?`	Album artist(s), may be `null` in some contexts
`year`	`Int?`	Release year, if available
`thumbnail`	`String`	Album artwork URL
`explicit`	`Boolean`	Whether the album is marked explicit (default `false`)
`description`	`String?`	Album description text, if available
`shareLink`	`String`	`https://music.youtube.com/playlist?list={playlistId}`

`data class PlaylistItem : YTItem`

Represents a user-created or auto-generated playlist.

Field	Type	Description
`id`	`String`	Playlist ID (without `VL` prefix)
`title`	`String`	Playlist title
`author`	`Artist?`	The playlist’s owner or creator
`songCountText`	`String?`	Formatted song count (e.g. `"42 songs"`)
`thumbnail`	`String?`	Playlist cover thumbnail URL
`playEndpoint`	`WatchEndpoint?`	Endpoint to begin sequential playback
`shuffleEndpoint`	`WatchEndpoint?`	Endpoint to begin shuffle playback
`radioEndpoint`	`WatchEndpoint?`	Endpoint to start a radio based on this playlist
`isEditable`	`Boolean`	Whether the current user can modify this playlist (default `false`)
`description`	`String?`	Playlist description text, if available
`explicit`	`Boolean`	Always `false` — playlists do not carry explicit flags
`shareLink`	`String`	`https://music.youtube.com/playlist?list={id}`

`data class ArtistItem : YTItem`

Represents a YouTube Music artist or channel.

Field	Type	Description
`id`	`String`	Artist browse ID (e.g. `UCxxxxxx`)
`title`	`String`	Artist display name
`thumbnail`	`String?`	Artist profile image URL
`channelId`	`String?`	YouTube channel ID, if available
`playEndpoint`	`WatchEndpoint?`	Endpoint to play the artist’s top songs
`shuffleEndpoint`	`WatchEndpoint?`	Endpoint to shuffle the artist’s songs
`radioEndpoint`	`WatchEndpoint?`	Endpoint to start an artist radio
`subtext`	`String?`	Secondary text shown beneath the name (e.g. subscriber count or genre)
`explicit`	`Boolean`	Always `false`
`shareLink`	`String`	`https://music.youtube.com/channel/{id}`

`data class Artist`

A lightweight artist reference used inside SongItem and AlbumItem. Not the same as ArtistItem.

Field	Type	Description
`name`	`String`	Artist display name
`id`	`String?`	Browse ID of the artist, or `null` if not linkable

`data class Album`

A lightweight album reference used inside SongItem.

Field	Type	Description
`name`	`String`	Album display name
`id`	`String`	Browse ID of the album (always present)

Extension Functions

Three filter extensions are defined on List<T : YTItem> for common content-filtering scenarios.

`filterExplicit`

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

Removes items where explicit == true when enabled is true. Pass enabled = false to disable filtering (returns the original list unchanged).

`filterVideoSongs`

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

Removes SongItem entries where isVideoSong == true when disableVideos is true. Useful for music-only playback modes.

`filterYoutubeShorts`

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

Removes PlaylistItem entries whose ID starts with "SS" (YouTube Shorts playlists) when enabled is true. Disabled by default.

Pattern Matching Example

Use a when expression to dispatch on the concrete subtype:

fun handleItem(item: YTItem) {
    when (item) {
        is SongItem -> {
            println("Song: ${item.title} by ${item.artists.joinToString { it.name }}")
            println("Duration: ${item.duration}s, isVideoSong: ${item.isVideoSong}")
            println("Share: ${item.shareLink}")
        }
        is AlbumItem -> {
            println("Album: ${item.title} (${item.year})")
            println("Browse ID: ${item.browseId}, Playlist ID: ${item.playlistId}")
        }
        is PlaylistItem -> {
            println("Playlist: ${item.title} — ${item.songCountText}")
            println("Editable: ${item.isEditable}")
        }
        is ArtistItem -> {
            println("Artist: ${item.title}")
            println("Share: ${item.shareLink}")
        }
    }
}

Applying Filters

val items: List<YTItem> = YouTube.search("lofi beats").getOrNull()?.items ?: emptyList()

val filtered = items
    .filterExplicit(enabled = true)          // remove explicit tracks
    .filterVideoSongs(disableVideos = true)  // audio-only
    .filterYoutubeShorts(enabled = true)     // no Shorts playlists

YouTube Object

Data Models

Utilities

YTItem Sealed Class and Content Type Models Reference

`sealed class YTItem`

`data class SongItem : YTItem`

Computed Properties

`data class AlbumItem : YTItem`

`data class PlaylistItem : YTItem`

`data class ArtistItem : YTItem`

`data class Artist`

`data class Album`

Extension Functions

`filterExplicit`

`filterVideoSongs`

`filterYoutubeShorts`

Pattern Matching Example

Applying Filters

Build docs developers (and LLMs) love

YouTube Object

Data Models

Utilities

Documentation Index

​sealed class YTItem

​data class SongItem : YTItem

​Computed Properties

​data class AlbumItem : YTItem

​data class PlaylistItem : YTItem

​data class ArtistItem : YTItem

​data class Artist

​data class Album

​Extension Functions

​filterExplicit

​filterVideoSongs

​filterYoutubeShorts

​Pattern Matching Example

​Applying Filters

Build docs developers (and LLMs) love

`sealed class YTItem`

`data class SongItem : YTItem`

Computed Properties

`data class AlbumItem : YTItem`

`data class PlaylistItem : YTItem`

`data class ArtistItem : YTItem`

`data class Artist`

`data class Album`

Extension Functions

`filterExplicit`

`filterVideoSongs`

`filterYoutubeShorts`

Pattern Matching Example

Applying Filters