Skip to content

Track ​

A Track is the one unit of content in the library. The same object describes a row in a browse list, an item in the playback queue, and the metadata on the lock screen — so once you know the Track shape, you can read and build content everywhere.

A Track is just a plain object. The only required field is title, plus at least one of path (browsable) or src (playable):

ts
const station: Track = {
  title: 'Smooth Floret FM',
  src: 'https://example.com/floret.mp3'
}

A real track usually carries more — identity, metadata, and artwork:

ts
const episode: Track = {
  id: 'atp-545',
  title: 'Episode 545',
  artist: 'Accidental Tech Podcast',
  album: 'ATP',
  artwork: 'https://example.com/atp.jpg',
  duration: 7200,
  src: 'https://example.com/atp/545.mp3'
}

This guide is the field-by-field reference. For where tracks come from (routes, callbacks, HTTP) see the Browser guide.

Browsable or playable ​

Two fields decide what a Track does. A Track must set at least one of them:

FieldMakes the trackEffect
pathbrowsablea container — tapping it navigates into its children
srcplayablea leaf — the player can stream it
ts
// Browsable: a folder you navigate into
{ title: 'Jazz', path: '/browse/jazz' }

// Playable: a station you stream
{ title: 'Smooth Floret FM', src: 'https://example.com/floret.mp3' }

Set exactly one. On a browse page a track that sets both plays: the library replaces its path with one that points back to the page it appears on.

src is usually an absolute audio URL, but it can be any string — a file path or your own identifier — that you turn into a real request in media.resolve (see Browser → Media and artwork).

Identity: id ​

id is an opaque, stable identifier you control. The library never parses it — it round-trips verbatim through setQueue, the queue, getActiveTrack, and onActiveTrackChanged.

Why it matters: when playback moves by an external control — a lock-screen / CarPlay / Android Auto / Bluetooth next-or-previous — you find out which of your items became active by matching its id, without re-parsing the src:

ts
// the callback gets a PlaybackActiveTrackChangedEvent — use event.track
const unsubscribe = onActiveTrackChanged.addListener((event) => {
  const episode = myEpisodes.find((e) => e.id === event.track?.id)
  // …update your UI for `episode`
})

The event also carries index, lastTrack, and lastIndex; addListener returns an unsubscribe function.

id is also passed to the per-track resolve hooks, so you can set src to the same stable identifier and synthesise the real request/artwork from it at request time.

id is optional

A track's identity is its id, falling back to src — so if the same item's src string is identical wherever it appears, you can skip id entirely.

Set ids consistently across your content or not at all: identity is compared whole, and a row carrying an id never matches a track without one. To compare tracks the same way in your own code, use getTrackIdentity.

Display fields ​

These set the text shown across surfaces. Only title is required.

FieldShown where
titleprimary line — browse rows and now-playing (required)
subtitlesecondary line in browse lists only
artistsecondary line on now-playing / lock screen; the head-unit "artist" slot
albumalbum name (and gates the tappable album line — see albumPath)
genre / descriptionextra metadata
durationcatalog metadata in seconds, for your UI

subtitle and artist are separate — neither falls back to the other

subtitle drives browse-list rows; artist drives the now-playing line and Bluetooth metadata. Set each one for the surface you want it on.

duration is catalog metadata only (e.g. an episode list) — it does not drive the now-playing scrubber. Every surface derives elapsed/remaining from the player itself.

Artwork ​

Set artwork to an image URL. It's transformed through your artwork configuration and the ready-to-render result comes back on the output-only artworkSource, shaped for React Native's <Image>:

tsx
<Image source={track.artworkSource} />

Don't set artworkSource yourself — the library populates it.

SF Symbols (iOS). Prefix artwork with sf: to use a system symbol, with optional colors: bg (background) and fg (symbol). On the lock screen and in artworkSource, an omitted bg is transparent and an omitted fg is black:

ts
{
  title: 'Favorites',
  path: '/favorites',
  artwork: 'sf:heart.fill?bg=#FF0090&fg=#fff'
}

On CarPlay, an SF Symbol with no fg adapts to light/dark mode automatically: black on light grey or white on dark grey, and a bg alone is ignored.

Tinting (style: { artworkRendering: 'stencil' }). For monochrome icons, declare this so CarPlay tints them per appearance — black in light mode, white in dark. Use it for icons, not full-color album art. iOS CarPlay only; for Android Auto see Tinting and platform icons.

On Android Auto, when a list or grid display applies and artwork is an android.resource:// URI, the library asks for the category style, which adds margins around small icons.

Light and dark images. When the appearances need genuinely different artwork rather than the same shape recolored, set artwork to an ArtworkVariants pair — { light, dark }. CarPlay adapts between them in place; everywhere that needs a single image uses dark. See Artwork → Light and dark.

Per-track request override ​

request is a narrow per-track field for how this track's audio request should be made.

TrackRequest says which platforms merge it into the media request. Where they don't, return per-track headers or query from media.resolve (or resolveSync), which receives the track.

ts
{
  title: 'Member Stream',
  src: 'https://example.com/members/floret.mp3',
  request: { headers: { authorization: 'Bearer …' } }
}

It carries only userAgent, headers, and query — not baseUrl / path / method / body, so a track (often server-sourced) can't repoint its own host or verb. Like every field, it round-trips verbatim through the queue.

Presentation on native surfaces ​

Optional fields that change how a Track renders on CarPlay / Android Auto. Each surface applies the ones it supports; an unsupported field is a no-op, never an error.

FieldEffectPlatform
style: { display: 'list' | 'grid' }on a browsable track: the layout of the page it opensAndroid Auto / AAOS
style: { artworkRendering: 'stencil' }tint monochrome artwork to the surface appearanceCarPlay
style: { imageShape: 'circular' }crop 'image' and 'condensed' tile artwork circular (people)CarPlay (iOS 26+)
style: { accessorySymbol: '…' }SF Symbol accessory; 'none' restores the derived accessoryCarPlay
style: { cardTint: '…', cardImage: '…' }card color and image mode, when the section renders gridTile: 'card'CarPlay (iOS 26+)
disabledunavailable: taps, voice selection, queue expansion and resume refuse it, but a setQueue list is not filtered and plays it when reached; grayed where drawable, hidden elsewhereall
favoritedfilled/empty heart (Android: needs the favorite capability; CarPlay: needs 'favorite' in ios.carPlayNowPlayingButtons)Android Auto, notification, CarPlay now-playing
livea "live" indicatoriOS now-playing
albumPathmake the now-playing album line tappableCarPlay

Constraints worth knowing:

  • display goes on the browsable track as it appears in its parent's list — Android Auto reads it there, before the page resolves, to decide how to lay out the page once you navigate in.

    It is only sent when you declare it — the library never infers it from the page's content. The drilled-into page's own sections override it per section via their style.

  • live is more than an indicator. On iOS it decides how a dropped or stalled stream recovers and stops a resume from seeking a stale position; on every platform, seekToLiveEdge() does nothing unless the active track is declared live. Declare it on every live track — see Live streams.

  • albumPath requires album (CarPlay renders the tappable line from album metadata), and pairs with resolveAlbumPath in the Browser config.

ts
// This track as it appears in its parent's list (no children here — the
// page supplies those): it declares the layout of the page it opens.
{
  path: '/genres',
  title: 'Genres',
  // the page this opens lays out as tiles in Android Auto
  style: { display: 'grid' }
}

Sections: grouping and tile layouts ​

A Track appears in two roles. As a row in its parent's list it's a handle: its own style.display only advertises the layout of the page it opens (see above). Once resolved, that same Track is the page — a ResolvedTrack — and that is when it carries sections.

Headers and layout belong to the container role: declare them on the page's Sections ({ title?, style?, path?, children }), never on the rows.

A section groups tracks under a header, and its style block's display picks their layout: 'list' rows (the default) or 'grid' artwork tiles — wrapping unless gridWrap: false keeps them to a single line.

The section's path is the navigation target for its header / "view all" surface; without one the header is a plain label, not a link — the section is self-contained.

A tile with src plays immediately on tap (same selection path as a playable list row — a station app can make tiles play their station directly); otherwise its path is navigated.

Tiles are ordinary Tracks, so playable ones carry the now-playing fields any track would (id, artist, album, albumPath, live, request). Tapping a playable child queues its section on every surface (see Playback behavior):

ts
{
  path: '/home',
  title: 'Home',
  sections: [
    {
      title: 'Featured',
      style: { display: 'grid', gridWrap: false },
      path: '/browse/featured', // header tap → the full list
      children: [
        {
          title: 'Jazz',
          path: '/browse/jazz',
          artwork: 'https://…/jazz.jpg'
        },
        {
          title: 'Beacon FM',
          src: 'https://audio.example.com/beacon.mp3', // tap plays it
          artist: 'Springfield',
          live: true,
          artwork: 'https://…/beacon.jpg'
        }
      ]
    },
    { title: 'All stations', children: [...] }
  ]
}

Each surface renders a declaration as its nearest supported form; see Browser → Presentation.

ResolvedTrack: a resolved page ​

A ResolvedTrack is the same Track plus its resolved content — the page the browser is currently showing. Its path is always present, and sections is the Section[] to render (optional — a leaf page has none).

A page authored with a plain children list resolves to a single untitled section: children is authoring sugar, never populated on resolved output — read sections.

Navigation is fire-and-forget: navigate(path) returns void. Read the resolved page from useContent() (or getContent() / onContentChanged):

tsx
import { navigate, useContent } from 'react-native-audio-browser'

navigate('/browse/jazz') // moves the browser to this path

function JazzPage() {
  const page = useContent() // ResolvedTrack | undefined
  // each section: { title?, style?, path?, children: Track[] }
  return <List sections={page?.sections ?? []} /> // sections may be undefined
}

A ResolvedTrack may also set carPlaySiriListButton: 'top' | 'bottom' to show the "Ask Siri to Play" cell on that page (needs Siri wiring — see CarPlay).

Stream title encoding: icyCharset ​

Some Shoutcast / Icecast stations send their ICY stream titles in a legacy code page rather than UTF-8. Set icyCharset to its IANA label ('windows-1251', …) and the player re-decodes those titles on iOS and Android. See Metadata.

Using tracks in your code ​

Tracks flow through the queue and playback API. A minimal playable track needs just title + src:

ts
import { setQueue, play, useActiveTrack } from 'react-native-audio-browser'

setQueue([
  { title: 'Smooth Floret FM', src: 'https://example.com/floret.mp3' },
  { title: 'The Stalk 88.5', src: 'https://example.com/stalk.mp3' }
])
play()

load(track) replaces the active track (or starts the queue if it is empty), add(tracks) appends to the queue, and getActiveTrack() / useActiveTrack() read what's playing now (with its artworkSource populated for your UI). See Basic Usage for the full queue and playback API.

Where to go next ​

  • Browser — where tracks come from: tabs, routes, sources.
  • Now Playing — how a track's fields drive the lock-screen / car metadata.
  • Favorites — the favorited field and the heart button.

For the exact types — every field and its JSDoc — see Track and ResolvedTrack in the API reference.