@remedia/node 0.1.0-dev.0 → 0.1.0-dev.2

package/dist/lifecycle.js

@@ -1,28 +1,51 @@
 /** 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. */
+/**
+ * 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');
@@ -33,6 +56,11 @@ export class PlaybackHooks {
                 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)
@@ -52,6 +80,14 @@ export class PlaybackHooks {
         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 }

package/dist/playback.d.ts

@@ -3,27 +3,71 @@ 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. */
+/**
+ * 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. */
+    /**
+     * 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. */
+    /**
+     * Stop and release this standalone playback session.
+     * @returns Resolves after disposal; rejects if resource cleanup fails.
+     */
     dispose(): Promise<void>;
 }

package/dist/playback.js

@@ -3,7 +3,10 @@ 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. */
+/**
+ * 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;
@@ -11,7 +14,9 @@ export class PlaybackSession extends RemediaEventEmitter {
     #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;
@@ -21,7 +26,16 @@ export class PlaybackSession extends RemediaEventEmitter {
     #abortListener;
     #latestGeneration = 0;
     #guildId;
-    /** @internal */
+    /**
+     * 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;
@@ -39,9 +53,11 @@ export class PlaybackSession extends RemediaEventEmitter {
     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 {
@@ -54,9 +70,11 @@ export class PlaybackSession extends RemediaEventEmitter {
             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;
     }
@@ -64,7 +82,12 @@ export class PlaybackSession extends RemediaEventEmitter {
     get volume() {
         return this.#native.playbackVolume(this.#playbackId);
     }
-    /** Set master gain independently of the raw filtergraph. */
+    /**
+     * 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);
@@ -78,6 +101,12 @@ export class PlaybackSession extends RemediaEventEmitter {
             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)) {
@@ -160,6 +189,10 @@ export class PlaybackSession extends RemediaEventEmitter {
             }
         }
     }
+    /**
+     * 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;
@@ -172,6 +205,10 @@ export class PlaybackSession extends RemediaEventEmitter {
             });
         }
     }
+    /**
+     * 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;
@@ -184,6 +221,11 @@ export class PlaybackSession extends RemediaEventEmitter {
             });
         }
     }
+    /**
+     * 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;
@@ -196,6 +238,10 @@ export class PlaybackSession extends RemediaEventEmitter {
             });
         }
     }
+    /**
+     * 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;
@@ -210,6 +256,10 @@ export class PlaybackSession extends RemediaEventEmitter {
             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
@@ -222,7 +272,10 @@ export class PlaybackSession extends RemediaEventEmitter {
             await this.#releaseInput();
         }
     }
-    /** Stop and release this standalone playback session. */
+    /**
+     * Stop and release this standalone playback session.
+     * @returns Resolves after disposal; rejects if resource cleanup fails.
+     */
     async dispose() {
         if (this.#disposed)
             return;
@@ -245,7 +298,12 @@ export class PlaybackSession extends RemediaEventEmitter {
             this.#onDispose?.();
         }
     }
-    /** @internal */
+    /**
+     * 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();
     }

package/dist/remedia.d.ts

@@ -1,13 +1,23 @@
+import { type MediaSource } from './input.js';
+import { type AudioStreamInfo } from './types.js';
 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;
 }
+/** Cancellation and deadline for disposable metadata inspection. */
+export interface ProbeOptions {
+    /** Cancels input I/O and releases probe resources; never destroys caller-owned Readables. */
+    signal?: AbortSignal;
+    /** Total deadline in milliseconds, from 1 through 4294967295; defaults to 15000. */
+    timeoutMs?: number;
+}
 /**
  * One embedded Remedia context. Create instances with `await Remedia.create()` so native
  * observability and optional asynchronous OpenTelemetry exporters initialize on NAPI-RS's runtime.
@@ -15,18 +25,43 @@ export interface RemediaOptions {
 export declare class Remedia extends RemediaEventEmitter<RemediaLifecycleEvents> {
     #private;
     private constructor();
-    /** Create an independent native context using REMEDIA_* and OTEL_* environment settings. */
+    /**
+     * 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>;
+    /**
+     * Inspect a disposable source without creating playback or voice resources. Readables may be partially or fully consumed.
+     * @param source - Encoded input; acquire a fresh source for subsequent playback.
+     * @param options - Cancellation and total deadline; defaults to 15000 ms.
+     * @returns Available stream metadata, with unknown numeric fields null; rejects invalid media, cancellation, timeout, or capacity exhaustion.
+     */
+    probe(source: MediaSource, options?: ProbeOptions): Promise<AudioStreamInfo>;
     /** Number of diagnostic events dropped by either bounded event queue. */
     get droppedDebugEvents(): number;
-    /** Register a structured native diagnostic listener. */
-    /** Create a local decoder session that discards its PCM output. */
+    /**
+     * 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. */
+    /**
+     * 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. */
+    /**
+     * 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. */
+    /**
+     * 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

@@ -1,3 +1,5 @@
+import { createReadableInput, toNativeSource } from './input.js';
+import { toStreamInfo } from './types.js';
 import { RemediaEventEmitter } from './events.js';
 import { NativeRemedia } from '../native.js';
 import { DiscordSession } from './discord.js';
@@ -11,6 +13,7 @@ import { toDiagnosticEvent } from './types.js';
  */
 export class Remedia extends RemediaEventEmitter {
     #native;
+    #probes = new Set();
     #sessions = new Set();
     #discordSessions = new Map();
     #gateway;
@@ -24,16 +27,64 @@ export class Remedia extends RemediaEventEmitter {
             this.emit(RemediaEvent.debug, diagnostic);
         });
     }
-    /** Create an independent native context using REMEDIA_* and OTEL_* environment settings. */
+    /**
+     * 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);
     }
+    /**
+     * Inspect a disposable source without creating playback or voice resources. Readables may be partially or fully consumed.
+     * @param source - Encoded input; acquire a fresh source for subsequent playback.
+     * @param options - Cancellation and total deadline; defaults to 15000 ms.
+     * @returns Available stream metadata, with unknown numeric fields null; rejects invalid media, cancellation, timeout, or capacity exhaustion.
+     */
+    async probe(source, options = {}) {
+        this.#assertOpen();
+        const timeoutMs = options.timeoutMs ?? 15_000;
+        if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 0xffffffff)
+            throw new RangeError('invalid probe timeoutMs');
+        options.signal?.throwIfAborted();
+        const id = this.#native.createProbe();
+        const controller = new AbortController();
+        this.#probes.add(controller);
+        const abort = () => {
+            controller.abort();
+            this.#native.cancelProbe(id);
+        };
+        options.signal?.addEventListener('abort', abort, { once: true });
+        controller.signal.addEventListener('abort', () => this.#native.cancelProbe(id), { once: true });
+        let input;
+        try {
+            const nativeSource = 'stream' in source
+                ? (input = createReadableInput(this.#native, source.stream)).source
+                : toNativeSource(source);
+            const info = await this.#native.probe(id, nativeSource, timeoutMs);
+            controller.signal.throwIfAborted();
+            return toStreamInfo(info);
+        }
+        catch (error) {
+            controller.signal.throwIfAborted();
+            throw error;
+        }
+        finally {
+            options.signal?.removeEventListener('abort', abort);
+            this.#native.cancelProbe(id);
+            await input?.cancel();
+            this.#probes.delete(controller);
+        }
+    }
     /** Number of diagnostic events dropped by either bounded event queue. */
     get droppedDebugEvents() {
         return this.#native.droppedDebugEvents;
     }
-    /** Register a structured native diagnostic listener. */
-    /** Create a local decoder session that discards its PCM output. */
+    /**
+     * 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;
@@ -44,7 +95,12 @@ export class Remedia extends RemediaEventEmitter {
         this.#sessions.add(playback);
         return playback;
     }
-    /** Create a Gateway-managed voice session. Call `connect()` to send OP 4 and join the channel. */
+    /**
+     * 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) {
@@ -61,7 +117,10 @@ export class Remedia extends RemediaEventEmitter {
         this.#discordSessions.set(session.guildId, session);
         return session;
     }
-    /** Forward a raw Discord Gateway packet to the matching in-process voice 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;
@@ -72,11 +131,16 @@ export class Remedia extends RemediaEventEmitter {
             .get(dispatch.guildId)
             ?.receiveGatewayDispatch(dispatch.event, dispatch.data, dispatch.sequence, dispatch.epoch);
     }
-    /** Stop all playbacks, disconnect transports, flush telemetry, and release native resources. */
+    /**
+     * 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;
+        for (const controller of this.#probes)
+            controller.abort();
         const voiceCleanup = await Promise.allSettled([...this.#discordSessions.values()].map((session) => session.dispose()));
         try {
             await Promise.all([...this.#sessions].map((session) => session.dispose()));

package/dist/types.d.ts

@@ -1,48 +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

@@ -1,3 +1,8 @@
+/**
+ * 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,
@@ -10,6 +15,11 @@ export function toStreamInfo(info) {
         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)) {

package/native.d.ts

@@ -102,6 +102,24 @@ export declare class NativeRemedia {
   playbackError(playbackId: string): string | null
   /** Stop and forget a standalone playback session. Voice sessions remain connected. */
   disposePlaybackSession(playbackId: string): Promise<void>
+  /**
+   * Register a cancellable probe; at most eight operations may be outstanding.
+   * @returns A disposable native operation identifier; rejects if closed or at capacity.
+   */
+  createProbe(): string
+  /**
+   * Cancel and release a disposable probe handle. Repeated calls are harmless.
+   * @param id - Operation identifier returned by createProbe.
+   */
+  cancelProbe(id: string): void
+  /**
+   * Inspect encoded input asynchronously without creating playback resources.
+   * @param id - Disposable operation identifier returned by createProbe.
+   * @param source - Encoded file, URL, owned bytes or bounded byte-stream handle.
+   * @param timeoutMs - Positive total deadline in milliseconds.
+   * @returns Available metadata; rejects invalid media, timeout, cancellation or capacity exhaustion.
+   */
+  probe(id: string, source: NativeMediaSource, timeoutMs: number): Promise<NativeStreamInfo>
 }
 
 export interface NativeDiagnosticEvent {