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

package/dist/discord.js

@@ -0,0 +1,1168 @@
+import { randomUUID } from 'node:crypto';
+import { RemediaEventEmitter } from './events.js';
+import { isSnowflake } from './gateway.js';
+import { PlaybackHooks, PlaybackSessionEvents as PlaybackEvent, VoiceSessionEvents as VoiceEvent, } from './lifecycle.js';
+import { PlaybackSession } from './playback.js';
+import { FilterControls, validateVolume } from './filters.js';
+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;
+    #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;
+    #nativeSession;
+    #attempt;
+    #voiceState;
+    #voiceServer;
+    #voiceServerUnavailable = false;
+    #nativeTransportGeneration = 0;
+    #gatewayEpoch;
+    #lastGatewaySequence;
+    #nativeWork = Promise.resolve();
+    #backgroundCleanup = Promise.resolve();
+    #disconnectPromise;
+    #connectionState = 'disconnected';
+    #connectionError;
+    #generation = 0;
+    #playbackGeneration = 0;
+    #joinRequested = false;
+    #disposed = false;
+    #filterGraph = null;
+    #volume = 1;
+    #configurationWork = Promise.resolve();
+    #nativeStateTimer;
+    /**
+     * @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.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)
+            return 'disconnected';
+        if (this.#connectionState === 'connected' && this.#nativeSession) {
+            try {
+                return this.#native.voiceState(this.#nativeSession.voiceId);
+            }
+            catch {
+                return this.#connectionState;
+            }
+        }
+        return this.#connectionState;
+    }
+    /** Most recent Gateway or native transport failure, if any. */
+    get connectionError() {
+        if (this.#connectionError)
+            return this.#connectionError;
+        if (!this.#nativeSession)
+            return null;
+        try {
+            return this.#native.voiceError(this.#nativeSession.voiceId) ?? null;
+        }
+        catch {
+            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,
+            mediaPositionAccuracy: null,
+            submittedMs: 0,
+            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;
+    }
+    /** Current normalized linear master gain, from 0.0 (mute) through 2.0. */
+    get volume() {
+        return this.#volume;
+    }
+    /** Current native source generation, useful to adapters that preserve event correlation. */
+    get generation() {
+        return this.#playback?.currentGeneration ?? this.#playbackGeneration;
+    }
+    /**
+     * 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);
+        await this.#serializeConfiguration(async () => {
+            if (this.#connectionState === 'disconnecting') {
+                throw new Error('Discord voice session is disconnecting');
+            }
+            const previousVolume = this.#volume;
+            if (previousVolume === gain)
+                return;
+            if (this.#playback) {
+                await this.#playback.setVolume(gain);
+            }
+            else {
+                this.emit(PlaybackEvent.volumeChanged, {
+                    sessionId: this.sessionId,
+                    guildId: this.guildId,
+                    nodeId: null,
+                    generation: this.#playbackGeneration,
+                    previousVolume,
+                    volume: gain,
+                });
+            }
+            this.#volume = gain;
+        });
+    }
+    /**
+     * 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();
+        if (this.#attempt)
+            return this.#attempt.promise;
+        const currentState = this.connectionState;
+        if (currentState === 'connected' || currentState === 'reconnecting')
+            return Promise.resolve();
+        if (this.#connectionState === 'disconnecting') {
+            return Promise.reject(new Error('Discord voice session is disconnecting'));
+        }
+        if (options.signal?.aborted) {
+            return Promise.reject(abortError('Discord voice connection was cancelled'));
+        }
+        const timeoutMs = options.timeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            return Promise.reject(new RangeError('timeoutMs must be a positive finite number'));
+        }
+        const attempt = this.#createAttempt(timeoutMs, options.signal, false);
+        this.#attempt = attempt;
+        this.#voiceState = undefined;
+        this.#voiceServer = undefined;
+        this.#voiceServerUnavailable = false;
+        this.#connectionError = undefined;
+        this.#setConnectionState('connecting');
+        this.#joinRequested = true;
+        if (attempt.signal) {
+            attempt.abortListener = () => {
+                this.#failAttempt(attempt, abortError('Discord voice connection was cancelled'), true);
+            };
+            attempt.signal.addEventListener('abort', attempt.abortListener, { once: true });
+        }
+        this.#requestGatewayJoin(attempt);
+        return attempt.promise;
+    }
+    /**
+     * 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.
+     */
+    async play(source, options = {}) {
+        await this.#configurationWork;
+        return this.#requirePlayback()
+            .play(source, options)
+            .then((info) => {
+            this.#playbackGeneration = this.#playback?.currentGeneration ?? this.#playbackGeneration;
+            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)
+            return Promise.resolve();
+        if (this.#disconnectPromise)
+            return this.#disconnectPromise;
+        const disconnect = this.#disconnect();
+        this.#disconnectPromise = disconnect.finally(() => {
+            this.#disconnectPromise = undefined;
+        });
+        return this.#disconnectPromise;
+    }
+    /**
+     * 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();
+        }
+        finally {
+            this.#disposed = true;
+            this.emit(PlaybackEvent.sessionDisposed, {
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+                nodeId: null,
+                generation: this.#playbackGeneration,
+            });
+            this.#onDispose();
+        }
+    }
+    /**
+     * @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;
+        if (epoch !== undefined && epoch !== this.#gatewayEpoch) {
+            this.#gatewayEpoch = epoch;
+            this.#lastGatewaySequence = undefined;
+            if (this.#attempt)
+                this.#attempt.sequenceFloor = undefined;
+        }
+        if (sequence !== undefined &&
+            this.#lastGatewaySequence !== undefined &&
+            sequence <= this.#lastGatewaySequence) {
+            return;
+        }
+        if (sequence !== undefined)
+            this.#lastGatewaySequence = sequence;
+        const attempt = this.#attempt;
+        if (attempt &&
+            sequence !== undefined &&
+            attempt.sequenceFloor !== undefined &&
+            sequence <= attempt.sequenceFloor) {
+            return;
+        }
+        if (event === 'VOICE_STATE_UPDATE') {
+            this.#receiveVoiceState(data);
+        }
+        else if (event === 'VOICE_SERVER_UPDATE') {
+            this.#receiveVoiceServer(data);
+        }
+    }
+    async #disconnect() {
+        const attempt = this.#attempt;
+        const shouldLeaveGateway = this.#joinRequested || this.#nativeSession !== undefined;
+        this.#joinRequested = false;
+        this.#generation += 1;
+        this.#stopNativeStateMonitor();
+        this.#voiceServerUnavailable = false;
+        this.#invalidateNativeTransport();
+        this.#setConnectionState('disconnecting');
+        this.#voiceState = undefined;
+        this.#voiceServer = undefined;
+        if (attempt) {
+            this.#finishAttempt(attempt);
+            attempt.reject(abortError('Discord voice connection was cancelled by disconnect()'));
+        }
+        const errors = [];
+        if (shouldLeaveGateway) {
+            try {
+                await this.#gateway.setVoiceChannel(this.guildId, null);
+            }
+            catch (error) {
+                errors.push(asError(error));
+            }
+        }
+        // A native connection attempt cannot be interrupted inside FFmpeg/transport setup. Its own
+        // network operations have finite timeouts; wait for its generation check to dispose late
+        // results before returning from disconnect.
+        await this.#nativeWork;
+        await this.#backgroundCleanup;
+        try {
+            await this.#closeCurrentNativeSession();
+        }
+        catch (error) {
+            errors.push(asError(error));
+        }
+        this.#joinRequested = false;
+        this.#setConnectionState('disconnected');
+        if (errors.length > 0) {
+            this.#connectionError = errors.map((error) => error.message).join('; ');
+            throw new AggregateError(errors, 'Discord voice disconnection failed');
+        }
+    }
+    #receiveVoiceState(data) {
+        if (data.user_id !== this.userId ||
+            !this.#joinRequested ||
+            this.#connectionState === 'disconnecting') {
+            return;
+        }
+        if (data.channel_id === null) {
+            if (this.#attempt?.moving)
+                return;
+            if (this.#connectionState === 'connected' || this.#connectionState === 'reconnecting') {
+                this.#handleGatewayDisconnect();
+            }
+            // A null channel can be a delayed state from a previous leave while a new join is pending.
+            return;
+        }
+        if (data.channel_id !== this.channelId || typeof data.session_id !== 'string')
+            return;
+        if (data.session_id.length === 0)
+            return;
+        const previousSessionId = this.#voiceState?.sessionId;
+        if (previousSessionId === data.session_id)
+            return;
+        const refreshRequired = !this.#attempt &&
+            (this.#connectionState === 'connected' ||
+                this.#connectionState === 'reconnecting' ||
+                this.#connectionState === 'disconnected' ||
+                this.#connectionState === 'failed');
+        this.#voiceState = { sessionId: data.session_id };
+        if (previousSessionId !== undefined) {
+            this.#voiceServer = undefined;
+            this.#voiceServerUnavailable = true;
+        }
+        if (refreshRequired) {
+            this.#beginCredentialRefresh();
+            return;
+        }
+        this.#credentialsChanged();
+    }
+    #receiveVoiceServer(data) {
+        if (!this.#joinRequested || this.#connectionState === 'disconnecting')
+            return;
+        if (data.endpoint === null) {
+            this.#voiceServerUnavailable = true;
+            if (!this.#attempt &&
+                ['connected', 'reconnecting', 'disconnected', 'failed'].includes(this.#connectionState)) {
+                this.#beginCredentialRefresh();
+            }
+            else if (this.#attempt && !this.#attempt.internal) {
+                this.#failGateway(new Error('Discord did not provide a voice server endpoint'));
+            }
+            return;
+        }
+        if (typeof data.token !== 'string' || typeof data.endpoint !== 'string')
+            return;
+        if (data.token.length === 0 || data.endpoint.length === 0)
+            return;
+        const sameServer = this.#voiceServer?.token === data.token && this.#voiceServer.endpoint === data.endpoint;
+        const currentState = this.connectionState;
+        const refreshRequired = !this.#attempt &&
+            currentState !== 'connecting' &&
+            currentState !== 'negotiatingDave' &&
+            (this.#voiceServerUnavailable || currentState !== 'connected' || !sameServer);
+        this.#voiceServerUnavailable = false;
+        if (sameServer && !refreshRequired) {
+            this.#credentialsChanged();
+            return;
+        }
+        this.#voiceServer = { token: data.token, endpoint: data.endpoint };
+        if (refreshRequired) {
+            this.#beginCredentialRefresh();
+            return;
+        }
+        this.#credentialsChanged();
+    }
+    #credentialsChanged() {
+        const attempt = this.#attempt;
+        if (!attempt ||
+            !this.#voiceState ||
+            !this.#voiceServer ||
+            this.#voiceServerUnavailable ||
+            !attempt.requestSent)
+            return;
+        this.#tryStartNativeConnection(attempt);
+    }
+    #createAttempt(timeoutMs, signal, internal) {
+        let resolve;
+        let reject;
+        const promise = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
+        });
+        void promise.catch(() => { });
+        let attempt;
+        const onTimeout = () => {
+            const error = new Error(`Discord voice connection timed out after ${timeoutMs} ms`);
+            if (this.#retryCredentialRefresh(attempt, error)) {
+                attempt.timer = setTimeout(onTimeout, timeoutMs);
+            }
+            else {
+                this.#failAttempt(attempt, error, true);
+            }
+        };
+        this.#generation += 1;
+        attempt = {
+            generation: this.#generation,
+            sequenceFloor: this.#gateway.lastSequence,
+            promise,
+            resolve,
+            reject,
+            timer: setTimeout(onTimeout, timeoutMs),
+            signal,
+            abortListener: undefined,
+            requestSent: false,
+            settled: false,
+            internal,
+            retryCount: 0,
+            transportGeneration: undefined,
+        };
+        return attempt;
+    }
+    #requestGatewayJoin(attempt) {
+        let sendPromise;
+        try {
+            sendPromise = this.#gateway.setVoiceChannel(this.guildId, this.channelId, this.#selfDeaf, this.#selfMute);
+        }
+        catch (error) {
+            if (!this.#retryCredentialRefresh(attempt, asError(error))) {
+                this.#failAttempt(attempt, asError(error), true);
+            }
+            return;
+        }
+        void Promise.resolve(sendPromise)
+            .then(() => {
+            if (this.#attempt !== attempt)
+                return;
+            attempt.requestSent = true;
+            this.#tryStartNativeConnection(attempt);
+        })
+            .catch((error) => {
+            if (!this.#retryCredentialRefresh(attempt, asError(error))) {
+                this.#failAttempt(attempt, asError(error), true);
+            }
+        });
+    }
+    #beginCredentialRefresh(requireFreshServer = false) {
+        if (this.#attempt || this.#disposed)
+            return;
+        if (requireFreshServer) {
+            this.#voiceServer = undefined;
+            this.#voiceServerUnavailable = true;
+        }
+        const attempt = this.#createAttempt(DEFAULT_CONNECT_TIMEOUT_MS, undefined, true);
+        // This internal attempt may have no direct caller waiting on its Promise.
+        void attempt.promise.catch(() => { });
+        this.#attempt = attempt;
+        this.#setConnectionState('reconnecting');
+        this.#connectionError = undefined;
+        this.#joinRequested = true;
+        this.#suspendCurrentNativeTransport(attempt);
+        this.#requestGatewayJoin(attempt);
+    }
+    #tryStartNativeConnection(attempt) {
+        if (this.#attempt !== attempt ||
+            !attempt.requestSent ||
+            !this.#voiceState ||
+            !this.#voiceServer ||
+            this.#voiceServerUnavailable) {
+            return;
+        }
+        this.#scheduleNativeConnection(attempt);
+    }
+    #scheduleNativeConnection(attempt) {
+        if (!this.#voiceState || !this.#voiceServer)
+            return;
+        const credentials = {
+            ...this.#voiceState,
+            ...this.#voiceServer,
+        };
+        const generation = ++this.#generation;
+        if (attempt)
+            attempt.generation = generation;
+        const existing = this.#nativeSession;
+        const transportGeneration = existing ? this.#nextNativeTransportGeneration() : undefined;
+        if (existing && transportGeneration !== undefined) {
+            if (attempt)
+                attempt.transportGeneration = transportGeneration;
+            try {
+                this.#native.invalidateVoiceRecovery(existing.voiceId, transportGeneration);
+            }
+            catch (error) {
+                this.#nativeConnectionFailed(asError(error), generation, attempt);
+                return;
+            }
+        }
+        this.#setConnectionState(this.#nativeSession ? 'reconnecting' : 'negotiatingDave');
+        const work = this.#nativeWork.then(async () => {
+            if (!this.#isCurrent(generation, attempt))
+                return;
+            await this.#backgroundCleanup;
+            if (!this.#isCurrent(generation, attempt))
+                return;
+            const options = {
+                guildId: this.guildId,
+                channelId: this.channelId,
+                userId: this.userId,
+                sessionId: credentials.sessionId,
+                token: credentials.token,
+                endpoint: credentials.endpoint,
+            };
+            let playback;
+            if (existing) {
+                if (transportGeneration === undefined) {
+                    throw new Error('Discord voice replacement generation is unavailable');
+                }
+                await this.#native.replaceVoice(existing.voiceId, transportGeneration, options);
+                if (!this.#isCurrent(generation, attempt))
+                    return;
+                playback = this.#playback;
+            }
+            else {
+                const nativeSession = await this.#native.connectVoice(options);
+                if (!this.#isCurrent(generation, attempt)) {
+                    await this.#releaseNativeSession(nativeSession, undefined);
+                    return;
+                }
+                this.#nativeSession = nativeSession;
+                const createdPlayback = new PlaybackSession(this.#native, nativeSession.playbackId, undefined, this.guildId, this.hooks);
+                playback = createdPlayback;
+                this.#playback = createdPlayback;
+                await this.#serializeConfiguration(async () => {
+                    if (this.#playback !== createdPlayback)
+                        return;
+                    if (this.#filterGraph !== null)
+                        await createdPlayback.filters.set(this.#filterGraph);
+                    if (this.#volume !== 1)
+                        await createdPlayback.setVolume(this.#volume);
+                });
+                if (!this.#isCurrent(generation, attempt))
+                    return;
+                this.#forwardPlaybackEvents(createdPlayback);
+            }
+            this.#connectionError = undefined;
+            this.#setConnectionState('connected');
+            this.#voiceState = { sessionId: credentials.sessionId };
+            this.#voiceServer = { token: credentials.token, endpoint: credentials.endpoint };
+            this.#voiceServerUnavailable = false;
+            this.#startNativeStateMonitor();
+            this.#playbackGeneration = playback?.currentGeneration ?? this.#playbackGeneration;
+            if (attempt && this.#attempt === attempt) {
+                this.#finishAttempt(attempt);
+                attempt.resolve();
+            }
+        });
+        this.#nativeWork = work.catch((error) => {
+            this.#nativeConnectionFailed(asError(error), generation, attempt);
+        });
+    }
+    #suspendCurrentNativeTransport(attempt) {
+        const nativeSession = this.#nativeSession;
+        if (!nativeSession)
+            return;
+        const generation = this.#nextNativeTransportGeneration();
+        attempt.transportGeneration = generation;
+        try {
+            this.#native.invalidateVoiceRecovery(nativeSession.voiceId, generation);
+        }
+        catch (error) {
+            this.#nativeConnectionFailed(asError(error), attempt.generation, attempt);
+            return;
+        }
+        const work = this.#nativeWork.then(() => this.#native.suspendVoice(nativeSession.voiceId, generation));
+        this.#nativeWork = work.catch((error) => {
+            if (this.#isCurrent(attempt.generation, attempt)) {
+                this.#connectionError = asError(error).message;
+            }
+        });
+    }
+    #startNativeStateMonitor() {
+        this.#stopNativeStateMonitor();
+        this.#nativeStateTimer = setInterval(() => {
+            if (this.#disposed || !this.#nativeSession || this.#attempt || !this.#joinRequested)
+                return;
+            try {
+                const state = this.#native.voiceState(this.#nativeSession.voiceId);
+                if (state === 'failed' || state === 'disconnected') {
+                    this.#beginCredentialRefresh(true);
+                }
+            }
+            catch {
+                // Explicit close/disposal owns cleanup if the native entry disappeared.
+            }
+        }, 250);
+        this.#nativeStateTimer.unref?.();
+    }
+    #stopNativeStateMonitor() {
+        if (!this.#nativeStateTimer)
+            return;
+        clearInterval(this.#nativeStateTimer);
+        this.#nativeStateTimer = undefined;
+    }
+    #invalidateNativeTransport() {
+        const nativeSession = this.#nativeSession;
+        if (!nativeSession)
+            return;
+        try {
+            this.#native.invalidateVoiceRecovery(nativeSession.voiceId, this.#nextNativeTransportGeneration());
+        }
+        catch {
+            // Explicit disconnect and disposal remain authoritative while native cleanup runs.
+        }
+    }
+    #nextNativeTransportGeneration() {
+        this.#nativeTransportGeneration =
+            this.#nativeTransportGeneration >= 0xffff_fffe ? 1 : this.#nativeTransportGeneration + 1;
+        return this.#nativeTransportGeneration;
+    }
+    #isCurrent(generation, attempt) {
+        return (!this.#disposed &&
+            this.#generation === generation &&
+            (attempt ? this.#attempt === attempt : this.#attempt === undefined));
+    }
+    #nativeConnectionFailed(error, generation, attempt) {
+        if (!this.#isCurrent(generation, attempt))
+            return;
+        if (attempt && this.#retryCredentialRefresh(attempt, error))
+            return;
+        this.#connectionError = error.message;
+        this.#stopNativeStateMonitor();
+        this.#setConnectionState('failed');
+        const pending = this.#attempt;
+        if (pending) {
+            this.#finishAttempt(pending);
+            pending.reject(error);
+        }
+        const shouldLeaveGateway = this.#joinRequested;
+        this.#joinRequested = false;
+        this.#generation += 1;
+        if (!attempt?.internal) {
+            this.#voiceState = undefined;
+            this.#voiceServer = undefined;
+            this.#voiceServerUnavailable = false;
+        }
+        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');
+            }
+            catch {
+                // A concurrently disposed native instance already released the router.
+            }
+        }
+        else {
+            this.#queueCurrentNativeCleanup();
+        }
+        if (shouldLeaveGateway)
+            void this.#sendGatewayLeave();
+    }
+    #failGateway(error) {
+        const attempt = this.#attempt;
+        if (attempt) {
+            if (!this.#retryCredentialRefresh(attempt, error))
+                this.#failAttempt(attempt, error, true);
+            return;
+        }
+        if (this.#connectionState === 'connected' || this.#connectionState === 'reconnecting') {
+            this.#nativeConnectionFailed(error, this.#generation, undefined);
+        }
+    }
+    #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;
+        this.#stopNativeStateMonitor();
+        this.#setConnectionState(error.name === 'AbortError' ? 'disconnected' : 'failed');
+        if (!attempt.internal) {
+            this.#voiceState = undefined;
+            this.#voiceServer = undefined;
+            this.#voiceServerUnavailable = false;
+        }
+        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');
+            }
+            catch {
+                // The owning Remedia instance may already be closing.
+            }
+        }
+        else {
+            this.#queueCurrentNativeCleanup();
+        }
+        const shouldLeaveGateway = leaveGateway && this.#joinRequested;
+        this.#joinRequested = false;
+        attempt.reject(error);
+        if (shouldLeaveGateway)
+            void this.#sendGatewayLeave();
+    }
+    #retryCredentialRefresh(attempt, _error) {
+        if (!attempt.internal ||
+            attempt.moving ||
+            this.#attempt !== attempt ||
+            attempt.settled ||
+            attempt.retryCount >= 2 ||
+            this.#disposed) {
+            return false;
+        }
+        attempt.retryCount += 1;
+        this.#generation += 1;
+        attempt.generation = this.#generation;
+        attempt.sequenceFloor = this.#gateway.lastSequence;
+        attempt.requestSent = false;
+        this.#voiceServer = undefined;
+        this.#voiceServerUnavailable = true;
+        this.#setConnectionState('reconnecting');
+        this.#suspendCurrentNativeTransport(attempt);
+        this.#requestGatewayJoin(attempt);
+        return true;
+    }
+    #finishAttempt(attempt) {
+        if (attempt.settled)
+            return;
+        attempt.settled = true;
+        clearTimeout(attempt.timer);
+        if (attempt.signal && attempt.abortListener) {
+            attempt.signal.removeEventListener('abort', attempt.abortListener);
+        }
+        if (this.#attempt === attempt)
+            this.#attempt = undefined;
+    }
+    async #handleGatewayDisconnect() {
+        const attempt = this.#attempt;
+        this.#generation += 1;
+        this.#setConnectionState('disconnecting');
+        this.#invalidateNativeTransport();
+        if (attempt) {
+            this.#finishAttempt(attempt);
+            attempt.reject(new Error('Discord Gateway reported that the bot left the voice channel'));
+        }
+        this.#joinRequested = false;
+        this.#voiceState = undefined;
+        this.#voiceServer = undefined;
+        this.#voiceServerUnavailable = false;
+        this.#stopNativeStateMonitor();
+        try {
+            await this.#nativeWork;
+            await this.#backgroundCleanup;
+            await this.#closeCurrentNativeSession();
+            this.#setConnectionState('disconnected');
+        }
+        catch (error) {
+            this.#connectionError = asError(error).message;
+            this.#setConnectionState('failed');
+        }
+    }
+    async #closeCurrentNativeSession() {
+        await this.#configurationWork;
+        const nativeSession = this.#nativeSession;
+        if (!nativeSession)
+            return;
+        this.#nativeSession = undefined;
+        const playback = this.#playback;
+        this.#playback = undefined;
+        await this.#releaseNativeSession(nativeSession, playback);
+    }
+    #queueCurrentNativeCleanup() {
+        const nativeSession = this.#nativeSession;
+        if (!nativeSession)
+            return;
+        this.#nativeSession = undefined;
+        const playback = this.#playback;
+        this.#playback = undefined;
+        this.#backgroundCleanup = this.#backgroundCleanup
+            .then(() => this.#releaseNativeSession(nativeSession, playback))
+            .catch((error) => {
+            this.#connectionError ??= asError(error).message;
+        });
+    }
+    async #releaseNativeSession(nativeSession, playback) {
+        const errors = [];
+        try {
+            await playback?.releaseInput();
+        }
+        catch (error) {
+            errors.push(asError(error));
+        }
+        try {
+            await this.#native.disconnectVoice(nativeSession.voiceId);
+        }
+        catch (error) {
+            errors.push(asError(error));
+        }
+        try {
+            this.#native.releaseVoiceSession(nativeSession.voiceId);
+        }
+        catch (error) {
+            errors.push(asError(error));
+        }
+        finally {
+            if (playback)
+                this.#detachPlaybackEvents(playback);
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'could not release native Discord voice session');
+        }
+    }
+    async #sendGatewayLeave() {
+        try {
+            await this.#gateway.setVoiceChannel(this.guildId, null);
+        }
+        catch (error) {
+            this.#connectionError ??= asError(error).message;
+        }
+    }
+    #requirePlayback() {
+        this.#assertNotDisposed();
+        if (this.connectionState !== 'connected' || !this.#playback) {
+            throw new Error('Discord voice session is not connected');
+        }
+        return this.#playback;
+    }
+    #requireExistingPlayback() {
+        this.#assertNotDisposed();
+        if (!this.#playback)
+            throw new Error('Discord voice session has no playback session');
+        return this.#playback;
+    }
+    async #replaceFilterGraph(graph) {
+        this.#assertNotDisposed();
+        await this.#serializeConfiguration(async () => {
+            if (this.#connectionState === 'disconnecting') {
+                throw new Error('Discord voice session is disconnecting');
+            }
+            const previousGraph = this.#filterGraph;
+            if (previousGraph === graph)
+                return;
+            if (graph !== null)
+                await this.#native.validateFilterGraph(graph);
+            if (this.#playback) {
+                if (graph === null)
+                    await this.#playback.filters.clear();
+                else
+                    await this.#playback.filters.set(graph);
+            }
+            else {
+                this.emit(PlaybackEvent.filterChanged, {
+                    sessionId: this.sessionId,
+                    guildId: this.guildId,
+                    nodeId: null,
+                    generation: this.#playbackGeneration,
+                    previousGraph,
+                    graph,
+                });
+            }
+            this.#filterGraph = graph;
+        });
+    }
+    #serializeConfiguration(operation) {
+        const result = this.#configurationWork.then(operation, operation);
+        this.#configurationWork = result.catch(() => { });
+        return result;
+    }
+    #assertNotDisposed() {
+        if (this.#disposed || this.#closing)
+            throw new Error('Discord voice session has been disposed');
+    }
+    #setConnectionState(state) {
+        const previousState = normalizeLifecycleVoiceState(this.#connectionState);
+        const nextState = normalizeLifecycleVoiceState(state);
+        if (previousState === nextState)
+            return;
+        this.#connectionState = state;
+        this.emit(VoiceEvent.voiceStateChanged, {
+            sessionId: this.sessionId,
+            guildId: this.guildId,
+            nodeId: null,
+            previousState,
+            state: nextState,
+        });
+        if (nextState === 'failed') {
+            this.emit(VoiceEvent.voiceFailed, {
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+                nodeId: null,
+                state: 'failed',
+                error: new Error(this.#connectionError ?? 'Discord voice transport failed'),
+            });
+        }
+    }
+    #forwardPlaybackEvents(playback) {
+        this.#detachPlaybackEvents();
+        const playbackEvents = playback;
+        const unsubscribers = [];
+        const forward = (name, listener) => {
+            playbackEvents.on(name, listener);
+            unsubscribers.push(() => playbackEvents.off(name, listener));
+        };
+        forward(PlaybackEvent.playbackStarted, (event) => {
+            this.#playbackGeneration = event.generation;
+            this.emit(PlaybackEvent.playbackStarted, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.playbackCompleted, (event) => {
+            this.emit(PlaybackEvent.playbackCompleted, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.playbackStopped, (event) => {
+            this.emit(PlaybackEvent.playbackStopped, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.playbackFailed, (event) => {
+            this.emit(PlaybackEvent.playbackFailed, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.playbackPaused, (event) => {
+            this.emit(PlaybackEvent.playbackPaused, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.playbackResumed, (event) => {
+            this.emit(PlaybackEvent.playbackResumed, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.playbackSeeked, (event) => {
+            this.emit(PlaybackEvent.playbackSeeked, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.filterChanged, (event) => {
+            this.emit(PlaybackEvent.filterChanged, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.volumeChanged, (event) => {
+            this.emit(PlaybackEvent.volumeChanged, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        this.#playbackSubscriptions = {
+            playback,
+            detach: () => {
+                for (const unsubscribe of unsubscribers.splice(0))
+                    unsubscribe();
+            },
+        };
+    }
+    #detachPlaybackEvents(playback) {
+        const subscriptions = this.#playbackSubscriptions;
+        if (!subscriptions || (playback && subscriptions.playback !== playback))
+            return;
+        this.#playbackSubscriptions = undefined;
+        subscriptions.detach();
+    }
+}
+function validateSnowflake(name, value) {
+    if (typeof value !== 'string' || !isSnowflake(value)) {
+        throw new TypeError(`${name} must be a decimal Discord snowflake string`);
+    }
+    return value;
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function abortError(message) {
+    const error = new Error(message);
+    error.name = 'AbortError';
+    return error;
+}
+function normalizeLifecycleVoiceState(state) {
+    return state === 'negotiatingDave' ? 'negotiating_dave' : state;
+}