@remedia/node 0.0.0-stage → 0.1.0-dev.1

package/dist/lifecycle.d.ts

@@ -0,0 +1,315 @@
+import type { MediaSource } from './input.js';
+import type { AudioStreamInfo, PlaybackPosition, PlaybackState } from './types.js';
+/** Stable names for playback/session event subscriptions and emission. */
+export declare const PlaybackSessionEvents: {
+    /** Emitted after a source starts and its stream information is available. */
+    readonly playbackStarted: "playbackStarted";
+    /** Emitted when a source generation reaches natural end-of-stream. */
+    readonly playbackCompleted: "playbackCompleted";
+    /** Emitted when a source generation is explicitly stopped or cancelled. */
+    readonly playbackStopped: "playbackStopped";
+    /** Emitted when a source generation fails to open, decode, process, or deliver output. */
+    readonly playbackFailed: "playbackFailed";
+    /** Emitted when playback is paused without replacing its source generation. */
+    readonly playbackPaused: "playbackPaused";
+    /** Emitted when paused playback resumes. */
+    readonly playbackResumed: "playbackResumed";
+    /** Emitted after seeking to a source timeline position. */
+    readonly playbackSeeked: "playbackSeeked";
+    /** Emitted when the configured session filtergraph changes. */
+    readonly filterChanged: "filterChanged";
+    /** Emitted when the configured session linear gain changes. */
+    readonly volumeChanged: "volumeChanged";
+    /** Emitted when a session is unregistered and its owned resources are released. */
+    readonly sessionDisposed: "sessionDisposed";
+};
+/** Union of the stable event names defined by PlaybackSessionEvents. */
+export type PlaybackSessionEvents = (typeof PlaybackSessionEvents)[keyof typeof PlaybackSessionEvents];
+/** Stable event names for typed VoiceSessionEvents subscriptions. */
+export declare const VoiceSessionEvents: {
+    /** Emitted when the Discord transport lifecycle state changes. */
+    readonly voiceStateChanged: "voiceStateChanged";
+    /** Emitted when voice connection or recovery fails. */
+    readonly voiceFailed: "voiceFailed";
+};
+/** Union of the stable event names defined by VoiceSessionEvents. */
+export type VoiceSessionEvents = (typeof VoiceSessionEvents)[keyof typeof VoiceSessionEvents];
+/** Stable event names for typed RemediaEvents subscriptions. */
+export declare const RemediaEvents: {
+    /** Emitted for a structured native diagnostic event. */
+    readonly debug: "debug";
+    /** Emitted when the Discord transport lifecycle state changes. */
+    readonly voiceStateChanged: "voiceStateChanged";
+    /** Emitted when voice connection or recovery fails. */
+    readonly voiceFailed: "voiceFailed";
+    /** Emitted after a source starts and its stream information is available. */
+    readonly playbackStarted: "playbackStarted";
+    /** Emitted when a source generation reaches natural end-of-stream. */
+    readonly playbackCompleted: "playbackCompleted";
+    /** Emitted when a source generation is explicitly stopped or cancelled. */
+    readonly playbackStopped: "playbackStopped";
+    /** Emitted when a source generation fails to open, decode, process, or deliver output. */
+    readonly playbackFailed: "playbackFailed";
+    /** Emitted when playback is paused without replacing its source generation. */
+    readonly playbackPaused: "playbackPaused";
+    /** Emitted when paused playback resumes. */
+    readonly playbackResumed: "playbackResumed";
+    /** Emitted after seeking to a source timeline position. */
+    readonly playbackSeeked: "playbackSeeked";
+    /** Emitted when the configured session filtergraph changes. */
+    readonly filterChanged: "filterChanged";
+    /** Emitted when the configured session linear gain changes. */
+    readonly volumeChanged: "volumeChanged";
+    /** Emitted when a session is unregistered and its owned resources are released. */
+    readonly sessionDisposed: "sessionDisposed";
+};
+/** Union of the stable event names defined by RemediaEvents. */
+export type RemediaEvents = (typeof RemediaEvents)[keyof typeof RemediaEvents];
+/**
+ * Correlation fields identifying the session and source generation that produced a playback event.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export interface PlaybackEventIdentity<Metadata = unknown> {
+    /** Opaque Remedia session identity used to correlate events; distinct from the Discord bot user ID. */
+    sessionId: string;
+    /** Discord guild snowflake as a decimal string; unique within the owning client. */
+    guildId?: string;
+    /** Node identifier; embedded session events use null. */
+    nodeId: string | null;
+    /** Source generation used to correlate playback events; independent of transport replacement generations. */
+    generation: number;
+    /** Application-owned metadata retained locally for the source generation and attached to its events. */
+    customMetadata?: Metadata;
+    /** True only when a terminal event was reconstructed from an authoritative remote snapshot. */
+    reconstructed?: boolean;
+}
+/**
+ * Typed argument tuples for playback lifecycle notifications.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export type PlaybackLifecycleEvents<Metadata = unknown> = {
+    /** Emitted after a source starts and its stream information is available. */
+    [PlaybackSessionEvents.playbackStarted]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Current playback lifecycle state. */
+            state: 'playing';
+            /** Metadata for the audio stream that started playback. */
+            info: AudioStreamInfo;
+        }
+    ];
+    /** Emitted when a source generation reaches natural end-of-stream. */
+    [PlaybackSessionEvents.playbackCompleted]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Current playback lifecycle state. */
+            state: 'completed';
+            /** Latest source and output timeline measurements in milliseconds. */
+            position: PlaybackPosition;
+        }
+    ];
+    /** Emitted when a source generation is explicitly stopped or cancelled. */
+    [PlaybackSessionEvents.playbackStopped]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Current playback lifecycle state. */
+            state: 'stopped';
+            /** Optional explanation for cancellation or a terminal playback event. */
+            reason?: string;
+        }
+    ];
+    /** Emitted when a source generation fails to open, decode, process, or deliver output. */
+    [PlaybackSessionEvents.playbackFailed]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Current playback lifecycle state. */
+            state: 'failed';
+            /** Error object describing the operation or source failure. */
+            error: Error;
+        }
+    ];
+    /** Emitted when playback is paused without replacing its source generation. */
+    [PlaybackSessionEvents.playbackPaused]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Playback or transport lifecycle state before this transition. */
+            previousState: PlaybackState;
+            /** Current playback lifecycle state. */
+            state: 'paused';
+        }
+    ];
+    /** Emitted when paused playback resumes. */
+    [PlaybackSessionEvents.playbackResumed]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Playback or transport lifecycle state before this transition. */
+            previousState: PlaybackState;
+            /** Current playback lifecycle state. */
+            state: 'playing';
+        }
+    ];
+    /** Emitted after seeking to a source timeline position. */
+    [PlaybackSessionEvents.playbackSeeked]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Requested source timeline position in milliseconds. */
+            positionMs: number;
+            /** Source timeline position before seeking, in milliseconds, or null when unknown. */
+            previousPositionMs: number | null;
+        }
+    ];
+    /** Emitted when the configured session filtergraph changes. */
+    [PlaybackSessionEvents.filterChanged]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Filtergraph active before this change, or null when filtering was disabled. */
+            previousGraph: string | null;
+            /** Current raw FFmpeg audio filtergraph, or null when filtering is disabled. */
+            graph: string | null;
+        }
+    ];
+    /** Emitted when the configured session linear gain changes. */
+    [PlaybackSessionEvents.volumeChanged]: [
+        PlaybackEventIdentity<Metadata> & {
+            /** Linear master gain before this change. */
+            previousVolume: number;
+            /** Session master linear gain from 0 through 2, independent of filtergraph processing; defaults to 1. */
+            volume: number;
+        }
+    ];
+};
+/** Correlation fields identifying the session that produced a voice transport event. */
+export interface VoiceEventIdentity {
+    /** Opaque Remedia session identity used to correlate events; distinct from the Discord bot user ID. */
+    sessionId: string;
+    /** Discord guild snowflake as a decimal string; unique within the owning client. */
+    guildId: string;
+    /** Node identifier; embedded session events use null. */
+    nodeId: string | null;
+}
+/** Normalized voice lifecycle state used in events; DAVE negotiation uses negotiating_dave. */
+export type LifecycleVoiceState = 'connecting' | 'negotiating_dave' | 'connected' | 'reconnecting' | 'disconnecting' | 'disconnected' | 'failed';
+/** Typed argument tuples for voice transport notifications, independent of playback generation. */
+export type VoiceLifecycleEvents = {
+    /** Emitted when the Discord transport lifecycle state changes. */
+    [VoiceSessionEvents.voiceStateChanged]: [
+        VoiceEventIdentity & {
+            /** Playback or transport lifecycle state before this transition. */
+            previousState: LifecycleVoiceState;
+            /** Current playback lifecycle state. */
+            state: LifecycleVoiceState;
+        }
+    ];
+    /** Emitted when voice connection or recovery fails. */
+    [VoiceSessionEvents.voiceFailed]: [
+        VoiceEventIdentity & {
+            /** Current playback lifecycle state. */
+            state: 'failed';
+            /** Error object describing the operation or source failure. */
+            error: Error;
+        }
+    ];
+};
+/**
+ * Combined playback, voice, and disposal event arguments for a session.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export type SessionLifecycleEvents<Metadata = unknown> = PlaybackLifecycleEvents<Metadata> & VoiceLifecycleEvents & {
+    /** Emitted when a session is unregistered and its owned resources are released. */
+    [PlaybackSessionEvents.sessionDisposed]: [
+        {
+            /** Opaque Remedia session identity used to correlate events; distinct from the Discord bot user ID. */
+            sessionId: string;
+            /** Discord guild snowflake as a decimal string; unique within the owning client. */
+            guildId?: string;
+            /** Node identifier; embedded session events use null. */
+            nodeId: string | null;
+            /** Source generation used to correlate playback events; independent of transport replacement generations. */
+            generation: number;
+        }
+    ];
+};
+/**
+ * Playback and disposal event arguments emitted by an embedded playback wrapper.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export type PlaybackSessionEventMap<Metadata = unknown> = PlaybackLifecycleEvents<Metadata> & {
+    /** Emitted when a session is unregistered and its owned resources are released. */
+    [PlaybackSessionEvents.sessionDisposed]: [
+        {
+            /** Opaque Remedia session identity used to correlate events; distinct from the Discord bot user ID. */
+            sessionId: string;
+            /** Discord guild snowflake as a decimal string; unique within the owning client. */
+            guildId?: string;
+            /** Node identifier; embedded session events use null. */
+            nodeId: string | null;
+            /** Source generation used to correlate playback events; independent of transport replacement generations. */
+            generation: number;
+        }
+    ];
+};
+/** Session lifecycle events and native diagnostic notifications forwarded by the embedded engine. */
+export interface RemediaLifecycleEvents extends SessionLifecycleEvents<unknown> {
+    /** Emitted for a structured native diagnostic event. */
+    [RemediaEvents.debug]: [import('./types.js').DiagnosticEvent];
+}
+/**
+ * Local metadata and cancellation options for one playback generation; session configuration persists across generations.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export interface PlayOptions<Metadata = unknown> {
+    /** Application-owned metadata retained locally for the source generation and attached to its events. */
+    customMetadata?: Metadata;
+    /**
+     * Optional cancellation signal; cancellation before startup prevents playback, and cancellation after startup stops that generation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Caller-owned media input, metadata, and cancellation signal supplied to each awaited pre-play hook.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export interface BeforePlayContext<Metadata = unknown> {
+    /** Caller-owned encoded input that the hooks inspect before the decoder opens it. */
+    readonly source: MediaSource;
+    /** Application-owned metadata retained locally for the source generation and attached to its events. */
+    readonly customMetadata: Metadata | undefined;
+    /** Cancellation signal for this hook invocation; check it before performing asynchronous work. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Hook result: return nothing to continue, or cancel with an optional explanation to reject playback with AbortError.
+ */
+export type BeforePlayResult = void | {
+    /** Return true from a pre-play hook to reject playback before opening the source. */
+    cancel: true;
+    /** Optional explanation for cancellation or a terminal playback event. */
+    reason?: string;
+};
+/**
+ * Awaited local callback run before a source opens; rejection or cancellation prevents that source from starting.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ * @param context - Source, local metadata, and cancellation signal supplied to the awaited hooks.
+ * @returns Nothing to continue, or a cancellation result; a promise is awaited before source opening.
+ */
+export type BeforePlayHook<Metadata = unknown> = (context: BeforePlayContext<Metadata>) => BeforePlayResult | Promise<BeforePlayResult>;
+/**
+ * Ordered, awaited local middleware. It is not a server authorization mechanism.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export declare class PlaybackHooks<Metadata = unknown> {
+    #private;
+    /**
+     * Append an awaited pre-play hook. Hooks run in registration order before a source opens.
+     * @param hook - Local callback to await before opening each source; returning cancel rejects playback.
+     * @returns An idempotent function that removes this hook registration.
+     */
+    beforePlay(hook: BeforePlayHook<Metadata>): () => void;
+    /**
+     * Run registered pre-play hooks in order and reject on cancellation or hook failure.
+     * @param context - Source, local metadata, and cancellation signal supplied to the awaited hooks.
+     * @returns Resolves when every hook permits playback; cancellation rejects with AbortError.
+     */
+    runBeforePlay(context: BeforePlayContext<Metadata>): Promise<void>;
+}
+/**
+ * Create playback event correlation fields for one local source generation.
+ * @param generation - Native source generation associated with the lifecycle notification.
+ * @param customMetadata - Application-owned metadata associated with this source generation.
+ * @returns Identity fields with metadata included only when provided.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ * @param sessionId - Opaque Remedia session identity used for event correlation.
+ */
+export declare function lifecycleContext<Metadata>(sessionId: string, generation: number, customMetadata: Metadata | undefined): PlaybackEventIdentity<Metadata>;

package/dist/lifecycle.js

@@ -0,0 +1,109 @@
+/** Stable names for playback/session event subscriptions and emission. */
+export const PlaybackSessionEvents = {
+    /** Emitted after a source starts and its stream information is available. */
+    playbackStarted: 'playbackStarted',
+    /** Emitted when a source generation reaches natural end-of-stream. */
+    playbackCompleted: 'playbackCompleted',
+    /** Emitted when a source generation is explicitly stopped or cancelled. */
+    playbackStopped: 'playbackStopped',
+    /** Emitted when a source generation fails to open, decode, process, or deliver output. */
+    playbackFailed: 'playbackFailed',
+    /** Emitted when playback is paused without replacing its source generation. */
+    playbackPaused: 'playbackPaused',
+    /** Emitted when paused playback resumes. */
+    playbackResumed: 'playbackResumed',
+    /** Emitted after seeking to a source timeline position. */
+    playbackSeeked: 'playbackSeeked',
+    /** Emitted when the configured session filtergraph changes. */
+    filterChanged: 'filterChanged',
+    /** Emitted when the configured session linear gain changes. */
+    volumeChanged: 'volumeChanged',
+    /** Emitted when a session is unregistered and its owned resources are released. */
+    sessionDisposed: 'sessionDisposed',
+};
+/** Stable event names for typed VoiceSessionEvents subscriptions. */
+export const VoiceSessionEvents = {
+    /** Emitted when the Discord transport lifecycle state changes. */
+    voiceStateChanged: 'voiceStateChanged',
+    /** Emitted when voice connection or recovery fails. */
+    voiceFailed: 'voiceFailed',
+};
+/** Stable event names for typed RemediaEvents subscriptions. */
+export const RemediaEvents = {
+    ...PlaybackSessionEvents,
+    ...VoiceSessionEvents,
+    /** Emitted for a structured native diagnostic event. */
+    debug: 'debug',
+};
+/**
+ * Ordered, awaited local middleware. It is not a server authorization mechanism.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export class PlaybackHooks {
+    #beforePlay = [];
+    /**
+     * Append an awaited pre-play hook. Hooks run in registration order before a source opens.
+     * @param hook - Local callback to await before opening each source; returning cancel rejects playback.
+     * @returns An idempotent function that removes this hook registration.
+     */
+    beforePlay(hook) {
+        if (typeof hook !== 'function')
+            throw new TypeError('beforePlay hook must be a function');
+        this.#beforePlay.push(hook);
+        return () => {
+            const index = this.#beforePlay.indexOf(hook);
+            if (index >= 0)
+                this.#beforePlay.splice(index, 1);
+        };
+    }
+    /**
+     * Run registered pre-play hooks in order and reject on cancellation or hook failure.
+     * @param context - Source, local metadata, and cancellation signal supplied to the awaited hooks.
+     * @returns Resolves when every hook permits playback; cancellation rejects with AbortError.
+     */
+    async runBeforePlay(context) {
+        for (const hook of [...this.#beforePlay]) {
+            if (context.signal.aborted)
+                throw abortError(context.signal.reason);
+            const result = await raceAbort(Promise.resolve().then(() => hook(context)), context.signal);
+            if (context.signal.aborted)
+                throw abortError(context.signal.reason);
+            if (result?.cancel) {
+                const error = new Error(result.reason ?? 'playback was cancelled by a beforePlay hook');
+                error.name = 'AbortError';
+                throw error;
+            }
+        }
+    }
+    /** @internal Release application hook references when the owning session is disposed. */
+    clear() {
+        this.#beforePlay.length = 0;
+    }
+}
+/**
+ * Create playback event correlation fields for one local source generation.
+ * @param generation - Native source generation associated with the lifecycle notification.
+ * @param customMetadata - Application-owned metadata associated with this source generation.
+ * @returns Identity fields with metadata included only when provided.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ * @param sessionId - Opaque Remedia session identity used for event correlation.
+ */
+export function lifecycleContext(sessionId, generation, customMetadata) {
+    return customMetadata === undefined
+        ? { sessionId, nodeId: null, generation }
+        : { sessionId, nodeId: null, generation, customMetadata };
+}
+function abortError(reason) {
+    const error = new Error(reason instanceof Error ? reason.message : 'playback was cancelled');
+    error.name = 'AbortError';
+    return error;
+}
+function raceAbort(operation, signal) {
+    if (signal.aborted)
+        return Promise.reject(abortError(signal.reason));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(signal.reason));
+        signal.addEventListener('abort', onAbort, { once: true });
+        operation.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}

package/dist/playback.d.ts

@@ -0,0 +1,73 @@
+import { RemediaEventEmitter } from './events.js';
+import { type MediaSource } from './input.js';
+import { PlaybackHooks, type PlayOptions, type PlaybackSessionEventMap } from './lifecycle.js';
+import { type AudioStreamInfo, type PlaybackPosition, type PlaybackState } from './types.js';
+import { FilterControls } from './filters.js';
+/**
+ * Controls one playback session. Local sessions decode into a no-op output.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export declare class PlaybackSession<Metadata = unknown> extends RemediaEventEmitter<PlaybackSessionEventMap<Metadata>> {
+    #private;
+    /** Ordered, awaited local pre-play hooks; listeners are separate from hooks. */
+    readonly hooks: PlaybackHooks<Metadata>;
+    /** Persistent raw FFmpeg filtergraph controls for this session. */
+    readonly filters: FilterControls;
+    /** Stable opaque identity for this wrapper, suitable for correlating lifecycle events. */
+    get sessionId(): string;
+    /** Current playback lifecycle state. */
+    get state(): PlaybackState;
+    /** Latest source and output timeline measurements in milliseconds. */
+    get position(): PlaybackPosition;
+    /** Source duration in milliseconds, or null when unknown. */
+    get durationMs(): number | null;
+    /** Most recent playback or voice failure message, or null when no error is available. */
+    get error(): string | null;
+    /** Current normalized linear master gain, from 0.0 (mute) through 2.0. */
+    get volume(): number;
+    /**
+     * Set master gain independently of the raw filtergraph.
+     * @param gain - Finite linear master gain from 0 through 2; 1 leaves amplitude unchanged.
+     * @returns Resolves after the gain is stored or applied; rejects for non-finite gain or values outside 0 through 2.
+     * @throws {RangeError} If gain is non-finite or outside the inclusive range 0 through 2.
+     */
+    setVolume(gain: number): Promise<void>;
+    /**
+     * Open one media source and begin a new playback generation using the persistent session configuration. Stop active playback before starting another source.
+     * @param source - Encoded media input; Buffer and caller-owned binary Readable inputs require embedded mode.
+     * @param options - Optional metadata for this generation and a cancellation signal.
+     * @returns Selected stream metadata once startup succeeds; rejects if hooks, input opening, or playback startup fail.
+     */
+    play(source: MediaSource, options?: PlayOptions<Metadata>): Promise<AudioStreamInfo>;
+    /**
+     * Pause the current playback without replacing its decoder or source generation.
+     * @returns Resolves when the backend accepts the pause request.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume paused playback on its existing source generation.
+     * @returns Resolves when the backend accepts the resume request.
+     */
+    resume(): Promise<void>;
+    /**
+     * Seek on the original media timeline; non-seekable and one-shot sources may reject.
+     * @param positionMs - Non-negative finite position on the original media timeline, in milliseconds.
+     * @returns Resolves after the backend accepts the seek; rejects for invalid positions or unsupported inputs.
+     */
+    seek(positionMs: number): Promise<void>;
+    /**
+     * Stop the active playback generation and release its input without leaving the voice channel.
+     * @returns Resolves after the backend stops the active source.
+     */
+    stop(): Promise<void>;
+    /**
+     * Wait for the current playback generation to reach a terminal state.
+     * @returns The terminal playback state for the generation captured by this wait.
+     */
+    wait(): Promise<PlaybackState>;
+    /**
+     * Stop and release this standalone playback session.
+     * @returns Resolves after disposal; rejects if resource cleanup fails.
+     */
+    dispose(): Promise<void>;
+}