Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/faraasaaay/inner/llms.txt

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

The playback API resolves audio streams, manages the play queue, and fetches supplementary content like lyrics and transcripts. All functions are suspend functions returning Result<T>. Token resolution (PoToken, GVS token) is handled automatically based on the configured authState.

​
player(...)

Resolves stream data for a single video ID using the specified client. This is the primary method for obtaining a playable stream URL. 
import com.tamed.music.innertube.YouTube
import com.tamed.music.innertube.models.YouTubeClient

val result = YouTube.player(
    videoId = "dQw4w9WgXcQ",
    playlistId = "RDdQw4w9WgXcQ",
    client = YouTubeClient.WEB_REMIX,
)
result.onSuccess { response ->
    val streamUrl = response.streamingData?.adaptiveFormats
        ?.maxByOrNull { it.bitrate ?: 0 }
        ?.url
    println("Stream URL: $streamUrl")
}
​
videoId
String
required
The YouTube video ID to resolve.
​
playlistId
String?
default:"null"
Optional playlist context. Used by some clients to unlock radio or automix streams.
​
client
YouTubeClient
required
The InnerTube client to use. Different clients return different stream formats and quality levels. Common choices: YouTubeClient.WEB_REMIX, YouTubeClient.ANDROID_MUSIC, YouTubeClient.TVHTML5.
​
signatureTimestamp
Int?
default:"null"
Required by clients where useSignatureTimestamp = true (e.g. WEB_REMIX, TVHTML5). Obtained from the player JavaScript. Pass null for clients that do not need it.
​
poToken
String?
default:"null"
Explicit PoToken for this single call. Overrides the auth state’s poTokenPlayer for this request. Set to null to use the value derived from the configured authState.
​
setLogin
Boolean
default:"true"
Whether to attach the session cookie to this player request. Set to false for anonymous stream resolution.
​
authState
PlaybackAuthState
default:"currentPlaybackAuthState()"
Auth state snapshot to use for this call. Defaults to the current global state. Useful when you need to resolve a stream with a specific auth context without changing global state.
​
PlayerResponse
object
The raw InnerTube player response, including streamingData (adaptive formats, HLS manifests), videoDetails, and playbackTracking URLs.
PoToken resolution follows this precedence for player requests: explicit poToken argument → authState.poTokenPlayer → authState.poToken. The token is only attached when webClientPoTokenEnabled = true and the client requires service integrity (web-family clients).

​
registerPlayback(playlistId, playbackTracking, authState)

Reports a playback start event to YouTube’s analytics endpoint. Call this after a stream begins playing to satisfy YouTube Music’s playback tracking requirements. 
val playerResponse = YouTube.player(
    videoId = "dQw4w9WgXcQ",
    client = YouTubeClient.WEB_REMIX
).getOrThrow()

val trackingUrl = playerResponse.playbackTracking?.videostatsPlaybackUrl?.baseUrl
if (trackingUrl != null) {
    YouTube.registerPlayback(
        playlistId = "RDdQw4w9WgXcQ",
        playbackTracking = trackingUrl
    )
}
​
playlistId
String?
default:"null"
Optional playlist context for the playback report.
​
playbackTracking
String
required
The base URL from PlayerResponse.playbackTracking.videostatsPlaybackUrl.baseUrl. Inner rewrites the domain to music.youtube.com automatically.
​
authState
PlaybackAuthState
default:"currentPlaybackAuthState()"
Auth state snapshot used to resolve the GVS PoToken (pot=) appended to the tracking URL.

​
next(endpoint, continuation, followAutomixPreview)

Fetches the queue for a watch session — the list of upcoming songs — along with endpoints for lyrics and related content. 
import com.tamed.music.innertube.models.WatchEndpoint

val result = YouTube.next(
    endpoint = WatchEndpoint(
        videoId = "dQw4w9WgXcQ",
        playlistId = "RDdQw4w9WgXcQ"
    )
).getOrThrow()

result.items.forEach { println(it.title) }
println("Lyrics endpoint: ${result.lyricsEndpoint}")
println("Related endpoint: ${result.relatedEndpoint}")
​
endpoint
WatchEndpoint
required
Contains videoId and optional playlistId, playlistSetVideoId, index, and params fields that define the watch context.
​
continuation
String?
default:"null"
Continuation token to load the next page of queue items.
​
followAutomixPreview
Boolean
default:"true"
When true, Inner automatically follows automix/radio preview endpoints at the end of the playlist panel, seamlessly extending the queue. Set to false if you want to page through a playlist’s own continuation first.
​
NextResult
object

​
queue(videoIds, playlistId)

Resolves track metadata for a list of video IDs or a playlist ID in a single request. 
// Resolve metadata for specific video IDs
val songs = YouTube.queue(
    videoIds = listOf("dQw4w9WgXcQ", "oHg5SJYRHA0")
).getOrThrow()
songs.forEach { println("${it.title} — ${it.duration}") }

// Or resolve an entire playlist
val playlistSongs = YouTube.queue(playlistId = "PLxxx").getOrThrow()
​
videoIds
List<String>?
default:"null"
List of video IDs to resolve. Must not exceed YouTube.MAX_GET_QUEUE_SIZE (1000).
​
playlistId
String?
default:"null"
Playlist ID to resolve. At least one of videoIds or playlistId must be non-null.
YouTube.MAX_GET_QUEUE_SIZE = 1000 — passing more than 1000 videoIds triggers an assertion error. Split large lists into batches if needed.

​
lyrics(endpoint)

Fetches the lyrics text for a track. 
val nextResult = YouTube.next(WatchEndpoint(videoId = "dQw4w9WgXcQ")).getOrThrow()
val lyricsEndpoint = nextResult.lyricsEndpoint ?: return

val lyrics = YouTube.lyrics(lyricsEndpoint).getOrThrow()
println(lyrics ?: "No lyrics available")
​
endpoint
BrowseEndpoint
required
The lyrics browse endpoint. Obtain from NextResult.lyricsEndpoint.
​
String?
String?
Lyrics text as a single string, or null if the track has no lyrics.
Fetches the related content page for a track — similar songs, albums, artists, and playlists. 
val nextResult = YouTube.next(WatchEndpoint(videoId = "dQw4w9WgXcQ")).getOrThrow()
val relatedEndpoint = nextResult.relatedEndpoint ?: return

val related = YouTube.related(relatedEndpoint).getOrThrow()
println("Related songs: ${related.songs.size}")
println("Related albums: ${related.albums.size}")
​
endpoint
BrowseEndpoint
required
The related browse endpoint. Obtain from NextResult.relatedEndpoint.
​
RelatedPage
object

​
transcript(videoId)

Fetches the full timestamped transcript for a video. 
val transcript = YouTube.transcript("dQw4w9WgXcQ").getOrThrow()
// Each line is formatted as [mm:ss.mmm]text
println(transcript)
​
videoId
String
required
The YouTube video ID.
​
String
String
Transcript formatted as newline-separated [mm:ss.mmm]text entries.

​
getMediaInfo(videoId)

Fetches extended metadata for a video including author details, view count, like/dislike counts, and description. 
val info = YouTube.getMediaInfo("dQw4w9WgXcQ").getOrThrow()
println("Title: ${info.title}")
println("Author: ${info.author} (${info.subscribers})")
println("Views: ${info.viewCount}")
println("Likes: ${info.like} / Dislikes: ${info.dislike}")
println("Uploaded: ${info.uploadDate}")
​
MediaInfo
object
The dislike field is sourced from the third-party ReturnYouTubeDislike API, not from YouTube directly.

​
visitorData()

Fetches a fresh visitorData token by parsing the YouTube Music service worker JavaScript. 
val token = YouTube.visitorData().getOrThrow()
YouTube.visitorData = token
println("Visitor data: $token")
​
String
String
A visitorData token matching the pattern ^Cg[t|s].... Store this value in YouTube.visitorData to use it in subsequent requests.

Build docs developers (and LLMs) love

Get started for freeTalk to us