@landr/audio-player 0.2.0-feat-CORE-23079-shared-player-audio-10175.0

package/README.md

@@ -0,0 +1,109 @@
+# @landr/audio-player
+
+Headless shared audio playback orchestration for React apps.
+
+The package owns player state, queue behavior, repeat/shuffle behavior, progress subscriptions, and normalized playback engine contracts. It does not own product UI, waveform rendering, stream fetching, analytics, notifications, or app-specific logging.
+
+Browser builds provide an `HTMLAudioElement` engine by default. Native and default builds require `createEngine`.
+
+## Public API
+
+```tsx
+import { PlayerProvider, usePlayer, useTrackProgress, usePlayerQueue } from '@landr/audio-player';
+import type { IPlayerEngine, PlayerTrack } from '@landr/audio-player';
+import { EngineState, RepeatMode } from '@landr/audio-player';
+```
+
+The public package surface is intentionally React-first:
+
+- `PlayerProvider`
+- `usePlayer()`
+- `useTrackProgress()`
+- `usePlayerQueue()`
+- `PlayerTrack<TMeta = unknown>`
+- `EngineState`
+- `RepeatMode`
+- `IPlayerEngine`
+
+The `Player` class, basic queue implementation, and browser engine are internal implementation details. Consumers should interact through the provider and hooks.
+
+## Provider Usage
+
+Browser consumers can rely on the default `HTMLAudioElement` engine:
+
+```tsx
+<PlayerProvider>
+  <App />
+</PlayerProvider>
+```
+
+Native consumers must provide a platform engine:
+
+```tsx
+<PlayerProvider createEngine={() => new ExpoAudioPlayer()}>
+  <App />
+</PlayerProvider>
+```
+
+Apps can keep stream loading, analytics, notifications, and waveforms outside this package by using `resolveTrackUrl` and app-level effects:
+
+```tsx
+<PlayerProvider resolveTrackUrl={(track) => loadStream(track.id)}>
+  <App />
+</PlayerProvider>
+```
+
+## Conditional Exports
+
+The package supports the same import path in every runtime:
+
+```ts
+import { PlayerProvider } from '@landr/audio-player';
+```
+
+The `browser` export creates a default `HTMLAudioElement` engine when `createEngine` is not provided. The `default` and `react-native` exports do not import DOM code and throw a clear error if `createEngine` is missing.
+
+## Engine Contract
+
+Custom engines implement `IPlayerEngine` and emit normalized events:
+
+- `state`
+- `position`
+- `remote`
+- `error`
+
+Durations and positions should be finite numbers. Browser playback normalizes `NaN` and `Infinity` to `0`.
+
+## Local Workflow
+
+From `LANDR.Web.Libs/packages/audio-player`:
+
+```sh
+pnpm watch:rollup
+```
+
+From `LANDR.Web.Projects`, use the local dependency:
+
+```json
+"@landr/audio-player": "../../../LANDR.Web.Libs/packages/audio-player"
+```
+
+Then run:
+
+```sh
+pnpm install
+```
+
+From `LANDR.MobileApp`, use the local dependency:
+
+```json
+"@landr/audio-player": "../LANDR.Web.Libs/packages/audio-player"
+```
+
+Then run:
+
+```sh
+bun i
+```
+
+Metro, Jest, and Rsbuild must resolve `react`, `react-dom`, and `react-native` from the consuming app to avoid duplicate React instances when using the local linked package.

package/lib/Player.d.ts

@@ -0,0 +1,47 @@
+import { type IPlayer, type PlayerDependencies, type PlayerSnapshot, type PlayerTrack, RepeatMode } from './types';
+export declare class Player implements IPlayer {
+    private static readonly PREVIOUS_TRACK_THRESHOLD_SECONDS;
+    private static readonly RELOAD_REQUIRED_STATES;
+    private readonly queue;
+    private readonly engine;
+    private readonly resolveTrackUrl?;
+    private readonly logger?;
+    private loadedTrackId;
+    private snapshot;
+    private position;
+    private readonly subscribers;
+    private readonly progressSubscribers;
+    private readonly unsubscribers;
+    constructor({ queue, engine, resolveTrackUrl, logger }: PlayerDependencies);
+    subscribe(listener: (snapshot: PlayerSnapshot) => void): () => void;
+    getSnapshot(): PlayerSnapshot;
+    getPosition(): number;
+    subscribeToProgress(listener: () => void): () => void;
+    play(track: PlayerTrack): Promise<void>;
+    pause(): Promise<void>;
+    toggle(): Promise<void>;
+    seek(position: number): Promise<void>;
+    skipNext(): Promise<void>;
+    skipPrevious(): Promise<void>;
+    addNext(items: PlayerTrack[]): void;
+    addToEnd(items: PlayerTrack[]): void;
+    removeFromQueue(trackId: PlayerTrack['id']): void;
+    setRepeatMode(mode: RepeatMode): void;
+    setShuffleMode(enabled: boolean): void;
+    replaceQueue(items: PlayerTrack[]): Promise<void>;
+    destroy(): Promise<void>;
+    private subscribeToEngineEvents;
+    private subscribeToQueueEvents;
+    private readonly handleEngineProgressEvent;
+    private readonly handleEngineStateEvent;
+    private readonly handleRemoteEvent;
+    private notifySubscribers;
+    private shouldReloadTrack;
+    private shouldMoveToPreviousTrack;
+    private resetPosition;
+    private createSnapshot;
+    private updateActiveLockScreenControls;
+    private getLockScreenControls;
+    private resolvePlayableTrack;
+    private ensureTrackIsInQueue;
+}

package/lib/engines/HtmlAudioPlayerEngine.d.ts

@@ -0,0 +1,40 @@
+import { EngineState, type IPlayerEngine, type LockScreenControls, type PlayerEngineEvent, type PlayerEngineEventMap, type PlayerTrack } from '../types';
+export type HtmlAudioPlayerEngineOptions = {
+    audio?: HTMLAudioElement;
+    progressIntervalMs?: number;
+};
+export declare class HtmlAudioPlayerEngine implements IPlayerEngine {
+    private readonly audio;
+    private readonly progressIntervalMs;
+    private state;
+    private progressInterval;
+    private readonly listeners;
+    constructor({ audio, progressIntervalMs }?: HtmlAudioPlayerEngineOptions);
+    getState(): EngineState;
+    setup(): Promise<void>;
+    loadTrack(track: PlayerTrack, _controls: LockScreenControls): Promise<void>;
+    play(): Promise<void>;
+    pause(): Promise<void>;
+    seek(position: number): Promise<void>;
+    getPosition(): number;
+    getDuration(): number;
+    updateActiveLockScreenControls(_controls: LockScreenControls): void;
+    clearLockScreenControls(): void;
+    destroy(): Promise<void>;
+    on<TEvent extends PlayerEngineEvent>(event: TEvent, handler: (payload: PlayerEngineEventMap[TEvent]) => void): () => void;
+    private readonly handleLoadedMetadata;
+    private readonly handleCanPlay;
+    private readonly handleWaiting;
+    private readonly handlePlaying;
+    private readonly handlePause;
+    private readonly handleEnded;
+    private readonly handleTimeUpdate;
+    private readonly handleAudioError;
+    private subscribeToAudioEvents;
+    private unsubscribeFromAudioEvents;
+    private startProgressPolling;
+    private stopProgressPolling;
+    private emitPosition;
+    private setState;
+    private emit;
+}