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.

The player API resolves the playback queue, retrieves streaming manifests, fetches rich video metadata, and manages playback telemetry. YouTube.next(), YouTube.player(), YouTube.queue(), and the helper methods below are all suspend functions that return Result<T>.

​
YouTube.next

Resolves the watch queue for a track or playlist, returning the ordered song list, the currently-playing index, and browse endpoints for lyrics and related content. If the queue contains an automix panel, next() resolves it recursively and merges the results. 
suspend fun next(
    endpoint: WatchEndpoint,
    continuation: String? = null,
): Result<NextResult>
​
endpoint
WatchEndpoint
required
Identifies the track or playlist to resolve.
​
continuation
String?
Token from a prior NextResult.continuation to page through a long queue. Defaults to null.
Return type
​
Result<NextResult>
Result
Example 
val endpoint = WatchEndpoint(videoId = "dQw4w9WgXcQ")
YouTube.next(endpoint).onSuccess { result ->
    println("Queue: ${result.title}")
    result.items.forEachIndexed { i, song ->
        val marker = if (i == result.currentIndex) "▶" else " "
        println("$marker ${song.title} — ${song.artists.firstOrNull()?.name}")
    }
    result.lyricsEndpoint?.let { ep ->
        YouTube.lyrics(ep).onSuccess { println(it) }
    }
}

​
YouTube.player

Fetches the PlayerResponse for a video, which contains stream URLs, adaptive format manifests, and playback status. 
suspend fun player(
    videoId: String,
    playlistId: String? = null,
    client: YouTubeClient,
    signatureTimestamp: Int? = null,
    poToken: String? = null,
): Result<PlayerResponse>
​
videoId
String
required
The video ID to retrieve streams for.
​
playlistId
String?
Optional playlist context. Some formats are only available in a playlist context.
​
client
YouTubeClient
required
The InnerTube client profile to use (e.g. YouTubeClient.WEB_REMIX, YouTubeClient.ANDROID, YouTubeClient.IOS). Different clients expose different format sets.
​
signatureTimestamp
Int?
Signature timestamp required by clients that set useSignatureTimestamp = true. Obtain from the player JavaScript.
​
poToken
String?
Proof-of-origin token for clients that set useWebPoTokens = true.
Return type
​
Result<PlayerResponse>
Result
Example 
YouTube.player(
    videoId = "dQw4w9WgXcQ",
    client = YouTubeClient.WEB_REMIX,
).onSuccess { response ->
    if (response.playabilityStatus.status == "OK") {
        val audioUrl = response.streamingData?.adaptiveFormats
            ?.filter { it.mimeType?.startsWith("audio/") == true }
            ?.maxByOrNull { it.bitrate ?: 0 }
            ?.url
        println("Best audio URL: $audioUrl")
    }
}

​
YouTube.getMediaInfo

Fetches rich metadata for a video — description, author details, view count, and like/dislike counts sourced from the Return YouTube Dislike API. 
suspend fun getMediaInfo(videoId: String): Result<MediaInfo>
​
videoId
String
required
The video ID to retrieve metadata for.
Return type
​
Result<MediaInfo>
Result
Example 
YouTube.getMediaInfo("dQw4w9WgXcQ").onSuccess { info ->
    println("${info.title} by ${info.author}")
    println("Views: ${info.viewCount}  👍 ${info.like}  👎 ${info.dislike}")
    println(info.description?.take(200))
}

​
YouTube.transcript

Fetches the timed transcript for a video as a formatted string. Each line is prefixed with a timestamp in [MM:SS.mmm] format. 
suspend fun transcript(videoId: String): Result<String>
​
videoId
String
required
The video ID to retrieve the transcript for.
Return type
​
Result<String>
Result
A newline-separated string of timestamped cue lines, e.g. "[00:04.080]Never gonna give you up".
Example 
YouTube.transcript("dQw4w9WgXcQ").onSuccess { text ->
    println(text.lines().take(5).joinToString("\n"))
}

​
YouTube.queue

Resolves up to MAX_GET_QUEUE_SIZE video IDs or an entire playlist into a flat list of SongItems using the music/get_queue endpoint. 
suspend fun queue(
    videoIds: List<String>? = null,
    playlistId: String? = null,
): Result<List<SongItem>>
​
videoIds
List<String>?
List of video IDs to resolve. Must not exceed YouTube.MAX_GET_QUEUE_SIZE (1 000).
​
playlistId
String?
A playlist ID to resolve all tracks for. Provide either videoIds or playlistId, not both.
Return type
​
Result<List<SongItem>>
Result
Resolved song metadata for every requested video ID.
Constants
ConstantValueMeaning
YouTube.MAX_GET_QUEUE_SIZE1000Maximum number of video IDs per queue() call.
Example 
val ids = listOf("dQw4w9WgXcQ", "9bZkp7q19f0")
YouTube.queue(videoIds = ids).onSuccess { songs ->
    songs.forEach { println("${it.title} — ${it.duration}s") }
}

​
YouTube.registerPlayback

Sends a playback telemetry ping to the YouTube tracking URL returned in the player response. Call this once when a track starts to satisfy the API’s engagement requirements. 
suspend fun registerPlayback(
    playlistId: String? = null,
    playbackTracking: String,
): Result<*>
​
playlistId
String?
Optional playlist context for the playback event.
​
playbackTracking
String
required
The playback-tracking URL from PlayerResponse.playbackTracking. A random 16-character content playback nonce (cpn) is generated automatically.
Example 
YouTube.player("dQw4w9WgXcQ", client = YouTubeClient.WEB_REMIX).onSuccess { response ->
    val trackingUrl = response.playbackTracking?.videostatsPlaybackUrl?.baseUrl
    if (trackingUrl != null) {
        YouTube.registerPlayback(playbackTracking = trackingUrl)
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us