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

package/dist/filters.js

@@ -3,7 +3,12 @@ export class FilterControls {
     #read;
     #replace;
     #clear;
-    /** @internal Constructed by playback session wrappers. */
+    /**
+     * @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;
@@ -13,7 +18,11 @@ export class FilterControls {
     get graph() {
         return this.#read();
     }
-    /** Validate and replace the graph at a safe PCM boundary. */
+    /**
+     * 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');
@@ -24,11 +33,18 @@ export class FilterControls {
             return Promise.resolve();
         return this.#replace(graph);
     }
-    /** Disable the raw filtergraph without changing master volume. */
+    /**
+     * 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

@@ -1,28 +1,52 @@
 /** 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;
-        self_mute: false;
-        self_deaf: false;
+        /** 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. */
+/**
+ * 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;
 }
 /**
@@ -32,14 +56,33 @@ export interface DiscordVoiceGatewayDispatch {
  */
 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. */
-    setVoiceChannel(guildId: string, channelId: string | null): void | Promise<void>;
-    /** Parse only relevant voice dispatches; malformed and unrelated packets are ignored. */
+    /**
+     * 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

@@ -7,6 +7,10 @@ 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;
     }
@@ -18,19 +22,29 @@ export class DiscordGatewayAdapter {
     get epoch() {
         return this.#epoch;
     }
-    /** Request a voice channel join or leave through Gateway OP 4. */
-    setVoiceChannel(guildId, channelId) {
+    /**
+     * 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: false,
-                self_deaf: false,
+                self_mute: selfMute,
+                self_deaf: selfDeaf,
             },
         });
     }
-    /** Parse only relevant voice dispatches; malformed and unrelated packets are ignored. */
+    /**
+     * 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;
@@ -65,6 +79,11 @@ export class DiscordGatewayAdapter {
         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;

package/dist/input.d.ts

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

@@ -1,4 +1,9 @@
 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 };
@@ -6,6 +11,12 @@ export function toNativeSource(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();

package/dist/lifecycle.d.ts

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