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

package/dist/playback.js

@@ -0,0 +1,445 @@
+import { RemediaEventEmitter } from './events.js';
+import { createReadableInput, toNativeSource, } from './input.js';
+import { lifecycleContext, PlaybackHooks, PlaybackSessionEvents as PlaybackEvent, } from './lifecycle.js';
+import { toStreamInfo, } from './types.js';
+import { FilterControls, validateVolume } 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 class PlaybackSession extends RemediaEventEmitter {
+    #native;
+    #playbackId;
+    #onDispose;
+    #terminalGenerations = new Set();
+    #metadata = new Map();
+    #startedGenerations = new Set();
+    /** Ordered, awaited local pre-play hooks; listeners are separate from hooks. */
+    hooks;
+    /** Persistent raw FFmpeg filtergraph controls for this session. */
+    filters;
+    #input;
+    #disposed = false;
+    #starting = false;
+    #playController;
+    #signal;
+    #abortListener;
+    #latestGeneration = 0;
+    #guildId;
+    /**
+     * Construct this wrapper with its owning services. Use the owning engine or client factory for application code.
+     *
+     * @internal
+     * @param native - Owning native engine instance; its resources must outlive this wrapper.
+     * @param playbackId - Opaque native playback identity owned by this wrapper.
+     * @param onDispose - Callback invoked when this wrapper releases its owning registration.
+     * @param guildId - Discord guild snowflake used to route the operation.
+     * @param hooks - Optional shared pre-play hooks for the owning Discord session.
+     */
+    constructor(native, playbackId, onDispose, guildId, hooks) {
+        super();
+        this.#native = native;
+        this.#playbackId = playbackId;
+        this.#onDispose = onDispose;
+        this.#guildId = guildId;
+        this.hooks = hooks ?? new PlaybackHooks();
+        this.filters = new FilterControls(() => this.#native.playbackFilterGraph(this.#playbackId) ?? null, (graph) => this.#replaceFilterGraph(graph), () => this.#replaceFilterGraph(null));
+    }
+    /** Stable opaque identity for this wrapper, suitable for correlating lifecycle events. */
+    get sessionId() {
+        return this.#playbackId;
+    }
+    /** @internal Latest native source generation observed by this wrapper. */
+    get currentGeneration() {
+        return this.#latestGeneration;
+    }
+    /** Current playback lifecycle state. */
+    get state() {
+        return this.#native.playbackState(this.#playbackId);
+    }
+    /** Latest source and output timeline measurements in milliseconds. */
+    get position() {
+        const position = this.#native.playbackPosition(this.#playbackId);
+        return {
+            mediaMs: position.mediaMs ?? null,
+            mediaPositionAccuracy: position.mediaPositionAccuracy === 'timestamp' ||
+                position.mediaPositionAccuracy === 'estimated'
+                ? position.mediaPositionAccuracy
+                : null,
+            submittedMs: position.submittedMs,
+            playedMs: position.playedMs ?? null,
+        };
+    }
+    /** Source duration in milliseconds, or null when unknown. */
+    get durationMs() {
+        return this.#native.playbackDurationMs(this.#playbackId) ?? null;
+    }
+    /** Most recent playback or voice failure message, or null when no error is available. */
+    get error() {
+        return this.#native.playbackError(this.#playbackId) ?? null;
+    }
+    /** Current normalized linear master gain, from 0.0 (mute) through 2.0. */
+    get volume() {
+        return this.#native.playbackVolume(this.#playbackId);
+    }
+    /**
+     * 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.
+     */
+    async setVolume(gain) {
+        this.#assertActive();
+        validateVolume(gain);
+        const previousVolume = this.volume;
+        if (previousVolume === gain)
+            return;
+        await this.#native.playbackSetVolume(this.#playbackId, gain);
+        this.emit(PlaybackEvent.volumeChanged, {
+            ...this.#eventContext(),
+            previousVolume,
+            volume: gain,
+        });
+    }
+    /**
+     * 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.
+     */
+    async play(source, options = {}) {
+        this.#assertActive();
+        if (this.#starting || isPlaybackActive(this.state)) {
+            throw new Error('playback is already active; stop it before starting another source');
+        }
+        if (options.signal?.aborted)
+            throw abortError(options.signal.reason);
+        this.#starting = true;
+        const controller = new AbortController();
+        let nativeAttempted = false;
+        this.#playController = controller;
+        this.#signal = options.signal;
+        const abortListener = () => {
+            controller.abort(options.signal?.reason);
+            // This native operation is asynchronous and cancellation-aware. It is never invoked from a
+            // Rust callback or while the core holds a playback-state lock.
+            if (nativeAttempted)
+                void this.#native.stop(this.#playbackId).catch(() => undefined);
+        };
+        this.#abortListener = abortListener;
+        options.signal?.addEventListener('abort', abortListener, { once: true });
+        let input;
+        const previousGeneration = numericGeneration(this.#native.playbackGeneration(this.#playbackId));
+        try {
+            await this.hooks.runBeforePlay({
+                source,
+                customMetadata: options.customMetadata,
+                signal: controller.signal,
+            });
+            this.#assertActive();
+            if (controller.signal.aborted)
+                throw abortError(controller.signal.reason);
+            await this.#releaseInput();
+            let nativeSource;
+            if ('stream' in source) {
+                input = createReadableInput(this.#native, source.stream);
+                nativeSource = input.source;
+                this.#input = input;
+            }
+            else {
+                nativeSource = toNativeSource(source);
+            }
+            if (controller.signal.aborted)
+                throw abortError(controller.signal.reason);
+            nativeAttempted = true;
+            const info = toStreamInfo(await this.#native.play(this.#playbackId, nativeSource));
+            const generation = numericGeneration(this.#native.playbackGeneration(this.#playbackId));
+            this.#latestGeneration = generation;
+            this.#metadata.set(generation, options.customMetadata);
+            this.#boundMetadata(generation);
+            this.#startedGenerations.add(generation);
+            this.emit(PlaybackEvent.playbackStarted, {
+                ...this.#eventContext(generation),
+                state: 'playing',
+                info,
+            });
+            this.#starting = false;
+            void this.#observeGeneration(generation, input);
+            return info;
+        }
+        catch (error) {
+            if (input && this.#input === input)
+                await this.#releaseInput();
+            if (nativeAttempted && !(error instanceof Error && error.name === 'AbortError')) {
+                const generation = numericGeneration(this.#native.playbackGeneration(this.#playbackId));
+                this.#latestGeneration = generation;
+                if (generation > previousGeneration && this.state === 'failed') {
+                    this.#metadata.set(generation, options.customMetadata);
+                    this.#emitTerminal('failed', generation, error);
+                }
+            }
+            if (controller.signal.aborted)
+                throw abortError(controller.signal.reason);
+            throw error;
+        }
+        finally {
+            this.#starting = false;
+            if (!nativeAttempted || this.state === 'failed' || controller.signal.aborted) {
+                this.#clearAbortBinding(controller);
+            }
+        }
+    }
+    /**
+     * Pause the current playback without replacing its decoder or source generation.
+     * @returns Resolves when the backend accepts the pause request.
+     */
+    async pause() {
+        this.#assertActive();
+        const previousState = this.state;
+        await this.#native.pause(this.#playbackId);
+        if (previousState === 'playing' && this.state === 'paused') {
+            this.emit(PlaybackEvent.playbackPaused, {
+                ...this.#eventContext(),
+                previousState,
+                state: 'paused',
+            });
+        }
+    }
+    /**
+     * Resume paused playback on its existing source generation.
+     * @returns Resolves when the backend accepts the resume request.
+     */
+    async resume() {
+        this.#assertActive();
+        const previousState = this.state;
+        await this.#native.resume(this.#playbackId);
+        if (previousState === 'paused' && this.state === 'playing') {
+            this.emit(PlaybackEvent.playbackResumed, {
+                ...this.#eventContext(),
+                previousState,
+                state: 'playing',
+            });
+        }
+    }
+    /**
+     * 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.
+     */
+    async seek(positionMs) {
+        this.#assertActive();
+        const previousPositionMs = this.position.mediaMs;
+        await this.#native.seek(this.#playbackId, positionMs);
+        if (previousPositionMs !== positionMs) {
+            this.emit(PlaybackEvent.playbackSeeked, {
+                ...this.#eventContext(),
+                positionMs,
+                previousPositionMs,
+            });
+        }
+    }
+    /**
+     * Stop the active playback generation and release its input without leaving the voice channel.
+     * @returns Resolves after the backend stops the active source.
+     */
+    async stop() {
+        this.#assertActive();
+        const previousState = this.state;
+        const generation = numericGeneration(this.#native.playbackGeneration(this.#playbackId));
+        try {
+            await this.#native.stop(this.#playbackId);
+            if (isPlaybackActive(previousState) && this.state === 'stopped') {
+                this.#emitTerminal('stopped', generation, undefined, 'stop');
+            }
+        }
+        finally {
+            await this.#releaseInput();
+        }
+    }
+    /**
+     * Wait for the current playback generation to reach a terminal state.
+     * @returns The terminal playback state for the generation captured by this wait.
+     */
+    async wait() {
+        this.#assertActive();
+        // Capture synchronously so the native blocking waiter stays bound to the source
+        // that was active when wait() was called, even if play() replaces it first.
+        const generation = this.#native.playbackGeneration(this.#playbackId);
+        try {
+            return (await this.#native.wait(this.#playbackId, generation));
+        }
+        finally {
+            await this.#releaseInput();
+        }
+    }
+    /**
+     * Stop and release this standalone playback session.
+     * @returns Resolves after disposal; rejects if resource cleanup fails.
+     */
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#playController?.abort(new Error('playback session disposed'));
+        this.#signal?.removeEventListener('abort', this.#abortListener);
+        try {
+            await this.#native.disposePlaybackSession(this.#playbackId);
+        }
+        finally {
+            await this.#releaseInput();
+            this.#disposed = true;
+            this.hooks.clear();
+            this.#metadata.clear();
+            this.emit(PlaybackEvent.sessionDisposed, {
+                sessionId: this.sessionId,
+                ...(this.#guildId === undefined ? {} : { guildId: this.#guildId }),
+                nodeId: null,
+                generation: this.#latestGeneration,
+            });
+            this.#onDispose?.();
+        }
+    }
+    /**
+     * Detach and cancel this wrapper's bounded input pump without destroying the caller-owned Readable.
+     *
+     * @internal
+     * @returns Resolves after the input pump has released its listeners and native queue.
+     */
+    async releaseInput() {
+        await this.#releaseInput();
+    }
+    async #replaceFilterGraph(graph) {
+        this.#assertActive();
+        const previousGraph = this.filters.graph;
+        if (previousGraph === graph)
+            return;
+        if (graph === null)
+            await this.#native.playbackClearFilterGraph(this.#playbackId);
+        else
+            await this.#native.playbackSetFilterGraph(this.#playbackId, graph);
+        this.emit(PlaybackEvent.filterChanged, {
+            ...this.#eventContext(),
+            previousGraph,
+            graph,
+        });
+    }
+    #eventContext(generation) {
+        const activeGeneration = generation ?? this.#latestGeneration;
+        const context = lifecycleContext(this.sessionId, activeGeneration, this.#metadata.get(activeGeneration));
+        return this.#guildId === undefined ? context : { ...context, guildId: this.#guildId };
+    }
+    async #observeGeneration(generation, input) {
+        try {
+            const state = (await this.#native.wait(this.#playbackId, String(generation)));
+            if (state === 'completed' || state === 'failed' || state === 'stopped') {
+                const error = state === 'failed' ? new Error(this.error ?? 'playback failed') : undefined;
+                this.#emitTerminal(state, generation, error);
+            }
+        }
+        catch (error) {
+            if (!this.#disposed) {
+                // Native disposal can remove the session before this generation-bound
+                // wait settles. In that race, reading playbackState also rejects; the
+                // disposal lifecycle event is authoritative and no terminal event is
+                // needed for the removed session.
+                let state;
+                try {
+                    state = this.state;
+                }
+                catch {
+                    state = undefined;
+                }
+                if (state === 'failed')
+                    this.#emitTerminal('failed', generation, asError(error));
+            }
+        }
+        finally {
+            this.#metadata.delete(generation);
+            this.#startedGenerations.delete(generation);
+            if (this.#latestGeneration === generation) {
+                this.#clearAbortBinding(this.#playController);
+            }
+            await this.#releaseInput(input, generation);
+        }
+    }
+    #emitTerminal(state, generation, error, reason) {
+        if ((state !== 'failed' && !this.#startedGenerations.has(generation)) ||
+            this.#terminalGenerations.has(generation))
+            return;
+        this.#terminalGenerations.add(generation);
+        while (this.#terminalGenerations.size > 16) {
+            const oldest = this.#terminalGenerations.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.#terminalGenerations.delete(oldest);
+        }
+        const base = this.#eventContext(generation);
+        if (state === 'completed') {
+            this.emit(PlaybackEvent.playbackCompleted, { ...base, state, position: this.position });
+        }
+        else if (state === 'stopped') {
+            this.emit(PlaybackEvent.playbackStopped, reason ? { ...base, state, reason } : { ...base, state });
+        }
+        else {
+            this.emit(PlaybackEvent.playbackFailed, { ...base, state, error: asError(error) });
+        }
+        this.#metadata.delete(generation);
+        this.#clearAbortBinding(this.#playController);
+    }
+    #boundMetadata(generation) {
+        while (this.#metadata.size > 4) {
+            const oldest = this.#metadata.keys().next().value;
+            if (oldest === undefined || oldest === generation)
+                break;
+            this.#metadata.delete(oldest);
+        }
+    }
+    #clearAbortBinding(controller) {
+        if (!controller || this.#playController !== controller)
+            return;
+        this.#signal?.removeEventListener('abort', this.#abortListener);
+        this.#playController = undefined;
+        this.#signal = undefined;
+        this.#abortListener = undefined;
+    }
+    async #releaseInput(expected, generation) {
+        if (generation !== undefined && this.#latestGeneration !== generation) {
+            await expected?.cancel();
+            return;
+        }
+        const input = this.#input;
+        if (expected !== undefined && input !== expected) {
+            await expected.cancel();
+            return;
+        }
+        this.#input = undefined;
+        if (input)
+            await input.cancel();
+    }
+    #assertActive() {
+        if (this.#disposed)
+            throw new Error('Playback session has been disposed');
+    }
+}
+function isPlaybackActive(state) {
+    return (state === 'starting' ||
+        state === 'playing' ||
+        state === 'pausing' ||
+        state === 'resuming' ||
+        state === 'paused' ||
+        state === 'stopping');
+}
+function numericGeneration(value) {
+    const generation = Number(value);
+    if (!Number.isSafeInteger(generation) || generation < 0) {
+        throw new RangeError('native playback generation exceeds the JavaScript safe integer range');
+    }
+    return generation;
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function abortError(reason) {
+    const error = new Error(reason instanceof Error ? reason.message : 'playback was cancelled');
+    error.name = 'AbortError';
+    return error;
+}

package/dist/remedia.d.ts

@@ -0,0 +1,51 @@
+import { RemediaEventEmitter } from './events.js';
+import { DiscordSession, type DiscordSessionOptions } from './discord.js';
+import { type DiscordGatewaySend } from './gateway.js';
+import type { RemediaLifecycleEvents } from './lifecycle.js';
+import { PlaybackSession } from './playback.js';
+import { type DebugListener, type DiagnosticEvent } from './types.js';
+/** Optional Gateway integration for the embedded engine; required when creating Discord sessions. */
+export interface RemediaOptions {
+    /** Send raw Gateway payloads through the application's existing Discord client or shard. */
+    send: DiscordGatewaySend;
+}
+/**
+ * One embedded Remedia context. Create instances with `await Remedia.create()` so native
+ * observability and optional asynchronous OpenTelemetry exporters initialize on NAPI-RS's runtime.
+ */
+export declare class Remedia extends RemediaEventEmitter<RemediaLifecycleEvents> {
+    #private;
+    private constructor();
+    /**
+     * Create an independent native context using REMEDIA_* and OTEL_* environment settings.
+     * @param options - Optional bot Gateway callback; required when creating Discord sessions.
+     * @returns An initialized independent native engine context.
+     */
+    static create(options?: RemediaOptions): Promise<Remedia>;
+    /** Number of diagnostic events dropped by either bounded event queue. */
+    get droppedDebugEvents(): number;
+    /**
+     * Create a local decoder session that discards its PCM output.
+     * @returns An independent playback session owned by this engine until disposal.
+     * @typeParam Metadata - Application-owned metadata attached to playback generations.
+     */
+    createPlaybackSession<Metadata = unknown>(): PlaybackSession<Metadata>;
+    /**
+     * Create a Gateway-managed voice session. Call `connect()` to send OP 4 and join the channel.
+     * @param options - Guild and bot identity, requested channel, initial processing settings, and voice flags.
+     * @returns The unconnected session; call connect() to request a Gateway voice join.
+     * @typeParam Metadata - Application-owned metadata attached to playback generations.
+     */
+    createDiscordSession<Metadata = unknown>(options: DiscordSessionOptions): DiscordSession<Metadata>;
+    /**
+     * Forward a raw Discord Gateway packet to the matching in-process voice session.
+     * @param packet - Raw packet from this bot's Gateway dispatch stream.
+     */
+    receive(packet: unknown): void;
+    /**
+     * Stop all playbacks, disconnect transports, flush telemetry, and release native resources.
+     * @returns Resolves after cleanup; rejects when a resource fails to close.
+     */
+    close(): Promise<void>;
+}
+export type { DebugListener, DiagnosticEvent };

package/dist/remedia.js

@@ -0,0 +1,150 @@
+import { RemediaEventEmitter } from './events.js';
+import { NativeRemedia } from '../native.js';
+import { DiscordSession } from './discord.js';
+import { DiscordGatewayAdapter } from './gateway.js';
+import { PlaybackSessionEvents as PlaybackEvent, RemediaEvents as RemediaEvent, VoiceSessionEvents as VoiceEvent, } from './lifecycle.js';
+import { PlaybackSession } from './playback.js';
+import { toDiagnosticEvent } from './types.js';
+/**
+ * One embedded Remedia context. Create instances with `await Remedia.create()` so native
+ * observability and optional asynchronous OpenTelemetry exporters initialize on NAPI-RS's runtime.
+ */
+export class Remedia extends RemediaEventEmitter {
+    #native;
+    #sessions = new Set();
+    #discordSessions = new Map();
+    #gateway;
+    #closed = false;
+    constructor(native, options) {
+        super();
+        this.#native = native;
+        this.#gateway = options ? new DiscordGatewayAdapter(options.send) : undefined;
+        native.setDebugCallback((event) => {
+            const diagnostic = toDiagnosticEvent(event);
+            this.emit(RemediaEvent.debug, diagnostic);
+        });
+    }
+    /**
+     * Create an independent native context using REMEDIA_* and OTEL_* environment settings.
+     * @param options - Optional bot Gateway callback; required when creating Discord sessions.
+     * @returns An initialized independent native engine context.
+     */
+    static async create(options) {
+        return new Remedia(await NativeRemedia.create(), options);
+    }
+    /** Number of diagnostic events dropped by either bounded event queue. */
+    get droppedDebugEvents() {
+        return this.#native.droppedDebugEvents;
+    }
+    /**
+     * Create a local decoder session that discards its PCM output.
+     * @returns An independent playback session owned by this engine until disposal.
+     * @typeParam Metadata - Application-owned metadata attached to playback generations.
+     */
+    createPlaybackSession() {
+        this.#assertOpen();
+        let playback;
+        playback = new PlaybackSession(this.#native, this.#native.createPlaybackSession(), () => {
+            this.#sessions.delete(playback);
+        });
+        forwardLifecycleEvents(playback, this);
+        this.#sessions.add(playback);
+        return playback;
+    }
+    /**
+     * Create a Gateway-managed voice session. Call `connect()` to send OP 4 and join the channel.
+     * @param options - Guild and bot identity, requested channel, initial processing settings, and voice flags.
+     * @returns The unconnected session; call connect() to request a Gateway voice join.
+     * @typeParam Metadata - Application-owned metadata attached to playback generations.
+     */
+    createDiscordSession(options) {
+        this.#assertOpen();
+        if (!this.#gateway) {
+            throw new Error('Remedia.create() requires a Gateway send function for Discord sessions');
+        }
+        if (this.#discordSessions.has(options.guildId)) {
+            throw new Error(`a Discord voice session already exists for guild ${options.guildId}`);
+        }
+        let session;
+        session = new DiscordSession(this.#native, this.#gateway, options, () => {
+            this.#discordSessions.delete(session.guildId);
+        });
+        forwardLifecycleEvents(session, this);
+        this.#discordSessions.set(session.guildId, session);
+        return session;
+    }
+    /**
+     * Forward a raw Discord Gateway packet to the matching in-process voice session.
+     * @param packet - Raw packet from this bot's Gateway dispatch stream.
+     */
+    receive(packet) {
+        if (this.#closed || !this.#gateway)
+            return;
+        const dispatch = this.#gateway.receive(packet);
+        if (!dispatch)
+            return;
+        this.#discordSessions
+            .get(dispatch.guildId)
+            ?.receiveGatewayDispatch(dispatch.event, dispatch.data, dispatch.sequence, dispatch.epoch);
+    }
+    /**
+     * Stop all playbacks, disconnect transports, flush telemetry, and release native resources.
+     * @returns Resolves after cleanup; rejects when a resource fails to close.
+     */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const voiceCleanup = await Promise.allSettled([...this.#discordSessions.values()].map((session) => session.dispose()));
+        try {
+            await Promise.all([...this.#sessions].map((session) => session.dispose()));
+            await this.#native.close();
+        }
+        finally {
+            await Promise.all([...this.#sessions].map((session) => session.releaseInput()));
+            this.#sessions.clear();
+            this.#discordSessions.clear();
+        }
+        const failures = voiceCleanup.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);
+        if (failures.length > 0) {
+            throw new AggregateError(failures, 'one or more Discord voice sessions failed to close');
+        }
+    }
+    #assertOpen() {
+        if (this.#closed)
+            throw new Error('Remedia instance is closed');
+    }
+}
+function forwardLifecycleEvents(source, target) {
+    const sourceEvents = source;
+    const targetEvents = target;
+    const names = [
+        PlaybackEvent.playbackStarted,
+        PlaybackEvent.playbackCompleted,
+        PlaybackEvent.playbackStopped,
+        PlaybackEvent.playbackFailed,
+        PlaybackEvent.playbackPaused,
+        PlaybackEvent.playbackResumed,
+        PlaybackEvent.playbackSeeked,
+        PlaybackEvent.filterChanged,
+        PlaybackEvent.volumeChanged,
+        PlaybackEvent.sessionDisposed,
+        ...(source instanceof DiscordSession
+            ? [VoiceEvent.voiceStateChanged, VoiceEvent.voiceFailed]
+            : []),
+    ];
+    const unsubs = [];
+    for (const name of names) {
+        const listener = (event) => {
+            targetEvents.emit(name, event);
+        };
+        sourceEvents.on(name, listener);
+        unsubs.push(() => sourceEvents.off(name, listener));
+    }
+    const detach = () => {
+        sourceEvents.off(PlaybackEvent.sessionDisposed, detach);
+        for (const unsubscribe of unsubs.splice(0))
+            unsubscribe();
+    };
+    sourceEvents.once(PlaybackEvent.sessionDisposed, detach);
+}