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.

YouTube is a Kotlin object (singleton) that serves as the primary API surface for the Inner library on Android. It wraps an internal InnerTube instance and exposes all configuration properties and suspend functions. Because it is a singleton, all properties you set are applied globally and persist for the lifetime of the process.

​
Configuration properties

Every writable property delegates internally to a PlaybackAuthState or to the underlying InnerTube instance. Setting authState is the most efficient way to update multiple fields at once; individual property setters are convenience wrappers that call authState = authState.copy(...) internally.
​
authState
PlaybackAuthState
Get or set the full authentication state atomically. When set, the value is first normalized (whitespace stripped, invalid values cleared) and then propagated to the internal InnerTube instance and to authStateFlow. Prefer setting this over individual properties when updating multiple fields simultaneously.
​
cookie
String?
Raw YouTube Music session cookie string (e.g. "SAPISID=xxx; __Secure-3PSID=xxx; ..."). When non-null and contains a SAPISID key, hasLoginCookie() returns true and authenticated requests become available.
​
visitorData
String?
The X-Goog-Visitor-Id header value. You can obtain a fresh token by calling the visitorData() suspend function. Used as the sessionId when no login cookie is present.
​
dataSyncId
String?
Sent as onBehalfOfUser in the InnerTube request context for authenticated clients. When both cookie and dataSyncId are set, hasPlaybackLoginContext() returns true. Values containing || are automatically normalized.
​
poToken
String?
Generic PoToken fallback. Used when a more specific token (poTokenPlayer or poTokenGvs) is not available and webClientPoTokenEnabled is true.
​
poTokenGvs
String?
PoToken that is appended to GVS stream URLs as the pot= query parameter. Takes precedence over the generic poToken for GVS resolution. Only applied when webClientPoTokenEnabled is true and the client requires service integrity (web-family clients).
​
poTokenPlayer
String?
PoToken sent in player requests. Takes precedence over the generic poToken for player resolution. Only applied when webClientPoTokenEnabled is true and the client requires service integrity.
​
webClientPoTokenEnabled
Boolean
Master switch that controls whether PoToken values are attached to web-family client requests (WEB, WEB_REMIX, WEB_CREATOR, MWEB, WEB_EMBEDDED_PLAYER, TVHTML5, and related). Defaults to false. Set to true when you have valid PoToken values and want them included.
​
proxy
Proxy?
An java.net.Proxy instance applied to all HTTP requests made by the internal Ktor client. Supports both Proxy.Type.HTTP and Proxy.Type.SOCKS. Set to null to disable proxy usage.
​
streamBypassProxy
Boolean
When true, stream URL fetches bypass the configured proxy (i.e. streamProxy returns null). Useful when your proxy does not handle large media streams well. Defaults to false.
​
streamProxy
Proxy?
Read-only computed property. Returns null when streamBypassProxy is true, otherwise returns the value of proxy. Use this when resolving stream URLs to respect the bypass setting automatically.
​
locale
YouTubeLocale
Controls the gl (country code) and hl (language tag) fields sent in every InnerTube request context. Affects the language and regional availability of results. Example: YouTubeLocale(gl = "US", hl = "en-US").
​
useLoginForBrowse
Boolean
When true, the session cookie is attached to browse requests (home, library, playlist, etc.). Enables personalised content. Defaults to false.

​
Auth state flow

authStateFlow is a StateFlow<PlaybackAuthState> that emits the current auth state and every subsequent change. Collect it from a coroutine to react to login or token updates in real time. 
import kotlinx.coroutines.flow.collectLatest

lifecycleScope.launch {
    YouTube.authStateFlow.collectLatest { state ->
        println("Auth updated: ${state.hasLoginCookie}")
    }
}
authStateFlow is a cold-read StateFlow — subscribing immediately delivers the current value, so there is no race condition between reading the initial state and observing future updates.

​
Helper methods

​
hasLoginCookie()
Boolean
Returns true if the current cookie string contains a SAPISID key. This is a synchronous check that does not make any network requests.
​
hasPlaybackLoginContext()
Boolean
Returns true when both hasLoginCookie() is true and dataSyncId is non-null and non-blank. Required for requests that use onBehalfOfUser.
​
currentPlaybackAuthState()
PlaybackAuthState
Returns a snapshot of the current PlaybackAuthState. Equivalent to reading authState. Useful when you need to capture state for an async operation without holding a reference to the mutable singleton.

​
Complete configuration example

import com.tamed.music.innertube.YouTube
import com.tamed.music.innertube.PlaybackAuthState
import com.tamed.music.innertube.models.YouTubeLocale
import java.net.Proxy
import java.net.InetSocketAddress

// Full configuration — sets everything atomically in one assignment
YouTube.authState = PlaybackAuthState(
    cookie = "SAPISID=xxx; __Secure-3PSID=xxx; ...",
    visitorData = "CgtAbCdEfG...",
    dataSyncId = "123456789",
    webClientPoTokenEnabled = true,
    poTokenPlayer = "player_token_here",
    poTokenGvs = "gvs_token_here"
)
YouTube.locale = YouTubeLocale(gl = "US", hl = "en-US")
YouTube.proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("127.0.0.1", 8080))
YouTube.useLoginForBrowse = true
Always set authState as a single PlaybackAuthState value rather than assigning individual properties in sequence. Each individual property setter triggers a copy() + normalization + innerTube.applyAuthState() call, so batching them avoids redundant work.

Build docs developers (and LLMs) love

Get started for freeTalk to us