Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/faraasaaay/innertube-v2/llms.txt

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

All configuration is applied through properties on the YouTube singleton. Changes take effect immediately — the YouTube object forwards each property to the underlying InnerTube HTTP client.

​
Locale

YouTube.locale controls the language and region of API responses. It accepts a YouTubeLocale data class with two fields:
FieldTypeDescription
glStringISO 3166-1 alpha-2 country code (e.g. "US", "GB", "JP")
hlStringBCP-47 language tag (e.g. "en", "ja", "fr-CA")
The default value is derived from Locale.getDefault() on the device. 
import com.music.innertube.YouTube
import com.music.innertube.models.YouTubeLocale

// US English
YouTube.locale = YouTubeLocale(gl = "US", hl = "en")

// British English
YouTube.locale = YouTubeLocale(gl = "GB", hl = "en-GB")

// Japanese
YouTube.locale = YouTubeLocale(gl = "JP", hl = "ja")
Set the locale once at app startup — ideally right after Application.onCreate() — before making any API calls. Changing locale mid-session will affect all subsequent requests but not in-flight ones.

​
Visitor Data

YouTube.visitorData is an anonymous session token that YouTube includes in API responses to track guest sessions. Setting it improves response consistency and is required for certain browse endpoints.
Property / MethodTypeDescription
YouTube.visitorDataString?Raw visitor data token. Read/write.
YouTube.refreshVisitorData()suspend funFetches a fresh token from YouTube, stores it in visitorData, and returns it as a Result<String>.
YouTube.clearGuestSession()funResets both visitorData and dataSyncId to null.
import com.music.innertube.YouTube

// Fetch and store a fresh visitor data token
YouTube.refreshVisitorData()
    .onSuccess { token ->
        println("Visitor data set: $token")
    }
    .onFailure { error ->
        error.printStackTrace()
    }

// Clear the guest session (e.g. on sign-out)
YouTube.clearGuestSession()
refreshVisitorData() automatically writes the fetched token into YouTube.visitorData — you do not need to assign it manually. The token format starts with "Cgt" or "Cgs".
To access authenticated features — liked songs, listen history, playlist editing, personal library — provide a YouTube session cookie string.
PropertyTypeDescription
YouTube.cookieString?Raw YouTube session cookie string.
YouTube.dataSyncIdString?Account data-sync ID; required alongside cookie for full authenticated access.
YouTube.useLoginForBrowseBooleanWhen true, forces login headers on all browse and search requests (default: false).
import com.music.innertube.YouTube

// Set the session cookie from a logged-in YouTube.com session
YouTube.cookie = "SAPISID=abc123XYZ; __Secure-3PSID=...; LOGIN_INFO=...; VISITOR_INFO1_LIVE=..."

// Set the data sync ID (found alongside the cookie in browser DevTools)
YouTube.dataSyncId = "12345678901234567890||abcdefghijklmnopqrstuvwxyz"

// Force login headers on browse calls (needed for some library endpoints)
YouTube.useLoginForBrowse = true
Cookie strings come from an active, logged-in youtube.com browser session. Extract them from the Cookie request header in your browser’s DevTools Network tab. Never hardcode production credentials — store them in secure, encrypted storage (e.g. Android EncryptedSharedPreferences).
When cookie is set and contains a SAPISID key, InnerTube automatically computes and attaches the Authorization: SAPISIDHASH header for requests that require login. You do not need to compute the hash yourself. Endpoints that require authentication:
  • YouTube.library() and YouTube.libraryContinuation()
  • YouTube.libraryRecentActivity()
  • YouTube.musicHistory()
  • YouTube.likeVideo() / YouTube.likePlaylist()
  • YouTube.subscribeChannel()
  • YouTube.createPlaylist(), YouTube.renamePlaylist(), YouTube.deletePlaylist()
  • YouTube.addToPlaylist(), YouTube.removeFromPlaylist(), YouTube.moveSongPlaylist()

​
Proxy

Route all InnerTube HTTP traffic through an HTTP or SOCKS proxy.
PropertyTypeDescription
YouTube.proxyjava.net.Proxy?Proxy configuration. Setting this recreates the HTTP client.
YouTube.proxyAuthString?Base64-encoded user:password string for proxy authentication.
import com.music.innertube.YouTube
import java.net.InetSocketAddress
import java.net.Proxy

// HTTP proxy
YouTube.proxy = Proxy(
    Proxy.Type.HTTP,
    InetSocketAddress("proxy.example.com", 8080)
)

// SOCKS proxy
YouTube.proxy = Proxy(
    Proxy.Type.SOCKS,
    InetSocketAddress("socks.example.com", 1080)
)

// Proxy with authentication (Base64 of "username:password")
YouTube.proxyAuth = android.util.Base64.encodeToString(
    "myuser:mypassword".toByteArray(),
    android.util.Base64.NO_WRAP
)

// Remove proxy
YouTube.proxy = null
Assigning a new value to YouTube.proxy or YouTube.ipVersion closes and recreates the underlying OkHttp client. Avoid changing these properties on the hot path (e.g. inside a loop or on every playback request).

​
IP Version

YouTube.ipVersion controls which IP address family the HTTP client will prefer when resolving hostnames. This is useful for forcing IPv4-only on networks with broken IPv6 connectivity, or for testing. The property uses the IpVersion enum: 
package com.music.innertube.models

enum class IpVersion {
    AUTO,   // System default — both IPv4 and IPv6 candidates
    IPV4,   // Filter to IPv4 addresses only (falls back to all if none found)
    IPV6    // Filter to IPv6 addresses only (falls back to all if none found)
}

import com.music.innertube.YouTube
import com.music.innertube.models.IpVersion

// Force IPv4 only
YouTube.ipVersion = IpVersion.IPV4

// Force IPv6 only
YouTube.ipVersion = IpVersion.IPV6

// Restore automatic selection (default)
YouTube.ipVersion = IpVersion.AUTO

​
Full Configuration Example

Here is a complete setup block combining all configuration options. Place this in Application.onCreate() or in a dedicated YouTubeConfig.init() function called at startup. 
import com.music.innertube.YouTube
import com.music.innertube.YouTubeExtractor
import com.music.innertube.models.IpVersion
import com.music.innertube.models.YouTubeLocale
import java.net.InetSocketAddress
import java.net.Proxy
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.GlobalScope
import kotlinx.coroutines.launch

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()
        configureYouTube()
    }

    private fun configureYouTube() {
        // ── Locale ─────────────────────────────────────────────────────────
        YouTube.locale = YouTubeLocale(gl = "US", hl = "en")

        // ── Authentication (load from secure storage in production) ────────
        val savedCookie = securePrefs.getString("yt_cookie", null)
        val savedDataSyncId = securePrefs.getString("yt_data_sync_id", null)
        if (savedCookie != null) {
            YouTube.cookie = savedCookie
            YouTube.dataSyncId = savedDataSyncId
            YouTube.useLoginForBrowse = true
        }

        // ── Proxy (optional) ───────────────────────────────────────────────
        // YouTube.proxy = Proxy(Proxy.Type.HTTP, InetSocketAddress("proxy.example.com", 8080))
        // YouTube.proxyAuth = android.util.Base64.encodeToString("user:pass".toByteArray(), 0)

        // ── IP Version (optional) ──────────────────────────────────────────
        YouTube.ipVersion = IpVersion.AUTO

        // ── Visitor Data & Extractor ───────────────────────────────────────
        YouTubeExtractor.cacheDir = cacheDir

        GlobalScope.launch(Dispatchers.IO) {
            // Pre-warm the signature deobfuscator before first playback
            YouTubeExtractor.ensureInitialized()

            // Fetch visitor data for guest session if not logged in
            if (savedCookie == null) {
                YouTube.refreshVisitorData()
            }
        }
    }
}
In production, store cookie and dataSyncId in EncryptedSharedPreferences (from Jetpack Security) rather than plain SharedPreferences. These values grant full access to the user’s YouTube account.

​
Configuration Property Reference

PropertyTypeDefaultDescription
YouTube.localeYouTubeLocaleDevice localeLanguage and region for API responses
YouTube.visitorDataString?nullAnonymous session token
YouTube.dataSyncIdString?nullAccount data-sync ID for authenticated requests
YouTube.cookieString?nullYouTube session cookie string
YouTube.useLoginForBrowseBooleanfalseForce login headers on browse and search calls
YouTube.proxyjava.net.Proxy?nullProxy for all outbound requests
YouTube.proxyAuthString?nullBase64 proxy credentials (user:password)
YouTube.ipVersionIpVersionIpVersion.AUTOIP address family preference

Build docs developers (and LLMs) love

Get started for freeTalk to us