@fluxerjs/voice 1.0.6 → 1.0.7

package/dist/index.js

@@ -43,6 +43,10 @@ var import_events3 = require("events");
 var import_core = require("@fluxerjs/core");
 var import_types = require("@fluxerjs/types");
 
+// src/streamPreviewPlaceholder.ts
+var MINIMAL_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+var thumbnail = MINIMAL_PNG_BASE64;
+
 // src/VoiceConnection.ts
 var import_events = require("events");
 var nacl = __toESM(require("tweetnacl"));
@@ -100,9 +104,11 @@ var VoiceConnection = class extends import_events.EventEmitter {
     this.guildId = channel.guildId;
     this._userId = userId;
   }
+  /** Discord voice session ID. */
   get sessionId() {
     return this._sessionId;
   }
+  /** Whether audio is currently playing. */
   get playing() {
     return this._playing;
   }
@@ -342,6 +348,7 @@ var VoiceConnection = class extends import_events.EventEmitter {
       this.udpSocket.send(packet, 0, packet.length, this.remoteUdpPort, this.remoteUdpAddress);
     }
   }
+  /** Stop playback and clear the queue. */
   stop() {
     this._playing = false;
     this.audioPacketQueue = [];
@@ -354,6 +361,7 @@ var VoiceConnection = class extends import_events.EventEmitter {
       this.currentStream = null;
     }
   }
+  /** Disconnect from voice (closes WebSocket and UDP). */
   disconnect() {
     this._destroyed = true;
     this.stop();
@@ -371,6 +379,7 @@ var VoiceConnection = class extends import_events.EventEmitter {
     }
     this.emit("disconnect");
   }
+  /** Disconnect and remove all listeners. */
   destroy() {
     this.disconnect();
     this.removeAllListeners();
@@ -378,6 +387,7 @@ var VoiceConnection = class extends import_events.EventEmitter {
 };
 
 // src/LiveKitRtcConnection.ts
+var import_node_child_process = require("child_process");
 var import_events2 = require("events");
 var import_rtc_node = require("@livekit/rtc-node");
 
@@ -470,27 +480,113 @@ function concatUint8Arrays(a, b) {
 // src/LiveKitRtcConnection.ts
 var SAMPLE_RATE = 48e3;
 var CHANNELS2 = 1;
+function getNaluByteLength(nalu) {
+  if (ArrayBuffer.isView(nalu)) return nalu.byteLength;
+  if (nalu instanceof ArrayBuffer) return nalu.byteLength;
+  if (Array.isArray(nalu)) return nalu.length;
+  return 0;
+}
+function toUint8Array(nalu) {
+  if (nalu instanceof Uint8Array) return nalu;
+  if (ArrayBuffer.isView(nalu)) return new Uint8Array(nalu.buffer, nalu.byteOffset, nalu.byteLength);
+  if (nalu instanceof ArrayBuffer) return new Uint8Array(nalu);
+  if (Array.isArray(nalu)) return new Uint8Array(nalu);
+  return new Uint8Array(0);
+}
+function buildAvcDecoderConfig(avcC) {
+  try {
+    let size = 6;
+    for (const s of avcC.SPS) size += 2 + getNaluByteLength(s.nalu);
+    size += 1;
+    for (const p of avcC.PPS) size += 2 + getNaluByteLength(p.nalu);
+    if (avcC.ext) size += getNaluByteLength(avcC.ext);
+    const buf = new ArrayBuffer(size);
+    const view = new DataView(buf);
+    const arr = new Uint8Array(buf);
+    let offset = 0;
+    view.setUint8(offset++, avcC.configurationVersion);
+    view.setUint8(offset++, avcC.AVCProfileIndication);
+    view.setUint8(offset++, avcC.profile_compatibility);
+    view.setUint8(offset++, avcC.AVCLevelIndication);
+    view.setUint8(offset++, avcC.lengthSizeMinusOne & 3 | 252);
+    view.setUint8(offset++, avcC.SPS.length & 31 | 224);
+    for (const s of avcC.SPS) {
+      const naluBytes = toUint8Array(s.nalu);
+      const naluLen = naluBytes.byteLength;
+      if (offset + 2 + naluLen > size) return void 0;
+      view.setUint16(offset, naluLen, false);
+      offset += 2;
+      arr.set(naluBytes, offset);
+      offset += naluLen;
+    }
+    view.setUint8(offset++, avcC.PPS.length);
+    for (const p of avcC.PPS) {
+      const naluBytes = toUint8Array(p.nalu);
+      const naluLen = naluBytes.byteLength;
+      if (offset + 2 + naluLen > size) return void 0;
+      view.setUint16(offset, naluLen, false);
+      offset += 2;
+      arr.set(naluBytes, offset);
+      offset += naluLen;
+    }
+    if (avcC.ext) {
+      const extBytes = toUint8Array(avcC.ext);
+      if (offset + extBytes.byteLength > size) return void 0;
+      arr.set(extBytes, offset);
+    }
+    return buf;
+  } catch {
+    return void 0;
+  }
+}
 var FRAME_SAMPLES = 480;
+function floatToInt16(float32) {
+  const int16 = new Int16Array(float32.length);
+  for (let i = 0; i < float32.length; i++) {
+    let s = float32[i];
+    if (!Number.isFinite(s)) {
+      int16[i] = 0;
+      continue;
+    }
+    s = Math.max(-1, Math.min(1, s));
+    const scale = s < 0 ? 32768 : 32767;
+    const dither = (Math.random() + Math.random() - 1) * 0.5;
+    const scaled = Math.round(s * scale + dither);
+    int16[i] = Math.max(-32768, Math.min(32767, scaled));
+  }
+  return int16;
+}
 var VOICE_DEBUG = process.env.VOICE_DEBUG === "1" || process.env.VOICE_DEBUG === "true";
 var LiveKitRtcConnection = class extends import_events2.EventEmitter {
   client;
   channel;
   guildId;
   _playing = false;
+  _playingVideo = false;
   _destroyed = false;
   room = null;
   audioSource = null;
   audioTrack = null;
+  videoSource = null;
+  videoTrack = null;
   currentStream = null;
+  currentVideoStream = null;
+  _videoCleanup = null;
   lastServerEndpoint = null;
   lastServerToken = null;
   _disconnectEmitted = false;
+  /**
+   * @param client - The Fluxer client instance
+   * @param channel - The voice channel to connect to
+   * @param _userId - The user ID (reserved for future use)
+   */
   constructor(client, channel, _userId) {
     super();
     this.client = client;
     this.channel = channel;
     this.guildId = channel.guildId;
   }
+  /** Whether audio is currently playing. */
   get playing() {
     return this._playing;
   }
@@ -512,7 +608,11 @@ var LiveKitRtcConnection = class extends import_events2.EventEmitter {
   isConnected() {
     return !this._destroyed && this.room != null && this.room.isConnected;
   }
-  /** Returns true if we're already connected to the given server (skip migration). */
+  /**
+   * Returns true if we're already connected to the given server (skip migration).
+   * @param endpoint - Voice server endpoint from the gateway
+   * @param token - Voice server token
+   */
   isSameServer(endpoint, token) {
     const ep = (endpoint ?? "").trim();
     return ep === (this.lastServerEndpoint ?? "") && token === (this.lastServerToken ?? "");
@@ -520,6 +620,13 @@ var LiveKitRtcConnection = class extends import_events2.EventEmitter {
   playOpus(_stream) {
     this.emit("error", new Error("LiveKit: playOpus not supported; use play(url) with a WebM/Opus URL"));
   }
+  /**
+   * Connect to the LiveKit room using voice server and state from the gateway.
+   * Called internally by VoiceManager; typically not used directly.
+   *
+   * @param server - Voice server update data (endpoint, token)
+   * @param _state - Voice state update data (session, channel)
+   */
   async connect(server, _state) {
     const raw = (server.endpoint ?? "").trim();
     const token = server.token;
@@ -557,6 +664,751 @@ var LiveKitRtcConnection = class extends import_events2.EventEmitter {
       throw err;
     }
   }
+  /** Whether a video track is currently playing in the voice channel. */
+  get playingVideo() {
+    return this._playingVideo;
+  }
+  /**
+   * Play video from an MP4 URL or buffer. Streams decoded frames to the LiveKit room as a video track.
+   * Uses node-webcodecs for decoding (no ffmpeg). Supports H.264 (avc1) and H.265 (hvc1/hev1) codecs.
+   *
+   * @param urlOrBuffer - Video source: HTTP(S) URL to an MP4 file, or raw ArrayBuffer/Uint8Array of MP4 data
+   * @param options - Optional playback options (see {@link VideoPlayOptions})
+   * @emits error - On fetch failure, missing video track, or decode errors
+   *
+   * @example
+   * ```ts
+   * const conn = await voiceManager.join(channel);
+   * if (conn instanceof LiveKitRtcConnection && conn.isConnected()) {
+   *   await conn.playVideo('https://example.com/video.mp4', { source: 'camera' });
+   * }
+   * ```
+   */
+  async playVideo(urlOrBuffer, options) {
+    this.stopVideo();
+    if (!this.room || !this.room.isConnected) {
+      this.emit("error", new Error("LiveKit: not connected"));
+      return;
+    }
+    const useFFmpeg = options?.useFFmpeg ?? process.env.FLUXER_VIDEO_FFMPEG === "1";
+    if (useFFmpeg && typeof urlOrBuffer === "string") {
+      await this.playVideoFFmpeg(urlOrBuffer, options);
+      return;
+    }
+    if (useFFmpeg && (urlOrBuffer instanceof ArrayBuffer || urlOrBuffer instanceof Uint8Array)) {
+      this.emit("error", new Error("useFFmpeg requires a URL; buffer/ArrayBuffer not supported"));
+      return;
+    }
+    const { createFile } = await import("mp4box");
+    const { VideoDecoder, EncodedVideoChunk } = await import("node-webcodecs");
+    const videoUrl = typeof urlOrBuffer === "string" ? urlOrBuffer : null;
+    let arrayBuffer;
+    if (typeof urlOrBuffer === "string") {
+      try {
+        const response = await fetch(urlOrBuffer);
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const buf = await response.arrayBuffer();
+        arrayBuffer = buf;
+      } catch (e) {
+        this.emit("error", e instanceof Error ? e : new Error(String(e)));
+        return;
+      }
+    } else if (urlOrBuffer instanceof Uint8Array) {
+      arrayBuffer = urlOrBuffer.buffer.slice(urlOrBuffer.byteOffset, urlOrBuffer.byteOffset + urlOrBuffer.byteLength);
+    } else {
+      arrayBuffer = urlOrBuffer;
+    }
+    const file = createFile();
+    const sourceOption = options?.source ?? "camera";
+    const loop = options?.loop ?? true;
+    file.onError = (e) => {
+      this._playingVideo = false;
+      this.emit("error", e);
+    };
+    file.onReady = (info) => {
+      const tracks = info.tracks ?? [];
+      const videoTrack = tracks.find((t) => t.type === "video");
+      if (!videoTrack) {
+        this.emit("error", new Error("No video track in MP4"));
+        return;
+      }
+      const audioTrackInfo = tracks.find((t) => t.type === "audio" && t.codec.startsWith("mp4a"));
+      const width = videoTrack.video?.width ?? 640;
+      const height = videoTrack.video?.height ?? 480;
+      const totalSamples = videoTrack.nb_samples ?? Number.POSITIVE_INFINITY;
+      const source = new import_rtc_node.VideoSource(width, height);
+      this.videoSource = source;
+      const track = import_rtc_node.LocalVideoTrack.createVideoTrack("video", source);
+      this.videoTrack = track;
+      let audioSource = null;
+      let audioTrack = null;
+      let audioFfmpegProc = null;
+      const decoderCodec = videoTrack.codec.startsWith("avc1") ? videoTrack.codec : videoTrack.codec.startsWith("hvc1") || videoTrack.codec.startsWith("hev1") ? videoTrack.codec : "avc1.42E01E";
+      let decoderDescription;
+      if (videoTrack.codec.startsWith("avc1") || videoTrack.codec.startsWith("avc3")) {
+        const isoFile = file;
+        const trak = isoFile.moov?.traks?.find((t) => t.tkhd.track_id === videoTrack.id);
+        const sampleEntry = trak?.mdia?.minf?.stbl?.stsd?.entries?.[0];
+        const avcC = sampleEntry?.avcC;
+        if (avcC) {
+          decoderDescription = buildAvcDecoderConfig(avcC);
+        }
+      }
+      if (videoUrl && audioTrackInfo) {
+        audioSource = new import_rtc_node.AudioSource(SAMPLE_RATE, CHANNELS2);
+        this.audioSource = audioSource;
+        audioTrack = import_rtc_node.LocalAudioTrack.createAudioTrack("audio", audioSource);
+        this.audioTrack = audioTrack;
+      }
+      const frameQueue = [];
+      let playbackStartMs = null;
+      const maxFps = options?.maxFramerate ?? 60;
+      const FRAME_INTERVAL_MS = Math.round(1e3 / maxFps);
+      const MAX_QUEUED_FRAMES = 30;
+      let pacingInterval = null;
+      const decoder = new VideoDecoder({
+        output: async (frame) => {
+          if (!this._playingVideo || !source) return;
+          const { codedWidth, codedHeight } = frame;
+          if (codedWidth <= 0 || codedHeight <= 0) {
+            frame.close();
+            if (VOICE_DEBUG) this.audioDebug("video frame skipped (invalid dimensions)", { codedWidth, codedHeight });
+            return;
+          }
+          try {
+            if (playbackStartMs === null) playbackStartMs = Date.now();
+            const frameTimestampUs = frame.timestamp ?? 0;
+            const frameTimeMs = frameTimestampUs / 1e3;
+            const copyOptions = frame.format !== "I420" ? { format: "I420" } : void 0;
+            const size = frame.allocationSize(copyOptions);
+            const buffer = new Uint8Array(size);
+            await frame.copyTo(buffer, copyOptions);
+            frame.close();
+            const expectedI420Size = Math.ceil(codedWidth * codedHeight * 3 / 2);
+            if (buffer.byteLength < expectedI420Size) {
+              if (VOICE_DEBUG) this.audioDebug("video frame skipped (buffer too small)", { codedWidth, codedHeight });
+              return;
+            }
+            while (frameQueue.length >= MAX_QUEUED_FRAMES) {
+              frameQueue.shift();
+            }
+            frameQueue.push({ buffer, width: codedWidth, height: codedHeight, timestampMs: frameTimeMs });
+          } catch (err) {
+            if (VOICE_DEBUG) this.audioDebug("video frame error", { error: String(err) });
+          }
+        },
+        error: (e) => {
+          this.emit("error", e);
+          doCleanup();
+        }
+      });
+      decoder.configure({
+        codec: decoderCodec,
+        codedWidth: width,
+        codedHeight: height,
+        ...decoderDescription && { description: decoderDescription }
+      });
+      let samplesReceived = 0;
+      let cleanupCalled = false;
+      let currentFile = file;
+      const doCleanup = () => {
+        if (cleanupCalled) return;
+        cleanupCalled = true;
+        this._videoCleanup = null;
+        this._playingVideo = false;
+        if (pacingInterval) {
+          clearInterval(pacingInterval);
+          pacingInterval = null;
+        }
+        this.emit("requestVoiceStateSync", { self_stream: false, self_video: false });
+        const fileObj = currentFile;
+        if (typeof fileObj.stop === "function") {
+          fileObj.stop();
+        }
+        try {
+          decoder.close();
+        } catch (_) {
+        }
+        if (audioFfmpegProc && !audioFfmpegProc.killed) {
+          audioFfmpegProc.kill("SIGKILL");
+          audioFfmpegProc = null;
+        }
+        this.currentVideoStream = null;
+        if (this.videoTrack) {
+          this.videoTrack.close().catch(() => {
+          });
+          this.videoTrack = null;
+        }
+        if (this.videoSource) {
+          this.videoSource.close().catch(() => {
+          });
+          this.videoSource = null;
+        }
+        if (audioTrack) {
+          audioTrack.close().catch(() => {
+          });
+          this.audioTrack = null;
+        }
+        if (audioSource) {
+          audioSource.close().catch(() => {
+          });
+          this.audioSource = null;
+        }
+      };
+      const flushAndCleanup = () => {
+        decoder.flush().then(doCleanup).catch(doCleanup);
+      };
+      const scheduleLoop = (mp4File) => {
+        setImmediate(async () => {
+          if (!this._playingVideo || cleanupCalled) return;
+          try {
+            await decoder.flush();
+            decoder.reset();
+            decoder.configure({
+              codec: decoderCodec,
+              codedWidth: width,
+              codedHeight: height,
+              ...decoderDescription && { description: decoderDescription }
+            });
+            const fileObj = mp4File;
+            if (typeof fileObj.stop === "function") fileObj.stop();
+          } catch (e) {
+            if (VOICE_DEBUG) this.audioDebug("loop reset error", { error: String(e) });
+          }
+          if (!this._playingVideo || cleanupCalled) return;
+          playbackStartMs = null;
+          frameQueue.length = 0;
+          samplesReceived = 0;
+          const loopFile = createFile();
+          loopFile.onError = (e) => {
+            this._playingVideo = false;
+            this.emit("error", e);
+          };
+          loopFile.onReady = (loopInfo) => {
+            const loopTracks = loopInfo.tracks ?? [];
+            const loopVt = loopTracks.find((t) => t.type === "video");
+            if (!loopVt || loopVt.id !== videoTrack.id) return;
+            currentFile = loopFile;
+            this.currentVideoStream = loopFile;
+            loopFile.setExtractionOptions(loopVt.id, null, { nbSamples: 16 });
+            loopFile.onSamples = (tid, _u, samp) => {
+              if (!this._playingVideo) return;
+              if (tid === videoTrack.id) {
+                try {
+                  for (const sample of samp) {
+                    const isKeyFrame = sample.is_sync ?? sample.is_rap ?? sample.dts === 0;
+                    const chunk = new EncodedVideoChunk({
+                      type: isKeyFrame ? "key" : "delta",
+                      timestamp: Math.round(sample.dts / sample.timescale * 1e6),
+                      duration: Math.round(sample.duration / sample.timescale * 1e6),
+                      data: sample.data
+                    });
+                    decoder.decode(chunk);
+                  }
+                } catch (decodeErr) {
+                  this.emit("error", decodeErr instanceof Error ? decodeErr : new Error(String(decodeErr)));
+                  doCleanup();
+                  return;
+                }
+                samplesReceived += samp.length;
+                if (samplesReceived >= totalSamples) {
+                  if (loop) scheduleLoop(loopFile);
+                  else flushAndCleanup();
+                }
+              }
+            };
+            loopFile.start();
+          };
+          arrayBuffer.fileStart = 0;
+          loopFile.appendBuffer(arrayBuffer);
+          loopFile.flush();
+        });
+      };
+      this._videoCleanup = () => {
+        doCleanup();
+      };
+      file.onSamples = (trackId, _user, samples) => {
+        if (!this._playingVideo) return;
+        if (trackId === videoTrack.id) {
+          try {
+            for (const sample of samples) {
+              const isKeyFrame = sample.is_sync ?? sample.is_rap ?? sample.dts === 0;
+              const chunk = new EncodedVideoChunk({
+                type: isKeyFrame ? "key" : "delta",
+                timestamp: Math.round(sample.dts / sample.timescale * 1e6),
+                duration: Math.round(sample.duration / sample.timescale * 1e6),
+                data: sample.data
+              });
+              decoder.decode(chunk);
+            }
+          } catch (decodeErr) {
+            this.emit("error", decodeErr instanceof Error ? decodeErr : new Error(String(decodeErr)));
+            doCleanup();
+            return;
+          }
+          samplesReceived += samples.length;
+          if (samplesReceived >= totalSamples) {
+            if (loop) scheduleLoop(file);
+            else flushAndCleanup();
+          }
+        }
+      };
+      const participant = this.room?.localParticipant;
+      if (!participant) return;
+      const publishOptions = new import_rtc_node.TrackPublishOptions({
+        source: sourceOption === "screenshare" ? import_rtc_node.TrackSource.SOURCE_SCREENSHARE : import_rtc_node.TrackSource.SOURCE_CAMERA,
+        videoEncoding: {
+          maxBitrate: BigInt(options?.videoBitrate ?? 25e5),
+          maxFramerate: options?.maxFramerate ?? 60
+        }
+      });
+      const publishVideo = participant.publishTrack(track, publishOptions);
+      const audioPublishOptions = new import_rtc_node.TrackPublishOptions();
+      audioPublishOptions.source = import_rtc_node.TrackSource.SOURCE_MICROPHONE;
+      const publishAudio = audioTrack ? participant.publishTrack(audioTrack, audioPublishOptions) : Promise.resolve();
+      Promise.all([publishVideo, publishAudio]).then(async () => {
+        this._playingVideo = true;
+        this.currentVideoStream = file;
+        file.setExtractionOptions(videoTrack.id, null, { nbSamples: 16 });
+        pacingInterval = setInterval(() => {
+          if (!this._playingVideo || !source || playbackStartMs === null) return;
+          const elapsed = Date.now() - playbackStartMs;
+          if (frameQueue.length > 10) {
+            while (frameQueue.length > 1 && frameQueue[1].timestampMs <= elapsed) {
+              frameQueue.shift();
+            }
+          }
+          if (frameQueue.length > 0 && frameQueue[0].timestampMs <= elapsed) {
+            const f = frameQueue.shift();
+            try {
+              const livekitFrame = new import_rtc_node.VideoFrame(f.buffer, f.width, f.height, import_rtc_node.VideoBufferType.I420);
+              source.captureFrame(livekitFrame);
+            } catch (captureErr) {
+              if (VOICE_DEBUG) this.audioDebug("captureFrame error", { error: String(captureErr) });
+              this.emit("error", captureErr instanceof Error ? captureErr : new Error(String(captureErr)));
+            }
+          }
+        }, FRAME_INTERVAL_MS);
+        setImmediate(() => {
+          if (!this._playingVideo) return;
+          file.start();
+        });
+        if (videoUrl && audioSource && audioTrack) {
+          const { opus: prismOpus } = await import("prism-media");
+          const { OpusDecoder } = await import("opus-decoder");
+          const runAudioFfmpeg = async () => {
+            if (!this._playingVideo || cleanupCalled || !audioSource) return;
+            const audioProc = (0, import_node_child_process.spawn)("ffmpeg", [
+              "-loglevel",
+              "warning",
+              "-re",
+              "-i",
+              videoUrl,
+              "-vn",
+              "-c:a",
+              "libopus",
+              "-f",
+              "webm",
+              ...loop ? ["-stream_loop", "-1"] : [],
+              "pipe:1"
+            ], { stdio: ["ignore", "pipe", "pipe"] });
+            audioFfmpegProc = audioProc;
+            const demuxer = new prismOpus.WebmDemuxer();
+            if (audioProc.stdout) audioProc.stdout.pipe(demuxer);
+            const decoder2 = new OpusDecoder({ sampleRate: SAMPLE_RATE, channels: CHANNELS2 });
+            await decoder2.ready;
+            let sampleBuffer = new Int16Array(0);
+            let opusBuffer = new Uint8Array(0);
+            let processing = false;
+            const opusFrameQueue = [];
+            const processOneOpusFrame = async (frame) => {
+              if (frame.length < 2 || !audioSource || !this._playingVideo) return;
+              try {
+                const result = decoder2.decodeFrame(frame);
+                if (!result?.channelData?.[0]?.length) return;
+                const int16 = floatToInt16(result.channelData[0]);
+                const newBuffer = new Int16Array(sampleBuffer.length + int16.length);
+                newBuffer.set(sampleBuffer);
+                newBuffer.set(int16, sampleBuffer.length);
+                sampleBuffer = newBuffer;
+                while (sampleBuffer.length >= FRAME_SAMPLES && this._playingVideo && audioSource) {
+                  const outSamples = sampleBuffer.subarray(0, FRAME_SAMPLES);
+                  sampleBuffer = sampleBuffer.subarray(FRAME_SAMPLES).slice();
+                  const audioFrame = new import_rtc_node.AudioFrame(outSamples, SAMPLE_RATE, CHANNELS2, FRAME_SAMPLES);
+                  if (audioSource.queuedDuration > 500) await audioSource.waitForPlayout();
+                  await audioSource.captureFrame(audioFrame);
+                }
+              } catch (_) {
+              }
+            };
+            const drainQueue = async () => {
+              if (processing || opusFrameQueue.length === 0) return;
+              processing = true;
+              while (opusFrameQueue.length > 0 && this._playingVideo && audioSource) {
+                const f = opusFrameQueue.shift();
+                await processOneOpusFrame(f);
+              }
+              processing = false;
+            };
+            demuxer.on("data", (chunk) => {
+              if (!this._playingVideo) return;
+              opusBuffer = new Uint8Array(concatUint8Arrays(opusBuffer, new Uint8Array(chunk)));
+              while (opusBuffer.length > 0) {
+                const parsed = parseOpusPacketBoundaries(opusBuffer);
+                if (!parsed) break;
+                opusBuffer = new Uint8Array(opusBuffer.subarray(parsed.consumed));
+                for (const frame of parsed.frames) opusFrameQueue.push(frame);
+              }
+              drainQueue().catch(() => {
+              });
+            });
+            audioProc.on("exit", (code) => {
+              if (audioFfmpegProc === audioProc) audioFfmpegProc = null;
+              if (loop && this._playingVideo && !cleanupCalled && (code === 0 || code === null)) {
+                setImmediate(() => runAudioFfmpeg());
+              }
+            });
+          };
+          runAudioFfmpeg().catch((e) => this.audioDebug("audio ffmpeg error", { error: String(e) }));
+        }
+        this.emit("requestVoiceStateSync", {
+          self_stream: sourceOption === "screenshare",
+          self_video: sourceOption === "camera"
+        });
+      }).catch((err) => {
+        this._playingVideo = false;
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      });
+    };
+    arrayBuffer.fileStart = 0;
+    file.appendBuffer(arrayBuffer);
+    file.flush();
+  }
+  /**
+   * FFmpeg-based video playback. Bypasses node-webcodecs to avoid libc++abi crashes on macOS.
+   * Requires ffmpeg and ffprobe in PATH. URL input only.
+   */
+  async playVideoFFmpeg(url, options) {
+    const sourceOption = options?.source ?? "camera";
+    const loop = options?.loop ?? true;
+    let width = 640;
+    let height = 480;
+    try {
+      const { execFile } = await import("child_process");
+      const { promisify } = await import("util");
+      const exec = promisify(execFile);
+      const { stdout } = await exec("ffprobe", [
+        "-v",
+        "error",
+        "-select_streams",
+        "v:0",
+        "-show_entries",
+        "stream=width,height",
+        "-of",
+        "json",
+        url
+      ], { encoding: "utf8", timeout: 1e4 });
+      const parsed = JSON.parse(stdout);
+      const stream = parsed?.streams?.[0];
+      if (stream?.width && stream?.height) {
+        width = stream.width;
+        height = stream.height;
+      }
+    } catch (probeErr) {
+      this.emit("error", new Error(`ffprobe failed: ${probeErr instanceof Error ? probeErr.message : String(probeErr)}`));
+      return;
+    }
+    if (options?.width && options?.height) {
+      width = options.width;
+      height = options.height;
+    }
+    const source = new import_rtc_node.VideoSource(width, height);
+    this.videoSource = source;
+    const track = import_rtc_node.LocalVideoTrack.createVideoTrack("video", source);
+    this.videoTrack = track;
+    const publishOptions = new import_rtc_node.TrackPublishOptions({
+      source: sourceOption === "screenshare" ? import_rtc_node.TrackSource.SOURCE_SCREENSHARE : import_rtc_node.TrackSource.SOURCE_CAMERA,
+      videoEncoding: {
+        maxBitrate: BigInt(options?.videoBitrate ?? 25e5),
+        maxFramerate: options?.maxFramerate ?? 60
+      }
+    });
+    const participant = this.room?.localParticipant;
+    if (!participant) return;
+    try {
+      await participant.publishTrack(track, publishOptions);
+    } catch (err) {
+      this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    let audioFfmpegProc = null;
+    let audioSource = new import_rtc_node.AudioSource(SAMPLE_RATE, CHANNELS2);
+    let audioTrack = import_rtc_node.LocalAudioTrack.createAudioTrack("audio", audioSource);
+    this.audioSource = audioSource;
+    this.audioTrack = audioTrack;
+    try {
+      await participant.publishTrack(audioTrack, new import_rtc_node.TrackPublishOptions({ source: import_rtc_node.TrackSource.SOURCE_MICROPHONE }));
+    } catch {
+      audioTrack.close().catch(() => {
+      });
+      this.audioTrack = null;
+      this.audioSource = null;
+      audioSource = null;
+      audioTrack = null;
+    }
+    this._playingVideo = true;
+    this.emit("requestVoiceStateSync", {
+      self_stream: sourceOption === "screenshare",
+      self_video: sourceOption === "camera"
+    });
+    const frameSize = Math.ceil(width * height * 3 / 2);
+    const maxFps = options?.maxFramerate ?? 60;
+    const FRAME_INTERVAL_MS = Math.round(1e3 / maxFps);
+    let pacingTimeout = null;
+    let ffmpegProc = null;
+    let cleanupCalled = false;
+    const doCleanup = () => {
+      if (cleanupCalled) return;
+      cleanupCalled = true;
+      this._videoCleanup = null;
+      this._playingVideo = false;
+      if (pacingTimeout !== null) {
+        clearTimeout(pacingTimeout);
+        pacingTimeout = null;
+      }
+      if (ffmpegProc && !ffmpegProc.killed) {
+        ffmpegProc.kill("SIGKILL");
+        ffmpegProc = null;
+      }
+      if (audioFfmpegProc && !audioFfmpegProc.killed) {
+        audioFfmpegProc.kill("SIGKILL");
+        audioFfmpegProc = null;
+      }
+      this.emit("requestVoiceStateSync", { self_stream: false, self_video: false });
+      this.currentVideoStream = null;
+      if (this.audioTrack) {
+        this.audioTrack.close().catch(() => {
+        });
+        this.audioTrack = null;
+      }
+      if (this.audioSource) {
+        this.audioSource.close().catch(() => {
+        });
+        this.audioSource = null;
+      }
+      if (this.videoTrack) {
+        this.videoTrack.close().catch(() => {
+        });
+        this.videoTrack = null;
+      }
+      if (this.videoSource) {
+        this.videoSource.close().catch(() => {
+        });
+        this.videoSource = null;
+      }
+    };
+    this._videoCleanup = () => doCleanup();
+    const frameBuffer = [];
+    let frameBufferBytes = 0;
+    const MAX_QUEUED_FRAMES = 60;
+    const FRAME_DURATION_US = BigInt(Math.round(1e6 / maxFps));
+    let frameIndex = 0n;
+    const pushFramesFromBuffer = () => {
+      if (!this._playingVideo || !source || cleanupCalled) return;
+      if (frameBufferBytes < frameSize) return;
+      if (frameBufferBytes > frameSize * MAX_QUEUED_FRAMES) {
+        const framesToDrop = Math.floor((frameBufferBytes - frameSize * 2) / frameSize);
+        let toDropBytes = framesToDrop * frameSize;
+        while (toDropBytes > 0 && frameBuffer.length > 0) {
+          const c = frameBuffer[0];
+          if (c.length <= toDropBytes) {
+            toDropBytes -= c.length;
+            frameBufferBytes -= c.length;
+            frameBuffer.shift();
+          } else {
+            frameBuffer[0] = c.subarray(toDropBytes);
+            frameBufferBytes -= toDropBytes;
+            toDropBytes = 0;
+          }
+        }
+      }
+      let remaining = frameSize;
+      const parts = [];
+      while (remaining > 0 && frameBuffer.length > 0) {
+        const c = frameBuffer[0];
+        const take = Math.min(remaining, c.length);
+        parts.push(c.subarray(0, take));
+        remaining -= take;
+        if (take >= c.length) {
+          frameBuffer.shift();
+        } else {
+          frameBuffer[0] = c.subarray(take);
+        }
+      }
+      frameBufferBytes -= frameSize;
+      const frameData = Buffer.concat(parts, frameSize);
+      if (frameData.length !== frameSize) return;
+      try {
+        const frame = new import_rtc_node.VideoFrame(
+          new Uint8Array(frameData.buffer, frameData.byteOffset, frameSize),
+          width,
+          height,
+          import_rtc_node.VideoBufferType.I420
+        );
+        const timestampUs = frameIndex * FRAME_DURATION_US;
+        frameIndex += 1n;
+        source.captureFrame(frame, timestampUs);
+      } catch (e) {
+        if (VOICE_DEBUG) this.audioDebug("captureFrame error", { error: String(e) });
+      }
+    };
+    const scheduleNextPacing = () => {
+      if (!this._playingVideo || cleanupCalled) return;
+      pushFramesFromBuffer();
+      pacingTimeout = setTimeout(scheduleNextPacing, FRAME_INTERVAL_MS);
+    };
+    scheduleNextPacing();
+    const runFFmpeg = () => {
+      const ffmpegArgs = [
+        "-loglevel",
+        "warning",
+        "-re",
+        "-i",
+        url,
+        "-f",
+        "rawvideo",
+        "-pix_fmt",
+        "yuv420p",
+        "-r",
+        String(maxFps)
+      ];
+      if (options?.width && options?.height) {
+        ffmpegArgs.splice(ffmpegArgs.indexOf("-f"), 0, "-vf", `scale=${width}:${height}`);
+      }
+      ffmpegArgs.push("-");
+      ffmpegProc = (0, import_node_child_process.spawn)("ffmpeg", ffmpegArgs, { stdio: ["ignore", "pipe", "pipe"] });
+      this.currentVideoStream = {
+        destroy: () => {
+          if (ffmpegProc && !ffmpegProc.killed) ffmpegProc.kill("SIGKILL");
+        }
+      };
+      const stdout = ffmpegProc.stdout;
+      const stderr = ffmpegProc.stderr;
+      if (stdout) {
+        stdout.on("data", (chunk) => {
+          if (!this._playingVideo || cleanupCalled) return;
+          frameBuffer.push(chunk);
+          frameBufferBytes += chunk.length;
+        });
+      }
+      if (stderr) {
+        stderr.on("data", (data) => {
+          const line = data.toString().trim();
+          if (line && VOICE_DEBUG) this.audioDebug("ffmpeg stderr", { line: line.slice(0, 200) });
+        });
+      }
+      ffmpegProc.on("error", (err) => {
+        this.emit("error", err);
+        doCleanup();
+      });
+      ffmpegProc.on("exit", (code) => {
+        ffmpegProc = null;
+        if (cleanupCalled || !this._playingVideo) return;
+        if (loop && (code === 0 || code === null)) {
+          frameBuffer.length = 0;
+          frameBufferBytes = 0;
+          frameIndex = 0n;
+          setImmediate(runFFmpeg);
+        } else {
+          doCleanup();
+        }
+      });
+    };
+    runFFmpeg();
+    const runAudioFfmpeg = async () => {
+      if (!this._playingVideo || cleanupCalled || !audioSource) return;
+      const audioProc = (0, import_node_child_process.spawn)("ffmpeg", [
+        "-loglevel",
+        "warning",
+        "-re",
+        "-i",
+        url,
+        "-vn",
+        "-c:a",
+        "libopus",
+        "-f",
+        "webm",
+        ...loop ? ["-stream_loop", "-1"] : [],
+        "pipe:1"
+      ], { stdio: ["ignore", "pipe", "pipe"] });
+      audioFfmpegProc = audioProc;
+      const { opus: prismOpus } = await import("prism-media");
+      const { OpusDecoder } = await import("opus-decoder");
+      const demuxer = new prismOpus.WebmDemuxer();
+      if (audioProc.stdout) audioProc.stdout.pipe(demuxer);
+      const decoder = new OpusDecoder({ sampleRate: SAMPLE_RATE, channels: CHANNELS2 });
+      await decoder.ready;
+      let sampleBuffer = new Int16Array(0);
+      let opusBuffer = new Uint8Array(0);
+      let processing = false;
+      const opusFrameQueue = [];
+      const processOneOpusFrame = async (frame) => {
+        if (frame.length < 2 || !audioSource || !this._playingVideo) return;
+        try {
+          const result = decoder.decodeFrame(frame);
+          if (!result?.channelData?.[0]?.length) return;
+          const int16 = floatToInt16(result.channelData[0]);
+          const newBuffer = new Int16Array(sampleBuffer.length + int16.length);
+          newBuffer.set(sampleBuffer);
+          newBuffer.set(int16, sampleBuffer.length);
+          sampleBuffer = newBuffer;
+          while (sampleBuffer.length >= FRAME_SAMPLES && this._playingVideo && audioSource) {
+            const outSamples = sampleBuffer.subarray(0, FRAME_SAMPLES);
+            sampleBuffer = sampleBuffer.subarray(FRAME_SAMPLES).slice();
+            const audioFrame = new import_rtc_node.AudioFrame(outSamples, SAMPLE_RATE, CHANNELS2, FRAME_SAMPLES);
+            if (audioSource.queuedDuration > 500) await audioSource.waitForPlayout();
+            await audioSource.captureFrame(audioFrame);
+          }
+        } catch (_) {
+        }
+      };
+      const drainQueue = async () => {
+        if (processing || opusFrameQueue.length === 0) return;
+        processing = true;
+        while (opusFrameQueue.length > 0 && this._playingVideo && audioSource) {
+          const f = opusFrameQueue.shift();
+          await processOneOpusFrame(f);
+        }
+        processing = false;
+      };
+      demuxer.on("data", (chunk) => {
+        if (!this._playingVideo) return;
+        opusBuffer = new Uint8Array(concatUint8Arrays(opusBuffer, new Uint8Array(chunk)));
+        while (opusBuffer.length > 0) {
+          const parsed = parseOpusPacketBoundaries(opusBuffer);
+          if (!parsed) break;
+          opusBuffer = new Uint8Array(opusBuffer.subarray(parsed.consumed));
+          for (const frame of parsed.frames) opusFrameQueue.push(frame);
+        }
+        drainQueue().catch(() => {
+        });
+      });
+      audioProc.on("exit", (code) => {
+        if (audioFfmpegProc === audioProc) audioFfmpegProc = null;
+        if (loop && this._playingVideo && !cleanupCalled && (code === 0 || code === null)) {
+          setImmediate(() => runAudioFfmpeg());
+        }
+      });
+    };
+    runAudioFfmpeg().catch(() => {
+    });
+  }
+  /**
+   * Play audio from a WebM/Opus URL or readable stream. Publishes to the LiveKit room as an audio track.
+   *
+   * @param urlOrStream - Audio source: HTTP(S) URL to a WebM/Opus file, or a Node.js ReadableStream
+   * @emits error - On fetch failure or decode errors
+   */
   async play(urlOrStream) {
     this.stop();
     if (!this.room || !this.room.isConnected) {
@@ -593,22 +1445,6 @@ var LiveKitRtcConnection = class extends import_events2.EventEmitter {
     const decoder = new OpusDecoder({ sampleRate: SAMPLE_RATE, channels: CHANNELS2 });
     await decoder.ready;
     this._playing = true;
-    function floatToInt16(float32) {
-      const int16 = new Int16Array(float32.length);
-      for (let i = 0; i < float32.length; i++) {
-        let s = float32[i];
-        if (!Number.isFinite(s)) {
-          int16[i] = 0;
-          continue;
-        }
-        s = Math.max(-1, Math.min(1, s));
-        const scale = s < 0 ? 32768 : 32767;
-        const dither = (Math.random() + Math.random() - 1) * 0.5;
-        const scaled = Math.round(s * scale + dither);
-        int16[i] = Math.max(-32768, Math.min(32767, scaled));
-      }
-      return int16;
-    }
     let sampleBuffer = new Int16Array(0);
     let opusBuffer = new Uint8Array(0);
     let streamEnded = false;
@@ -706,8 +1542,34 @@ var LiveKitRtcConnection = class extends import_events2.EventEmitter {
       }
     });
   }
+  /**
+   * Stop video playback and unpublish the video track from the LiveKit room.
+   * Safe to call even when no video is playing.
+   */
+  stopVideo() {
+    if (this._videoCleanup) {
+      this._videoCleanup();
+      return;
+    }
+    this._playingVideo = false;
+    this.emit("requestVoiceStateSync", { self_stream: false, self_video: false });
+    if (this.currentVideoStream?.destroy) this.currentVideoStream.destroy();
+    this.currentVideoStream = null;
+    if (this.videoTrack) {
+      this.videoTrack.close().catch(() => {
+      });
+      this.videoTrack = null;
+    }
+    if (this.videoSource) {
+      this.videoSource.close().catch(() => {
+      });
+      this.videoSource = null;
+    }
+  }
+  /** Stop playback and clear both audio and video tracks. */
   stop() {
     this._playing = false;
+    this.stopVideo();
     if (this.currentStream?.destroy) this.currentStream.destroy();
     this.currentStream = null;
     if (this.audioTrack) {
@@ -721,6 +1583,7 @@ var LiveKitRtcConnection = class extends import_events2.EventEmitter {
       this.audioSource = null;
     }
   }
+  /** Disconnect from the LiveKit room and stop all playback. */
   disconnect() {
     this._destroyed = true;
     this.stop();
@@ -733,6 +1596,7 @@ var LiveKitRtcConnection = class extends import_events2.EventEmitter {
     this.lastServerToken = null;
     this.emit("disconnect");
   }
+  /** Disconnect from the room and remove all event listeners. */
   destroy() {
     this.disconnect();
     this.removeAllListeners();
@@ -744,6 +1608,8 @@ var import_collection = require("@fluxerjs/collection");
 var VoiceManager = class extends import_events3.EventEmitter {
   client;
   connections = new import_collection.Collection();
+  /** guild_id -> connection_id (from VoiceServerUpdate; required for voice state updates when in channel) */
+  connectionIds = /* @__PURE__ */ new Map();
   /** guild_id -> user_id -> channel_id */
   voiceStates = /* @__PURE__ */ new Map();
   pending = /* @__PURE__ */ new Map();
@@ -766,7 +1632,11 @@ var VoiceManager = class extends import_events3.EventEmitter {
       guildMap.set(vs.user_id, vs.channel_id);
     }
   }
-  /** Get the voice channel ID the user is in, or null. */
+  /**
+   * Get the voice channel ID the user is currently in, or null if not in voice.
+   * @param guildId - Guild ID to look up
+   * @param userId - User ID to look up
+   */
   getVoiceChannelId(guildId, userId) {
     const guildMap = this.voiceStates.get(guildId);
     if (!guildMap) return null;
@@ -775,6 +1645,7 @@ var VoiceManager = class extends import_events3.EventEmitter {
   handleVoiceStateUpdate(data) {
     const guildId = data.guild_id ?? "";
     if (!guildId) return;
+    this.client.emit?.("debug", `[VoiceManager] VoiceStateUpdate guild=${guildId} user=${data.user_id} channel=${data.channel_id ?? "null"} (bot=${this.client.user?.id})`);
     let guildMap = this.voiceStates.get(guildId);
     if (!guildMap) {
       guildMap = /* @__PURE__ */ new Map();
@@ -782,7 +1653,12 @@ var VoiceManager = class extends import_events3.EventEmitter {
     }
     guildMap.set(data.user_id, data.channel_id);
     const pending = this.pending.get(guildId);
-    if (pending && data.user_id === this.client.user?.id) {
+    const isBot = String(data.user_id) === String(this.client.user?.id);
+    if (isBot && data.connection_id) {
+      this.storeConnectionId(guildId, data.connection_id);
+    }
+    if (pending && isBot) {
+      this.client.emit?.("debug", `[VoiceManager] VoiceStateUpdate for bot - completing pending guild ${guildId}`);
       pending.state = data;
       this.tryCompletePending(guildId);
     }
@@ -791,6 +1667,8 @@ var VoiceManager = class extends import_events3.EventEmitter {
     const guildId = data.guild_id;
     const pending = this.pending.get(guildId);
     if (pending) {
+      const hasToken = !!(data.token && data.token.length > 0);
+      this.client.emit?.("debug", `[VoiceManager] VoiceServerUpdate guild=${guildId} endpoint=${data.endpoint ?? "null"} token=${hasToken ? "yes" : "NO"}`);
       pending.server = data;
       this.tryCompletePending(guildId);
       return;
@@ -811,6 +1689,7 @@ var VoiceManager = class extends import_events3.EventEmitter {
     this.client.emit?.("debug", `[VoiceManager] Voice server migration for guild ${guildId}; reconnecting`);
     conn.destroy();
     this.connections.delete(guildId);
+    this.storeConnectionId(guildId, data.connection_id);
     const ConnClass = LiveKitRtcConnection;
     const newConn = new ConnClass(this.client, channel, this.client.user.id);
     this.registerConnection(guildId, newConn);
@@ -825,23 +1704,66 @@ var VoiceManager = class extends import_events3.EventEmitter {
       newConn.emit("error", e instanceof Error ? e : new Error(String(e)));
     });
   }
+  storeConnectionId(guildId, connectionId) {
+    const id = connectionId != null ? String(connectionId) : null;
+    if (id) this.connectionIds.set(guildId, id);
+    else this.connectionIds.delete(guildId);
+  }
   registerConnection(guildId, conn) {
     this.connections.set(guildId, conn);
-    conn.once("disconnect", () => this.connections.delete(guildId));
+    conn.once("disconnect", () => {
+      this.connections.delete(guildId);
+      this.connectionIds.delete(guildId);
+    });
+    conn.on("requestVoiceStateSync", (p) => {
+      this.updateVoiceState(guildId, p);
+      if (p.self_stream) {
+        this.uploadStreamPreview(guildId, conn).catch(
+          (e) => this.client.emit?.("debug", `[VoiceManager] Stream preview upload failed: ${String(e)}`)
+        );
+      }
+    });
+  }
+  /** Upload a placeholder stream preview so the preview URL returns 200 instead of 404. */
+  async uploadStreamPreview(guildId, conn) {
+    const connectionId = this.connectionIds.get(guildId);
+    if (!connectionId) return;
+    const streamKey = `${guildId}:${conn.channel.id}:${connectionId}`;
+    const route = import_types.Routes.streamPreview(streamKey);
+    const body = { channel_id: conn.channel.id, thumbnail, content_type: "image/png" };
+    await this.client.rest.post(route, { body, auth: true });
+    this.client.emit?.("debug", `[VoiceManager] Uploaded stream preview for ${streamKey}`);
   }
   tryCompletePending(guildId) {
     const pending = this.pending.get(guildId);
-    if (!pending?.server || !pending.state) return;
+    if (!pending?.server) return;
+    const useLiveKit = isLiveKitEndpoint(pending.server.endpoint, pending.server.token);
+    const hasState = !!pending.state;
+    if (!useLiveKit && !hasState) return;
+    if (useLiveKit && !hasState) {
+      this.client.emit?.("debug", `[VoiceManager] Proceeding with VoiceServerUpdate only (LiveKit does not require VoiceStateUpdate)`);
+    }
+    const state = pending.state ?? {
+      guild_id: guildId,
+      channel_id: pending.channel.id,
+      user_id: this.client.user.id,
+      session_id: ""
+    };
+    this.storeConnectionId(guildId, pending.server.connection_id ?? state.connection_id);
     this.pending.delete(guildId);
-    const ConnClass = isLiveKitEndpoint(pending.server.endpoint, pending.server.token) ? LiveKitRtcConnection : VoiceConnection;
+    const ConnClass = useLiveKit ? LiveKitRtcConnection : VoiceConnection;
     const conn = new ConnClass(this.client, pending.channel, this.client.user.id);
     this.registerConnection(guildId, conn);
-    conn.connect(pending.server, pending.state).then(
+    conn.connect(pending.server, state).then(
       () => pending.resolve(conn),
       (e) => pending.reject(e)
     );
   }
-  /** Join a voice channel. Resolves when the connection is ready. */
+  /**
+   * Join a voice channel. Resolves when the connection is ready.
+   * @param channel - The voice channel to join
+   * @returns The voice connection (LiveKitRtcConnection when Fluxer uses LiveKit)
+   */
   async join(channel) {
     const existing = this.connections.get(channel.guildId);
     if (existing) {
@@ -851,12 +1773,17 @@ var VoiceManager = class extends import_events3.EventEmitter {
       this.connections.delete(channel.guildId);
     }
     return new Promise((resolve, reject) => {
+      this.client.emit?.("debug", `[VoiceManager] Requesting voice join guild=${channel.guildId} channel=${channel.id}`);
       const timeout = setTimeout(() => {
         if (this.pending.has(channel.guildId)) {
           this.pending.delete(channel.guildId);
-          reject(new Error("Voice connection timeout"));
+          reject(
+            new Error(
+              "Voice connection timeout. Ensure the server has voice enabled and the bot has Connect permissions. The gateway must send VoiceServerUpdate and VoiceStateUpdate in response."
+            )
+          );
         }
-      }, 15e3);
+      }, 2e4);
       this.pending.set(channel.guildId, {
         channel,
         resolve: (c) => {
@@ -879,12 +1806,16 @@ var VoiceManager = class extends import_events3.EventEmitter {
       });
     });
   }
-  /** Leave a guild's voice channel. */
+  /**
+   * Leave a guild's voice channel and disconnect.
+   * @param guildId - Guild ID to leave
+   */
   leave(guildId) {
     const conn = this.connections.get(guildId);
     if (conn) {
       conn.destroy();
       this.connections.delete(guildId);
+      this.connectionIds.delete(guildId);
     }
     this.client.sendToGateway(this.shardId, {
       op: import_types.GatewayOpcodes.VoiceStateUpdate,
@@ -896,9 +1827,42 @@ var VoiceManager = class extends import_events3.EventEmitter {
       }
     });
   }
+  /**
+   * Get the active voice connection for a guild, if any.
+   * @param guildId - Guild ID to look up
+   */
   getConnection(guildId) {
     return this.connections.get(guildId);
   }
+  /**
+   * Update voice state (e.g. self_stream, self_video) while in a channel.
+   * Sends a VoiceStateUpdate to the gateway so the server and clients see the change.
+   * Requires connection_id (from VoiceServerUpdate); without it, the gateway would treat
+   * the update as a new join and trigger a new VoiceServerUpdate, causing connection loops.
+   * @param guildId - Guild ID
+   * @param partial - Partial voice state to update (self_stream, self_video, self_mute, self_deaf)
+   */
+  updateVoiceState(guildId, partial) {
+    const conn = this.connections.get(guildId);
+    if (!conn) return;
+    const connectionId = this.connectionIds.get(guildId);
+    if (!connectionId) {
+      this.client.emit?.("debug", `[VoiceManager] Skipping voice state sync: no connection_id for guild ${guildId}`);
+      return;
+    }
+    this.client.sendToGateway(this.shardId, {
+      op: import_types.GatewayOpcodes.VoiceStateUpdate,
+      d: {
+        guild_id: guildId,
+        channel_id: conn.channel.id,
+        connection_id: connectionId,
+        self_mute: partial.self_mute ?? false,
+        self_deaf: partial.self_deaf ?? false,
+        self_video: partial.self_video ?? false,
+        self_stream: partial.self_stream ?? false
+      }
+    });
+  }
 };
 
 // src/index.ts