react-native-queue-player 1.0.0

package/lib/typescript/TrackPlayer.nitro.d.ts

@@ -0,0 +1,584 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type { TrackItem, PlayerConfig, PlayerState, BufferState, PlaybackMode, RepeatMode, RemoteControlOptions, StateChangeReason, TrackChangeReason, TrackSource, PlaybackError, PlayerProgress, SkipCapability, SleepTimerState, LookaheadCacheConfig, CacheStatus, MediaSearchRequest, BrowseItem, BrowseSnapshot, ShuffleResult, NowPlayingFormat, ReplayGainMode, PitchCorrectionMode, ServiceReadyReason, VoiceVocabulary } from './types';
+export interface TrackPlayer extends HybridObject<{
+    ios: 'swift';
+    android: 'kotlin';
+}> {
+    /**
+     * Configure the player. **Each call runs an internal `destroy()`
+     * before reinitialising.** The lib tears down any existing playback
+     * engine, audio session, observers, and pending pipeline state, then
+     * constructs a fresh engine with the supplied config. On the FIRST
+     * configure of a session the internal destroy is a no-op (nothing
+     * exists yet); on subsequent calls it is a real teardown.
+     *
+     * Effect: configure is always a clean-slate operation. Consumers do
+     * not need to call `destroy()` before re-configuring — the lib does
+     * it for them.
+     *
+     * **Recommended usage**: call once at app initialisation in a
+     * headless service. Re-configure only on app restart or explicit
+     * state-reset flows. Each call clears the queue, drops the playhead
+     * to zero, and surfaces a teardown signal to active subscribers; they
+     * can resubscribe after the new engine wires up.
+     *
+     * `destroy()` remains exposed publicly for consumers who want to
+     * explicitly tear down without immediately reconfiguring (e.g. on
+     * app background → release audio resources).
+     */
+    configure(config: PlayerConfig): Promise<void>;
+    /**
+     * Tear down the playback engine, audio session, observers, and any
+     * pending pipeline state. Active subscribers receive a teardown
+     * signal. Idempotent — safe to call when nothing is currently
+     * configured (no-op).
+     *
+     * Note: `configure()` calls this internally before each
+     * reinitialise, so explicit `destroy()` is only needed for shutdown
+     * / resource-release flows that do not immediately reconfigure
+     * (e.g. app background).
+     */
+    destroy(): Promise<void>;
+    /**
+     * Replace the queue with `tracks`. Optional `startAtIndex` selects
+     * which queue entry plays first when transport resumes (defaults to
+     * 0). Out-of-range values clamp to `[0, tracks.length - 1]`; empty
+     * queue ignores the parameter.
+     *
+     * `startAtIndex` matches Spotify / Apple Music "tap a song inside an
+     * album" UX — push the whole album as the queue but start playback
+     * at the tapped track. Skip-next walks through the remaining tracks
+     * in their original order.
+     */
+    setQueue(tracks: TrackItem[], startAtIndex?: number): Promise<void>;
+    /**
+     * Append (or insert at `insertBefore`) the given tracks to the queue.
+     *
+     * Non-finite `insertBefore` (NaN / ±Infinity) is dropped on both
+     * natives — the call falls through to append-at-end.
+     *
+     * Cross-platform note: when `setQueue([])` was called immediately
+     * before `addToQueue([t])`, iOS leaves the AVQueuePlayer empty until
+     * `skipToIndex(0)` is called explicitly; Android calls `prepare()`
+     * after the add and starts playback ready immediately. Consumer apps
+     * adding tracks to a previously-empty queue should call
+     * `skipToIndex(0)` before `play()` for cross-platform consistency.
+     */
+    addToQueue(tracks: TrackItem[], insertBefore?: number): Promise<void>;
+    removeFromQueue(indices: number[]): Promise<void>;
+    /**
+     * Move a track within the queue.
+     *
+     * Cross-platform note: moving the currently-playing track to a new
+     * position causes an audible restart from 0 on iOS (full
+     * AVQueuePlayer rebuild — AVQueuePlayer can't reorder around its
+     * play head); Android `moveMediaItem` preserves position. If
+     * cross-platform consistency matters more than the iOS rebuild's
+     * cost, defer the move until playback ends or the user pauses.
+     */
+    moveInQueue(fromIndex: number, toIndex: number): Promise<void>;
+    /**
+     * Returns the current queue snapshot.
+     *
+     * Cross-platform note: on Android the read crosses thread boundaries
+     * (`@Volatile tracks` field, no main-hop) — calling `getQueue()` and
+     * `getCurrentTrackIndex()` back-to-back can observe a one-tick skew
+     * during a concurrent queue mutation (e.g. mid-`setQueue`). For UI
+     * code that needs the pair to be consistent, prefer the
+     * `useActiveTrack` hook which subscribes to `onTrackChange` and
+     * receives both atomically.
+     */
+    getQueue(): TrackItem[];
+    clearQueue(): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Manually re-attempt the current track after its automatic retries were
+     * exhausted (the track is in the error state). Rebuilds the failed item and
+     * resumes from where it stopped, then plays. Use for a "tap to retry" button:
+     * e.g. the user left WiFi coverage so the auto-retries failed, then came back
+     * in range and taps retry. A no-op when there is no current track or the
+     * current track is not in the error state.
+     */
+    retry(): Promise<void>;
+    /** position in seconds from the start of the current track */
+    seekTo(position: number): Promise<void>;
+    skipToIndex(index: number): Promise<void>;
+    skipToNext(): Promise<void>;
+    skipToPrevious(): Promise<void>;
+    setPlaybackMode(mode: PlaybackMode): Promise<void>;
+    /**
+     * Read the requested playback mode. Returns whatever was last
+     * passed to `setPlaybackMode`, regardless of whether the engine
+     * has actually swapped (mid-track switches are deferred to the
+     * next track-boundary; the requested mode is the user's intent
+     * and what consumer UI should reflect).
+     */
+    getPlaybackMode(): PlaybackMode;
+    /**
+     * Set playback speed. Lib clamps to a minimum of 0.25 — passing
+     * 0 would pause on iOS (`AVPlayer.rate = 0` ≡ pause) and produce
+     * undefined audio behaviour on Android (`PlaybackParameters(0f, …)`
+     * is unspecified at the AudioSink). Values < 0.25 are silently
+     * clamped to 0.25; consumers wanting to pause must call `pause()`.
+     * No upper-bound clamp — native engines apply their own ceilings
+     * (typically ~4.0).
+     */
+    setPlaybackSpeed(rate: number): Promise<void>;
+    /**
+     * Set how pitch behaves when `playbackSpeed != 1.0`: `none`
+     * (pitch follows rate), `voice` (speech-tuned, pitch preserved),
+     * or `music` (music-tuned, transient-preserving). Persists until
+     * changed and is auto-bypassed at `playbackSpeed == 1.0`. Default
+     * `voice`.
+     *
+     * iOS maps the three modes to native
+     * `AVPlayerItem.audioTimePitchAlgorithm`
+     * (`.varispeed` / `.timeDomain` / `.spectral`). On Android `none`
+     * and `voice` use the built-in Media3 time-stretch; `music`
+     * currently uses the same voice-grade algorithm as `voice` (a
+     * dedicated music-grade engine is tracked separately).
+     */
+    setPitchCorrectionMode(mode: PitchCorrectionMode): Promise<void>;
+    /** 0.0 .. 1.0 linear */
+    setVolume(volume: number): Promise<void>;
+    setRepeatMode(mode: RepeatMode): Promise<void>;
+    /**
+     * Choose how the lock-screen / notification skip controls behave — skip
+     * between queue tracks (`'track'`) or jump forward/back within the current
+     * track by a fixed interval (`'interval'`) — and set the jump intervals in
+     * seconds. Applies immediately, so a consumer can let users pick their
+     * preferred controls at runtime. In `'interval'` mode the jump seek is
+     * performed natively; the default is `'track'` with 15-second intervals.
+     */
+    setRemoteControls(options: RemoteControlOptions): Promise<void>;
+    /**
+     * Arm a native sleep timer that pauses playback after `seconds` of
+     * wall-clock time (it counts down whether playing or paused). Playback
+     * fades out over the final 10 seconds, then pauses; `onStateChange` fires
+     * `paused` with reason `sleep-timer`. Re-arming replaces any existing timer.
+     *
+     * To avoid cutting a track off near its end, if the deadline lands with 60
+     * seconds or less left on the current track, the pause is deferred to the
+     * track's natural end (and the fade is undone so the tail plays at full
+     * volume).
+     */
+    setSleepTimer(seconds: number): Promise<void>;
+    /**
+     * Arm a native sleep timer that pauses playback when the CURRENT track
+     * finishes, rather than after a fixed duration. Re-arming replaces any
+     * existing timer. (Same 10-second fade + `sleep-timer` reason as
+     * `setSleepTimer`, applied over the track's final seconds.)
+     */
+    setSleepTimerToTrackEnd(): Promise<void>;
+    /** Cancel any armed sleep timer and restore the pre-fade volume. */
+    clearSleepTimer(): Promise<void>;
+    /**
+     * Destructive shuffle action. Mutates the current queue: takes a
+     * copy of `tracks`, applies a Fisher-Yates shuffle, sets the
+     * shuffled order as the new queue, resets `currentTrackIndex` to
+     * `0` (or `-1` for an empty queue), and — if state was `'playing'`
+     * before the call — resumes playback on the new tracks[0].
+     *
+     * Returns the post-shuffle queue + new current so the consumer
+     * app can immediately reflect the new ordering in its UI without
+     * having to re-fetch via `getQueue()` + `getCurrentTrackIndex()`.
+     *
+     * **No "shuffle off" toggle.** The pre-shuffle ordering is not
+     * preserved; once shuffled the queue stays in the new order until
+     * the consumer calls `setQueue` to install a fresh ordering. This
+     * matches Apple-Music-style "shuffle is an action, not a mode."
+     */
+    shuffleQueue(): Promise<ShuffleResult>;
+    getState(): PlayerState;
+    /**
+     * Index of the currently-playing track in the queue. Returns `-1`
+     * sentinel when the queue is empty OR when no track has been
+     * selected yet (post-`setQueue` before the first `skipToIndex` /
+     * `play`). Consumers should treat any negative value as "no
+     * current track" — the lib does not emit other negative
+     * values today, but the `< 0` check is forward-compatible.
+     */
+    getCurrentTrackIndex(): number;
+    /**
+     * How the active track is being played: `'local'` (file://), `'cached'`
+     * (http(s):// served from the lookahead cache), or `'streaming'`
+     * (http(s):// served from the network). `undefined` when there is no
+     * active track.
+     *
+     * Classified at currentItem-change time. A track whose lookahead
+     * download completes mid-playback continues to report `'streaming'`
+     * until the NEXT track-change re-classifies — the lib does not emit
+     * a synthetic source-change event today. Subscribe to `onTrackChange`
+     * and re-read this value whenever it fires.
+     *
+     * Native-owned + cached: this is a sync read of a value the native
+     * side computes once per track-change.
+     */
+    getCurrentTrackSource(): TrackSource | undefined;
+    getPlaybackSpeed(): number;
+    /** Returns the current pitch-correction mode (default `'voice'`). */
+    getPitchCorrectionMode(): PitchCorrectionMode;
+    getVolume(): number;
+    /** The current remote-control configuration (skip mode + jump intervals). */
+    getRemoteControls(): RemoteControlOptions;
+    /**
+     * Current discrete buffer state for the active track (`'empty'` before any
+     * media loads). See `onBufferStateChange` for the semantics and firing
+     * behaviour.
+     */
+    getBufferState(): BufferState;
+    /**
+     * Whether the active track can be sought. `false` for a genuinely unseekable
+     * stream (e.g. a live source, or a variable-bitrate MP3 with no seek index) —
+     * a `seekTo` on such a track is a no-op rather than a reset to the start. A UI
+     * can grey out its scrubber when this is `false`. `true` when there is no
+     * active track (nothing to forbid). Constant-bitrate MP3 / ADTS / AMR are
+     * seekable (the lib enables constant-bitrate seeking).
+     */
+    getIsSeekable(): boolean;
+    /**
+     * Whether the active track is fully buffered — the entire media has been
+     * downloaded and there is nothing left to transfer. Distinct from
+     * `BufferState` `'full'` (which is "enough buffered to keep up"): a track can
+     * keep up while still downloading. Once fully buffered, a seek can go to the
+     * end and the buffered bar reaches 100%. Always `false` for a live / unknown-
+     * length stream that never completes. See `onFullyBufferedChange`.
+     */
+    isFullyBuffered(): boolean;
+    /**
+     * Whether the user-facing Next button should be enabled. True when
+     * there's a next track to skip to under the current repeat mode:
+     * - `'off'` and `'track'`: false at the last track (no wrap)
+     * - `'queue'`: always true with an active track (wraps)
+     *
+     * `'track'` (repeat-one) navigates exactly like `'off'`: a user skip
+     * advances through the queue and repeat-one persists so the newly
+     * current track loops on natural end. Only natural auto-advance
+     * replays the current track.
+     *
+     * Native-owned + cached: this is a sync read of a value the native
+     * side recomputes whenever queue, current index, repeat mode, or
+     * shuffle changes. Subscribe to `onSkipCapabilityChange` for live
+     * updates; the `useCanSkip()` React hook does this for you.
+     */
+    getCanSkipNext(): boolean;
+    /**
+     * Whether the user-facing Previous button should be enabled.
+     * Symmetric with `getCanSkipNext` — true when there's a previous
+     * track to skip to under the current repeat mode:
+     * - `'off'` and `'track'` at index 0: false (no previous, no wrap)
+     * - `'queue'`: true with an active track (wraps)
+     *
+     * **Apps that want the Apple-Music-style "tap Previous restarts
+     * current when position > 3s" UX** should implement that
+     * themselves in their button handler — branch on the live
+     * `useProgress().position` value to either `seekTo(0)` or
+     * `skipToPrevious()`. The lib intentionally ships the primitive,
+     * not the policy.
+     */
+    getCanSkipPrevious(): boolean;
+    /**
+     * Atomic snapshot of the (canSkipNext, canSkipPrevious) pair.
+     * Prefer this over calling `getCanSkipNext()` and
+     * `getCanSkipPrevious()` separately when you need a consistent
+     * pair: the two scalar getters read independent fields that can
+     * be observed mid-update during a concurrent
+     * `recomputeCapabilities()` write, surfacing a torn pair. The
+     * struct getter reads a single atomically-published reference.
+     */
+    getSkipCapability(): SkipCapability;
+    /** Current sleep-timer state (inactive when no timer is armed). */
+    getSleepTimer(): SleepTimerState;
+    onStateChange(callback: (state: PlayerState, reason: StateChangeReason) => void): () => void;
+    /**
+     * Fires when the active track changes — user skip, auto-advance,
+     * queue replace, mid-track seek that crosses a queue boundary.
+     *
+     * Crossfade contract: under crossfade mode the active track flips
+     * to the INCOMING leg the instant the fade-in begins (not when
+     * the outgoing leg finishes). The reported `(track, index)` pair
+     * is the incoming track from fade-start; `useProgress()` retargets
+     * to the incoming leg's clock at the same instant; iOS Now Playing
+     * Info Center + Android MediaSession metadata flip in lockstep so
+     * the lock-screen / CarPlay / Android Auto / BT scrubber shows
+     * the incoming track from 0:00 the moment it begins audibly
+     * playing. The outgoing leg continues fading out for the
+     * configured `crossfadeDurationMs` after the event fires.
+     *
+     * `transitionGapMs` is the measured silence gap in milliseconds
+     * between the previous track ending and this track's first audio,
+     * timed natively (`mach_absolute_time()` on iOS, `System.nanoTime()`
+     * on Android). It is populated only on a natural gapless auto-advance
+     * (`reason === 'auto-advance'` under the gapless engine); it is
+     * `undefined` for user skips, queue replacement, seeks, crossfade
+     * transitions, and cast-receiver advances, where an inter-track gap is
+     * not meaningful. Always null-check it — an `'auto-advance'` reason
+     * alone does not guarantee a value (crossfade + cast advances also use
+     * that reason). Empirically
+     * `< 1ms` for native gapless auto-advance (AVQueuePlayer / Media3
+     * ExoPlayer are gapless by design) — a larger value flags a
+     * scheduling regression (a useful CI assertion seed).
+     */
+    onTrackChange(callback: (track: TrackItem | undefined, index: number, reason: TrackChangeReason, transitionGapMs: number | undefined) => void): () => void;
+    /**
+     * Subscribes to playback-progress ticks. Native side fires at ~2 Hz
+     * via `addPeriodicTimeObserver` (iOS) / a coroutine-driven handler
+     * (Android). Payload is a `PlayerProgress` struct so the callback
+     * shape can grow new fields without a breaking change.
+     */
+    onProgress(callback: (progress: PlayerProgress) => void): () => void;
+    /**
+     * Fires when forward playback crosses a fixed progress threshold of
+     * the current track: `milestone` is one of `25`, `50`, `75`, `90`
+     * (percent). The 100% case is end-of-track — observe `onQueueEnd` /
+     * `onTrackChange`. `trackIndex` is the queue index the milestone
+     * belongs to. Intended for "mark as listened" / scrobbling without
+     * the consumer running its own timer over `onProgress`.
+     *
+     * Semantics:
+     * - **Forward playback only.** A milestone fires only when normal
+     *   playback reaches the threshold. Seeking *past* a threshold
+     *   consumes it silently — seek straight to 80% and only `90` fires
+     *   (once playback reaches it); 25/50/75 do not fire that playthrough.
+     * - **Once per threshold per playthrough.** A repeat-one loop is a new
+     *   playthrough, so the milestones fire again on each loop.
+     * - **Requires a computable duration.** If the player reports no/zero
+     *   duration AND the track carries no `duration`, percentages can't be
+     *   computed and nothing fires.
+     *
+     * Computed off the existing ~2Hz progress tick, so a milestone is
+     * reported within ~one tick of the threshold being crossed.
+     */
+    onPlaybackMilestone(callback: (milestone: number, trackIndex: number) => void): () => void;
+    onError(callback: (error: PlaybackError) => void): () => void;
+    onQueueEnd(callback: () => void): () => void;
+    /**
+     * Subscribes to changes in `canSkipNext` / `canSkipPrevious`. The
+     * native side recomputes whenever queue, current index, repeat
+     * mode, or shuffle changes, and only fires when the
+     * `SkipCapability` tuple actually changes.
+     *
+     * **Auto-fire on subscribe:** the callback is invoked once
+     * immediately on registration with the current cached values.
+     * This mirrors Media3 `Player.Listener.onAvailableCommandsChanged`
+     * and removes the seed-then-subscribe race (you don't need to
+     * call `getCanSkipNext` / `getCanSkipPrevious` first).
+     *
+     * Wrapped in a `SkipCapability` struct (rather than two boolean
+     * callback args) so future capability flags can be added without
+     * a breaking API change. Also works around a Nitrogen 0.35.4
+     * codegen bug for `(bool, bool) → void` callback signatures
+     * specifically.
+     */
+    onSkipCapabilityChange(callback: (capability: SkipCapability) => void): () => void;
+    /**
+     * Fires whenever the sleep-timer state changes — armed, cleared, converted
+     * from end-of-track to a concrete deadline, or fired. Fires once on subscribe
+     * with the current state so a UI can render immediately. Payload is the
+     * `SleepTimerState` snapshot (also available synchronously via
+     * `getSleepTimer()`).
+     */
+    onSleepTimerChange(callback: (state: SleepTimerState) => void): () => void;
+    /**
+     * Fires whenever the current track's discrete `BufferState` changes
+     * (`'empty' | 'buffering' | 'stalled' | 'full'`). Driven by the platform's native buffer
+     * signals (iOS `AVPlayerItem` KVO on the playback-buffer properties; Android
+     * Media3 `STATE_BUFFERING` / `STATE_READY` transitions) rather than the 2 Hz
+     * progress tick, so a stall / loading indicator reacts immediately. Only
+     * fires on an actual state change (deduplicated natively).
+     *
+     * Fires once on subscribe with the current state so a UI can render
+     * immediately (also available synchronously via `getBufferState()`).
+     */
+    onBufferStateChange(callback: (state: BufferState) => void): () => void;
+    /**
+     * Fires when the active track's fully-buffered state changes — `true` once the
+     * whole media has finished downloading, `false` on a track change back to a
+     * still-loading item. Fires once on subscribe with the current value. See
+     * `isFullyBuffered()`.
+     */
+    onFullyBufferedChange(callback: (fullyBuffered: boolean) => void): () => void;
+    /**
+     * Push the full pre-computed browse tree to the native cache. Consumers
+     * call this on bootstrap and on data changes (new playlists, new
+     * downloads, library refresh). Native serves CarPlay / Android Auto
+     * browse callbacks from this snapshot for instant cold-start
+     * presentation; deeper drilldown into items with `hasChildren: true`
+     * whose children are NOT inlined in the snapshot falls through to
+     * `onBrowseRequest`.
+     *
+     * Calls notifyChildrenChanged on connected MediaControllers + posts the
+     * iOS scene-refresh notification so any active CarPlay scene rebuilds
+     * its visible templates.
+     */
+    setBrowseSnapshot(snapshot: BrowseSnapshot): void;
+    /**
+     * Drilldown / lazy lookup. Native calls this when a controller asks for
+     * children of a parentId NOT covered by the snapshot. Returns the items
+     * to display; an empty array means "no children" (treated as a leaf).
+     */
+    onBrowseRequest(callback: (parentId: string) => Promise<BrowseItem[]>): () => void;
+    /**
+     * Live search for CarPlay's `CPSearchTemplate` (search-as-you-type) and
+     * Android Auto's `MediaLibrarySession.Callback.onSearch`. Returns items
+     * to display in a list. Tapping an item fires `onPlayFromIdRequest`
+     * with that item's `id`.
+     */
+    onSearchRequest(callback: (query: string) => Promise<BrowseItem[]>): () => void;
+    /**
+     * Voice / structured search resolution. Fires when a voice assistant
+     * delivers a structured request:
+     * - Android: Google Assistant via
+     *   `MediaSession.Callback.onPlayFromSearch`, parsed into
+     *   `MediaSearchRequest`.
+     * - iOS: SiriKit `INPlayMediaIntent` ("Hey Siri play X on MyApp"),
+     *   parsed by Siri into an `INMediaSearch` and mapped by the lib's
+     *   `PlayMediaIntentHandler` into `MediaSearchRequest`.
+     *
+     * Returns the tracks to play. The consumer's JS handler typically
+     * calls `setQueue` + `play()` against the resolved list.
+     */
+    onPlayFromSearchRequest(callback: (request: MediaSearchRequest) => Promise<TrackItem[]>): () => void;
+    /**
+     * Resolves a specific browse-tree item (or search result) to playable
+     * tracks. `mediaId` matches the `BrowseItem.id` the consumer chose.
+     */
+    onPlayFromIdRequest(callback: (mediaId: string) => Promise<TrackItem[]>): () => void;
+    /**
+     * **iOS-only.** Seed Siri's NLU with the consumer's catalog so voice
+     * queries like "Play Pearl Jam" resolve to the right strings. Maps
+     * to `INVocabulary.setVocabularyStrings(_:of:)` with
+     * `.mediaMusicArtistName` for `artists` and `.mediaPlaylistTitle`
+     * for `playlists`. Both lists are required (empty array means
+     * "nothing to donate"). Apple recommends calling this once per
+     * library refresh — not every launch — and the lib dispatches the
+     * actual write to a background queue per Apple's guidance.
+     *
+     * **Android**: no-op. Google Assistant has no in-app vocabulary
+     * donation API.
+     */
+    donateVoiceVocabulary(vocabulary: VoiceVocabulary): void;
+    /**
+     * Fires when the FIRST automotive controller connects (CarPlay scene
+     * attach, Android Auto MediaController bind, or any other connection
+     * the lib classifies as automotive). Subsequent connections during the
+     * same session do not re-fire. Use this to push a fresh
+     * `setBrowseSnapshot` so the controller sees current data.
+     */
+    onCarConnect(callback: () => void): () => void;
+    /**
+     * Fires when the LAST automotive controller drops. Use to release any
+     * automotive-specific subscriptions the consumer set up on connect.
+     */
+    onCarDisconnect(callback: () => void): () => void;
+    /**
+     * Fires when the platform's media service is freshly bound to the JS
+     * side. `reason = 'first-bind'` for the initial bind during a JS-
+     * process lifetime; `reason = 'service-reborn'` when the lib's
+     * auto-rebind watchdog reconnects after an OS-driven service kill
+     * (Android memory reclaim, idle-bucket reaper). Consumers typically
+     * respond by re-pushing the browse snapshot — the new service
+     * instance starts with a fresh `BrowseDataProvider`, so the cached
+     * snapshot from the prior service instance is gone.
+     *
+     * **Android-only signal.** iOS apps die fully under memory pressure
+     * (no separate service lifecycle to rebirth), so this callback is
+     * never invoked on iOS — the registration is accepted for API
+     * parity and the returned disposer is a no-op. Consumers writing
+     * for both platforms can wire one handler and ignore the
+     * platform-iOS branch.
+     */
+    onServiceReady(callback: (reason: ServiceReadyReason) => void): () => void;
+    /**
+     * Reconfigure the lookahead cache (enable / disable, change budget,
+     * change directory, change eviction policy). Idempotent — calling
+     * with the same config is a no-op.
+     *
+     * **Cross-platform note on size shrink**: dropping `maxSizeMb`
+     * (e.g. 100 → 10) takes effect at different points on each platform.
+     * iOS evicts immediately via `LookaheadCache.setMaxSizeBytes`; the
+     * over-budget entries are deleted before the promise resolves.
+     * Android **does not** resize the live cache — Media3's SimpleCache
+     * holds a single instance per directory and cannot resize after
+     * construction. The new budget is recorded but the running player
+     * keeps honouring the previous one until the cache instance is
+     * rebuilt, which only happens on `destroy()` + `configure()`. A
+     * bare `configure({ ... })` against the same player+headers is a
+     * no-op (the existing ExoPlayer is reused). Consumers who need
+     * immediate Android eviction must `await player.destroy()` then
+     * `await player.configure({ ... })` to force a rebuild.
+     *
+     * **Cross-platform note on enable transition**: flipping `enabled`
+     * from `false` → `true` follows the same Android limitation —
+     * a fresh SimpleCache is only constructed during `configureInternal`,
+     * so the cache only comes online on the next `destroy()` +
+     * `configure()` cycle. iOS instantiates the cache lazily on the
+     * first prefetch event, so the enable flip is effectively
+     * immediate.
+     */
+    setLookaheadCache(config: LookaheadCacheConfig): Promise<void>;
+    getLookaheadCacheStatus(): CacheStatus;
+    /**
+     * Wipe every cached entry + cancel any in-flight prefetch. Does
+     * NOT auto-restart the prefetcher — `clear` means "wipe and stop".
+     * Trigger refill explicitly via `setLookaheadCache(...)`,
+     * `setQueue(...)`, or `skipToIndex(...)` when you want a new
+     * prefetch window.
+     */
+    clearLookaheadCache(): Promise<void>;
+    onCacheStatusChange(callback: (status: CacheStatus) => void): () => void;
+    /**
+     * Set the ReplayGain loudness-normalisation mode.
+     *
+     * The lib reads each track's `REPLAYGAIN_*` tags at track-load
+     * time and applies a per-track linear gain to the audio stream
+     * BEFORE the EQ stage. The peak tag (if present + trustworthy)
+     * caps the effective gain to prevent clipping.
+     *
+     * Tag-format coverage:
+     * - **MP3** (ID3v2 TXXX), **AAC / ALAC / M4A** (iTunes-style
+     *   atoms): iOS + Android.
+     * - **FLAC**, **OGG-Vorbis** (Vorbis-comments): Android only;
+     *   iOS Vorbis-comment surfacing varies and is best-effort.
+     * - **Opus**: `OpusHead.output_gain` is auto-applied by the OS
+     *   decoder per RFC 7845. Tag-based RG is intentionally ignored
+     *   on Opus containers to avoid double-correction.
+     * - **HLS / streaming-manifest sources**: not supported.
+     *
+     * Strict mode semantics: `'album'` mode requires the track to
+     * carry `REPLAYGAIN_ALBUM_GAIN` to apply gain — there is NO
+     * fallback to track-gain when the album tag is absent. The
+     * `replayGainActive` field on `getNowPlayingFormat()` reports
+     * the live state.
+     *
+     * Effect is per-track and live: changing the mode mid-track
+     * takes effect within ~1 audio buffer. Crossfade applies the
+     * per-track gain on each leg independently.
+     *
+     * Default: `'off'`.
+     */
+    setReplayGainMode(mode: ReplayGainMode): Promise<void>;
+    /** Returns the current ReplayGain mode. */
+    getReplayGainMode(): ReplayGainMode;
+    /**
+     * Snapshot of the currently-playing track's audio format.
+     * Returns `null` until the format has been loaded for the active
+     * track — iOS requires `await asset.load(.formatDescriptions,
+     * .estimatedDataRate)` per item; Android lands the data via
+     * `Player.Listener.onTracksChanged(Tracks)` before STATE_READY.
+     * Re-fired on every `onTrackChange`. Use the `useNowPlayingFormat`
+     * hook for the React-side ergonomics.
+     */
+    getNowPlayingFormat(): NowPlayingFormat | null;
+    /**
+     * Subscribe to format changes. Fires `null` during the brief
+     * window between a track-change and the new format loading
+     * (iOS) / `onTracksChanged` arriving (Android), then fires the
+     * populated `NowPlayingFormat` once detection completes. Returns
+     * a dispose function — match the existing on...Change pattern.
+     */
+    onNowPlayingFormatChange(callback: (format: NowPlayingFormat | null) => void): () => void;
+}
+//# sourceMappingURL=TrackPlayer.nitro.d.ts.map

package/lib/typescript/TrackPlayer.nitro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrackPlayer.nitro.d.ts","sourceRoot":"","sources":["../../src/TrackPlayer.nitro.ts"],"names":[],"mappings":"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"}

package/lib/typescript/Visualizer.nitro.d.ts

@@ -0,0 +1,36 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+import type { VisualizerConfig, VisualizerErrorReason, VisualizerFrame } from './types';
+export interface Visualizer extends HybridObject<{
+    ios: 'swift';
+    android: 'kotlin';
+}> {
+    /**
+     * Subscribe to FFT (and optionally raw PCM) frames.
+     *
+     * `onFrame` fires every `config.updateIntervalMs` while the engine is
+     * actively producing audio:
+     *   - `frame.fft`: Float32 magnitudes, length = `fftSize / 2`.
+     *     Underlying storage is shared zero-copy with the native buffer
+     *     for the lifetime of the call.
+     *   - `frame.samples`: Float32 raw pre-window time-domain PCM,
+     *     length = `fftSize`. The Hann window applied for the FFT
+     *     does NOT touch this payload — consumers receive the same
+     *     mono-mixed samples that fed the FFT, suitable for
+     *     oscilloscope / Lissajous / waveform displays. Present iff
+     *     `config.includeSamples === true`.
+     *   - `frame.sampleRate`: stream sample rate in Hz.
+     *
+     * `onError` fires when a subscription cannot deliver frames — see
+     * VisualizerErrorReason for the cases. The lib does not request the
+     * Android `RECORD_AUDIO` permission: the FFT runs against the app's
+     * own decoded PCM via Media3's TeeAudioProcessor (Android) and an
+     * MTAudioProcessingTap on the AVAudioMix (iOS).
+     *
+     * Call the returned disposer to unsubscribe; when the last subscriber
+     * disposes, native FFT processing stops.
+     */
+    subscribe(config: VisualizerConfig, onFrame: (frame: VisualizerFrame) => void, onError: (reason: VisualizerErrorReason) => void): () => void;
+    /** How many active subscriptions exist right now. Useful for diagnostics. */
+    getSubscriberCount(): number;
+}
+//# sourceMappingURL=Visualizer.nitro.d.ts.map

package/lib/typescript/Visualizer.nitro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Visualizer.nitro.d.ts","sourceRoot":"","sources":["../../src/Visualizer.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EAChB,MAAM,SAAS,CAAC;AAOjB,MAAM,WAAW,UACf,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;IACzD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,SAAS,CACP,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,EACzC,OAAO,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,GAC/C,MAAM,IAAI,CAAC;IAEd,6EAA6E;IAC7E,kBAAkB,IAAI,MAAM,CAAC;CAC9B"}