Search
Search is the query subsystem: it turns a voice command ("play jazz") or a text query into a list of playable tracks. It is distinct from Browse (navigating the content tree) — search takes structured query parameters and returns results.
Search powers both your in-app search UI and the voice search on external surfaces (Siri / CarPlay, Android Auto).
Configuring search
Set search on your BrowserConfiguration. It takes one of two shapes:
A callback — resolve results yourself and return a Track[]. The simplest possible search just filters a list you already have in memory:
import { configureBrowser } from 'react-native-audio-browser'
configureBrowser({
// …the rest of your config (tabs, browse, request, …)
search: async ({ query }) => {
const q = query.toLowerCase()
return allTracks.filter((track) => track.title?.toLowerCase().includes(q))
}
})The callback can return Track[] from anywhere — an in-memory filter as above, a local database, or your own API:
configureBrowser({
search: async (params) => {
// db / toTrack are yours
const rows = await db.findStations(params.query)
return rows.map(toTrack)
}
})An HTTP endpoint — a TransformableRequestConfig. The library issues the request natively and appends the query parameters for you.
The endpoint must return a bare Track[], a JSON array of results, not the page object a browse endpoint returns. iOS and Android decode only the array. On Android a page object gives no results, and on iOS the search rejects. The web accepts either shape. See SearchSource.
configureBrowser({
search: {
baseUrl: 'https://api.example.com/search',
// "play jazz" → GET .../search with q=jazz, genre=jazz and limit=20
// (q always; genre because the intent carried one; no mode here
// because "play jazz" carries none; limit added by transformSync)
transformSync(request) {
return { ...request, query: { ...request.query, limit: '20' } }
}
}
})With the HTTP form the library adds to request.query: q (always, even when empty), mode, reference (only when it is 'my', see below), and the filter fields, each only when the intent carried it. The callback's query is sent as q.
Searching from your own UI
The same source powers your in-app search box. search(query) runs it and resolves to a Track[] — it only returns results, it never queues or plays anything.
hasSearch() tells you (synchronously) whether a search source is configured at all, so you can hide the search UI when it isn't. Check it before calling search(): with no source configured, Android and web resolve [] but iOS rejects. With a source configured, [] means it found nothing:
import { search, hasSearch, navigate } from 'react-native-audio-browser'
import type { Track } from 'react-native-audio-browser'
function SearchScreen() {
const [results, setResults] = useState<Track[]>([])
if (!hasSearch()) return null // no search source configured
return (
<>
<SearchInput onSubmit={async (text) => setResults(await search(text))} />
<List
sections={[{ children: results }]}
onSelect={(track) => navigate(track)} // load & play via the library
/>
</>
)
}Four things to know about the in-app call:
- Your resolver sees a plain query. An in-app
search('jazz')arrives as{ query: 'jazz', reference: 'unknown' }— nomode, no filter fields. Only the voice assistants extract those. (On the HTTP form, onlyqis appended.) A resolver written against the fields that are present handles both callers. - You get the flat list, untouched. The browsable-first-result drill-in is voice-only — in-app results are handed to you as returned, and the user picks. A result with neither a
pathnor asrccan't be rendered, so don't return one. - Route taps through
navigate(track)rather thansetQueue+play— that gives a tapped result the library's load path (handleTrackLoad, Gate checks, favorite hearts) just like a tap on a browse row. - A failed search rejects; catch it to tell a failure from no results. On web a failed HTTP search's error carries a
code:'http-error'or'network-error'; a callback's rejection reaches you unchanged. On Android an HTTP source never rejects: it resolves[]on any failure (status, network, decoding), so there a failure looks like no results. Seesearch.
SearchParams
Both forms receive the same structured SearchParams:
| Field | Type | Meaning |
|---|---|---|
query | string | The raw query (always present, may be ""). |
mode | SearchMode? | The container vertical — what kind of result. Absent for an unstructured search. |
genre | string? | Genre filter. |
artist | string? | Artist filter. |
album | string? | Album filter. |
title | string? | Track-title filter (song intents). |
playlist | string? | Playlist-name filter. |
reference | 'my' | 'unknown' | Whether the user asked for their own collection. |
query and reference are always present (reference defaults to 'unknown'); the short literals in the tables below omit them for brevity, but a real SearchParams always carries both.
Search modes are verticals, not filters
mode answers "what kind of thing did the user ask for?" — a station, a podcast, a song. It is orthogonal to the filter fields, which say which item:
// "play a jazz podcast"
{ mode: 'podcast', genre: 'jazz', query: 'jazz' }
// ^ vertical ^ filterThe values:
| Mode | Asked for |
|---|---|
any | Anything sensible — smart shuffle / "play something" (empty query). |
station | A live radio station / channel. |
podcast | A podcast (show, episode, or station). |
audiobook | An audiobook. |
news | News content. |
music | The music vertical (as opposed to talk/podcasts). |
song | An individual track. |
playlist | A named playlist / mix. |
music-video / movie / tv-show / tv-show-episode | Video kinds (see Mixed audio/video). |
There is no genre/artist/album mode
Those are filters, not result shapes — read them from params.genre / params.artist / params.album directly. A genre search arrives as { genre: 'jazz' } with mode left unset.
mode is advisory — use it to route to the right index, or ignore it and full-text search query.
Cross-platform differences
The two voice platforms feed the same SearchParams; they just differ in how many fields they fill:
- iOS (SiriKit) supplies the richer set: every
modeexceptany, and thereferenceaxis. - Android (
onPlayFromSearch) supplies the subset it can express:query, the modesany(for "play music" with no query),songandplaylist, the genre, artist, album, title and playlist filters, and alwaysreference: 'unknown'.
Write your resolver against the fields that are present (if (params.genre) …), not against the platform. A field that's empty on one platform simply means "the assistant didn't provide it."
Voice playback (Siri & Google Assistant)
A spoken command — "play jazz on «App»" — funnels to the same search source on both platforms, then the result is queued and played. Any active Gate sees the search first, so voice can't slip past a paywall or region block unless your gate lets it through.
A browsable first result is drilled into
The library inspects the first voice result. If it is browsable-only — a path with no src — the library resolves that page and queues its playable children. So "play jazz" plays the first station inside the jazz page, not the page itself.
Disabled results are skipped, so a disabled first result never counts. If the first result is already playable (has a src), or the drill-in finds nothing playable, the playable results (those with a src that are not disabled) are queued in order.
This applies on both platforms, and only to voice playback — an in-app search UI renders your results and lets the user pick.
For ordinary queries ("play jazz", "play «station name»") the two behave identically — same resolver, same queue, same playback. The entry point and a few conveniences differ:
| iOS (Siri) | Android (Google Assistant) | |
|---|---|---|
| Delivered as | INPlayMediaIntent | MEDIA_PLAY_FROM_SEARCH intent |
| "play my favorites" | reference: 'my' → resolves to the user's collection | no collection signal → searched as plain text; reach favorites by browsing the Favorites tab instead |
| "play «App»" | recognised as a resume | searched literally (no app-name heuristic) |
| bare "play" / "resume" | resumes the current/last track | separate resume path (onPlay), not a search |
| "play music" (no query) | may send mode: 'music' | mode: 'any' → return smart-shuffle / recent content |
The gaps are all iOS-only conveniences — collection-by-voice and resume-by-name. Everything in the shared column is fully cross-platform.
Playing the user's own collection
When the user says "play my favorites", the intent carries reference: 'my'. Resolve it however your collection lives:
Local collection — read params.reference in a callback and return your own tracks:
configureBrowser({
search: async (params) => {
// getFavorites returns your local Track[]
if (params.reference === 'my') return getFavorites(params)
return searchByQuery(params)
}
})Server collection — when you use the HTTP form, reference=my is appended to request.query, so branch in transformSync to route the request — for example, to a favorites endpoint, injecting locally-stored identifiers:
configureBrowser({
search: {
baseUrl: 'https://api.example.com/search',
transformSync(request) {
// `transformSync` runs for every search — pass normal queries straight
// through to /search; only "play my favorites" is rewritten below.
if (request.query?.reference !== 'my') return request
return {
...request,
method: 'POST',
path: '/search/favorites',
contentType: 'application/json',
body: JSON.stringify({
q: request.query.q,
ids: getLocalFavoriteIds() // your stored identifiers
})
}
}
}
})reference is only ever 'my' or 'unknown' — "currently playing" ("play this") is resolved natively as a resume and never reaches search.
Voice phrase → params
These mappings are illustrative, not guaranteed. The assistant (Siri / Google Assistant) decides how to parse a spoken phrase, and the same words can arrive structured differently — or as a bare query — depending on the platform, locale, and the assistant's own interpretation.
Treat the table as plausible shapes to handle, and always write your resolver against the fields actually present (see Cross-platform differences) rather than assuming a phrase produces a specific shape.
| Phrase | Resulting SearchParams |
|---|---|
| "play something" | { mode: 'any', query: '' } |
| "play music" | { mode: 'any', query: '' } (iOS may send mode: 'music') |
| "play jazz" | { genre: 'jazz', query: 'jazz' } |
| "play The Stalk 88.5" | { mode: 'station', query: 'The Stalk 88.5' } |
| "play a jazz podcast" | { mode: 'podcast', genre: 'jazz' } |
| "play my favorites" | { reference: 'my', query: '' } |
| "play my jazz" | { reference: 'my', genre: 'jazz' } |
Mixed audio/video
This is an audio library — its player streams audio and has no video surface, and CarPlay / Android Auto forbid video playback while driving. So video is fundamentally an in-app concern: a search can signal a video request (via the video mode values), but the library will not render video.
To play video from your in-app search, intercept the load with handleTrackLoad. It runs whenever a track is loaded through navigate(track) (or the library's own browse UI) — so route your in-app search-result taps through navigate(track) rather than calling setQueue / play yourself, or this hook never fires.
When set, it is called instead of the library auto-playing the track — for every such load, not just video — so your handler must either route the track elsewhere or hand it back to the library to play:
import {
configureBrowser,
setQueue,
play,
type Track
} from 'react-native-audio-browser'
// You build the search-result tracks, so encode "this is video" however
// you like. `src` can be any string you recognise later — here, a scheme
// prefix your own player understands.
const isVideo = (track: Track) => track.src?.startsWith('video:') ?? false
configureBrowser({
handleTrackLoad: async ({ track, queue, startIndex }) => {
if (isVideo(track)) {
openVideoPlayer(track) // your own video surface
return
}
setQueue(queue, startIndex) // hand audio back to the library
play() // setQueue does not start playback, so play() is required
}
})The mode you saw at search time (music-video / movie / …) is not carried onto the Track, and handleTrackLoad runs at load time with no mode.
The tracks your search source returns for a video request are yours, though — so tag them with a recognizable src (as above) when you build them, and read that tag in isVideo here.
On external surfaces (CarPlay / Android Auto), a video request falls back to audio or is declined — there is no video playback path there.