@kattowo/distube 6.0.2 → 6.2.0

package/dist/index.mjs

@@ -2,7 +2,7 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/constant.ts
-var version = "6.0.2";
+var version = "6.2.0";
 var AUDIO_SAMPLE_RATE = 48e3;
 var AUDIO_CHANNELS = 2;
 var DEFAULT_VOLUME = 50;
@@ -29,6 +29,12 @@ var defaultFilters = {
   surround: "surround",
   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,
@@ -38,7 +44,13 @@ var defaultOptions = {
   emitAddListWhenCreatingQueue: true,
   joinNewVoiceChannel: true,
   unhandledError: "log",
-  stuckThreshold: STUCK_THRESHOLD_MS
+  stuckThreshold: STUCK_THRESHOLD_MS,
+  preload: false,
+  crossfade: {
+    duration: DEFAULT_CROSSFADE_DURATION_SECS,
+    curve: DEFAULT_CROSSFADE_CURVE,
+    warmup: DEFAULT_CROSSFADE_WARMUP_SECS
+  }
 };
 
 // src/core/DisTubeBase.ts
@@ -615,7 +627,14 @@ var DisTubeVoice = class extends TypedEmitter {
       if (newState.reason === VoiceConnectionDisconnectReason.Manual) {
         this.leave();
       } else if (newState.reason === VoiceConnectionDisconnectReason.WebSocketClose && newState.closeCode === 4014) {
-        entersState(this.connection, VoiceConnectionStatus.Connecting, RECONNECT_TIMEOUT_MS).catch(() => {
+        entersState(this.connection, VoiceConnectionStatus.Connecting, RECONNECT_TIMEOUT_MS).then(() => entersState(this.connection, VoiceConnectionStatus.Ready, RECONNECT_TIMEOUT_MS)).then(() => {
+          const oldChannel = this.#channel;
+          const currentChannel = this.channel;
+          if (oldChannel && currentChannel && oldChannel.id !== currentChannel.id) {
+            this.#channel = currentChannel;
+            this.emit("channelChange", oldChannel, currentChannel);
+          }
+        }).catch(() => {
           if (![VoiceConnectionStatus.Ready, VoiceConnectionStatus.Connecting].includes(this.connection.state.status)) {
             this.leave();
           }
@@ -676,8 +695,12 @@ var DisTubeVoice = class extends TypedEmitter {
       if (channel.full) throw new DisTubeError("VOICE_FULL");
       else throw new DisTubeError("VOICE_MISSING_PERMS");
     }
+    const oldChannel = this.#channel;
     this.connection = this.#join(channel);
     this.#channel = channel;
+    if (oldChannel && oldChannel.id !== channel.id) {
+      this.emit("channelChange", oldChannel, channel);
+    }
   }
   #join(channel) {
     return joinVoiceChannel({
@@ -757,7 +780,7 @@ var DisTubeVoice = class extends TypedEmitter {
     if (this.audioPlayer.state.status !== 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;
     }
@@ -965,7 +988,13 @@ var FilterManager = class extends BaseManager {
     }
     throw new DisTubeError("INVALID_TYPE", "FilterResolvable", filter, "filter");
   }
-  #apply() {
+  #apply(oldFilters) {
+    this.queue._clearPreload?.();
+    const newFilters = this.names;
+    const changed = oldFilters.length !== newFilters.length || !oldFilters.every((f) => newFilters.includes(f));
+    if (changed) {
+      this.emit("changeFilter" /* CHANGE_FILTER */, this.queue, newFilters, oldFilters);
+    }
     void this.queue._restartStream().catch((e) => {
       const errorMessage = e instanceof Error ? e.message : String(e);
       this.queue.debug(`[${this.queue.id}] Failed to apply the filters: ${errorMessage}`);
@@ -983,6 +1012,7 @@ var FilterManager = class extends BaseManager {
    * ```
    */
   add(filterOrFilters, override = false) {
+    const oldFilters = this.names;
     if (Array.isArray(filterOrFilters)) {
       for (const filter of filterOrFilters) {
         const ft = this.#resolve(filter);
@@ -992,7 +1022,7 @@ var FilterManager = class extends BaseManager {
       const ft = this.#resolve(filterOrFilters);
       if (override || !this.has(ft)) this.collection.set(ft.name, ft);
     }
-    this.#apply();
+    this.#apply(oldFilters);
     return this;
   }
   /**
@@ -1011,12 +1041,13 @@ var FilterManager = class extends BaseManager {
    */
   set(filters) {
     if (!Array.isArray(filters)) throw new DisTubeError("INVALID_TYPE", "Array<FilterResolvable>", filters, "filters");
+    const oldFilters = this.names;
     this.collection.clear();
     for (const f of filters) {
       const filter = this.#resolve(f);
       this.collection.set(filter.name, filter);
     }
-    this.#apply();
+    this.#apply(oldFilters);
     return this;
   }
   #removeFn(f) {
@@ -1029,9 +1060,10 @@ var FilterManager = class extends BaseManager {
    * @throws {@link DisTubeError} When a filter is not a valid {@link FilterResolvable}
    */
   remove(filterOrFilters) {
+    const oldFilters = this.names;
     if (Array.isArray(filterOrFilters)) filterOrFilters.forEach((f) => this.#removeFn(f));
     else this.#removeFn(filterOrFilters);
-    this.#apply();
+    this.#apply(oldFilters);
     return this;
   }
   /**
@@ -1087,6 +1119,17 @@ var Events = /* @__PURE__ */ ((Events2) => {
   Events2["DELETE_QUEUE"] = "deleteQueue";
   Events2["FFMPEG_DEBUG"] = "ffmpegDebug";
   Events2["DEBUG"] = "debug";
+  Events2["PAUSE_SONG"] = "pauseSong";
+  Events2["RESUME_SONG"] = "resumeSong";
+  Events2["SEEK_SONG"] = "seekSong";
+  Events2["SET_VOLUME"] = "setVolume";
+  Events2["SHUFFLE_QUEUE"] = "shuffleQueue";
+  Events2["SKIP_SONG"] = "skipSong";
+  Events2["CHANGE_FILTER"] = "changeFilter";
+  Events2["VOICE_CHANNEL_CHANGE"] = "voiceChannelChange";
+  Events2["PRELOAD_SONG"] = "preloadSong";
+  Events2["PRELOADED_SONG"] = "preloadedSong";
+  Events2["PRELOAD_ERROR"] = "preloadError";
   return Events2;
 })(Events || {});
 var SearchResultType = /* @__PURE__ */ ((SearchResultType2) => {
@@ -1220,6 +1263,7 @@ var Queue = class extends DisTubeBase {
    */
   _beginTime;
   #filters;
+  #initialized = false;
   /**
    * Whether or not the queue is being updated manually (skip, jump, previous)
    * @internal
@@ -1235,6 +1279,75 @@ var Queue = class extends DisTubeBase {
    * @internal
    */
   _listeners;
+  /**
+   * Preload timer
+   * @internal
+   */
+  _preloadTimeout;
+  /**
+   * Preloaded song
+   * @internal
+   */
+  _preloadedSong;
+  /**
+   * Preloaded stream
+   * @internal
+   */
+  _preloadedStream;
+  /**
+   * In-flight preload task
+   * @internal
+   */
+  _preloading;
+  /**
+   * Bumped whenever the preloaded state is invalidated, so an in-flight
+   * preload task can detect that its result is no longer needed.
+   * @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);
+      this._preloadTimeout = void 0;
+    }
+    if (this._preloadedStream) {
+      this._preloadedStream.kill();
+      this._preloadedStream = void 0;
+    }
+    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
@@ -1263,6 +1376,8 @@ 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) {
     if (Array.isArray(songs)) {
@@ -1320,6 +1435,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.
    */
@@ -1345,7 +1482,11 @@ var Queue = class extends DisTubeBase {
    * negative
    */
   set volume(value) {
+    const oldVolume = this.voice.volume;
     this.voice.volume = value;
+    if (this.#initialized && oldVolume !== value) {
+      this.emit("setVolume" /* SET_VOLUME */, this, value, oldVolume);
+    }
   }
   /**
    * Add a song or a list of songs to the queue.
@@ -1374,6 +1515,7 @@ var Queue = class extends DisTubeBase {
     } else {
       this.songs.splice(position, 0, song);
     }
+    this.queues?.schedulePreload?.(this);
     return this;
   }
   /**
@@ -1391,7 +1533,9 @@ var Queue = class extends DisTubeBase {
     try {
       if (this.paused) throw new DisTubeError("PAUSED");
       this.paused = true;
+      this._clearPreload();
       this.voice.pause();
+      this.emit("pauseSong" /* PAUSE_SONG */, this, this.songs[0]);
       return this;
     } finally {
       this._taskQueue.resolve();
@@ -1412,6 +1556,9 @@ var Queue = class extends DisTubeBase {
       if (!this.paused) throw new DisTubeError("RESUMED");
       this.paused = false;
       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();
@@ -1476,11 +1623,14 @@ var Queue = class extends DisTubeBase {
     try {
       const playing = this.songs.shift();
       if (playing === void 0) return this;
+      this._clearPreload();
       for (let i = this.songs.length - 1; i > 0; i--) {
         const j = Math.floor(Math.random() * (i + 1));
         [this.songs[i], this.songs[j]] = [this.songs[j], this.songs[i]];
       }
       this.songs.unshift(playing);
+      this.emit("shuffleQueue" /* SHUFFLE_QUEUE */, this, this.songs);
+      this.queues?.schedulePreload?.(this);
       return this;
     } finally {
       this._taskQueue.resolve();
@@ -1518,12 +1668,14 @@ var Queue = class extends DisTubeBase {
         } else {
           this.#addToPreviousSongs(skipped);
         }
+        this.emit("skipSong" /* SKIP_SONG */, this, skipped[0]);
       } else if (!this.options.savePreviousSongs) {
         throw new DisTubeError("DISABLED_OPTION", "savePreviousSongs");
       } else {
         const skipped = this.previousSongs.splice(position);
         this.songs.unshift(...skipped);
       }
+      this._clearPreload();
       this.#stop();
       return this.songs[0];
     } finally {
@@ -1562,8 +1714,10 @@ var Queue = class extends DisTubeBase {
     try {
       if (typeof time !== "number") throw new DisTubeError("INVALID_TYPE", "number", time, "time");
       if (Number.isNaN(time) || time < 0) throw new DisTubeError("NUMBER_COMPARE", "time", "bigger or equal to", 0);
+      this._clearPreload();
       this._beginTime = time;
       await this.play(false);
+      this.emit("seekSong" /* SEEK_SONG */, this, this.songs[0], time);
       return this;
     } finally {
       this._taskQueue.resolve();
@@ -1634,6 +1788,7 @@ var Queue = class extends DisTubeBase {
    * @returns Nothing
    */
   remove() {
+    this._clearPreload();
     this.paused = true;
     this.stopped = true;
     this.songs = [];
@@ -1660,6 +1815,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.
@@ -2307,6 +2473,16 @@ var Options = class {
    * @default 10000
    */
   stuckThreshold;
+  /**
+   * The preload options of the DisTube instance.
+   * @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.
    */
@@ -2332,10 +2508,76 @@ var Options = class {
     this.joinNewVoiceChannel = opts.joinNewVoiceChannel;
     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();
   }
+  #preloadOption(value) {
+    if (value === void 0 || value === false) {
+      return { enabled: false, threshold: DEFAULT_PRELOAD_THRESHOLD_SECS };
+    }
+    if (value === true) {
+      return { enabled: true, threshold: DEFAULT_PRELOAD_THRESHOLD_SECS };
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+      throw new DisTubeError("INVALID_TYPE", ["boolean", "object"], value, "DisTubeOptions.preload");
+    }
+    checkInvalidKey(value, ["enabled", "threshold"], "DisTubeOptions.preload");
+    const { enabled, threshold } = value;
+    if (enabled !== void 0 && typeof enabled !== "boolean") {
+      throw new DisTubeError("INVALID_TYPE", "boolean", enabled, "DisTubeOptions.preload.enabled");
+    }
+    if (threshold !== void 0 && (typeof threshold !== "number" || Number.isNaN(threshold) || threshold < 0)) {
+      throw new DisTubeError("INVALID_TYPE", "number", threshold, "DisTubeOptions.preload.threshold");
+    }
+    return {
+      enabled: enabled ?? false,
+      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",
@@ -2347,7 +2589,7 @@ var Options = class {
     ]);
     const numberOptions = /* @__PURE__ */ new Set(["stuckThreshold"]);
     const stringOptions = /* @__PURE__ */ new Set(["unhandledError"]);
-    const objectOptions = /* @__PURE__ */ new Set(["customFilters", "ffmpeg"]);
+    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;
@@ -2465,8 +2707,40 @@ var DisTubeStream = class extends TypedEmitter2 {
    */
   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 = createAudioResource(this.stream, {
+      inputType: 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,
@@ -2482,29 +2756,91 @@ var DisTubeStream = class extends TypedEmitter2 {
       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 = createAudioResource(this.stream, {
-      inputType: StreamType.Raw,
-      inlineVolume: false
-    });
   }
   /**
    * Spawn the FFmpeg process that decodes the audio.
@@ -2735,7 +3071,10 @@ var QueueManager = class extends GuildIdManager {
         if (error) this.emitError(error, queue, queue.songs?.[0]);
       }, "disconnect"),
       error: /* @__PURE__ */ __name((error) => void this.#handlePlayingError(queue, error), "error"),
-      finish: /* @__PURE__ */ __name(() => void this.handleSongFinish(queue), "finish")
+      finish: /* @__PURE__ */ __name(() => void this.handleSongFinish(queue), "finish"),
+      channelChange: /* @__PURE__ */ __name((oldChannel, newChannel) => {
+        this.emit("voiceChannelChange" /* VOICE_CHANNEL_CHANGE */, queue, oldChannel, newChannel);
+      }, "channelChange")
     };
     for (const event of objectKeys(queue._listeners)) {
       queue.voice.on(event, queue._listeners[event]);
@@ -2833,12 +3172,110 @@ var QueueManager = class extends GuildIdManager {
     }
     try {
       const song = queue.songs[0];
-      this.debug(`[${queue.id}] Getting stream from: ${song}`);
-      await this.handler.attachStreamInfo(song);
-      const willPlaySong = song.stream.playFromSource ? song : song.stream.song;
+      let dtStream;
+      if (queue._preloadedSong === song && queue._preloadedStream) {
+        this.debug(`[${queue.id}] Using preloaded stream for: ${song}`);
+        dtStream = queue._preloadedStream;
+        queue._preloadedSong = void 0;
+        queue._preloadedStream = void 0;
+      } else {
+        queue._clearPreload();
+        this.debug(`[${queue.id}] Getting stream from: ${song}`);
+        await this.handler.attachStreamInfo(song);
+        const willPlaySong = song.stream.playFromSource ? song : song.stream.song;
+        const stream = willPlaySong?.stream;
+        if (!willPlaySong || !stream?.playFromSource || !stream.url) throw new DisTubeError("NO_STREAM_URL", `${song}`);
+        this.debug(`[${queue.id}] Creating DisTubeStream for: ${willPlaySong}`);
+        const streamOptions = {
+          ffmpeg: {
+            path: this.options.ffmpeg.path,
+            args: {
+              global: { ...queue.ffmpegArgs.global },
+              input: { ...queue.ffmpegArgs.input },
+              output: { ...queue.ffmpegArgs.output, ...queue.filters.ffmpegArgs }
+            }
+          },
+          seek: willPlaySong.duration ? queue._beginTime : void 0
+        };
+        queue._beginTime = 0;
+        dtStream = new DisTubeStream(stream.url, streamOptions);
+        dtStream.on("debug", (data) => this.emit("ffmpegDebug" /* FFMPEG_DEBUG */, `[${queue.id}] ${data}`));
+      }
+      queue._beginTime = 0;
+      this.debug(`[${queue.id}] Started playing: ${song}`);
+      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) {
+        this.debug(`[${queue.id}] Error while restarting the stream: ${error.stack || error.message}`);
+        this.emitError(error, queue, queue.songs[0]);
+        return;
+      }
+      await this.#handlePlayingError(queue, error);
+    }
+  }
+  /**
+   * Schedule preloading the next song in the queue before the current song finishes.
+   * @param queue - The guild queue
+   */
+  schedulePreload(queue) {
+    if (!this.options.preload.enabled || queue.stopped || queue.paused) return;
+    if (queue._preloadTimeout) {
+      clearTimeout(queue._preloadTimeout);
+      queue._preloadTimeout = void 0;
+    }
+    const currentSong = queue.songs[0];
+    const nextSong = queue.songs[1];
+    if (!currentSong || !nextSong) return;
+    if (queue._preloadedSong === nextSong && queue._preloadedStream) return;
+    const threshold = this.options.preload.threshold;
+    const duration = currentSong.duration ?? 0;
+    const currentTime = queue.currentTime;
+    const remaining = duration > 0 && Number.isFinite(currentTime) ? duration - currentTime : 0;
+    if (duration === 0 || remaining <= threshold) {
+      void this.preloadNextSong(queue);
+    } else {
+      const delayMs = Math.max(0, (remaining - threshold) * 1e3);
+      queue._preloadTimeout = setTimeout(() => {
+        queue._preloadTimeout = void 0;
+        void this.preloadNextSong(queue);
+      }, delayMs);
+      queue._preloadTimeout.unref?.();
+    }
+  }
+  /**
+   * Preload the next song in the queue.
+   * @param queue - The guild queue
+   */
+  async preloadNextSong(queue) {
+    if (queue._preloading) return queue._preloading;
+    const task = this.#preloadTask(queue);
+    queue._preloading = task;
+    try {
+      await task;
+    } finally {
+      if (queue._preloading === task) queue._preloading = void 0;
+    }
+  }
+  async #preloadTask(queue) {
+    if (!this.options.preload.enabled || queue.stopped || queue.paused) return;
+    const nextSong = queue.songs[1];
+    if (!nextSong) return;
+    if (queue._preloadedSong === nextSong && queue._preloadedStream) return;
+    const generation = queue._preloadGeneration;
+    this.debug(`[${queue.id}] Preloading next song: ${nextSong}`);
+    this.emit("preloadSong" /* PRELOAD_SONG */, queue, nextSong);
+    try {
+      await this.handler.attachStreamInfo(nextSong);
+      if (queue.stopped || queue.songs[1] !== nextSong || generation !== queue._preloadGeneration) return;
+      const willPlaySong = nextSong.stream.playFromSource ? nextSong : nextSong.stream.song;
       const stream = willPlaySong?.stream;
-      if (!willPlaySong || !stream?.playFromSource || !stream.url) throw new DisTubeError("NO_STREAM_URL", `${song}`);
-      this.debug(`[${queue.id}] Creating DisTubeStream for: ${willPlaySong}`);
+      if (!willPlaySong || !stream?.playFromSource || !stream.url) {
+        throw new DisTubeError("NO_STREAM_URL", `${nextSong}`);
+      }
       const streamOptions = {
         ffmpeg: {
           path: this.options.ffmpeg.path,
@@ -2848,22 +3285,185 @@ var QueueManager = class extends GuildIdManager {
             output: { ...queue.ffmpegArgs.output, ...queue.filters.ffmpegArgs }
           }
         },
-        seek: willPlaySong.duration ? queue._beginTime : void 0
+        seek: void 0
       };
-      queue._beginTime = 0;
       const dtStream = new DisTubeStream(stream.url, streamOptions);
-      dtStream.on("debug", (data) => this.emit("ffmpegDebug" /* FFMPEG_DEBUG */, `[${queue.id}] ${data}`));
-      this.debug(`[${queue.id}] Started playing: ${willPlaySong}`);
-      await queue.voice.play(dtStream);
-      if (emitPlaySong) this.emit("playSong" /* PLAY_SONG */, queue, song);
+      dtStream.on("debug", (data) => this.emit("ffmpegDebug" /* FFMPEG_DEBUG */, `[${queue.id}] [preload] ${data}`));
+      if (queue.stopped || queue.songs[1] !== nextSong || generation !== queue._preloadGeneration) {
+        dtStream.kill();
+        return;
+      }
+      queue._preloadedSong = nextSong;
+      queue._preloadedStream = dtStream;
+      this.debug(`[${queue.id}] Successfully preloaded next song: ${nextSong}`);
+      this.emit("preloadedSong" /* PRELOADED_SONG */, queue, nextSong);
     } catch (e) {
+      if (queue._preloadedSong === nextSong) {
+        queue._preloadedSong = void 0;
+        queue._preloadedStream?.kill();
+        queue._preloadedStream = void 0;
+      }
       const error = e instanceof Error ? e : new Error(String(e));
-      if (options?.keepSongOnError) {
-        this.debug(`[${queue.id}] Error while restarting the stream: ${error.stack || error.message}`);
-        this.emitError(error, queue, queue.songs[0]);
+      this.debug(`[${queue.id}] Preload failed for ${nextSong}: ${error.message}`);
+      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;
       }
-      await this.#handlePlayingError(queue, error);
+      queue._crossfadeWarmup = transitionStream;
+      transitionStream.spawn();
+      const boundaryMs = Math.max(0, (remaining - 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();
+        }
+        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}`);
     }
   }
 };
@@ -3879,6 +4479,11 @@ export {
   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,
   DisTubeBase,
@@ -3894,6 +4499,7 @@ export {
   HTTP_REDIRECT_CODES,
   InfoExtractorPlugin,
   JOIN_TIMEOUT_MS,
+  MAX_CROSSFADE_DURATION_SECS,
   MAX_REDIRECT_DEPTH,
   Options,
   PlayableExtractorPlugin,