@symbiote-native/audio 0.1.1 → 0.1.3

package/README.md

@@ -1,13 +1,14 @@
 # @symbiote-native/audio
 
-A wrapper package for [SymbioteNative](../../README.md) that makes
-[`expo-audio`](https://github.com/expo/expo/tree/main/packages/expo-audio) usable from **every**
-adapter — React, Vue, Svelte, Solid, and Angular. `AudioPlayer`, `AudioRecorder`, `AudioPlaylist`,
-and `AudioStream` are JSI-backed `SharedObject` instances — per-instance native objects with real
-state and methods, not one-shot functions — so there is no hook/composable/service wrapper here
-either: the React, Vue, Svelte, Solid, and Angular entry points are plain re-exports of the same
-`core`, and each adapter's own lifecycle code (the equivalent of upstream's `useAudioPlayer`)
-decides when to create one and when to call `.remove()` / `.destroy()`.
+Play a track, record the microphone, queue a playlist or read raw PCM samples, and keep playing when
+the app goes to the background. One API for every [SymbioteNative](../../README.md) adapter (React,
+Vue, Svelte, Solid and Angular).
+
+It wraps [`expo-audio`](https://github.com/expo/expo/tree/main/packages/expo-audio).
+`AudioPlayer`, `AudioRecorder`, `AudioPlaylist` and `AudioStream` are JSI-backed `SharedObject`
+instances: per-instance native objects with real state and methods, not one-shot functions. Every
+upstream lifecycle hook, including `useAudioStream`, is ported to every adapter (see "Hooks"
+below), so a player is created, replaced and released with its component.
 
 ## Install
 
@@ -23,49 +24,49 @@ npx @symbiote-native/cli new my-app --audio
 npx @symbiote-native/cli add --audio
 ```
 
-Either way: installs `@symbiote-native/audio`, wires the native autolinking automatically, and — since
-this package has an optional, policy-sensitive Android bundle — asks at the end whether to grant
+Either way: installs `@symbiote-native/audio`, wires the native autolinking automatically, and - since
+this package has an optional, policy-sensitive Android bundle - asks at the end whether to grant
 background recording too (see the note below the manual-install block). See
 [`@symbiote-native/cli`](../cli).
 
 <details>
-<summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
+<summary>Manual install (no CLI - installing and wiring native autolinking by hand)</summary>
 
 ```bash
 npm install @symbiote-native/audio
 ```
 
 `expo-audio` and `expo-modules-core` come along as regular dependencies, pinned to exact
-versions — never install either yourself, and never add the `expo` meta-package to your project
+versions - never install either yourself, and never add the `expo` meta-package to your project
 (it bundles its own Metro/Babel pipeline, which conflicts with this project's own).
 
 ## Required one-time step: native autolinking wiring
 
-Same one-time step as every other `expo-modules-core` package this project ships — see
+Same one-time step as every other `expo-modules-core` package this project ships - see
 [`@symbiote-native/local-auth`'s README](../local-auth/README.md#required-one-time-step-native-autolinking-wiring)
 and the `symbiote-expo-native-module` project skill. Nothing package-specific beyond one Info.plist
 string:
 
-- iOS — `NSMicrophoneUsageDescription` in `Info.plist`, wired automatically by
+- iOS - `NSMicrophoneUsageDescription` in `Info.plist`, wired automatically by
   `@symbiote-native/expo-modules-link`'s aggregator (`native-link.json`'s `ios.infoPlistKeys`) the
-  next time it runs — override the default text by adding the key yourself first. Same aggregator
-  also adds `UIBackgroundModes: audio` (`ios.infoPlistArrayKeys`) — upstream's own `withAudio.ts`
+  next time it runs - override the default text by adding the key yourself first. Same aggregator
+  also adds `UIBackgroundModes: audio` (`ios.infoPlistArrayKeys`) - upstream's own `withAudio.ts`
   config plugin defaults `enableBackgroundPlayback` to `true`, and without this key iOS suspends
   playback the moment the app backgrounds.
-- Android — `RECORD_AUDIO` / `MODIFY_AUDIO_SETTINGS` already ship in `expo-audio`'s own
+- Android - `RECORD_AUDIO` / `MODIFY_AUDIO_SETTINGS` already ship in `expo-audio`'s own
   `AndroidManifest.xml` and merge automatically, same as every other autolinked permission.
   Background **playback** is wired the same way as iOS: `native-link.json`'s
   `android.manifestPermissions` adds `FOREGROUND_SERVICE`/`FOREGROUND_SERVICE_MEDIA_PLAYBACK`, and
   `android.manifestServices` declares `AudioControlsService` (`foregroundServiceType="mediaPlayback"`)
-  — matching upstream's own `withAudio.ts` config plugin, whose `enableBackgroundPlayback` defaults
+  - matching upstream's own `withAudio.ts` config plugin, whose `enableBackgroundPlayback` defaults
   to `true`. Background **recording** (`allowsBackgroundRecording: true`) is opt-in, matching
-  upstream's own `enableBackgroundRecording` default of `false` — requesting the microphone
+  upstream's own `enableBackgroundRecording` default of `false` - requesting the microphone
   foreground-service type is exactly the kind of thing that should be a deliberate app choice, not
   a package side effect (same reasoning as `@symbiote-native/location`'s background permission).
 
 </details>
 
-**Background recording — opt-in, asked for you.** `new --audio`/`add --audio` above already ask,
+**Background recording - opt-in, asked for you.** `new --audio`/`add --audio` above already ask,
 interactively, whether to grant it; say yes and `FOREGROUND_SERVICE_MICROPHONE`/
 `POST_NOTIFICATIONS` plus the `AudioRecordingService` (`foregroundServiceType="microphone"`)
 `<service>` land in your `AndroidManifest.xml` for you, along with the `allowsBackgroundRecording`
@@ -76,21 +77,21 @@ Run it any time after:
 npx @symbiote-native/cli grant audio
 ```
 
-Idempotent — safe to run again even if already granted.
+Idempotent - safe to run again even if already granted.
 
 ## Shape
 
 ```
 src/core/     AudioPlayer / AudioRecorder / AudioPlaylist / AudioStream classes (each a thin
               subclass of the native SharedObject, adding only the JS-side logic upstream's own
-              ExpoAudio.ts shims onto the prototype — source resolution on `replace()`, the
+              ExpoAudio.ts shims onto the prototype - source resolution on `replace()`, the
               Android arg-count fix for `setPlaybackRate()`, per-platform option processing for
               `prepareToRecordAsync()`), the createAudioPlayer / createAudioPlaylist /
               createAudioStream factories, the audio-session/permission/preload module functions,
               RecordingPresets, and the event-name constants `addListener` accepts.
               native-module.ts resolves the native module via expo-modules-core's
               requireNativeModule.
-src/angular/  @symbiote-native/audio/angular — export * from '../core'
+src/angular/  @symbiote-native/audio/angular - export * from '../core'
 ```
 
 `./react`, `./vue`, `./svelte`, and `./solid` are `exports`-map aliases straight onto
@@ -144,13 +145,12 @@ recorder.addListener(RECORDING_STATUS_UPDATE, status => console.log(status));
 await recorder.stop();
 ```
 
-Playlist and real-time PCM streaming follow the same `create*` + `addListener` shape:
-`createAudioPlaylist({ sources: [...], loop: 'all' })` and `createAudioStream()` — the stream
-factory takes no `onBuffer` callback (unlike upstream's `useAudioStream` hook); subscribe with
-`stream.addListener(AUDIO_STREAM_BUFFER, ...)` after `stream.start()`, same as every other event
-on these classes.
+Playlist follows the same `create*` + `addListener` shape: `createAudioPlaylist({ sources: [...],
+loop: 'all' })`. Real-time PCM streaming has both a bare factory (`createAudioStream()` plus
+`stream.addListener(AUDIO_STREAM_BUFFER, ...)` after `stream.start()`) and the full
+`useAudioStream(options)` hook on every adapter, see "Hooks" below.
 
-Identical import surface on every adapter — `@symbiote-native/audio/react`, `/vue`, `/svelte`,
+Identical import surface on every adapter - `@symbiote-native/audio/react`, `/vue`, `/svelte`,
 `/solid`, `/angular` all re-export the same classes and functions.
 
 ## API
@@ -216,34 +216,78 @@ TRACK_CHANGED, AUDIO_STREAM_BUFFER, AUDIO_STREAM_STATUS  // event names for .add
 
 Plus the full `I`-prefixed type surface ported from upstream's `Audio.types.ts` /
 `AudioModule.types.ts` / `AudioStream.types.ts` / `AudioConstants.ts`, re-exported from the
-barrel — see `src/core/types.ts`.
-
-## Deliberately not ported
-
-- **`useAudioPlayer` / `useAudioPlayerStatus` / `useAudioSampleListener` / `useAudioRecorder` /
-  `useAudioRecorderState` / `useAudioPlaylist` / `useAudioPlaylistStatus` / `useAudioStream`** —
-  React hooks, framework-specific by construction. `createAudioPlayer` / `createAudioPlaylist` /
-  `createAudioStream` are the framework-agnostic equivalents each already exposes (upstream's own
-  hooks are thin wrappers over these plus `useReleasingSharedObject` for cleanup-on-unmount); each
-  adapter's own lifecycle wrapper is where a hook/composable/service belongs, per
-  `<components_split_logic_view_lifecycle>` in the root project CLAUDE.md. None ship yet.
-- **The `Asset`-instance form of `AudioSource`, and the `downloadFirst` player option.** Upstream
-  resolves both through `expo-asset` (`Asset.fromModule` / `Asset.downloadAsync`), which depends
-  on `expo-constants` and peers on the `expo` meta-package — this project never depends on `expo`
-  (root CLAUDE.md's dependency-scope invariant, and the `symbiote-expo-native-module` skill §1).
-  The plain `number` form (`require('./song.mp3')`) **is** supported — `resolveSource`/
-  `resolveSources` resolve it through RN's own generic `resolveAssetSource`, wired by
-  `bootstrapHost`, no `expo-asset` needed.
-- **`interruptionModeAndroid`** on `IAudioMode` — upstream marks it `@deprecated`, superseded by
-  the cross-platform `interruptionMode`.
+barrel - see `src/core/types.ts`.
+
+`IAudioSource` accepts a URI string, a `require('./song.mp3')` module id, an `@symbiote-native/asset`
+`Asset` instance, or a `{ uri | assetId, headers?, name? }` object - matching upstream's full
+`AudioSource` union now that `@symbiote-native/asset` ships. `createAudioPlayer`'s `downloadFirst`
+option is ported too: the player starts with no source and `replace()`s it once
+`Asset.downloadAsync()` resolves a local cache file, same as upstream's `useAudioPlayer`.
+
+## Hooks
+
+Every upstream hook is ported to all five adapters (Angular names each `injectX` per its own
+`injectX` convention). Framework-name suffix is dropped below; read `useAudioPlayer` as
+`useAudioPlayer`/`injectAudioPlayer` depending on adapter.
+
+- **`useAudioPlayer(source?, options?)`** - resource lifecycle (recreate-on-source-change, dispose
+  the stale one), via `createResourceController`/`createResourceHook` in
+  `core/audio-player-controller.ts`.
+- **`useAudioPlayerStatus(player)`** - subscribes to `playbackStatusUpdate`, via the shared
+  `createEventValueHook` factory (`core/index.ts`'s `IEventValueSource` contract).
+- **`useAudioSampleListener(player, listener)`** - enables sampling and subscribes to
+  `audioSampleUpdate`, via `subscribeAudioSampleListener` in `core/audio-sample-listener.ts`.
+- **`useAudioPlaylist(options?)`** - same resource-lifecycle shape as `useAudioPlayer`, via
+  `core/audio-playlist-controller.ts`.
+- **`useAudioPlaylistStatus(playlist)`** - subscribes to `playlistStatusUpdate`, same
+  `createEventValueHook` factory.
+- **`useAudioRecorder(options, statusListener?)`** - resource lifecycle plus a
+  `recordingStatusUpdate` subscription, via `core/audio-recorder-controller.ts` and
+  `subscribeRecordingStatus` in `core/audio-recorder-status.ts`.
+- **`useAudioRecorderState(recorder, interval?)`** - polls `recorder.getStatus()` and only writes
+  a meaningful change, via `pollRecorderState`/`shouldUpdateRecorderState` in
+  `core/audio-recorder-polling.ts`.
+- **`useAudioStream(options)`** - resource lifecycle keyed on `{sampleRate, channels, encoding}`
+  plus an `audioStreamStatus`/`audioStreamBuffer` subscription, via `createAudioStreamHooks`/
+  `runAudioStreamBufferEffect` in `core/audio-stream-hooks.ts`/`core/audio-stream-lifecycle.ts`.
+
+Every adapter shares the framework-agnostic diffing/subscription logic from `core/`; only the
+lifecycle primitive differs (React/Solid/Vue/Angular's own `createResourceHook`/
+`createEventValueHook`, Svelte's from `@symbiote-native/svelte/runes/*`).
+
+## Notes
+
+- **Silent mode on iOS.** Call `setAudioModeAsync({ playsInSilentMode: true })` or playback is
+  muted by the ring/silent switch.
+- **Release what you create by hand.** `createAudioPlayer` and the other factories leave cleanup to
+  you (`remove()`); the hooks do it automatically.
+- **Android background playback needs lock-screen controls.** Without `setActiveForLockScreen`,
+  Android stops background audio after about three minutes (an OS limit).
+
+## Common questions
+
+- **Silent on iPhone.** `setAudioModeAsync({ playsInSilentMode: true })`.
+- **Stops in the background.** `shouldPlayInBackground: true`; on Android also
+  `setActiveForLockScreen`, or the OS stops it after about three minutes.
+- **Recording permission error.** `requestRecordingPermissionsAsync()` first; background recording
+  is opt-in (`npx @symbiote-native/cli grant audio`).
+- **Change the track.** `player.replace(source)`; `useAudioPlayer` recreates on a changed source.
+- **Leaking players.** Factory-made players need `remove()`; the hooks do it for you.
+
+Sources: [Expo docs: Audio](https://docs.expo.dev/versions/latest/sdk/audio/),
+[expo/expo#24484](https://github.com/expo/expo/issues/24484),
+[expo/expo#43086](https://github.com/expo/expo/issues/43086).
+
+## Scope exclusions
+
 - **Web-only surfaces** (`ExpoAudio.web.ts`, `AudioPlayer.web.ts`, `AudioStream.web.ts`,
-  `MediaSessionController.web.ts`) — this project targets iOS + Android only.
+  `MediaSessionController.web.ts`) - this project targets iOS + Android only.
 
 ## Test it
 
-No Fabric/Descriptor angle at all — every class here is a `SharedObject` with no visual
+No Fabric/Descriptor angle at all - every class here is a `SharedObject` with no visual
 component. Tests fake the native `AudioPlayer`/`AudioRecorder`/`AudioPlaylist`/`AudioStream`
 classes `expoAudio` exposes (real prototype methods, so the subclass `super.*()` calls in
 `audio-player.ts`/`audio-recorder.ts` resolve correctly) and the plain async module functions
 (`src/core/audio-classes.test.ts`, `src/core/audio-module.test.ts`, `src/core/
-resolve-source.test.ts`) — no `installFabric()`, no ViewConfig.
+resolve-source.test.ts`) - no `installFabric()`, no ViewConfig.

package/build/angular/index.d.ts

@@ -1 +1,9 @@
 export * from '../core';
+export { injectAudioPlayer } from './inject-audio-player';
+export { injectAudioPlayerStatus } from './inject-audio-player-status';
+export { injectAudioSampleListener } from './inject-audio-sample-listener';
+export { injectAudioPlaylist } from './inject-audio-playlist';
+export { injectAudioPlaylistStatus } from './inject-audio-playlist-status';
+export { injectAudioRecorder } from './inject-audio-recorder';
+export { injectAudioRecorderState } from './inject-audio-recorder-state';
+export { injectAudioStream } from './inject-audio-stream';

package/build/angular/index.js

@@ -1,4 +1,9 @@
-// @symbiote-native/audio/angular: the Angular entry over the framework-agnostic core. Same
-// reasoning as the React/Vue entries — every export here is a plain class/function with no
-// framework-specific lifecycle to wrap, so this is a plain re-export.
 export * from '../core/index.js';
+export { injectAudioPlayer } from './inject-audio-player.js';
+export { injectAudioPlayerStatus } from './inject-audio-player-status.js';
+export { injectAudioSampleListener } from './inject-audio-sample-listener.js';
+export { injectAudioPlaylist } from './inject-audio-playlist.js';
+export { injectAudioPlaylistStatus } from './inject-audio-playlist-status.js';
+export { injectAudioRecorder } from './inject-audio-recorder.js';
+export { injectAudioRecorderState } from './inject-audio-recorder-state.js';
+export { injectAudioStream } from './inject-audio-stream.js';

package/build/angular/inject-audio-player-status.d.ts

@@ -0,0 +1,4 @@
+import type { AudioPlayer } from '../core';
+import type { IAudioStatus } from '../core';
+/** Angular twin of `expo-audio`'s `useAudioPlayerStatus` */
+export declare const injectAudioPlayerStatus: (getSource: () => AudioPlayer) => import("@angular/core").Signal<IAudioStatus>;

package/build/angular/inject-audio-player-status.js

@@ -0,0 +1,4 @@
+import { createEventValueHook } from '@symbiote-native/angular';
+import { PLAYBACK_STATUS_UPDATE } from '../core/types.js';
+/** Angular twin of `expo-audio`'s `useAudioPlayerStatus` */
+export const injectAudioPlayerStatus = createEventValueHook(PLAYBACK_STATUS_UPDATE, player => player.currentStatus);

package/build/angular/inject-audio-player.d.ts

@@ -0,0 +1,4 @@
+import type { Signal } from '@angular/core';
+import type { AudioPlayer } from '../core';
+import type { IAudioPlayerOptions, IAudioSource } from '../core';
+export declare function injectAudioPlayer(source: () => IAudioSource, options?: () => IAudioPlayerOptions): Signal<AudioPlayer>;

package/build/angular/inject-audio-player.js

@@ -0,0 +1,8 @@
+// Angular twin of `useAudioPlayer`, `injectX` shape matching
+// `@symbiote-native/navigation`'s `injectLinkingIntegration`
+import { createResourceHook } from '@symbiote-native/angular';
+import { createAudioPlayerController } from '../core/audio-player-controller.js';
+const injectPlayerResource = createResourceHook(createAudioPlayerController);
+export function injectAudioPlayer(source, options = () => ({})) {
+    return injectPlayerResource(() => [source(), options()]);
+}

package/build/angular/inject-audio-playlist-status.d.ts

@@ -0,0 +1,3 @@
+import type { IAudioPlaylistStatus } from '../core';
+/** Angular twin of `expo-audio`'s `useAudioPlaylistStatus` */
+export declare const injectAudioPlaylistStatus: (getSource: () => import("../core/native-module").NativeAudioPlaylist) => import("@angular/core").Signal<IAudioPlaylistStatus>;

package/build/angular/inject-audio-playlist-status.js

@@ -0,0 +1,4 @@
+import { createEventValueHook } from '@symbiote-native/angular';
+import { PLAYLIST_STATUS_UPDATE } from '../core/types.js';
+/** Angular twin of `expo-audio`'s `useAudioPlaylistStatus` */
+export const injectAudioPlaylistStatus = createEventValueHook(PLAYLIST_STATUS_UPDATE, playlist => playlist.currentStatus);

package/build/angular/inject-audio-playlist.d.ts

@@ -0,0 +1,5 @@
+import type { Signal } from '@angular/core';
+import type { AudioPlaylist } from '../core';
+import type { IAudioPlaylistOptions } from '../core';
+/** Angular twin of `expo-audio`'s `useAudioPlaylist` */
+export declare function injectAudioPlaylist(getOptions: () => IAudioPlaylistOptions): Signal<AudioPlaylist>;

package/build/angular/inject-audio-playlist.js

@@ -0,0 +1,7 @@
+import { createResourceHook } from '@symbiote-native/angular';
+import { createAudioPlaylistController } from '../core/audio-playlist-controller.js';
+const injectPlaylistResource = createResourceHook(createAudioPlaylistController);
+/** Angular twin of `expo-audio`'s `useAudioPlaylist` */
+export function injectAudioPlaylist(getOptions) {
+    return injectPlaylistResource(() => [getOptions()]);
+}

package/build/angular/inject-audio-recorder-state.d.ts

@@ -0,0 +1,5 @@
+import { type Signal } from '@angular/core';
+import type { AudioRecorder } from '../core';
+import type { IRecorderState } from '../core';
+/** Angular twin of `expo-audio`'s `useAudioRecorderState` */
+export declare function injectAudioRecorderState(recorder: AudioRecorder, interval?: number): Signal<IRecorderState>;

package/build/angular/inject-audio-recorder-state.js

@@ -0,0 +1,10 @@
+import { DestroyRef, inject, signal } from '@angular/core';
+import { pollRecorderState } from '../core/audio-recorder-polling.js';
+const DEFAULT_POLL_INTERVAL_MS = 500;
+/** Angular twin of `expo-audio`'s `useAudioRecorderState` */
+export function injectAudioRecorderState(recorder, interval = DEFAULT_POLL_INTERVAL_MS) {
+    const state = signal(recorder.getStatus());
+    const stop = pollRecorderState(recorder, interval, updater => state.set(updater(state())));
+    inject(DestroyRef).onDestroy(stop);
+    return state.asReadonly();
+}

package/build/angular/inject-audio-recorder.d.ts

@@ -0,0 +1,5 @@
+import { type Signal } from '@angular/core';
+import type { AudioRecorder } from '../core';
+import type { IRecordingOptions, IRecordingStatus } from '../core';
+/** Angular twin of `expo-audio`'s `useAudioRecorder` */
+export declare function injectAudioRecorder(getOptions: () => IRecordingOptions, statusListener?: (status: IRecordingStatus) => void): Signal<AudioRecorder>;

package/build/angular/inject-audio-recorder.js

@@ -0,0 +1,13 @@
+import { effect } from '@angular/core';
+import { createResourceHook } from '@symbiote-native/angular';
+import { createAudioRecorderController } from '../core/audio-recorder-controller.js';
+import { subscribeRecordingStatus } from '../core/audio-recorder-status.js';
+const injectRecorderResource = createResourceHook(createAudioRecorderController);
+/** Angular twin of `expo-audio`'s `useAudioRecorder` */
+export function injectAudioRecorder(getOptions, statusListener) {
+    const recorder = injectRecorderResource(() => [getOptions()]);
+    effect(onCleanup => {
+        onCleanup(subscribeRecordingStatus(recorder(), statusListener));
+    });
+    return recorder;
+}

package/build/angular/inject-audio-sample-listener.d.ts

@@ -0,0 +1,4 @@
+import type { IAudioSamplePlayer } from '../core/audio-sample-listener';
+import type { IAudioSample } from '../core/types';
+/** Angular twin of `expo-audio`'s `useAudioSampleListener` */
+export declare function injectAudioSampleListener(player: IAudioSamplePlayer, listener: (data: IAudioSample) => void): void;

package/build/angular/inject-audio-sample-listener.js

@@ -0,0 +1,7 @@
+import { DestroyRef, inject } from '@angular/core';
+import { subscribeAudioSampleListener } from '../core/audio-sample-listener.js';
+/** Angular twin of `expo-audio`'s `useAudioSampleListener` */
+export function injectAudioSampleListener(player, listener) {
+    const unsubscribe = subscribeAudioSampleListener(player, listener);
+    inject(DestroyRef).onDestroy(unsubscribe);
+}

package/build/angular/inject-audio-stream.d.ts

@@ -0,0 +1,4 @@
+import { type Signal } from '@angular/core';
+import type { IAudioStreamResult, IUseAudioStreamOptions } from '../core';
+/** Angular twin of `expo-audio`'s `useAudioStream` */
+export declare function injectAudioStream(getOptions: () => IUseAudioStreamOptions): Signal<IAudioStreamResult>;

package/build/angular/inject-audio-stream.js

@@ -0,0 +1,17 @@
+import { computed, DestroyRef, effect, inject, } from '@angular/core';
+import { createResourceHook, createEventValueHook, } from '@symbiote-native/angular';
+import { createAudioStreamHooks } from '../core/audio-stream-hooks.js';
+import { toAudioStreamKey } from '../core/audio-stream-subscription.js';
+import { runAudioStreamBufferEffect } from '../core/audio-stream-lifecycle.js';
+const { useStreamResource, useStreamStatus } = createAudioStreamHooks(createResourceHook, createEventValueHook);
+/** Angular twin of `expo-audio`'s `useAudioStream` */
+export function injectAudioStream(getOptions) {
+    const destroyRef = inject(DestroyRef);
+    const stream = useStreamResource(() => [toAudioStreamKey(getOptions())]);
+    const status = useStreamStatus(stream);
+    runAudioStreamBufferEffect(stream, () => getOptions().onBuffer, effect, cleanup => destroyRef.onDestroy(cleanup));
+    return computed(() => ({
+        stream: stream(),
+        isStreaming: status().isStreaming,
+    }));
+}

package/build/core/audio-module.js

@@ -12,7 +12,7 @@ export async function setAudioModeAsync(mode) {
         : {
             shouldPlayInBackground: mode.shouldPlayInBackground,
             shouldRouteThroughEarpiece: mode.shouldRouteThroughEarpiece,
-            interruptionMode: mode.interruptionMode,
+            interruptionMode: mode.interruptionMode ?? mode.interruptionModeAndroid,
             allowsBackgroundRecording: mode.allowsBackgroundRecording,
             playsInSilentMode: mode.playsInSilentMode,
         };

package/build/core/audio-player-controller.d.ts

@@ -0,0 +1,7 @@
+import { type AudioPlayer } from './audio-player';
+import type { IAudioPlayerOptions, IAudioSource } from './types';
+export declare function createAudioPlayerController(): {
+    resolve: (source: IAudioSource, options: IAudioPlayerOptions) => AudioPlayer;
+    flushDispose: () => void;
+    dispose: () => void;
+};

package/build/core/audio-player-controller.js

@@ -0,0 +1,10 @@
+import { createJsonKeyedResourceController } from './json-keyed-resource-controller.js';
+import { createAudioPlayer } from './audio-player.js';
+export function createAudioPlayerController() {
+    const controller = createJsonKeyedResourceController(key => createAudioPlayer(key.source, key.options), player => player.remove());
+    return {
+        resolve: (source, options) => controller.resolve({ source, options }),
+        flushDispose: controller.flushDispose,
+        dispose: controller.dispose,
+    };
+}

package/build/core/audio-player.js

@@ -1,6 +1,6 @@
 import { Platform } from 'expo-modules-core';
 import { expoAudio } from './native-module.js';
-import { resolveSource } from './resolve-source.js';
+import { resolveSource, resolveSourceWithDownload } from './resolve-source.js';
 // Upstream shims these two methods onto `AudioModule.AudioPlayer.prototype` at module load
 // (ExpoAudio.ts). We do the equivalent by subclassing instead of monkey-patching the native
 // class's prototype — same shape packages/media-library/src/next/asset.ts uses for its own
@@ -25,7 +25,19 @@ export class AudioPlayer extends expoAudio.AudioPlayer {
  * upstream's `useReleasingSharedObject`.
  */
 export function createAudioPlayer(source = null, options = {}) {
-    const { updateInterval = 500, keepAudioSessionActive = false, preferredForwardBufferDuration = 0, } = options;
-    const resolvedSource = resolveSource(source);
-    return new AudioPlayer(resolvedSource, updateInterval, keepAudioSessionActive, preferredForwardBufferDuration);
+    const { updateInterval = 500, downloadFirst = false, keepAudioSessionActive = false, preferredForwardBufferDuration = 0, } = options;
+    const player = new AudioPlayer(downloadFirst ? null : resolveSource(source), updateInterval, keepAudioSessionActive, preferredForwardBufferDuration);
+    if (downloadFirst && source) {
+        resolveSourceWithDownload(source)
+            .then(resolved => {
+            if (resolved)
+                player.replace(resolved);
+        })
+            .catch(() => {
+            const fallback = resolveSource(source);
+            if (fallback)
+                player.replace(fallback);
+        });
+    }
+    return player;
 }

package/build/core/audio-playlist-controller.d.ts

@@ -0,0 +1,4 @@
+import type { IResourceController } from '@symbiote-native/engine';
+import { type AudioPlaylist } from './audio-playlist';
+import type { IAudioPlaylistOptions } from './types';
+export declare function createAudioPlaylistController(): IResourceController<IAudioPlaylistOptions, AudioPlaylist>;

package/build/core/audio-playlist-controller.js

@@ -0,0 +1,5 @@
+import { createJsonKeyedResourceController } from './json-keyed-resource-controller.js';
+import { createAudioPlaylist } from './audio-playlist.js';
+export function createAudioPlaylistController() {
+    return createJsonKeyedResourceController(createAudioPlaylist, playlist => playlist.destroy());
+}

package/build/core/audio-recorder-controller.d.ts

@@ -0,0 +1,4 @@
+import type { IResourceController } from '@symbiote-native/engine';
+import { type AudioRecorder } from './audio-recorder';
+import type { IRecordingOptions } from './types';
+export declare function createAudioRecorderController(): IResourceController<IRecordingOptions, AudioRecorder>;

package/build/core/audio-recorder-controller.js

@@ -0,0 +1,5 @@
+import { createJsonKeyedResourceController } from './json-keyed-resource-controller.js';
+import { createAudioRecorder } from './audio-recorder.js';
+export function createAudioRecorderController() {
+    return createJsonKeyedResourceController(createAudioRecorder, recorder => recorder.release());
+}

package/build/core/audio-recorder-polling.d.ts

@@ -0,0 +1,5 @@
+import type { IRecorderState } from './types';
+export type IPollableRecorder = {
+    getStatus: () => IRecorderState;
+};
+export declare function pollRecorderState(recorder: IPollableRecorder, interval: number, update: (updater: (prev: IRecorderState) => IRecorderState) => void): () => void;

package/build/core/audio-recorder-polling.js

@@ -0,0 +1,10 @@
+import { shouldUpdateRecorderState } from './audio-recorder-state.js';
+// Ported from `useAudioRecorderState`'s `setInterval` body; `update` matches every adapter's
+// own state setter (`useState`, Solid's `createSignal`, a plain `(prev) => next` writer, ...)
+export function pollRecorderState(recorder, interval, update) {
+    const id = setInterval(() => {
+        const next = recorder.getStatus();
+        update(prev => (shouldUpdateRecorderState(prev, next) ? next : prev));
+    }, interval);
+    return () => clearInterval(id);
+}

package/build/core/audio-recorder-state.d.ts

@@ -0,0 +1,2 @@
+import type { IRecorderState } from './types';
+export declare function shouldUpdateRecorderState(prev: IRecorderState, next: IRecorderState): boolean;

package/build/core/audio-recorder-state.js

@@ -0,0 +1,18 @@
+const METERING_EPSILON = 0.1;
+const DURATION_EPSILON_MS = 50;
+function meteringChanged(prev, next) {
+    if ((prev.metering === undefined) !== (next.metering === undefined))
+        return true;
+    if (prev.metering === undefined || next.metering === undefined)
+        return false;
+    return Math.abs(prev.metering - next.metering) > METERING_EPSILON;
+}
+// Ported from `useAudioRecorderState`'s poll-diff `setState` body
+export function shouldUpdateRecorderState(prev, next) {
+    return (prev.canRecord !== next.canRecord ||
+        prev.isRecording !== next.isRecording ||
+        prev.mediaServicesDidReset !== next.mediaServicesDidReset ||
+        prev.url !== next.url ||
+        Math.abs(prev.durationMillis - next.durationMillis) > DURATION_EPSILON_MS ||
+        meteringChanged(prev, next));
+}

package/build/core/audio-recorder-status.d.ts

@@ -0,0 +1,8 @@
+import { RECORDING_STATUS_UPDATE } from './types';
+import type { IRecordingStatus } from './types';
+export type IStatusRecorder = {
+    addListener: (event: typeof RECORDING_STATUS_UPDATE, listener: (status: IRecordingStatus) => void) => {
+        remove: () => void;
+    };
+};
+export declare function subscribeRecordingStatus(recorder: IStatusRecorder, statusListener: ((status: IRecordingStatus) => void) | undefined): () => void;

package/build/core/audio-recorder-status.js

@@ -0,0 +1,6 @@
+import { RECORDING_STATUS_UPDATE } from './types.js';
+import { subscribeSingleEvent } from './subscribe-single-event.js';
+// Ported from `useAudioRecorder`'s status-listener `useEffect` body
+export function subscribeRecordingStatus(recorder, statusListener) {
+    return subscribeSingleEvent(recorder, RECORDING_STATUS_UPDATE, statusListener);
+}

package/build/core/audio-recorder.d.ts

@@ -3,3 +3,5 @@ import type { IRecordingOptions } from './types';
 export declare class AudioRecorder extends expoAudio.AudioRecorder {
     prepareToRecordAsync(options?: Partial<IRecordingOptions>): Promise<void>;
 }
+/** Does not release automatically, same lifecycle note as `createAudioPlayer` */
+export declare function createAudioRecorder(options: IRecordingOptions): AudioRecorder;

package/build/core/audio-recorder.js

@@ -38,3 +38,7 @@ export class AudioRecorder extends expoAudio.AudioRecorder {
         return super.prepareToRecordAsync(processedOptions);
     }
 }
+/** Does not release automatically, same lifecycle note as `createAudioPlayer` */
+export function createAudioRecorder(options) {
+    return new AudioRecorder(createRecordingOptions(options));
+}

package/build/core/audio-sample-listener.d.ts

@@ -0,0 +1,11 @@
+import { AUDIO_SAMPLE_UPDATE } from './types';
+import type { IAudioSample } from './types';
+export type IAudioSamplePlayer = {
+    isAudioSamplingSupported: boolean;
+    setAudioSamplingEnabled: (enabled: boolean) => void;
+    addListener: (event: typeof AUDIO_SAMPLE_UPDATE, listener: (data: IAudioSample) => void) => {
+        remove: () => void;
+    };
+};
+/** Ported from `expo-audio`'s `useAudioSampleListener` (its `useEffect` body factored out) */
+export declare function subscribeAudioSampleListener(player: IAudioSamplePlayer, listener: (data: IAudioSample) => void): () => void;

package/build/core/audio-sample-listener.js

@@ -0,0 +1,9 @@
+import { AUDIO_SAMPLE_UPDATE } from './types.js';
+/** Ported from `expo-audio`'s `useAudioSampleListener` (its `useEffect` body factored out) */
+export function subscribeAudioSampleListener(player, listener) {
+    if (!player.isAudioSamplingSupported)
+        return () => { };
+    player.setAudioSamplingEnabled(true);
+    const subscription = player.addListener(AUDIO_SAMPLE_UPDATE, listener);
+    return () => subscription.remove();
+}

package/build/core/audio-stream-controller.d.ts

@@ -0,0 +1,4 @@
+import type { IResourceController } from '@symbiote-native/engine';
+import { type AudioStream } from './audio-stream';
+import type { IAudioStreamOptions } from './types';
+export declare function createAudioStreamController(): IResourceController<IAudioStreamOptions, AudioStream>;

package/build/core/audio-stream-controller.js

@@ -0,0 +1,5 @@
+import { createJsonKeyedResourceController } from './json-keyed-resource-controller.js';
+import { createAudioStream } from './audio-stream.js';
+export function createAudioStreamController() {
+    return createJsonKeyedResourceController(createAudioStream, stream => stream.release());
+}

package/build/core/audio-stream-hooks.d.ts

@@ -0,0 +1,8 @@
+import type { IResourceController } from '@symbiote-native/engine';
+import { AUDIO_STREAM_STATUS } from './types';
+import type { AudioStream } from './audio-stream';
+import type { IAudioStreamOptions, IAudioStreamStatus } from './types';
+export declare function createAudioStreamHooks<TResourceBox, TStatusBox>(createResourceHook: (createController: () => IResourceController<IAudioStreamOptions, AudioStream>) => (getArgs: () => [IAudioStreamOptions]) => TResourceBox, createEventValueHook: (event: typeof AUDIO_STREAM_STATUS, getValue: (source: AudioStream) => IAudioStreamStatus) => (getSource: () => AudioStream) => TStatusBox): {
+    useStreamResource: (getArgs: () => [IAudioStreamOptions]) => TResourceBox;
+    useStreamStatus: (getSource: () => AudioStream) => TStatusBox;
+};