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.

InnerTube is a Kotlin Android library that wraps YouTube’s internal InnerTube API, giving your app structured, type-safe access to YouTube Music data — no scraping, no unofficial REST wrappers, just direct communication with the same endpoints the YouTube Music web app uses.
InnerTube targets Android API 26+ and is built on Kotlin coroutines. Every YouTube method is a suspend function and must be called from a coroutine scope.

​
What InnerTube Does

InnerTube exposes a single YouTube singleton with suspend functions covering the full breadth of YouTube Music functionality:
CapabilityKey Methods
Searchsearch(), searchSummary(), searchSuggestions(), searchContinuation()
Playbackplayer(), next(), queue(), registerPlayback(), newPipePlayer()
Browsehome(), explore(), browse(), moodAndGenres(), newReleaseAlbums()
Artist & Albumartist(), artistItems(), album(), albumSongs()
Playlistsplaylist(), createPlaylist(), renamePlaylist(), deletePlaylist(), addToPlaylist(), removeFromPlaylist(), moveSongPlaylist()
User Librarylibrary(), libraryRecentActivity(), musicHistory()
EngagementlikeVideo(), likePlaylist(), subscribeChannel(), feedback()
Commentscomments(), commentContinuation(), commentReplies()
Bot MitigationrefreshVisitorData(), PoToken support via player()
Lyrics & Transcriptlyrics(), transcript()
ChartsgetChartsPage()
AccountaccountInfo()

​
Architecture Overview

Your App Code
     │
     ▼
 YouTube  (object)          ← Public API: parses JSON into typed Kotlin data classes
     │  delegates all HTTP to
     ▼
 InnerTube  (class)         ← HTTP client: Ktor + OkHttp, signs requests, manages sessions
     │
     ▼
 YouTube InnerTube API      ← music.youtube.com/youtubei/v1/...
YouTube is the only class you interact with. It owns an InnerTube instance and forwards configuration properties to it. After receiving raw JSON from InnerTube, YouTube methods delegate parsing to page-level helpers (SearchPage, ArtistPage, AlbumPage, etc.) that convert JSON renderer trees into typed Kotlin data classes such as SongItem, ArtistItem, AlbumItem, and PlaylistItem. InnerTube handles all HTTP concerns: building the Ktor/OkHttp client, attaching the correct X-YouTube-Client-* headers, managing cookies and SAPISIDHASH authorization, applying proxy and IP version configuration, and retrying transient network failures with exponential backoff. YouTubeExtractor is a standalone Rhino-based deobfuscator that resolves YouTube’s signature cipher and n parameter throttling transforms directly from the player base JS — no WebView required.

​
Requirements

RequirementValue
Min Android SDKAPI 26 (Android 8.0 Oreo)
Compile SDK37
KotlinCoroutines required
Java Toolchain21
Core Library DesugaringEnabled

​
Dependencies

InnerTube pulls in the following libraries (declared in build.gradle.kts):
LibraryRole
ktor-client-core + ktor-client-okhttpHTTP engine for all InnerTube requests
ktor-client-content-negotiation + ktor-serialization-jsonJSON (de)serialization via kotlinx.serialization
ktor-client-encoding + brotliBrotli/gzip response decompression
newpipeextractorFallback stream URL extraction via NewPipeExtractor
rhinoJavaScript engine for YouTube signature/throttling deobfuscation

​
Get Started

Quickstart

Add InnerTube to your project and make your first API call in under 5 minutes.

Configuration

Configure locale, authentication, proxy settings, and IP version filtering.

The YouTube Object

Explore the full surface area of the YouTube singleton and its suspend functions.

Search API

Search for songs, videos, albums, artists, and playlists with type-safe filters.

Build docs developers (and LLMs) love

Get started for freeTalk to us