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

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+import type { NativeDiagnosticEvent, NativeStreamInfo } from '../native.js';
+/** Lifecycle state of a playback pipeline, independent of its voice transport state. */
+export type PlaybackState = 'idle' | 'starting' | 'playing' | 'pausing' | 'resuming' | 'paused' | 'stopping' | 'stopped' | 'completed' | 'failed';
+/** Discord transport lifecycle state, including credential negotiation and recovery. */
+export type VoiceConnectionState = 'connecting' | 'negotiatingDave' | 'connected' | 'reconnecting' | 'disconnecting' | 'disconnected' | 'failed';
+/** Metadata and format information for the selected audio stream; unavailable measurements are null. */
+export interface AudioStreamInfo {
+    /** Zero-based index of the selected audio stream in the media container. */
+    streamIndex: number;
+    /** Codec name reported by the selected audio stream. */
+    codec: string;
+    /** Encoded stream sample rate in Hz, or null when unknown; playback output is normalized separately. */
+    sampleRate: number | null;
+    /** Encoded stream channel count, or null when unknown. */
+    channels: number | null;
+    /** Encoded stream channel layout description, or null when unknown. */
+    channelLayout: string | null;
+    /** Source duration in milliseconds, or null when unknown. */
+    durationMs: number | null;
+    /** Stream bit rate in bits per second, or null when unknown. */
+    bitRate: number | null;
+    /** Container or stream metadata keyed by native tag name. */
+    metadata: Readonly<Record<string, string>>;
+}
+/** Source and output timeline measurements in milliseconds; unsupported measurements are null. */
+export interface PlaybackPosition {
+    /** Original media timeline associated with the latest submitted PCM block. */
+    mediaMs: number | null;
+    /** `timestamp` when derived from source PTS, `estimated` when inferred, or null. */
+    mediaPositionAccuracy: 'timestamp' | 'estimated' | null;
+    /**
+     * Duration of audio submitted to the output in milliseconds; may differ from source position after filtering.
+     */
+    submittedMs: number;
+    /** Output-reported played duration in milliseconds, or null when the output does not provide it. */
+    playedMs: number | null;
+}
+/** Severity of a structured native tracing event. */
+export type DiagnosticSeverity = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/** Typed diagnostic value; integers remain decimal strings to preserve precision in JavaScript. */
+export type DiagnosticFieldValue = {
+    /** Discriminant describing the representation of the diagnostic field. */
+    kind: 'string' | 'debug';
+    /** Diagnostic field value in the representation selected by kind. */
+    value: string;
+} | {
+    /** Discriminant describing the representation of the diagnostic field. */
+    kind: 'integer';
+    /** Diagnostic field value in the representation selected by kind. */
+    value: string;
+} | {
+    /** Discriminant describing the representation of the diagnostic field. */
+    kind: 'boolean';
+    /** Diagnostic field value in the representation selected by kind. */
+    value: boolean;
+} | {
+    /** Discriminant describing the representation of the diagnostic field. */
+    kind: 'number';
+    /** Diagnostic field value in the representation selected by kind. */
+    value: number;
+};
+/** Structured native diagnostic event forwarded through the bounded diagnostic queues. */
+export interface DiagnosticEvent {
+    /** Unix timestamp of the diagnostic event in milliseconds. */
+    timestamp: number;
+    /** Native tracing severity associated with the event. */
+    severity: DiagnosticSeverity;
+    /** Native tracing target or module that emitted the diagnostic. */
+    target: string;
+    /** Server or diagnostic event name. */
+    event: string;
+    /** Human-readable diagnostic or failure description. */
+    message: string | null;
+    /** Native playback identity, or null for diagnostics without playback context. */
+    playbackId: string | null;
+    /** Native voice connection identity, or null for diagnostics without voice context. */
+    voiceConnectionId: string | null;
+    /** Typed structured diagnostic fields; integers are represented as decimal strings. */
+    fields: Readonly<Record<string, DiagnosticFieldValue>>;
+}
+/**
+ * Callback receiving a structured native diagnostic event.
+ * @param event - Structured native diagnostic delivered by the bounded event queue.
+ */
+export type DebugListener = (event: DiagnosticEvent) => void;
+/**
+ * Normalize native optional stream metadata into explicit nullable public fields.
+ * @param info - Native stream metadata to normalize into the public nullable representation.
+ * @returns Stream metadata using the public AudioStreamInfo representation.
+ */
+export declare function toStreamInfo(info: NativeStreamInfo): AudioStreamInfo;
+/**
+ * Normalize a structured native diagnostic; invalid severity or field representations throw.
+ * @param event - Event name identifying the typed notification or Gateway voice dispatch.
+ * @returns A diagnostic event with typed field values.
+ */
+export declare function toDiagnosticEvent(event: NativeDiagnosticEvent): DiagnosticEvent;

package/dist/types.js

@@ -0,0 +1,75 @@
+/**
+ * Normalize native optional stream metadata into explicit nullable public fields.
+ * @param info - Native stream metadata to normalize into the public nullable representation.
+ * @returns Stream metadata using the public AudioStreamInfo representation.
+ */
+export function toStreamInfo(info) {
+    return {
+        streamIndex: info.streamIndex,
+        codec: info.codec,
+        sampleRate: info.sampleRate ?? null,
+        channels: info.channels ?? null,
+        channelLayout: info.channelLayout ?? null,
+        durationMs: info.durationMs ?? null,
+        bitRate: info.bitRate ?? null,
+        metadata: info.metadata,
+    };
+}
+/**
+ * Normalize a structured native diagnostic; invalid severity or field representations throw.
+ * @param event - Event name identifying the typed notification or Gateway voice dispatch.
+ * @returns A diagnostic event with typed field values.
+ */
+export function toDiagnosticEvent(event) {
+    const severity = event.severity;
+    if (!isDiagnosticSeverity(severity)) {
+        throw new Error(`Unknown native diagnostic severity: ${severity}`);
+    }
+    const fields = {};
+    for (const [key, field] of Object.entries(event.fields)) {
+        if (field.kind === 'string' || field.kind === 'debug') {
+            if (field.stringValue === undefined) {
+                throw new Error(`Invalid native diagnostic field: ${key}`);
+            }
+            fields[key] = { kind: field.kind, value: field.stringValue };
+        }
+        else if (field.kind === 'integer') {
+            if (field.stringValue === undefined) {
+                throw new Error(`Invalid native diagnostic field: ${key}`);
+            }
+            fields[key] = { kind: 'integer', value: field.stringValue };
+        }
+        else if (field.kind === 'boolean') {
+            if (field.boolValue === undefined) {
+                throw new Error(`Invalid native diagnostic field: ${key}`);
+            }
+            fields[key] = { kind: 'boolean', value: field.boolValue };
+        }
+        else if (field.kind === 'number') {
+            if (field.numberValue === undefined) {
+                throw new Error(`Invalid native diagnostic field: ${key}`);
+            }
+            fields[key] = { kind: 'number', value: field.numberValue };
+        }
+        else {
+            throw new Error(`Unknown native diagnostic field kind: ${field.kind}`);
+        }
+    }
+    return {
+        timestamp: event.timestamp,
+        severity,
+        target: event.target,
+        event: event.event,
+        message: event.message ?? null,
+        playbackId: event.playbackId ?? null,
+        voiceConnectionId: event.voiceConnectionId ?? null,
+        fields,
+    };
+}
+function isDiagnosticSeverity(value) {
+    return (value === 'trace' ||
+        value === 'debug' ||
+        value === 'info' ||
+        value === 'warn' ||
+        value === 'error');
+}

package/native.d.ts

@@ -0,0 +1,162 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
+export declare class NativeRemedia {
+  /** Forward this context's bounded diagnostic queue to one JavaScript callback. */
+  setDebugCallback(callback: (arg: NativeDiagnosticEvent) => void): void
+  /** Number of events discarded by the observability queue or full N-API callback queue. */
+  get droppedDebugEvents(): number
+  /** Open a Discord voice transport using session data collected by the caller's Gateway client. */
+  connectVoice(options: NativeVoiceOptions): Promise<NativeVoiceSessionIds>
+  /**
+   * Replace only the Discord transport while retaining the existing
+   * playback decoder, filters, volume, pause state, and output timeline.
+   */
+  replaceVoice(voiceId: string, generation: number, options: NativeVoiceOptions): Promise<void>
+  /**
+   * Invalidate an in-flight transport replacement before newer Gateway
+   * credentials are used. This does not touch the active playback session.
+   */
+  invalidateVoiceRecovery(voiceId: string, generation: number): void
+  /** Close the old Discord transport while leaving the playback session parked for recovery. */
+  suspendVoice(voiceId: string, generation: number): Promise<void>
+  /** Terminate a playback parked during voice recovery after retries fail. */
+  failVoiceRecovery(voiceId: string, message: string): void
+  /** Current transport state for one voice session. */
+  voiceState(voiceId: string): string
+  /** Return the latest transport failure for one voice session. */
+  voiceError(voiceId: string): string | null
+  /** Stop playback and release the associated voice transport. */
+  disconnectVoice(voiceId: string): Promise<void>
+  /** Forget a voice session after its transport has been disconnected. */
+  releaseVoiceSession(voiceId: string): void
+  /** Create a bounded native byte input for one Node.js Readable producer. */
+  createByteStream(): string
+  /**
+   * Copy one Node buffer into the native-owned bounded input, applying
+   * backpressure when the decoder has not consumed enough pending bytes.
+   */
+  writeByteStream(streamId: string, chunk: Buffer): Promise<void>
+  /**
+   * Signal a clean producer EOF. The stream handle remains valid until it is
+   * cancelled so playback can resolve its source if EOF arrives quickly.
+   */
+  finishByteStream(streamId: string): Promise<void>
+  /** Propagate a JavaScript Readable error through FFmpeg to playback state. */
+  failByteStream(streamId: string, message: string): Promise<void>
+  /**
+   * Cancel an input and wake any native readers or writers blocked by its
+   * bounded queue. Repeated calls are harmless.
+   */
+  cancelByteStream(streamId: string): void
+  /** Create an isolated, diagnostics-only Remedia context from environment configuration. */
+  static create(): Promise<NativeRemedia>
+  /**
+   * Stop all playback, disconnect all voice transports, flush telemetry, and close the context.
+   * This method is safe to call repeatedly.
+   */
+  close(): Promise<void>
+  /** Create a decoder-only session that consumes frames into a no-op output. */
+  createPlaybackSession(): string
+  /** Start decoding into the null output or the associated Discord Opus sender. */
+  play(playbackId: string, source: NativeMediaSource): Promise<NativeStreamInfo>
+  /** Request playback pause at the current output frame boundary. */
+  pause(playbackId: string): Promise<void>
+  /** Resume a paused playback session. */
+  resume(playbackId: string): Promise<void>
+  /** Seek to a media position in milliseconds. */
+  seek(playbackId: string, positionMs: number): Promise<void>
+  /** Validate and replace the trusted native FFmpeg audio filtergraph. */
+  playbackSetFilterGraph(playbackId: string, graph: string): Promise<void>
+  /** Clear the current native audio filtergraph. */
+  playbackClearFilterGraph(playbackId: string): Promise<void>
+  /** Current configured raw FFmpeg filtergraph, if any. */
+  playbackFilterGraph(playbackId: string): string | null
+  /** Set normalized linear master gain in the inclusive range 0.0 through 2.0. */
+  playbackSetVolume(playbackId: string, gain: number): Promise<void>
+  /** Current normalized linear master gain. */
+  playbackVolume(playbackId: string): number
+  /** Validate a filtergraph before a Discord voice session has a native playback object. */
+  validateFilterGraph(graph: string): Promise<void>
+  /** Stop playback without disconnecting its Discord voice transport. */
+  stop(playbackId: string): Promise<void>
+  /** Capture the source generation before an asynchronous wait is scheduled. */
+  playbackGeneration(playbackId: string): string
+  /** Wait for a generation captured synchronously by the JavaScript wrapper. */
+  wait(playbackId: string, generation: string): Promise<string>
+  /** Current playback lifecycle state. */
+  playbackState(playbackId: string): string
+  /** Source media, filtered output submission, and output-reported played positions. */
+  playbackPosition(playbackId: string): NativePlaybackPosition
+  /** Known media duration in milliseconds. */
+  playbackDurationMs(playbackId: string): number | null
+  /** Latest decoder, resampler, output, or worker failure. */
+  playbackError(playbackId: string): string | null
+  /** Stop and forget a standalone playback session. Voice sessions remain connected. */
+  disposePlaybackSession(playbackId: string): Promise<void>
+}
+
+export interface NativeDiagnosticEvent {
+  timestamp: number
+  severity: string
+  target: string
+  event: string
+  message?: string
+  playbackId?: string
+  voiceConnectionId?: string
+  fields: Record<string, NativeDiagnosticField>
+}
+
+export interface NativeDiagnosticField {
+  kind: string
+  stringValue?: string
+  boolValue?: boolean
+  numberValue?: number
+}
+
+export interface NativeMediaSource {
+  /** Explicitly `file`, `url`, `buffer`, or `stream`. */
+  kind: string
+  value?: string
+  bytes?: Buffer
+}
+
+export interface NativePlaybackPosition {
+  mediaMs?: number
+  mediaPositionAccuracy?: string
+  submittedMs: number
+  playedMs?: number
+}
+
+export interface NativeStreamInfo {
+  streamIndex: number
+  codec: string
+  sampleRate?: number
+  channels?: number
+  channelLayout?: string
+  durationMs?: number
+  bitRate?: number
+  metadata: Record<string, string>
+}
+
+export interface NativeVoiceOptions {
+  guildId: string
+  channelId: string
+  userId: string
+  sessionId: string
+  token: string
+  endpoint: string
+}
+
+export interface NativeVoiceSessionIds {
+  voiceId: string
+  playbackId: string
+}