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.

YouTube is a Kotlin object (singleton) declared in com.metrolist.innertube. It is the only interface your application code needs to interact with — every search, browse, player, library, and account operation is exposed as a method on this single object. You never instantiate it; the JVM guarantees exactly one instance for the lifetime of the process.

​
Two-Layer Architecture

InnerTube is built on two cooperating layers. YouTube owns all the business logic: it parses raw JSON responses, maps renderer trees into typed page models, and returns clean Kotlin data classes. Underneath it, InnerTube handles the raw HTTP transport — building request bodies, managing ktor client configuration, computing authentication headers, and retrying transient I/O errors. 
Your App  ──→  YouTube (object)        ← parsing, models, business logic
                   │
                   └──→  InnerTube (class)   ← ktor HTTP client, headers, retry
                              │
                              └──→  music.youtube.com/youtubei/v1/
YouTube holds a private InnerTube instance and delegates all network calls to it. All configurable properties on YouTube are thin forwarding properties that read and write the underlying InnerTube field.

​
The Result Pattern

Every YouTube method is a suspend function that returns Result<T>. Internally they all use runCatching { … }, which means network failures, HTTP errors, and parse exceptions are all captured as Failure variants — your coroutine is never interrupted by an unexpected exception from the library. 
// Option 1 – crash on failure (use inside your own runCatching or try/catch)
val page = YouTube.search("tame impala", YouTube.SearchFilter.FILTER_SONG).getOrThrow()

// Option 2 – return null on failure
val page = YouTube.search("tame impala", YouTube.SearchFilter.FILTER_SONG).getOrNull()

// Option 3 – branch on success / failure
YouTube.search("tame impala", YouTube.SearchFilter.FILTER_SONG).fold(
    onSuccess = { result -> displayItems(result.items) },
    onFailure = { error -> showError(error.message) },
)

// Option 4 – provide a fallback value
val items = YouTube.search("lofi", YouTube.SearchFilter.FILTER_SONG)
    .getOrDefault(SearchResult(items = emptyList(), continuation = null))
Because all methods are suspend, they must be called from a coroutine context. Use viewModelScope.launch, lifecycleScope.launch, or any other coroutine scope appropriate for your application.

​
Configurable Properties

Configure YouTube once at startup (for example in Application.onCreate) before making any API calls. All properties forward directly to the inner InnerTube instance.
​
locale
YouTubeLocale
Controls the geolocation (gl) and host language (hl) sent with every request. Defaults to the device locale. Change this to request region-specific charts or localised search results.
YouTube.locale = YouTubeLocale(gl = "US", hl = "en")
​
visitorData
String?
An opaque session token that YouTube uses to maintain continuity across requests (personalised recommendations, consistent radio queues). Call the separate YouTube.visitorData() suspend function to fetch a fresh token from the API, then assign it here and persist it across app restarts.
YouTube.visitorData = savedVisitorData
// Or fetch fresh from the API:
YouTube.visitorData = YouTube.visitorData().getOrNull()
​
dataSyncId
String?
When set, this value is sent as onBehalfOfUser inside every request context, allowing the server to return account-specific data (personalised playlists, liked songs, etc.). Obtain it from the authenticated account info response.
​
cookie
String?
A raw YouTube session cookie string (e.g. "SAPISID=abc123; __Secure-3PSID=xyz..."). Setting this enables authenticated requests. The library automatically parses the cookie string and computes a SAPISIDHASH Authorization header for every request that requires login. See Authentication for details.
​
proxy
java.net.Proxy?
An optional Proxy for all HTTP traffic. Assigning a new value recreates the internal ktor HttpClient transparently — no restart required.
YouTube.proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("10.0.0.1", 8080))
​
proxyAuth
String?
A Proxy-Authorization header value string to authenticate against a proxy that requires credentials.
​
useLoginForBrowse
Boolean
When true, login headers are attached to every browse request regardless of whether the individual method explicitly opts in. Useful when you want the personalised home page, continue-watching state, or other account-level browse results on all endpoints.

​
Typical Usage Pattern

// Application.onCreate or your DI setup
YouTube.locale = YouTubeLocale(gl = "US", hl = "en")
YouTube.cookie = securePreferences.getString("yt_cookie", null)
YouTube.dataSyncId = securePreferences.getString("yt_data_sync_id", null)
YouTube.visitorData = securePreferences.getString("yt_visitor_data", null)
    ?: YouTube.visitorData().getOrNull()?.also { fresh ->
        securePreferences.edit().putString("yt_visitor_data", fresh).apply()
    }
YouTube.useLoginForBrowse = true

// In a ViewModel
viewModelScope.launch {
    val result = YouTube.search("daft punk", YouTube.SearchFilter.FILTER_ALBUM)
    result.fold(
        onSuccess = { _albums.value = it.items.filterIsInstance<AlbumItem>() },
        onFailure = { Timber.e(it) },
    )
}

​
Search Filters

YouTube.SearchFilter is a @JvmInline value class wrapping an encoded InnerTube params string. Pass a constant from its companion to the YouTube.search() method to restrict results to a specific content type.

FILTER_SONG

Returns audio tracks / official song recordings.

FILTER_VIDEO

Returns music videos and user-uploaded videos.

FILTER_ALBUM

Returns studio albums, EPs, and singles.

FILTER_ARTIST

Returns artist channel results.

FILTER_FEATURED_PLAYLIST

Returns curated / editorial playlists.

FILTER_COMMUNITY_PLAYLIST

Returns user-created community playlists.

FILTER_PODCAST

Returns podcast series.

FILTER_EPISODE

Returns individual podcast episodes.

FILTER_PROFILE

Returns YouTube profile / channel pages.
// Searching for songs only
val songs = YouTube.search("radiohead", YouTube.SearchFilter.FILTER_SONG).getOrThrow()

// Searching for community playlists
val playlists = YouTube.search("lofi study", YouTube.SearchFilter.FILTER_COMMUNITY_PLAYLIST).getOrNull()

​
Library Filters

YouTube.LibraryFilter is also a @JvmInline value class wrapping an encoded continuation token. These are used internally by YouTube.libraryRecentActivity() and related library browsing methods to select which library view to load.
ConstantDescription
FILTER_RECENT_ACTIVITYItems most recently interacted with across the library.
FILTER_RECENTLY_PLAYEDAlbums and playlists in order of last playback.
FILTER_PLAYLISTS_ALPHABETICALLiked and saved playlists sorted A → Z.
FILTER_PLAYLISTS_RECENTLY_SAVEDLiked and saved playlists sorted by save date.
Library filters require an authenticated session (YouTube.cookie must be set). Calling library methods without authentication will typically return an empty result or throw a 401 error captured inside the Result.Failure.

Build docs developers (and LLMs) love

Get started for freeTalk to us