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.

Inner exposes YouTube.search(), YouTube.searchSummary(), YouTube.searchSuggestions(), and YouTube.searchContinuation() for querying YouTube Music content. All methods are suspend functions that return a Result<T>, which you can unwrap with .getOrThrow(), .getOrNull(), or .getOrElse {}. YouTube.search(query, filter) returns Result<SearchResult>. The SearchResult data class contains:
  • items: List<YTItem> — the matching content items (songs, albums, artists, or playlists depending on the filter applied)
  • continuation: String? — an opaque token for fetching the next page, or null if there are no more results
import com.tamed.music.innertube.YouTube
import com.tamed.music.innertube.YouTube.SearchFilter

val result = YouTube.search("Taylor Swift", SearchFilter.FILTER_SONG).getOrThrow()
result.items.forEach { item ->
    println("${item.title} (${item.id})")
}

​
Search filters

Pass one of the SearchFilter constants as the second argument to YouTube.search() to restrict results to a specific content type.
Filter constantDescription
SearchFilter.FILTER_SONGSongs only
SearchFilter.FILTER_VIDEOMusic videos
SearchFilter.FILTER_ALBUMAlbums and EPs
SearchFilter.FILTER_ARTISTArtist profiles
SearchFilter.FILTER_FEATURED_PLAYLISTYouTube-curated playlists
SearchFilter.FILTER_COMMUNITY_PLAYLISTUser-created playlists
Each constant is a @JvmInline value class SearchFilter(val value: String) wrapping the InnerTube filter parameter string.

​
Pagination

SearchResult.continuation holds the token for the next page. Pass it to YouTube.searchContinuation() to fetch subsequent pages. The continuation is null when there are no more results, or when the next page returns an empty item list. 
var result = YouTube.search("Taylor Swift", SearchFilter.FILTER_ALBUM).getOrThrow()
while (result.continuation != null) {
    // Process current page
    result.items.forEach { println(it.title) }
    // Fetch next page
    result = YouTube.searchContinuation(result.continuation!!).getOrThrow()
}
searchContinuation sets continuation to null in the returned SearchResult when the returned item list is empty, so the loop terminates naturally.

​
Search suggestions

YouTube.searchSuggestions(query) returns Result<SearchSuggestions>. The SearchSuggestions data class contains:
  • queries: List<String> — autocomplete query strings matching what the user typed
  • recommendedItems: List<YTItem> — fully resolved content items (songs, artists, etc.) recommended for the current input
val suggestions = YouTube.searchSuggestions("Taylor").getOrThrow()
suggestions.queries.forEach { println(it) }
suggestions.recommendedItems.forEach { println("${it.title} (${it.id})") }

​
Search summary

YouTube.searchSummary(query) returns Result<SearchSummaryPage>. Instead of filtering by a single content type, it returns a SearchSummaryPage containing a summaries: List<SearchSummary> — one entry per category found in the results (e.g. “Top result”, “Songs”, “Albums”, “Artists”). Each SearchSummary has a title: String and items: List<YTItem>. This is the method to use when you need a quick cross-category overview rather than a deep, paginated single-category result list. 
val summaryPage = YouTube.searchSummary("Taylor Swift").getOrThrow()
summaryPage.summaries.forEach { summary ->
    println("=== ${summary.title} ===")
    summary.items.forEach { println("  ${it.title}") }
}
SearchSummaryPage also exposes filterExplicit(enabled: Boolean) and filterVideo(enabled: Boolean) methods that return a new SearchSummaryPage with the matching items removed from each summary group.

​
Filtering explicit content

The filterExplicit() extension is available on any List<T : YTItem>. Set enabled = true to drop items whose explicit flag is true. 
import com.tamed.music.innertube.models.SongItem
import com.tamed.music.innertube.models.filterExplicit

val result = YouTube.search("Taylor Swift", SearchFilter.FILTER_SONG).getOrThrow()
val songs = result.items.filterIsInstance<SongItem>().filterExplicit(enabled = true)
songs.forEach { println(it.title) }
filterVideo(enabled: Boolean) on List<YTItem> removes SongItem entries whose endpoint.watchEndpointMusicSupportedConfigs indicates an official music video (OMV) or user-generated content (UGC) type.
Use searchSummary() when building an omnisearch results page — it gives you a categorised overview across all content types in a single round trip. Use search() with a specific filter for category-specific browsing or when you need full pagination support.

Build docs developers (and LLMs) love

Get started for freeTalk to us