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

package/README.md

@@ -88,3 +88,58 @@ service terms.
 Remedia is provided under the [MIT License](./LICENSE) without warranty. Dependency terms remain
 separate; see [third-party notices](./THIRD_PARTY_NOTICES.md), including bundled libopus and
 independently installed FFmpeg.
+
+## Session configuration and channel movement
+
+A client owns one session per guild. Separate clients (including separate bot users) can use the
+same guild and channel with independent playback, transport generations, and events. `userId` is
+the Discord bot user ID, not a Remedia client session ID. Channel IDs are mutable destinations.
+Duplicate guild registration on the same client throws; dispose the old session before replacing it.
+
+```ts
+const session = remedia.createDiscordSession({
+  guildId,
+  channelId,
+  userId,
+  selfDeaf: true,
+  selfMute: false,
+  volume: 0.75,
+  filterGraph: 'bass=gain=3',
+});
+await session.connect();
+await session.move(otherChannelId);
+await session.setSelfDeaf(false);
+await session.setSelfMute(true);
+await session.dispose();
+```
+
+`selfDeaf` defaults to `true` (previously joins always sent `false`); `selfMute` defaults to
+`false`. These flags affect Discord voice state, independently of playback pause and gain.
+Setters retain values before connection and update Gateway OP 4 after joining. Unchanged values
+send nothing. Joins, credential refreshes, and moves preserve the flags. Keep the library-agnostic
+`send(guildId, payload)` and `receive(payload)` Gateway integration wired throughout the session.
+
+Initial `volume` is finite linear gain from 0 through 2, default 1. `filterGraph` is a trusted raw
+FFmpeg audio filtergraph or `null` (default). Invalid gain and empty/non-string graphs are rejected
+at creation; native FFmpeg validates graph syntax when the backend is allocated/configured, before
+playback is allowed. Configuration is serialized with runtime setters and applied before audio
+starts. Both values persist across tracks and transport replacement; existing `setVolume()` and
+`filters.set()`/`clear()` remain available with their existing change events.
+
+`move(channelId): Promise<void>` requests fresh Gateway credentials and replaces the existing voice
+transport without restarting or seeking playback. Decoder input (including one-shot Readables),
+filters, gain, playback generation, and paused state are retained. A move to the current destination
+shares a pending connection or resolves immediately when connected. A newer destination supersedes
+a pending attempt with an `AbortError`; `connect()` shares the latest attempt. Moving while explicit
+disconnection or disposal is underway rejects. `disconnect()`/`dispose()` cancel a pending move.
+`channelId` reports the latest requested destination, including after a failed move.
+
+Intentional moves do not use the automatic recovery retry policy. A failed move reports a failed
+voice state and leaves playback parked with bounded buffering; call `connect()` to retry the
+requested destination, `move()` to choose another, or `disconnect()`/`dispose()` to release it.
+Ordinary transport recovery retains its existing bounded credential-refresh retries. Transport
+replacement itself does not emit playback stopped/completed/failed events.
+
+Gateway mocks verify orchestration and local native tests verify media lifecycles. Real Discord
+channel movement, same-channel multi-bot voice, credential ordering, and self flags still require
+an application integration test with Discord. Forward only each bot's own Gateway dispatch stream.

package/dist/discord.d.ts

@@ -3,6 +3,9 @@ import { PlaybackHooks, type PlayOptions, type SessionLifecycleEvents } from './
 import { FilterControls } from './filters.js';
 import type { MediaSource } from './input.js';
 import type { AudioStreamInfo, PlaybackPosition, PlaybackState, VoiceConnectionState } from './types.js';
+/**
+ * Identity, initial playback configuration, and Gateway voice flags for one guild session. The channel is a mutable destination, while userId identifies the bot.
+ */
 export interface DiscordSessionOptions {
     /** Discord server snowflake as a decimal string. */
     guildId: string;
@@ -10,9 +13,18 @@ export interface DiscordSessionOptions {
     channelId: string;
     /** Bot user snowflake as a decimal string. */
     userId: string;
+    /** Discord Gateway self-deaf state; defaults to true. */
+    selfDeaf?: boolean;
+    /** Discord Gateway self-mute state; defaults to false. */
+    selfMute?: boolean;
+    /** Session master linear gain, finite from 0 through 2; defaults to 1. */
+    volume?: number;
+    /** Trusted raw FFmpeg audio filtergraph; defaults to null. Native syntax validation occurs during backend configuration before playback. */
+    filterGraph?: string | null;
 }
+/** Cancellation and timeout controls for obtaining credentials and establishing a voice transport. */
 export interface DiscordConnectOptions {
-    /** Abort the Gateway request and any pending connection attempt. */
+    /** Optional signal that cancels Gateway negotiation and pending transport setup. */
     signal?: AbortSignal;
     /** Maximum time to receive Gateway credentials and establish voice transport/DAVE. */
     timeoutMs?: number;
@@ -21,49 +33,117 @@ export interface DiscordConnectOptions {
  * One Discord voice session. The caller supplies a Gateway send adapter to `Remedia.create()` and
  * forwards raw dispatch packets to `Remedia.receive()`; this session collects the matching voice
  * credentials and opens the native transport after both dispatches arrive.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
  */
 export declare class DiscordSession<Metadata = unknown> extends RemediaEventEmitter<SessionLifecycleEvents<Metadata>> {
     #private;
+    /** Opaque Remedia session identity used to correlate events; distinct from the Discord bot user ID. */
     readonly sessionId: `${string}-${string}-${string}-${string}-${string}`;
+    /** Discord guild snowflake as a decimal string; unique within the owning client. */
     readonly guildId: string;
-    readonly channelId: string;
+    /** Discord bot user snowflake as a decimal string; separate from Remedia session identity. */
     readonly userId: string;
+    /** Persistent raw FFmpeg filtergraph controls for this session. */
     readonly filters: FilterControls;
+    /** Ordered, awaited local pre-play hooks; listeners are separate from hooks. */
     readonly hooks: PlaybackHooks<Metadata>;
+    /** Current requested voice destination; independent of playback identity. */
+    get channelId(): string;
+    /** Discord Gateway self-deaf state; defaults to true and persists across moves and recovery. */
+    get selfDeaf(): boolean;
+    /** Discord Gateway self-mute state; defaults to false and persists across moves and recovery. */
+    get selfMute(): boolean;
+    /**
+     * Replace only the voice transport. A newer move supersedes a pending move.
+     * @param channelId - Destination Discord voice channel snowflake as a positive decimal string.
+     * @returns Resolves when the requested destination connects; rejects on supersession, cancellation, or connection failure.
+     */
+    move(channelId: string): Promise<void>;
+    /**
+     * Update Discord self-deaf state without rebuilding playback. Unchanged values send nothing.
+     * @param enabled - The requested Discord self-state flag.
+     * @returns Resolves after storing the flag or sending its Gateway update; rejects if the update fails.
+     */
+    setSelfDeaf(enabled: boolean): Promise<void>;
+    /**
+     * Update Discord self-mute state without changing audio gain or playback pause. Unchanged values send nothing.
+     * @param enabled - The requested Discord self-state flag.
+     * @returns Resolves after storing the flag or sending its Gateway update; rejects if the update fails.
+     */
+    setSelfMute(enabled: boolean): Promise<void>;
     /** Current voice transport state. A connected voice WebSocket may temporarily be reconnecting. */
     get connectionState(): VoiceConnectionState;
     /** Most recent Gateway or native transport failure, if any. */
     get connectionError(): string | null;
+    /** 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;
     /** Current native source generation, useful to adapters that preserve event correlation. */
     get generation(): number;
-    /** Set master gain independently of this session's configured filtergraph. */
+    /**
+     * Set master gain independently of this session's configured 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>;
     /**
      * Request a Gateway voice join and wait until both voice dispatches have arrived and the native
      * voice transport has completed its DAVE setup. Repeated calls while connecting share a promise.
+     * @param options - Optional cancellation signal and positive timeout in milliseconds; defaults to 45000.
+     * @returns Resolves when connected; rejects on timeout, cancellation, session loss, or transport failure.
      */
     connect(options?: DiscordConnectOptions): Promise<void>;
     /**
      * Begin playback on this connected voice session. The decoder and Opus encoder remain in core;
      * this object only associates their output with the native Discord transport.
+     * @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>;
     /**
      * Leave the Discord channel through Gateway OP 4 and close the native transport. This does not
      * dispose the wrapper, so `connect()` can be called again with fresh Gateway dispatches.
+     * @returns Resolves after cleanup; concurrent disconnects share cleanup work.
      */
     disconnect(): Promise<void>;
-    /** Disconnect and unregister this session. */
+    /**
+     * Disconnect and unregister this session.
+     * @returns Resolves after disposal; rejects if resource cleanup fails.
+     */
     dispose(): Promise<void>;
 }

package/dist/discord.js

@@ -9,16 +9,26 @@ const DEFAULT_CONNECT_TIMEOUT_MS = 45_000;
  * One Discord voice session. The caller supplies a Gateway send adapter to `Remedia.create()` and
  * forwards raw dispatch packets to `Remedia.receive()`; this session collects the matching voice
  * credentials and opens the native transport after both dispatches arrive.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
  */
 export class DiscordSession extends RemediaEventEmitter {
+    /** Opaque Remedia session identity used to correlate events; distinct from the Discord bot user ID. */
     sessionId = randomUUID();
+    /** Discord guild snowflake as a decimal string; unique within the owning client. */
     guildId;
-    channelId;
+    #channelId;
+    #selfDeaf;
+    #selfMute;
+    #closing = false;
+    #disposeWork;
+    /** Discord bot user snowflake as a decimal string; separate from Remedia session identity. */
     userId;
     #native;
     #gateway;
     #onDispose;
+    /** Persistent raw FFmpeg filtergraph controls for this session. */
     filters;
+    /** Ordered, awaited local pre-play hooks; listeners are separate from hooks. */
     hooks = new PlaybackHooks();
     #playback;
     #playbackSubscriptions;
@@ -43,17 +53,113 @@ export class DiscordSession extends RemediaEventEmitter {
     #volume = 1;
     #configurationWork = Promise.resolve();
     #nativeStateTimer;
-    /** @internal Constructed by `Remedia.createDiscordSession()`. */
+    /**
+     * @internal Constructed by `Remedia.createDiscordSession()`.
+     * @param native - Owning native engine instance; its resources must outlive this wrapper.
+     * @param gateway - Adapter for the application-owned Discord Gateway connection.
+     * @param options - Configuration and lifecycle options for this operation.
+     * @param onDispose - Callback invoked when this wrapper releases its owning registration.
+     */
     constructor(native, gateway, options, onDispose) {
         super();
         this.guildId = validateSnowflake('guildId', options.guildId);
-        this.channelId = validateSnowflake('channelId', options.channelId);
+        this.#channelId = validateSnowflake('channelId', options.channelId);
         this.userId = validateSnowflake('userId', options.userId);
+        validateVolume(options.volume ?? 1);
+        if (options.filterGraph !== undefined &&
+            options.filterGraph !== null &&
+            (typeof options.filterGraph !== 'string' || !options.filterGraph.trim()))
+            throw new TypeError('filterGraph must be a non-empty string or null');
+        for (const value of [options.selfDeaf, options.selfMute]) {
+            if (value !== undefined && typeof value !== 'boolean')
+                throw new TypeError('voice flags must be boolean');
+        }
+        this.#volume = options.volume ?? 1;
+        this.#filterGraph = options.filterGraph ?? null;
+        this.#selfDeaf = options.selfDeaf ?? true;
+        this.#selfMute = options.selfMute ?? false;
         this.#native = native;
         this.#gateway = gateway;
         this.#onDispose = onDispose;
         this.filters = new FilterControls(() => this.#filterGraph, (graph) => this.#replaceFilterGraph(graph), () => this.#replaceFilterGraph(null));
     }
+    /** Current requested voice destination; independent of playback identity. */
+    get channelId() {
+        return this.#channelId;
+    }
+    /** Discord Gateway self-deaf state; defaults to true and persists across moves and recovery. */
+    get selfDeaf() {
+        return this.#selfDeaf;
+    }
+    /** Discord Gateway self-mute state; defaults to false and persists across moves and recovery. */
+    get selfMute() {
+        return this.#selfMute;
+    }
+    /**
+     * Replace only the voice transport. A newer move supersedes a pending move.
+     * @param channelId - Destination Discord voice channel snowflake as a positive decimal string.
+     * @returns Resolves when the requested destination connects; rejects on supersession, cancellation, or connection failure.
+     */
+    move(channelId) {
+        this.#assertNotDisposed();
+        validateSnowflake('channelId', channelId);
+        if (this.#connectionState === 'disconnecting')
+            return Promise.reject(new Error('Discord session is disconnecting'));
+        if (channelId === this.channelId)
+            return this.connect();
+        const previous = this.#attempt;
+        if (previous) {
+            this.#finishAttempt(previous);
+            previous.reject(abortError('Discord voice connection was superseded by move()'));
+        }
+        this.#channelId = channelId;
+        if (!this.#nativeSession)
+            return this.connect();
+        const attempt = this.#createAttempt(DEFAULT_CONNECT_TIMEOUT_MS, undefined, true);
+        attempt.moving = true;
+        this.#attempt = attempt;
+        this.#voiceState = undefined;
+        this.#voiceServer = undefined;
+        this.#voiceServerUnavailable = false;
+        this.#setConnectionState('connecting');
+        this.#suspendCurrentNativeTransport(attempt);
+        this.#requestGatewayJoin(attempt);
+        return attempt.promise;
+    }
+    /**
+     * Update Discord self-deaf state without rebuilding playback. Unchanged values send nothing.
+     * @param enabled - The requested Discord self-state flag.
+     * @returns Resolves after storing the flag or sending its Gateway update; rejects if the update fails.
+     */
+    setSelfDeaf(enabled) {
+        return this.#setVoiceFlag('deaf', enabled);
+    }
+    /**
+     * Update Discord self-mute state without changing audio gain or playback pause. Unchanged values send nothing.
+     * @param enabled - The requested Discord self-state flag.
+     * @returns Resolves after storing the flag or sending its Gateway update; rejects if the update fails.
+     */
+    setSelfMute(enabled) {
+        return this.#setVoiceFlag('mute', enabled);
+    }
+    async #setVoiceFlag(flag, enabled) {
+        this.#assertNotDisposed();
+        if (typeof enabled !== 'boolean')
+            throw new TypeError('voice flag must be boolean');
+        await this.#serializeConfiguration(async () => {
+            this.#assertNotDisposed();
+            if (this.#connectionState === 'disconnecting')
+                throw new Error('Discord session is disconnecting');
+            if ((flag === 'deaf' ? this.#selfDeaf : this.#selfMute) === enabled)
+                return;
+            if (this.#joinRequested)
+                await this.#gateway.setVoiceChannel(this.guildId, this.channelId, flag === 'deaf' ? enabled : this.#selfDeaf, flag === 'mute' ? enabled : this.#selfMute);
+            if (flag === 'deaf')
+                this.#selfDeaf = enabled;
+            else
+                this.#selfMute = enabled;
+        });
+    }
     /** Current voice transport state. A connected voice WebSocket may temporarily be reconnecting. */
     get connectionState() {
         if (this.#disposed)
@@ -81,11 +187,13 @@ export class DiscordSession extends RemediaEventEmitter {
             return null;
         }
     }
+    /** Current playback lifecycle state. */
     get state() {
         if (this.#playback)
             return this.#playback.state;
         return this.connectionState === 'failed' ? 'failed' : 'idle';
     }
+    /** Latest source and output timeline measurements in milliseconds. */
     get position() {
         return (this.#playback?.position ?? {
             mediaMs: null,
@@ -94,9 +202,11 @@ export class DiscordSession extends RemediaEventEmitter {
             playedMs: null,
         });
     }
+    /** Source duration in milliseconds, or null when unknown. */
     get durationMs() {
         return this.#playback?.durationMs ?? null;
     }
+    /** Most recent playback or voice failure message, or null when no error is available. */
     get error() {
         return this.#playback?.error ?? this.connectionError;
     }
@@ -108,7 +218,12 @@ export class DiscordSession extends RemediaEventEmitter {
     get generation() {
         return this.#playback?.currentGeneration ?? this.#playbackGeneration;
     }
-    /** Set master gain independently of this session's configured filtergraph. */
+    /**
+     * Set master gain independently of this session's configured 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.#assertNotDisposed();
         validateVolume(gain);
@@ -138,6 +253,8 @@ export class DiscordSession extends RemediaEventEmitter {
     /**
      * Request a Gateway voice join and wait until both voice dispatches have arrived and the native
      * voice transport has completed its DAVE setup. Repeated calls while connecting share a promise.
+     * @param options - Optional cancellation signal and positive timeout in milliseconds; defaults to 45000.
+     * @returns Resolves when connected; rejects on timeout, cancellation, session loss, or transport failure.
      */
     connect(options = {}) {
         this.#assertNotDisposed();
@@ -176,8 +293,12 @@ export class DiscordSession extends RemediaEventEmitter {
     /**
      * Begin playback on this connected voice session. The decoder and Opus encoder remain in core;
      * this object only associates their output with the native Discord transport.
+     * @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, options = {}) {
+    async play(source, options = {}) {
+        await this.#configurationWork;
         return this.#requirePlayback()
             .play(source, options)
             .then((info) => {
@@ -185,24 +306,46 @@ export class DiscordSession extends RemediaEventEmitter {
             return info;
         });
     }
+    /**
+     * Pause the current playback without replacing its decoder or source generation.
+     * @returns Resolves when the backend accepts the pause request.
+     */
     pause() {
         return this.#requireExistingPlayback().pause();
     }
+    /**
+     * Resume paused playback on its existing source generation.
+     * @returns Resolves when the backend accepts the resume request.
+     */
     resume() {
         return this.#requireExistingPlayback().resume();
     }
+    /**
+     * 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) {
         return this.#requireExistingPlayback().seek(positionMs);
     }
+    /**
+     * Stop the active playback generation and release its input without leaving the voice channel.
+     * @returns Resolves after the backend stops the active source.
+     */
     stop() {
         return this.#requireExistingPlayback().stop();
     }
+    /**
+     * Wait for the current playback generation to reach a terminal state.
+     * @returns The terminal playback state for the generation captured by this wait.
+     */
     wait() {
         return this.#requireExistingPlayback().wait();
     }
     /**
      * Leave the Discord channel through Gateway OP 4 and close the native transport. This does not
      * dispose the wrapper, so `connect()` can be called again with fresh Gateway dispatches.
+     * @returns Resolves after cleanup; concurrent disconnects share cleanup work.
      */
     disconnect() {
         if (this.#disposed)
@@ -215,10 +358,20 @@ export class DiscordSession extends RemediaEventEmitter {
         });
         return this.#disconnectPromise;
     }
-    /** Disconnect and unregister this session. */
-    async dispose() {
+    /**
+     * Disconnect and unregister this session.
+     * @returns Resolves after disposal; rejects if resource cleanup fails.
+     */
+    dispose() {
+        if (this.#disposeWork)
+            return this.#disposeWork;
+        this.#disposeWork = this.#dispose();
+        return this.#disposeWork;
+    }
+    async #dispose() {
         if (this.#disposed)
             return;
+        this.#closing = true;
         try {
             await this.disconnect();
         }
@@ -233,7 +386,13 @@ export class DiscordSession extends RemediaEventEmitter {
             this.#onDispose();
         }
     }
-    /** @internal Routes a parsed raw Gateway dispatch to this guild's active voice lifecycle. */
+    /**
+     * @internal Routes a parsed raw Gateway dispatch to this guild's active voice lifecycle.
+     * @param event - Event name identifying the typed notification or Gateway voice dispatch.
+     * @param data - Validated guild-scoped Gateway dispatch data.
+     * @param sequence - Gateway dispatch sequence, when supplied by the host application.
+     * @param epoch - Gateway READY epoch used to reset stale-sequence tracking.
+     */
     receiveGatewayDispatch(event, data, sequence, epoch) {
         if (this.#disposed || data.guild_id !== this.guildId)
             return;
@@ -313,6 +472,8 @@ export class DiscordSession extends RemediaEventEmitter {
             return;
         }
         if (data.channel_id === null) {
+            if (this.#attempt?.moving)
+                return;
             if (this.#connectionState === 'connected' || this.#connectionState === 'reconnecting') {
                 this.#handleGatewayDisconnect();
             }
@@ -395,6 +556,7 @@ export class DiscordSession extends RemediaEventEmitter {
             resolve = res;
             reject = rej;
         });
+        void promise.catch(() => { });
         let attempt;
         const onTimeout = () => {
             const error = new Error(`Discord voice connection timed out after ${timeoutMs} ms`);
@@ -426,7 +588,7 @@ export class DiscordSession extends RemediaEventEmitter {
     #requestGatewayJoin(attempt) {
         let sendPromise;
         try {
-            sendPromise = this.#gateway.setVoiceChannel(this.guildId, this.channelId);
+            sendPromise = this.#gateway.setVoiceChannel(this.guildId, this.channelId, this.#selfDeaf, this.#selfMute);
         }
         catch (error) {
             if (!this.#retryCredentialRefresh(attempt, asError(error))) {
@@ -645,7 +807,10 @@ export class DiscordSession extends RemediaEventEmitter {
             this.#voiceServer = undefined;
             this.#voiceServerUnavailable = false;
         }
-        if (attempt?.internal && this.#nativeSession) {
+        if (attempt?.moving) {
+            // Keep playback suspended for an explicit retry or disconnect.
+        }
+        else if (attempt?.internal && this.#nativeSession) {
             try {
                 this.#native.failVoiceRecovery(this.#nativeSession.voiceId, 'Discord voice recovery failed');
             }
@@ -673,6 +838,8 @@ export class DiscordSession extends RemediaEventEmitter {
     #failAttempt(attempt, error, leaveGateway) {
         if (this.#attempt !== attempt)
             return;
+        if (attempt.moving)
+            this.#suspendCurrentNativeTransport(attempt);
         this.#generation += 1;
         this.#finishAttempt(attempt);
         this.#connectionError = error.name === 'AbortError' ? undefined : error.message;
@@ -683,7 +850,10 @@ export class DiscordSession extends RemediaEventEmitter {
             this.#voiceServer = undefined;
             this.#voiceServerUnavailable = false;
         }
-        if (attempt.internal && this.#nativeSession) {
+        if (attempt.moving) {
+            // Keep playback suspended for an explicit retry or disconnect.
+        }
+        else if (attempt.internal && this.#nativeSession) {
             try {
                 this.#native.failVoiceRecovery(this.#nativeSession.voiceId, 'Discord voice recovery timed out');
             }
@@ -702,6 +872,7 @@ export class DiscordSession extends RemediaEventEmitter {
     }
     #retryCredentialRefresh(attempt, _error) {
         if (!attempt.internal ||
+            attempt.moving ||
             this.#attempt !== attempt ||
             attempt.settled ||
             attempt.retryCount >= 2 ||
@@ -864,7 +1035,7 @@ export class DiscordSession extends RemediaEventEmitter {
         return result;
     }
     #assertNotDisposed() {
-        if (this.#disposed)
+        if (this.#disposed || this.#closing)
             throw new Error('Discord voice session has been disposed');
     }
     #setConnectionState(state) {

package/dist/events.d.ts

@@ -4,8 +4,18 @@ type EventMap<Events> = {
 };
 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. */
+/**
+ * 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

@@ -1,6 +1,16 @@
 import { EventEmitter } from 'node:events';
-/** EventEmitter-compatible base that isolates synchronous listener failures from engine work. */
+/**
+ * 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);

package/dist/filters.d.ts

@@ -3,9 +3,20 @@ 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. */
+    /**
+     * 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. */
+    /**
+     * 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;