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

package/dist/events.d.ts

@@ -0,0 +1,21 @@
+import { EventEmitter } from 'node:events';
+type EventMap<Events> = {
+    [Key in keyof Events]: unknown[];
+};
+type EventKey<Key, Events> = Events extends [never] ? string | symbol : Key | keyof Events;
+type EventArgs<Key, Events> = Events extends [never] ? any[] : Key extends keyof Events ? Events[Key] : never;
+/**
+ * EventEmitter-compatible base that isolates synchronous listener failures from engine work.
+ * @typeParam Events - Type used to correlate typed event keys and argument tuples.
+ */
+export declare class RemediaEventEmitter<Events extends EventMap<Events>> extends EventEmitter<Events> {
+    /**
+     * Emit a typed lifecycle event while isolating exceptions thrown by application listeners.
+     * @param event - Event name identifying the typed notification or Gateway voice dispatch.
+     * @param args - Typed event arguments delivered to registered listeners.
+     * @returns Whether at least one listener handled the event, or false when a listener threw.
+     * @typeParam Key - Type used to correlate typed event keys and argument tuples.
+     */
+    emit<Key>(event: EventKey<Key, Events>, ...args: EventArgs<Key, Events>): boolean;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,28 @@
+import { EventEmitter } from 'node:events';
+/**
+ * EventEmitter-compatible base that isolates synchronous listener failures from engine work.
+ * @typeParam Events - Type used to correlate typed event keys and argument tuples.
+ */
+export class RemediaEventEmitter extends EventEmitter {
+    /**
+     * Emit a typed lifecycle event while isolating exceptions thrown by application listeners.
+     * @param event - Event name identifying the typed notification or Gateway voice dispatch.
+     * @param args - Typed event arguments delivered to registered listeners.
+     * @returns Whether at least one listener handled the event, or false when a listener threw.
+     * @typeParam Key - Type used to correlate typed event keys and argument tuples.
+     */
+    emit(event, ...args) {
+        try {
+            return super.emit(event, ...args);
+        }
+        catch {
+            try {
+                process.emitWarning(`A listener for Remedia event ${String(event)} threw; the exception was isolated.`, { code: 'REMEDIA_LISTENER_ERROR' });
+            }
+            catch {
+                // A custom process warning handler must not re-enter native or lifecycle operations.
+            }
+            return false;
+        }
+    }
+}

package/dist/filters.d.ts

@@ -0,0 +1,22 @@
+/** Controls one playback session's trusted raw FFmpeg audio filtergraph. */
+export declare class FilterControls {
+    #private;
+    /** Current configured raw filtergraph, or null when filtering is disabled. */
+    get graph(): string | null;
+    /**
+     * Validate and replace the graph at a safe PCM boundary.
+     * @param graph - Trusted, non-empty raw FFmpeg audio filtergraph; native validation errors reject the operation.
+     * @returns Resolves after configuration is applied; rejects for an empty or invalid filtergraph.
+     */
+    set(graph: string): Promise<void>;
+    /**
+     * Disable the raw filtergraph without changing master volume.
+     * @returns Resolves when filtering is disabled.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Validate a finite linear gain in the inclusive range 0 through 2; invalid values throw RangeError.
+ * @param gain - Finite linear master gain from 0 through 2; 1 leaves amplitude unchanged.
+ */
+export declare function validateVolume(gain: number): void;

package/dist/filters.js

@@ -0,0 +1,52 @@
+/** Controls one playback session's trusted raw FFmpeg audio filtergraph. */
+export class FilterControls {
+    #read;
+    #replace;
+    #clear;
+    /**
+     * @internal Constructed by playback session wrappers.
+     * @param read - Callback returning the currently configured raw filtergraph.
+     * @param replace - Callback that validates and applies a replacement raw filtergraph.
+     * @param clear - Callback that disables the current raw filtergraph.
+     */
+    constructor(read, replace, clear) {
+        this.#read = read;
+        this.#replace = replace;
+        this.#clear = clear;
+    }
+    /** Current configured raw filtergraph, or null when filtering is disabled. */
+    get graph() {
+        return this.#read();
+    }
+    /**
+     * Validate and replace the graph at a safe PCM boundary.
+     * @param graph - Trusted, non-empty raw FFmpeg audio filtergraph; native validation errors reject the operation.
+     * @returns Resolves after configuration is applied; rejects for an empty or invalid filtergraph.
+     */
+    set(graph) {
+        if (typeof graph !== 'string')
+            throw new TypeError('filtergraph must be a string');
+        if (graph.trim().length === 0) {
+            throw new RangeError('filtergraph must not be empty or whitespace-only');
+        }
+        if (this.graph === graph)
+            return Promise.resolve();
+        return this.#replace(graph);
+    }
+    /**
+     * Disable the raw filtergraph without changing master volume.
+     * @returns Resolves when filtering is disabled.
+     */
+    clear() {
+        return this.#clear();
+    }
+}
+/**
+ * Validate a finite linear gain in the inclusive range 0 through 2; invalid values throw RangeError.
+ * @param gain - Finite linear master gain from 0 through 2; 1 leaves amplitude unchanged.
+ */
+export function validateVolume(gain) {
+    if (!Number.isFinite(gain) || gain < 0 || gain > 2) {
+        throw new RangeError('volume must be a finite linear gain between 0.0 and 2.0');
+    }
+}

package/dist/gateway.d.ts

@@ -0,0 +1,88 @@
+/** Minimal Discord Gateway integration used by the Node.js voice adapter. */
+export interface DiscordGatewayVoicePayload {
+    /** Discord Gateway operation code; voice state requests use 4. */
+    op: 4;
+    /** Gateway payload data; voice requests contain guild, channel, and self-state fields. */
+    d: {
+        /** Discord guild snowflake to route through the bot Gateway. */
+        guild_id: string;
+        /** Voice channel snowflake, or null to leave voice. */
+        channel_id: string | null;
+        /** Discord self-mute flag; independent of playback volume and pause. */
+        self_mute: boolean;
+        /** Discord self-deaf flag; independent of playback volume and pause. */
+        self_deaf: boolean;
+    };
+}
+/**
+ * Send a Gateway payload through the application's existing Discord client or shard.
+ * @param guildId - Discord guild snowflake used to route the operation.
+ * @param payload - Discord Gateway OP 4 payload to send through the guild shard.
+ */
+export type DiscordGatewaySend = (guildId: string, payload: DiscordGatewayVoicePayload) => void | Promise<void>;
+/** A raw Discord Gateway packet, such as the value emitted by a client's `raw` event. */
+export interface DiscordGatewayPacket {
+    /** Gateway dispatch event name, when the packet represents a dispatch. */
+    t?: string;
+    /** Raw event-specific Gateway payload, validated only for supported voice dispatches. */
+    d?: unknown;
+    /** Gateway operation code, when supplied by the host application. */
+    op?: number;
+    /**
+     * Additional Gateway packet fields forwarded unchanged by the host application.
+     * @param key - Additional Gateway packet field name.
+     */
+    [key: string]: unknown;
+}
+/** Gateway dispatch names used to obtain voice transport credentials. */
+export type DiscordVoiceGatewayEvent = 'VOICE_STATE_UPDATE' | 'VOICE_SERVER_UPDATE';
+/** Validated guild-scoped voice dispatch with sequence and Gateway epoch correlation. */
+export interface DiscordVoiceGatewayDispatch {
+    /** Gateway voice dispatch name. */
+    event: DiscordVoiceGatewayEvent;
+    /** Event-specific structured payload. */
+    data: Record<string, unknown>;
+    /** Discord guild snowflake as a decimal string; unique within the owning client. */
+    guildId: string;
+    /** Host Gateway dispatch sequence used to reject stale voice credentials. */
+    sequence?: number;
+    /** Gateway READY epoch used to distinguish independent dispatch sequence spaces. */
+    epoch: number;
+}
+/**
+ * Adapts the caller-owned Discord Gateway to Remedia's voice lifecycle. The adapter only sends
+ * Gateway OP 4 and parses the two voice dispatches; voice WebSocket, UDP, RTP, and DAVE remain in
+ * the native transport.
+ */
+export declare class DiscordGatewayAdapter {
+    #private;
+    /**
+     * Construct this wrapper with its owning services. Use the owning engine or client factory for application code.
+     * @param send - Application callback routing Gateway OP 4 through the correct guild shard.
+     */
+    constructor(send: DiscordGatewaySend);
+    /** Most recently observed Gateway dispatch sequence, when supplied by the host client. */
+    get lastSequence(): number | undefined;
+    /** Changes when the host Gateway starts a new READY session and resets its sequence. */
+    get epoch(): number;
+    /**
+     * Request a voice channel join or leave through Gateway OP 4.
+     * @param guildId - Discord guild snowflake used to route the operation.
+     * @param channelId - Destination Discord voice channel snowflake; null requests a leave where supported.
+     * @param selfDeaf - Discord self-deaf flag; defaults to true.
+     * @param selfMute - Discord self-mute flag; defaults to false.
+     */
+    setVoiceChannel(guildId: string, channelId: string | null, selfDeaf?: boolean, selfMute?: boolean): void | Promise<void>;
+    /**
+     * Parse only relevant voice dispatches; malformed and unrelated packets are ignored.
+     * @param packet - Raw packet from this bot's Gateway dispatch stream.
+     * @returns Validated voice dispatch, or undefined for an unrelated or malformed packet.
+     */
+    receive(packet: unknown): DiscordVoiceGatewayDispatch | undefined;
+}
+/**
+ * Check whether a string contains a positive decimal Discord snowflake that fits u64.
+ * @param value - Discord snowflake string to validate.
+ * @returns True for a valid positive u64 snowflake string.
+ */
+export declare function isSnowflake(value: string): boolean;

package/dist/gateway.js

@@ -0,0 +1,100 @@
+/**
+ * Adapts the caller-owned Discord Gateway to Remedia's voice lifecycle. The adapter only sends
+ * Gateway OP 4 and parses the two voice dispatches; voice WebSocket, UDP, RTP, and DAVE remain in
+ * the native transport.
+ */
+export class DiscordGatewayAdapter {
+    #send;
+    #lastSequence;
+    #epoch = 0;
+    /**
+     * Construct this wrapper with its owning services. Use the owning engine or client factory for application code.
+     * @param send - Application callback routing Gateway OP 4 through the correct guild shard.
+     */
+    constructor(send) {
+        this.#send = send;
+    }
+    /** Most recently observed Gateway dispatch sequence, when supplied by the host client. */
+    get lastSequence() {
+        return this.#lastSequence;
+    }
+    /** Changes when the host Gateway starts a new READY session and resets its sequence. */
+    get epoch() {
+        return this.#epoch;
+    }
+    /**
+     * Request a voice channel join or leave through Gateway OP 4.
+     * @param guildId - Discord guild snowflake used to route the operation.
+     * @param channelId - Destination Discord voice channel snowflake; null requests a leave where supported.
+     * @param selfDeaf - Discord self-deaf flag; defaults to true.
+     * @param selfMute - Discord self-mute flag; defaults to false.
+     */
+    setVoiceChannel(guildId, channelId, selfDeaf = true, selfMute = false) {
+        return this.#send(guildId, {
+            op: 4,
+            d: {
+                guild_id: guildId,
+                channel_id: channelId,
+                self_mute: selfMute,
+                self_deaf: selfDeaf,
+            },
+        });
+    }
+    /**
+     * Parse only relevant voice dispatches; malformed and unrelated packets are ignored.
+     * @param packet - Raw packet from this bot's Gateway dispatch stream.
+     * @returns Validated voice dispatch, or undefined for an unrelated or malformed packet.
+     */
+    receive(packet) {
+        if (!isRecord(packet) || typeof packet.t !== 'string')
+            return undefined;
+        const sequence = typeof packet.s === 'number' && Number.isSafeInteger(packet.s) && packet.s >= 0
+            ? packet.s
+            : undefined;
+        if (packet.t === 'READY') {
+            this.#epoch += 1;
+            this.#lastSequence = sequence;
+            return undefined;
+        }
+        if (sequence !== undefined) {
+            if (this.#lastSequence !== undefined && sequence <= this.#lastSequence)
+                return undefined;
+            this.#lastSequence = sequence;
+        }
+        if (!isRecord(packet.d))
+            return undefined;
+        if (packet.t !== 'VOICE_STATE_UPDATE' && packet.t !== 'VOICE_SERVER_UPDATE')
+            return undefined;
+        const guildId = packet.d.guild_id;
+        if (typeof guildId !== 'string' || !isSnowflake(guildId))
+            return undefined;
+        const dispatch = {
+            event: packet.t,
+            data: packet.d,
+            guildId,
+            epoch: this.#epoch,
+        };
+        if (sequence !== undefined)
+            dispatch.sequence = sequence;
+        return dispatch;
+    }
+}
+/**
+ * Check whether a string contains a positive decimal Discord snowflake that fits u64.
+ * @param value - Discord snowflake string to validate.
+ * @returns True for a valid positive u64 snowflake string.
+ */
+export function isSnowflake(value) {
+    if (!/^\d{1,20}$/.test(value))
+        return false;
+    try {
+        const id = BigInt(value);
+        return id > 0n && id <= 18446744073709551615n;
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { DiscordSession } from './discord.js';
+export type { DiscordConnectOptions, DiscordSessionOptions } from './discord.js';
+export type { DiscordGatewayPacket, DiscordGatewaySend, DiscordGatewayVoicePayload, } from './gateway.js';
+export { PlaybackSession } from './playback.js';
+export { PlaybackHooks, PlaybackSessionEvents, RemediaEvents, VoiceSessionEvents, } from './lifecycle.js';
+export { Remedia, type RemediaOptions } from './remedia.js';
+export type { MediaSource } from './input.js';
+export type { AudioStreamInfo, DebugListener, DiagnosticEvent, DiagnosticFieldValue, DiagnosticSeverity, PlaybackPosition, PlaybackState, VoiceConnectionState, } from './types.js';
+export type { BeforePlayContext, BeforePlayHook, BeforePlayResult, LifecycleVoiceState, PlayOptions, PlaybackEventIdentity, PlaybackLifecycleEvents, PlaybackSessionEventMap, RemediaLifecycleEvents, SessionLifecycleEvents, VoiceEventIdentity, VoiceLifecycleEvents, } from './lifecycle.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { DiscordSession } from './discord.js';
+export { PlaybackSession } from './playback.js';
+export { PlaybackHooks, PlaybackSessionEvents, RemediaEvents, VoiceSessionEvents, } from './lifecycle.js';
+export { Remedia } from './remedia.js';

package/dist/input.d.ts

@@ -0,0 +1,46 @@
+import { Buffer } from 'node:buffer';
+import type { Readable } from 'node:stream';
+import type { NativeMediaSource, NativeRemedia } from '../native.js';
+/**
+ * Encoded media input. Files and HTTP(S) URLs work in both modes; owned bytes and caller-owned binary Readables require embedded playback.
+ */
+export type MediaSource = {
+    /** Local media file path; remote mode resolves it on the server and enforces configured file roots. */
+    file: string;
+} | {
+    /** HTTP(S) media URL opened by the selected engine; remote nodes enforce server URL policy. */
+    url: string;
+} | {
+    /** Owned encoded media bytes, supported by embedded nodes only. */
+    buffer: Buffer | Uint8Array;
+} | {
+    /**
+     * Caller-owned binary Readable, consumed with bounded backpressure in embedded mode; Remedia does not destroy it.
+     */
+    stream: Readable;
+};
+/** Internal bounded byte-stream input and cancellation handle owned by a playback wrapper. */
+export interface ReadableInputHandle {
+    /** Native byte-stream source fed by the bounded input pump. */
+    readonly source: NativeMediaSource;
+    /**
+     * Cancel the native byte queue and detach input-pump listeners without destroying the caller-owned stream.
+     * @returns Resolves after the input pump has released its resources.
+     */
+    cancel(): Promise<void>;
+}
+/**
+ * Convert a file, HTTP(S) URL, or owned byte input to the native media representation.
+ * @param source - Encoded media input; Buffer and caller-owned binary Readable inputs require embedded mode.
+ * @returns A native source; bytes are copied into an owned Buffer.
+ */
+export declare function toNativeSource(source: Exclude<MediaSource, {
+    stream: Readable;
+}>): NativeMediaSource;
+/**
+ * Start a bounded native input pump for a caller-owned binary Readable.
+ * @param native - Owning native engine instance; its resources must outlive this wrapper.
+ * @param stream - Caller-owned binary Readable to consume with bounded native backpressure.
+ * @returns Native stream source and an idempotent cancellation handle.
+ */
+export declare function createReadableInput(native: NativeRemedia, stream: Readable): ReadableInputHandle;

package/dist/input.js

@@ -0,0 +1,135 @@
+import { Buffer } from 'node:buffer';
+/**
+ * Convert a file, HTTP(S) URL, or owned byte input to the native media representation.
+ * @param source - Encoded media input; Buffer and caller-owned binary Readable inputs require embedded mode.
+ * @returns A native source; bytes are copied into an owned Buffer.
+ */
+export function toNativeSource(source) {
+    if ('file' in source)
+        return { kind: 'file', value: source.file };
+    if ('url' in source)
+        return { kind: 'url', value: source.url };
+    return { kind: 'buffer', bytes: Buffer.from(source.buffer) };
+}
+/**
+ * Start a bounded native input pump for a caller-owned binary Readable.
+ * @param native - Owning native engine instance; its resources must outlive this wrapper.
+ * @param stream - Caller-owned binary Readable to consume with bounded native backpressure.
+ * @returns Native stream source and an idempotent cancellation handle.
+ */
+export function createReadableInput(native, stream) {
+    const streamId = native.createByteStream();
+    const cancellation = new AbortController();
+    const pump = pumpReadable(native, streamId, stream, cancellation.signal);
+    let cleanup;
+    return {
+        source: { kind: 'stream', value: streamId },
+        cancel() {
+            cleanup ??= (async () => {
+                cancellation.abort();
+                native.cancelByteStream(streamId);
+                await pump;
+            })();
+            return cleanup;
+        },
+    };
+}
+async function pumpReadable(native, streamId, stream, signal) {
+    let sourceError;
+    let failureSent = false;
+    const failSource = (error) => {
+        sourceError ??= error;
+        if (failureSent || signal.aborted)
+            return;
+        failureSent = true;
+        void native.failByteStream(streamId, sourceError.message).catch(() => { });
+    };
+    const onError = (error) => failSource(error);
+    stream.pause();
+    stream.on('error', onError);
+    try {
+        while (!signal.aborted) {
+            if (sourceError)
+                throw sourceError;
+            if (stream.errored)
+                throw stream.errored;
+            const chunk = stream.read();
+            if (chunk === null) {
+                const wake = await waitForReadable(stream, signal, () => sourceError);
+                if (wake === 'abort')
+                    return;
+                if (wake === 'end')
+                    break;
+                if (wake === 'close')
+                    throw sourceError ?? new Error('Readable closed before ending');
+                continue;
+            }
+            if (!(chunk instanceof Uint8Array)) {
+                throw new TypeError('Readable media sources must produce Buffer or Uint8Array chunks');
+            }
+            // This copy gives native code an independent snapshot of the chunk. The
+            // byte queue then takes ownership and waits for decoder backpressure.
+            await native.writeByteStream(streamId, Buffer.from(chunk));
+        }
+        if (!signal.aborted && !sourceError)
+            await native.finishByteStream(streamId);
+    }
+    catch (error) {
+        if (!signal.aborted) {
+            failSource(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    finally {
+        stream.pause();
+        stream.off('error', onError);
+    }
+}
+function waitForReadable(stream, signal, getError) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            stream.off('readable', onReadable);
+            stream.off('end', onEnd);
+            stream.off('close', onClose);
+            stream.off('error', onError);
+            signal.removeEventListener('abort', onAbort);
+        };
+        const finish = (wake) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(wake);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const onReadable = () => finish('readable');
+        const onEnd = () => finish('end');
+        const onClose = () => finish('close');
+        const onError = (error) => fail(error);
+        const onAbort = () => finish('abort');
+        stream.once('readable', onReadable);
+        stream.once('end', onEnd);
+        stream.once('close', onClose);
+        stream.once('error', onError);
+        signal.addEventListener('abort', onAbort, { once: true });
+        // An event can arrive between read() returning null and listener setup.
+        if (signal.aborted)
+            onAbort();
+        else if (getError())
+            onError(getError());
+        else if (stream.errored)
+            onError(stream.errored);
+        else if (stream.readableEnded)
+            onEnd();
+        else if (stream.destroyed)
+            onClose();
+        else if (stream.readableLength > 0)
+            onReadable();
+    });
+}