react-native-audio-browser 0.1.0 → 0.2.0-next.1

package/AudioBrowser.podspec

@@ -10,7 +10,7 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
-  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
+  s.platforms    = { :ios => "16.0", :visionos => 1.0 }
   s.source       = { :git => "https://github.com/puckey/react-native-audio-browser.git", :tag => "#{s.version}" }
 
   s.swift_version = '6.2'

package/README.md

@@ -1,5 +1,183 @@
 # react-native-audio-browser
 
-> **Alpha** - This library is under active development and not yet published to npm. APIs may change without notice.
+[![npm](https://img.shields.io/npm/v/react-native-audio-browser)](https://www.npmjs.com/package/react-native-audio-browser)
+[![license](https://img.shields.io/npm/l/react-native-audio-browser)](LICENSE)
 
-A modern React Native audio framework featuring a browser-like navigation tree that can be defined manually or through JSON endpoints, built from the ground up with first class support for Android Auto and Apple Car Play.
+Full-featured React Native audio for production apps that span app screens, lock screens, CarPlay, Android Auto, voice controls, and the web, with one shared playback and browse model.
+
+Built by former [react-native-track-player](https://github.com/doublesymmetry/react-native-track-player) maintainers and contributors, and developed for the official [Radio Garden](https://radio.garden) apps. Audio Browser takes that experience in a new direction: a browse-first architecture for the surfaces modern audio apps need.
+
+> **Coming from react-native-track-player?** The playback and queue API is intentionally familiar, so most code ports over with small changes — see the [migration guide](https://audiobrowser.dev/guide/migrating-from-track-player).
+
+In the car, audio apps are organized as a browse tree: tabs, nested lists, and playable items, often loaded on demand from your backend. Define the tree in JS, fetch it from your API, or resolve it lazily with callbacks. Audio Browser renders it as native CarPlay and Android Auto UI, with playback wired into the lock screen and system controls.
+
+Use the same tree in your app UI, or keep it focused on CarPlay and Android Auto. Either way, [hooks](#hooks) expose playback, queue, and browse state for your own screens.
+
+## Features
+
+- **[Browse-first architecture](https://audiobrowser.dev/guide/browser)** — tabs, nested lists, routes, and playable items resolved from static data, JS callbacks, or your JSON API, then rendered natively on CarPlay and Android Auto.
+- **Car cold start** — launch directly from CarPlay or Android Auto with the phone app closed. The browse tree and playback come up on the head unit without opening the app first.
+- **Production [playback](https://audiobrowser.dev/guide/playback)** — [queue](https://audiobrowser.dev/guide/queue), background audio, playback rate, interruptions, audio focus, and lock screen, notification, and headset controls.
+- **Built on Nitro** — React Native's New Architecture, synchronous native calls, and no bridge overhead.
+- **Real native-to-JS callbacks** — route resolvers, request transforms, gates, search, and track-load interception call into your JS and use what you return, instead of going through fire-and-forget bridge events.
+- **Playback resumption** — persist the last session and resume after the app is killed, including the Android system play button and “play «App»” via Siri.
+- **[Live-stream ready](#streaming)** — HLS, ICY/Icecast, and progressive streams, with stall recovery, reconnects, fresh URL resolution, and live-edge seeking.
+- **[React hooks](#hooks)** — reactive playback, queue, browse, progress, sleep timer, and car-connection state for your app UI.
+- **[Now Playing](https://audiobrowser.dev/guide/now-playing)** — metadata, artwork, [timed metadata, chapter metadata](https://audiobrowser.dev/guide/metadata), lock screen updates, and media-session integration.
+- **[Favorites](https://audiobrowser.dev/guide/favorites)** — favorite the current track from the Now Playing heart button or by voice, ask Siri to “play my favorites” or search within them, and keep favorited state in sync across surfaces — even when your app stores favorites by ID instead of stream URL.
+- **[Voice search](https://audiobrowser.dev/guide/search)** — Siri and Google Assistant route into one structured `search` source, so “play some jazz” can arrive as a genre filter instead of a raw query string.
+- **[Access gates](https://audiobrowser.dev/guide/gate)** — put browse and search behind a paywall, login, or region wall with per-request resolvers.
+- **Request and [artwork](https://audiobrowser.dev/guide/artwork) control** — rewrite outbound requests, add auth headers, shape URLs, and customize artwork loading.
+- **Web support** — the same `AudioBrowser` API works with `react-native-web` for playback, browse, search, and sleep timer.
+- **Platform extras** — [AirPlay and output routing](https://audiobrowser.dev/guide/audio-output) on iOS, [Android battery-resume handling](https://audiobrowser.dev/guide/battery), [sleep timer](https://audiobrowser.dev/guide/sleep-timer), and [Android equalizer support](https://audiobrowser.dev/guide/equalizer).
+
+## Requirements
+
+- React Native **0.76+** with the **New Architecture** (Fabric + TurboModules)
+- iOS **16+** · Android **API 23+**
+- [`react-native-nitro-modules`](https://nitro.margelo.com) (peer dependency)
+
+## Installation
+
+```sh
+npm install react-native-audio-browser react-native-nitro-modules
+```
+
+iOS:
+
+```sh
+cd ios && pod install
+```
+
+Android links automatically.
+
+CarPlay and Android Auto need extra native setup (entitlements, manifest entries) — see the [CarPlay](https://audiobrowser.dev/guide/carplay) and [Android Auto](https://audiobrowser.dev/guide/android-auto) guides.
+
+## Quick Start
+
+Point the library at your API and it drives the whole CarPlay / Android Auto browse tree — lazily, as the listener navigates:
+
+```ts
+import AudioBrowser from 'react-native-audio-browser'
+
+await AudioBrowser.setupPlayer()
+
+AudioBrowser.configureBrowser({
+  tabs: [{ title: 'Browse', url: '/browse' }],
+  routes: {
+    // Every path under /browse is fetched from your API, on demand.
+    '/browse/**': { baseUrl: 'https://api.example.com' },
+  },
+})
+```
+
+Each route returns a page of children — a child with a `url` is browsable (open it for more), one with a `src` is a playable track (plus optional `artist`, `artwork`, …):
+
+```jsonc
+// GET https://api.example.com/browse/jazz  →
+{
+  "url": "/browse/jazz",
+  "title": "Jazz",
+  "children": [
+    { "title": "Smooth Floret FM", "url": "/browse/jazz/floret-fm" },           // url → open for children
+    { "title": "The Stalk 88.5", "src": "https://stream.example.com/stalk.mp3" } // src → play this stream
+  ]
+}
+```
+
+The player works standalone, too — no browse tree required:
+
+```ts
+import AudioBrowser from 'react-native-audio-browser'
+
+await AudioBrowser.setupPlayer()
+AudioBrowser.setQueue([{ title: 'Track', artist: 'Artist', src: 'https://example.com/track.mp3' }])
+AudioBrowser.play()
+```
+
+## Hooks
+
+Reactive hooks for your in-app UI — they update automatically as playback, the queue, and browse state change. Call `setupPlayer()` once at startup, before rendering any component that uses them.
+
+| Hook | Returns |
+| --- | --- |
+| `usePlayingState()` | `{ playing, buffering }` |
+| `useProgress()` | `{ position, duration, buffered }` (seconds) |
+| `useActiveTrack()` | the current `Track` |
+| `useNowPlaying()` | now-playing metadata |
+| `useQueue()` | the current queue |
+| `useRepeatMode()` / `useShuffle()` | repeat / shuffle state |
+| `useSleepTimer()` | sleep-timer state |
+| `useCarConnected()` | whether a car is connected |
+| `usePath()` / `useTabs()` / `useContent()` | current browse path, tabs, and the resolved page at the current path |
+
+…and more — see the [Hooks guide](https://audiobrowser.dev/guide/hooks) and the [API Reference](https://audiobrowser.dev/api/).
+
+```tsx
+import { View, Text, Button } from 'react-native'
+import AudioBrowser, {
+  usePlayingState,
+  useProgress,
+  useActiveTrack,
+} from 'react-native-audio-browser'
+
+function PlayerBar() {
+  const { playing } = usePlayingState()        // { playing, buffering }
+  const { position, duration } = useProgress() // in seconds
+  const track = useActiveTrack()               // Track | undefined
+
+  return (
+    <View>
+      <Text>{track?.title}</Text>
+      <Text>{Math.floor(position)} / {Math.floor(duration)}s</Text>
+      <Button
+        title={playing ? 'Pause' : 'Play'}
+        onPress={() => AudioBrowser.togglePlayback()}
+      />
+    </View>
+  )
+}
+```
+
+## Streaming
+
+Optimizations for live radio and long-running streams:
+
+- **Auto-reconnect** — opt in with `setupPlayer({ retry: true })`. On a network error the player retries with exponential backoff (~1→5s, up to a 2-minute window), waits out offline gaps, and reconnects the instant the network returns.
+- **Fresh URLs on reconnect** — if you resolve sources with a `media.resolve` callback, every retry re-runs it, so expired signed / token-authenticated stream URLs refresh on their own.
+- **Live edge** — `seekToLiveEdge()` jumps back to live: the DVR-window end for seekable HLS, a clean reconnect for non-seekable ICY/Icecast.
+- **ICY & chapter metadata** — Shoutcast `StreamTitle` and chapter markers surface via `onTimedMetadata` / `onChapterMetadata`, and feed the lock screen.
+- **Plays nicely** — pauses cleanly on calls, audio-focus loss, and headphone/Bluetooth disconnect, and resumes when it should.
+- **HLS, ICY/Icecast, and progressive** everywhere; DASH on Android and web.
+
+Plus deeper per-platform hardening — Android stuck-stream recovery, optional disk caching, and opt-in [AIA-chasing TLS](https://audiobrowser.dev/guide/android-certificates) (supports streams whose servers omit intermediate CA certificates); iOS media-services-reset and AirPlay stall recovery.
+
+## Documentation
+
+Full guides and the complete [API Reference](https://audiobrowser.dev/api/) live at [audiobrowser.dev](https://audiobrowser.dev).
+
+**Start here** — [Getting Started](https://audiobrowser.dev/guide/getting-started) · [Basic Usage](https://audiobrowser.dev/guide/basic-usage) · [Configuration](https://audiobrowser.dev/guide/configuration) · [Track](https://audiobrowser.dev/guide/track) · [Hooks](https://audiobrowser.dev/guide/hooks) · [Migrating from react-native-track-player](https://audiobrowser.dev/guide/migrating-from-track-player)
+
+**Player** — [Playback](https://audiobrowser.dev/guide/playback) · [Queue](https://audiobrowser.dev/guide/queue) · [Now Playing](https://audiobrowser.dev/guide/now-playing) · [Metadata](https://audiobrowser.dev/guide/metadata) · [Remote Controls](https://audiobrowser.dev/guide/remote-controls) · [Errors](https://audiobrowser.dev/guide/errors) · [Artwork](https://audiobrowser.dev/guide/artwork)
+
+**Browse** — [Browser](https://audiobrowser.dev/guide/browser) · [Search](https://audiobrowser.dev/guide/search) · [Favorites](https://audiobrowser.dev/guide/favorites) · [Gate](https://audiobrowser.dev/guide/gate)
+
+**Automotive** — [Overview](https://audiobrowser.dev/guide/automotive) · [CarPlay](https://audiobrowser.dev/guide/carplay) · [Android Auto](https://audiobrowser.dev/guide/android-auto)
+
+**Extras** — [Sleep Timer](https://audiobrowser.dev/guide/sleep-timer) · [Equalizer](https://audiobrowser.dev/guide/equalizer) · [Audio Output](https://audiobrowser.dev/guide/audio-output) · [Network](https://audiobrowser.dev/guide/network) · [Battery](https://audiobrowser.dev/guide/battery)
+
+**Troubleshooting** — [Networking in native callbacks](https://audiobrowser.dev/guide/native-callback-fetch) · [Android SSL / trust anchors](https://audiobrowser.dev/guide/android-certificates)
+
+The example app in [`apps/example-native`](https://github.com/radio-garden/react-native-audio-browser/tree/main/apps/example-native) browses archive.org's audio collection — in-app, on CarPlay, and on Android Auto — with search, favorites, and the gate.
+
+## Support
+
+Questions or bugs? [Open an issue](https://github.com/radio-garden/react-native-audio-browser/issues). Release notes live in the [changelog](CHANGELOG.md).
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE) © the react-native-audio-browser contributors

package/android/build.gradle

@@ -56,6 +56,14 @@ android {
   ndkVersion getExtOrDefault("ndkVersion")
   compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
 
+  // JVM unit tests don't link the Android framework, so un-mocked android.* calls
+  // (e.g. android.util.LruCache.evictAll) throw "not mocked". Returning default
+  // values makes them no-ops so logic-only tests (e.g. layer-generation caching)
+  // can exercise code paths that touch framework types.
+  testOptions {
+    unitTests.returnDefaultValues = true
+  }
+
   defaultConfig {
     minSdkVersion getExtOrIntegerDefault("minSdkVersion")
     targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
@@ -158,6 +166,8 @@ dependencies {
 
   // Make sure we're using androidx
   implementation "androidx.core:core-ktx:1.13.1"
+  // CarConnection: the documented Android Auto / Automotive connection signal
+  implementation "androidx.car.app:app:1.4.0"
   implementation "androidx.localbroadcastmanager:localbroadcastmanager:1.1.0"
   implementation "androidx.lifecycle:lifecycle-process:2.8.6"
   implementation 'androidx.media:media:1.7.0'

package/android/gradle.properties

@@ -3,4 +3,4 @@ AudioBrowser_minSdkVersion=23
 AudioBrowser_targetSdkVersion=35
 AudioBrowser_compileSdkVersion=34
 AudioBrowser_ndkVersion=27.1.12297006
-AudioBrowser_media3Version=1.8.0
+AudioBrowser_media3Version=1.10.1

package/android/src/main/AndroidManifest.xml

@@ -7,6 +7,12 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
 
+    <!-- Lets the CarConnection query reach the car system app's content
+         provider under Android 11+ package-visibility rules -->
+    <queries>
+        <provider android:authorities="androidx.car.app.connection" />
+    </queries>
+
     <application>
         <!-- Audio Browser Service -->
         <service android:name="com.audiobrowser.Service" android:enabled="true" android:exported="true" android:foregroundServiceType="mediaPlayback">
@@ -24,6 +30,15 @@
             </intent-filter>
         </service>
 
+        <!-- Exported, token-gated content provider serving browse artwork to Android Auto / AAOS.
+             Exported is required: AAOS runs in a different uid and no URI grant is issued by Media3.
+             The authority placeholder is replaced by the app's package name at build time. -->
+        <provider
+            android:name="com.audiobrowser.util.ArtworkContentProvider"
+            android:authorities="${applicationId}.audiobrowser.artwork"
+            android:exported="true"
+            android:grantUriPermissions="false" />
+
         <!-- Headless Task Service for background JS execution -->
         <service android:name="com.audiobrowser.HeadlessTaskService" android:enabled="true" android:exported="false" />
         <!-- Media button receiver for playback resumption -->