@kattowo/distube 6.1.0 → 6.2.1

package/dist/index.js

@@ -34,6 +34,10 @@ __export(index_exports, {
   AUDIO_CHANNELS: () => AUDIO_CHANNELS,
   AUDIO_SAMPLE_RATE: () => AUDIO_SAMPLE_RATE,
   BaseManager: () => BaseManager,
+  CROSSFADE_DRIFT_TOLERANCE_SECS: () => CROSSFADE_DRIFT_TOLERANCE_SECS,
+  DEFAULT_CROSSFADE_CURVE: () => DEFAULT_CROSSFADE_CURVE,
+  DEFAULT_CROSSFADE_DURATION_SECS: () => DEFAULT_CROSSFADE_DURATION_SECS,
+  DEFAULT_CROSSFADE_WARMUP_SECS: () => DEFAULT_CROSSFADE_WARMUP_SECS,
   DEFAULT_PRELOAD_THRESHOLD_SECS: () => DEFAULT_PRELOAD_THRESHOLD_SECS,
   DEFAULT_VOLUME: () => DEFAULT_VOLUME,
   DisTube: () => DisTube,
@@ -50,6 +54,7 @@ __export(index_exports, {
   HTTP_REDIRECT_CODES: () => HTTP_REDIRECT_CODES,
   InfoExtractorPlugin: () => InfoExtractorPlugin,
   JOIN_TIMEOUT_MS: () => JOIN_TIMEOUT_MS,
+  MAX_CROSSFADE_DURATION_SECS: () => MAX_CROSSFADE_DURATION_SECS,
   MAX_REDIRECT_DEPTH: () => MAX_REDIRECT_DEPTH,
   Options: () => Options,
   PlayableExtractorPlugin: () => PlayableExtractorPlugin,
@@ -97,7 +102,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/constant.ts
-var version = "6.1.0";
+var version = "6.2.1";
 var AUDIO_SAMPLE_RATE = 48e3;
 var AUDIO_CHANNELS = 2;
 var DEFAULT_VOLUME = 50;
@@ -125,6 +130,11 @@ var defaultFilters = {
   earwax: "earwax"
 };
 var DEFAULT_PRELOAD_THRESHOLD_SECS = 15;
+var DEFAULT_CROSSFADE_DURATION_SECS = 0;
+var MAX_CROSSFADE_DURATION_SECS = 12;
+var DEFAULT_CROSSFADE_CURVE = "qsin";
+var DEFAULT_CROSSFADE_WARMUP_SECS = 5;
+var CROSSFADE_DRIFT_TOLERANCE_SECS = 0.75;
 var defaultOptions = {
   plugins: [],
   emitNewSongOnly: false,
@@ -135,7 +145,12 @@ var defaultOptions = {
   joinNewVoiceChannel: true,
   unhandledError: "log",
   stuckThreshold: STUCK_THRESHOLD_MS,
-  preload: false
+  preload: false,
+  crossfade: {
+    duration: DEFAULT_CROSSFADE_DURATION_SECS,
+    curve: DEFAULT_CROSSFADE_CURVE,
+    warmup: DEFAULT_CROSSFADE_WARMUP_SECS
+  }
 };
 
 // src/core/DisTubeBase.ts
@@ -858,7 +873,7 @@ var DisTubeVoice = class extends import_tiny_typed_emitter.TypedEmitter {
     if (this.audioPlayer.state.status !== import_voice.AudioPlayerStatus.Paused) {
       this.audioPlayer.play(dtStream.audioResource);
       this.stream?.kill();
-      dtStream.spawn();
+      if (!dtStream.process) dtStream.spawn();
     } else if (!this.pausingStream) {
       this.pausingStream = this.stream;
     }
@@ -1383,11 +1398,24 @@ var Queue = class extends DisTubeBase {
    * @internal
    */
   _preloadGeneration = 0;
+  #crossfade;
+  /**
+   * Crossfade boundary timer
+   * @internal
+   */
+  _crossfadeTimeout;
+  /**
+   * The merged transition stream that is warming up before the fade window
+   * starts
+   * @internal
+   */
+  _crossfadeWarmup;
   /**
    * Clear any preloaded song and cancel pending preload timer.
    * @internal
    */
   _clearPreload() {
+    this._crossfadeCancel();
     this._preloadGeneration++;
     if (this._preloadTimeout) {
       clearTimeout(this._preloadTimeout);
@@ -1399,6 +1427,20 @@ var Queue = class extends DisTubeBase {
     }
     this._preloadedSong = void 0;
   }
+  /**
+   * Cancel a pending crossfade and kill its warming-up transition stream.
+   * @internal
+   */
+  _crossfadeCancel() {
+    if (this._crossfadeTimeout) {
+      clearTimeout(this._crossfadeTimeout);
+      this._crossfadeTimeout = void 0;
+    }
+    if (this._crossfadeWarmup) {
+      this._crossfadeWarmup.kill();
+      this._crossfadeWarmup = void 0;
+    }
+  }
   /**
    * Create a queue for the guild
    * @param distube     - DisTube
@@ -1427,6 +1469,7 @@ var Queue = class extends DisTubeBase {
       input: { ...this.options.ffmpeg.args.input },
       output: { ...this.options.ffmpeg.args.output }
     };
+    this.#crossfade = Number(this.options.crossfade?.duration) || 0;
     this.#initialized = true;
   }
   #addToPreviousSongs(songs) {
@@ -1485,6 +1528,28 @@ var Queue = class extends DisTubeBase {
   get currentTime() {
     return this.voice.playbackTime;
   }
+  /**
+   * The crossfade duration (in seconds) between this song and the next one.
+   *
+   * `0` (the default) disables the crossfade. Changing it takes effect for the
+   * next transition; call {@link Queue#scheduleCrossfade} to re-arm the
+   * transition for the currently playing song immediately.
+   * @throws {@link DisTubeError} When the value is not a number between `0`
+   * and the maximum crossfade duration
+   */
+  get crossfade() {
+    return this.#crossfade;
+  }
+  set crossfade(value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+      throw new DisTubeError("INVALID_TYPE", "number", value, "Queue.crossfade");
+    }
+    if (value < 0) throw new DisTubeError("NUMBER_COMPARE", "Crossfade", "bigger or equal to", 0);
+    if (value > MAX_CROSSFADE_DURATION_SECS) {
+      throw new DisTubeError("NUMBER_COMPARE", "Crossfade", "smaller or equal to", MAX_CROSSFADE_DURATION_SECS);
+    }
+    this.#crossfade = value;
+  }
   /**
    * Formatted {@link Queue#currentTime} string.
    */
@@ -1586,6 +1651,7 @@ var Queue = class extends DisTubeBase {
       this.voice.unpause();
       this.emit("resumeSong" /* RESUME_SONG */, this, this.songs[0]);
       this.queues?.schedulePreload?.(this);
+      this.queues?.scheduleCrossfade?.(this);
       return this;
     } finally {
       this._taskQueue.resolve();
@@ -1842,6 +1908,17 @@ var Queue = class extends DisTubeBase {
     if (this.stopped) throw new DisTubeError("QUEUE_STOPPED");
     return this.queues.playSong(this, emitPlaySong);
   }
+  /**
+   * Re-arm the crossfade into the next song for the currently playing one.
+   *
+   * Useful after changing {@link Queue#crossfade} while a song is playing: the
+   * fade may still fit into the remaining time. This is called automatically
+   * after every song switch.
+   * @returns Nothing
+   */
+  scheduleCrossfade() {
+    this.queues.scheduleCrossfade(this);
+  }
   /**
    * Restart the current stream with the current FFmpeg arguments, keeping the
    * playback position.
@@ -2494,6 +2571,11 @@ var Options = class {
    * @default { enabled: false, threshold: 15 }
    */
   preload;
+  /**
+   * The crossfade options of the DisTube instance.
+   * @default { duration: 0, curve: "qsin", warmup: 5 }
+   */
+  crossfade;
   /**
    * The FFmpeg options of the DisTube instance.
    */
@@ -2520,6 +2602,7 @@ var Options = class {
     this.unhandledError = opts.unhandledError;
     this.stuckThreshold = opts.stuckThreshold;
     this.preload = this.#preloadOption(opts.preload);
+    this.crossfade = this.#crossfadeOption(opts.crossfade);
     this.ffmpeg = this.#ffmpegOption(options);
     checkInvalidKey(opts, this, "DisTubeOptions");
     this.#validateOptions();
@@ -2547,6 +2630,47 @@ var Options = class {
       threshold: threshold ?? DEFAULT_PRELOAD_THRESHOLD_SECS
     };
   }
+  #crossfadeOption(value) {
+    if (value === void 0) {
+      return {
+        duration: DEFAULT_CROSSFADE_DURATION_SECS,
+        curve: DEFAULT_CROSSFADE_CURVE,
+        warmup: DEFAULT_CROSSFADE_WARMUP_SECS
+      };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+      throw new DisTubeError("INVALID_TYPE", "object", value, "DisTubeOptions.crossfade");
+    }
+    checkInvalidKey(value, ["duration", "curve", "warmup"], "DisTubeOptions.crossfade");
+    const { duration, curve, warmup } = value;
+    if (duration !== void 0 && (typeof duration !== "number" || Number.isNaN(duration) || duration < 0)) {
+      throw new DisTubeError(
+        "INVALID_TYPE",
+        `number >= 0 (max ${MAX_CROSSFADE_DURATION_SECS})`,
+        duration,
+        "DisTubeOptions.crossfade.duration"
+      );
+    }
+    if (duration !== void 0 && duration > MAX_CROSSFADE_DURATION_SECS) {
+      throw new DisTubeError(
+        "NUMBER_COMPARE",
+        "Crossfade duration",
+        "smaller or equal to",
+        MAX_CROSSFADE_DURATION_SECS
+      );
+    }
+    if (curve !== void 0 && (typeof curve !== "string" || !curve)) {
+      throw new DisTubeError("INVALID_TYPE", "string", curve, "DisTubeOptions.crossfade.curve");
+    }
+    if (warmup !== void 0 && (typeof warmup !== "number" || Number.isNaN(warmup) || warmup < 0)) {
+      throw new DisTubeError("INVALID_TYPE", "number >= 0", warmup, "DisTubeOptions.crossfade.warmup");
+    }
+    return {
+      duration: duration ?? DEFAULT_CROSSFADE_DURATION_SECS,
+      curve: curve ?? DEFAULT_CROSSFADE_CURVE,
+      warmup: warmup ?? DEFAULT_CROSSFADE_WARMUP_SECS
+    };
+  }
   #validateOptions(options = this) {
     const booleanOptions = /* @__PURE__ */ new Set([
       "emitNewSongOnly",
@@ -2558,7 +2682,7 @@ var Options = class {
     ]);
     const numberOptions = /* @__PURE__ */ new Set(["stuckThreshold"]);
     const stringOptions = /* @__PURE__ */ new Set(["unhandledError"]);
-    const objectOptions = /* @__PURE__ */ new Set(["customFilters", "ffmpeg", "preload"]);
+    const objectOptions = /* @__PURE__ */ new Set(["customFilters", "ffmpeg", "preload", "crossfade"]);
     const optionalOptions = /* @__PURE__ */ new Set(["customFilters"]);
     for (const [key, value] of Object.entries(options)) {
       if (value === void 0 && optionalOptions.has(key)) continue;
@@ -2669,6 +2793,17 @@ var DisTubeStream = class extends import_tiny_typed_emitter2.TypedEmitter {
    * The seek time in seconds that this stream started from
    */
   seekTime;
+  /**
+   * Whether FFmpeg has already produced audio that is waiting to be read.
+   *
+   * The stream is spawned ahead of the playback (crossfade warmup) and the
+   * pipe backs up once its buffers are full, so this is `true` as soon as the
+   * first frame exists. A stream that is still `false` at playback time would
+   * leave the audio player buffering until FFmpeg catches up.
+   */
+  get hasBufferedAudio() {
+    return this.stream.readableLength > 0;
+  }
   /**
    * Create a DisTubeStream to play with {@link DisTubeVoice}
    * @param url     - Stream URL
@@ -2676,8 +2811,40 @@ var DisTubeStream = class extends import_tiny_typed_emitter2.TypedEmitter {
    */
   constructor(url, options) {
     super();
-    const { ffmpeg, seek } = options;
+    const { ffmpeg, seek, crossfade } = options;
     this.seekTime = typeof seek === "number" && seek > 0 ? seek : 0;
+    this.#ffmpegPath = ffmpeg.path;
+    this.#opts = crossfade ? this.#crossfadeArgs(url, ffmpeg, crossfade) : this.#singleInputArgs(url, ffmpeg, seek);
+    this.stream = new VolumeTransformer();
+    this.stream.on("close", () => this.kill()).on("error", (err) => {
+      this.debug(`[stream] error: ${err.message}`);
+      this.emit("error", err);
+    }).on("finish", () => this.debug("[stream] log: stream finished"));
+    this.audioResource = (0, import_voice2.createAudioResource)(this.stream, {
+      inputType: import_voice2.StreamType.Raw,
+      inlineVolume: false
+    });
+  }
+  #flattenArgs(args) {
+    return Object.entries(args).flatMap(
+      ([key, value]) => Array.isArray(value) ? value.filter(Boolean).map((v) => [`-${key}`, String(v)]) : value == null || value === false ? [] : [value === true ? `-${key}` : [`-${key}`, String(value)]]
+    ).flat();
+  }
+  /**
+   * Translate a `file:` URL into a local filesystem path that FFmpeg accepts.
+   *
+   * `file:///C:/x` loses its drive-letter leading slash on Windows (`C:/x`),
+   * UNC shares keep their `//host` prefix, POSIX paths stay untouched, and
+   * other protocols return `undefined`.
+   */
+  #localPath(url) {
+    const fileUrl = new URL(url);
+    if (fileUrl.protocol !== "file:") return void 0;
+    const pathname = decodeURIComponent(fileUrl.pathname);
+    if (fileUrl.hostname) return `//${fileUrl.hostname}${pathname}`;
+    return /^\/[A-Za-z]:\//.test(pathname) ? pathname.slice(1) : pathname;
+  }
+  #singleInputArgs(url, ffmpeg, seek) {
     const opts = {
       reconnect: 1,
       reconnect_streamed: 1,
@@ -2693,29 +2860,91 @@ var DisTubeStream = class extends import_tiny_typed_emitter2.TypedEmitter {
       f: "s16le"
     };
     if (typeof seek === "number" && seek > 0) opts.ss = seek.toString();
-    const fileUrl = new URL(url);
-    if (fileUrl.protocol === "file:") {
+    const localPath = this.#localPath(url);
+    if (localPath !== void 0) {
       opts.reconnect = null;
       opts.reconnect_streamed = null;
       opts.reconnect_delay_max = null;
-      opts.i = fileUrl.hostname + fileUrl.pathname;
+      opts.i = localPath;
     }
-    this.#ffmpegPath = ffmpeg.path;
-    this.#opts = [
-      ...Object.entries(opts).flatMap(
-        ([key, value]) => Array.isArray(value) ? value.filter(Boolean).map((v) => [`-${key}`, String(v)]) : value == null || value === false ? [] : [value === true ? `-${key}` : [`-${key}`, String(value)]]
-      ).flat(),
+    return [...this.#flattenArgs(opts), "pipe:1"];
+  }
+  /**
+   * Build the arguments of a crossfade transition stream: a single FFmpeg
+   * process with two inputs (the fading out song seeked to its final
+   * `duration` seconds and the fading in song from its beginning) mixed by an
+   * `acrossfade` filter graph.
+   *
+   * Both inputs are normalized (48kHz stereo s16) before the fade, and the
+   * queue's `af` filter chain, when present, is folded into the filter complex
+   * after the fade (FFmpeg cannot combine `-af` with `-filter_complex`).
+   */
+  #crossfadeArgs(url, ffmpeg, crossfade) {
+    const {
+      duration,
+      primarySeek,
+      secondaryUrl,
+      outCurve = DEFAULT_CROSSFADE_CURVE,
+      inCurve = DEFAULT_CROSSFADE_CURVE
+    } = crossfade;
+    const outputArgs = { ...ffmpeg.args.output };
+    const extraFilters = typeof outputArgs.af === "string" ? outputArgs.af : Array.isArray(outputArgs.af) ? outputArgs.af.filter(Boolean).join(",") : void 0;
+    delete outputArgs.af;
+    const primaryOpts = {
+      reconnect: 1,
+      reconnect_streamed: 1,
+      reconnect_delay_max: 5,
+      analyzeduration: 0,
+      hide_banner: true,
+      ...ffmpeg.args.global,
+      ...ffmpeg.args.input,
+      ss: typeof primarySeek === "number" && primarySeek > 0 ? primarySeek.toString() : null,
+      i: url
+    };
+    const secondaryOpts = {
+      reconnect: 1,
+      reconnect_streamed: 1,
+      reconnect_delay_max: 5,
+      analyzeduration: 0,
+      ...ffmpeg.args.input,
+      i: secondaryUrl
+    };
+    const primaryLocal = this.#localPath(url);
+    if (primaryLocal !== void 0) {
+      primaryOpts.reconnect = null;
+      primaryOpts.reconnect_streamed = null;
+      primaryOpts.reconnect_delay_max = null;
+      primaryOpts.i = primaryLocal;
+    }
+    const secondaryLocal = this.#localPath(secondaryUrl);
+    if (secondaryLocal !== void 0) {
+      secondaryOpts.reconnect = null;
+      secondaryOpts.reconnect_streamed = null;
+      secondaryOpts.reconnect_delay_max = null;
+      secondaryOpts.i = secondaryLocal;
+    }
+    const normalize = `aresample=${AUDIO_SAMPLE_RATE},aformat=sample_fmts=s16:channel_layouts=stereo`;
+    const fade = `[a0][a1]acrossfade=d=${duration}:c1=${outCurve}:c2=${inCurve}[xf]`;
+    const graph = [
+      `[0:a]${normalize}[a0]`,
+      `[1:a]${normalize}[a1]`,
+      fade,
+      ...extraFilters ? [`[xf]${extraFilters}[aout]`] : []
+    ].join(";");
+    const outputOpts = {
+      ar: AUDIO_SAMPLE_RATE,
+      ac: AUDIO_CHANNELS,
+      ...outputArgs,
+      filter_complex: graph,
+      map: extraFilters ? "[aout]" : "[xf]",
+      f: "s16le"
+    };
+    return [
+      ...this.#flattenArgs(primaryOpts),
+      ...this.#flattenArgs(secondaryOpts),
+      ...this.#flattenArgs(outputOpts),
       "pipe:1"
     ];
-    this.stream = new VolumeTransformer();
-    this.stream.on("close", () => this.kill()).on("error", (err) => {
-      this.debug(`[stream] error: ${err.message}`);
-      this.emit("error", err);
-    }).on("finish", () => this.debug("[stream] log: stream finished"));
-    this.audioResource = (0, import_voice2.createAudioResource)(this.stream, {
-      inputType: import_voice2.StreamType.Raw,
-      inlineVolume: false
-    });
   }
   /**
    * Spawn the FFmpeg process that decodes the audio.
@@ -3081,6 +3310,7 @@ var QueueManager = class extends GuildIdManager {
       await queue.voice.play(dtStream);
       if (emitPlaySong) this.emit("playSong" /* PLAY_SONG */, queue, song);
       this.schedulePreload(queue);
+      this.scheduleCrossfade(queue);
     } catch (e) {
       const error = e instanceof Error ? e : new Error(String(e));
       if (options?.keepSongOnError) {
@@ -3182,6 +3412,168 @@ var QueueManager = class extends GuildIdManager {
       this.emit("preloadError" /* PRELOAD_ERROR */, queue, nextSong, error);
     }
   }
+  /**
+   * Schedule the crossfade into the next song: a single FFmpeg process mixes
+   * the current song (seeked to its final fade window) with the next song, and
+   * replaces the playback stream exactly when the fade window begins.
+   *
+   * Canceled automatically whenever the preloaded state is invalidated
+   * (pause, seek, stop...), as both schedulers share the same generation.
+   * @param queue - The guild queue
+   */
+  scheduleCrossfade(queue) {
+    queue._crossfadeCancel();
+    if (queue.stopped || queue.paused) return;
+    const currentSong = queue.songs[0];
+    if (!currentSong) return;
+    const songDuration = currentSong.duration ?? 0;
+    if (!songDuration || !Number.isFinite(songDuration)) return;
+    const fade = Math.min(Number(queue.crossfade) || 0, songDuration);
+    if (fade <= 0) return;
+    const nextSong = queue.repeatMode === 1 /* SONG */ ? currentSong : queue.songs[1];
+    if (!nextSong) return;
+    const currentTime = queue.currentTime;
+    if (!Number.isFinite(currentTime)) return;
+    const remaining = songDuration - currentTime;
+    if (remaining <= fade) return;
+    const delayMs = Math.max(0, (remaining - fade - this.options.crossfade.warmup) * 1e3);
+    this.debug(
+      `[${queue.id}] Scheduling crossfade (${fade}s fade) in ${(delayMs / 1e3).toFixed(1)}s: ${currentSong} -> ${nextSong}`
+    );
+    queue._crossfadeTimeout = setTimeout(() => {
+      queue._crossfadeTimeout = void 0;
+      void this.#crossfadeWarmupTask(queue);
+    }, delayMs);
+    queue._crossfadeTimeout.unref?.();
+  }
+  /**
+   * Spawn the merged transition stream ahead of the fade window so both of
+   * its inputs are buffered when the fade must start, then arm the boundary
+   * timer that swaps the playback stream.
+   */
+  async #crossfadeWarmupTask(queue) {
+    let transitionStream;
+    try {
+      if (queue.stopped || queue.paused) return;
+      const song = queue.songs[0];
+      const generation = queue._preloadGeneration;
+      const repeatSong = queue.repeatMode === 1 /* SONG */;
+      const nextSong = repeatSong ? song : queue.songs[1];
+      if (!song || !nextSong) return;
+      const songDuration = song.duration ?? 0;
+      const fade = Math.min(Number(queue.crossfade) || 0, songDuration);
+      if (fade <= 0) return;
+      const remaining = songDuration - queue.currentTime;
+      if (remaining <= fade) return;
+      if (!repeatSong) {
+        if (this.options.preload.enabled) await this.preloadNextSong(queue);
+        else await this.handler.attachStreamInfo(nextSong);
+      }
+      if (queue.stopped || queue.paused || queue.songs[0] !== song || generation !== queue._preloadGeneration) return;
+      if (repeatSong ? queue.songs[0] !== song : queue.songs[1] !== nextSong) return;
+      const primary = song.stream.playFromSource ? song : song.stream.song;
+      const secondary = repeatSong ? primary : nextSong.stream.playFromSource ? nextSong : nextSong.stream.song;
+      if (!primary?.stream.playFromSource || !primary.stream.url) return;
+      if (!secondary?.stream.playFromSource || !secondary.stream.url) return;
+      this.debug(`[${queue.id}] Warming up crossfade stream: ${song} -> ${nextSong}`);
+      transitionStream = new DisTubeStream(primary.stream.url, {
+        ffmpeg: {
+          path: this.options.ffmpeg.path,
+          args: {
+            global: { ...queue.ffmpegArgs.global },
+            input: { ...queue.ffmpegArgs.input },
+            output: { ...queue.ffmpegArgs.output, ...queue.filters.ffmpegArgs }
+          }
+        },
+        crossfade: {
+          duration: fade,
+          primarySeek: Math.max(0, songDuration - fade),
+          secondaryUrl: secondary.stream.url,
+          inCurve: this.options.crossfade.curve,
+          outCurve: this.options.crossfade.curve
+        }
+      });
+      transitionStream.on("debug", (data) => this.emit("ffmpegDebug" /* FFMPEG_DEBUG */, `[${queue.id}] [crossfade] ${data}`));
+      if (queue.stopped || queue.paused || queue.songs[0] !== song || generation !== queue._preloadGeneration) {
+        transitionStream.kill();
+        return;
+      }
+      queue._crossfadeWarmup = transitionStream;
+      transitionStream.spawn();
+      const boundaryMs = Math.max(0, (songDuration - queue.currentTime - fade) * 1e3);
+      queue._crossfadeTimeout = setTimeout(() => {
+        queue._crossfadeTimeout = void 0;
+        void this.#crossfadeSwapTask(queue, transitionStream);
+      }, boundaryMs);
+      queue._crossfadeTimeout.unref?.();
+    } catch (e) {
+      const errorMessage = e instanceof Error ? e.message : String(e);
+      this.debug(`[${queue.id}] Crossfade warmup failed, using the regular transition: ${errorMessage}`);
+      if (transitionStream) transitionStream.kill();
+    }
+  }
+  /**
+   * Swap the playing stream for the merged transition stream and update the
+   * queue as if the current song had just finished.
+   */
+  async #crossfadeSwapTask(queue, transitionStream) {
+    const abort = /* @__PURE__ */ __name(() => {
+      if (queue._crossfadeWarmup === transitionStream) queue._crossfadeWarmup = void 0;
+      transitionStream.kill();
+    }, "abort");
+    try {
+      if (queue.stopped || queue.paused || queue._crossfadeWarmup !== transitionStream) return abort();
+      const song = queue.songs[0];
+      if (!song) return abort();
+      const songDuration = song.duration ?? 0;
+      const fade = Math.min(Number(queue.crossfade) || 0, songDuration);
+      if (fade <= 0) return abort();
+      const drift = queue.currentTime - (songDuration - fade);
+      if (Math.abs(drift) > CROSSFADE_DRIFT_TOLERANCE_SECS) {
+        this.debug(`[${queue.id}] Crossfade aborted: playback drifted ${drift.toFixed(2)}s from the fade boundary`);
+        return abort();
+      }
+      await queue._taskQueue.queuing();
+      try {
+        if (queue.stopped || queue.paused || queue.songs[0] !== song || queue._crossfadeWarmup !== transitionStream) {
+          return abort();
+        }
+        if (!transitionStream.hasBufferedAudio) {
+          this.debug(`[${queue.id}] Crossfade aborted: the transition stream is not ready`);
+          return abort();
+        }
+        this.debug(`[${queue.id}] Starting crossfade: ${song} -> ${queue.songs.length > 1 ? queue.songs[1] : song}`);
+        await queue.voice.play(transitionStream);
+        queue._crossfadeWarmup = void 0;
+        this.emit("finishSong" /* FINISH_SONG */, queue, song);
+        if (queue.repeatMode === 2 /* QUEUE */) queue.songs.push(song);
+        if (queue.repeatMode !== 1 /* SONG */) {
+          const prev = queue.songs.shift();
+          if (this.options.savePreviousSongs) queue.previousSongs.push(prev);
+          else queue.previousSongs.push({ id: prev.id });
+        } else {
+        }
+        if (song !== queue.songs[0]) {
+          const playedSong = song.stream.playFromSource ? song : song.stream.song;
+          if (playedSong?.stream.playFromSource) delete playedSong.stream.url;
+        }
+        if (queue._preloadedStream) {
+          queue._preloadedStream.kill();
+          queue._preloadedStream = void 0;
+          queue._preloadedSong = void 0;
+        }
+        this.emit("playSong" /* PLAY_SONG */, queue, queue.songs[0]);
+        this.schedulePreload(queue);
+        this.scheduleCrossfade(queue);
+      } finally {
+        queue._taskQueue.resolve();
+      }
+    } catch (e) {
+      abort();
+      const errorMessage = e instanceof Error ? e.message : String(e);
+      this.debug(`[${queue.id}] Crossfade swap failed, using the regular transition: ${errorMessage}`);
+    }
+  }
 };
 
 // src/core/StreamServer.ts
@@ -4196,6 +4588,10 @@ var PlayableExtractorPlugin = class extends ExtractorPlugin {
   AUDIO_CHANNELS,
   AUDIO_SAMPLE_RATE,
   BaseManager,
+  CROSSFADE_DRIFT_TOLERANCE_SECS,
+  DEFAULT_CROSSFADE_CURVE,
+  DEFAULT_CROSSFADE_DURATION_SECS,
+  DEFAULT_CROSSFADE_WARMUP_SECS,
   DEFAULT_PRELOAD_THRESHOLD_SECS,
   DEFAULT_VOLUME,
   DisTube,
@@ -4212,6 +4608,7 @@ var PlayableExtractorPlugin = class extends ExtractorPlugin {
   HTTP_REDIRECT_CODES,
   InfoExtractorPlugin,
   JOIN_TIMEOUT_MS,
+  MAX_CROSSFADE_DURATION_SECS,
   MAX_REDIRECT_DEPTH,
   Options,
   PlayableExtractorPlugin,