@kattowo/distube 6.0.2 → 6.1.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.1.0";
 var AUDIO_SAMPLE_RATE = 48e3;
 var AUDIO_CHANNELS = 2;
 var DEFAULT_VOLUME = 50;
@@ -29,6 +29,7 @@ var defaultFilters = {
   surround: "surround",
   earwax: "earwax"
 };
+var DEFAULT_PRELOAD_THRESHOLD_SECS = 15;
 var defaultOptions = {
   plugins: [],
   emitNewSongOnly: false,
@@ -38,7 +39,8 @@ var defaultOptions = {
   emitAddListWhenCreatingQueue: true,
   joinNewVoiceChannel: true,
   unhandledError: "log",
-  stuckThreshold: STUCK_THRESHOLD_MS
+  stuckThreshold: STUCK_THRESHOLD_MS,
+  preload: false
 };
 
 // src/core/DisTubeBase.ts
@@ -615,7 +617,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 +685,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({
@@ -965,7 +978,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 +1002,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 +1012,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 +1031,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 +1050,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 +1109,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 +1253,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 +1269,48 @@ 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;
+  /**
+   * Clear any preloaded song and cancel pending preload timer.
+   * @internal
+   */
+  _clearPreload() {
+    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;
+  }
   /**
    * Create a queue for the guild
    * @param distube     - DisTube
@@ -1263,6 +1339,7 @@ var Queue = class extends DisTubeBase {
       input: { ...this.options.ffmpeg.args.input },
       output: { ...this.options.ffmpeg.args.output }
     };
+    this.#initialized = true;
   }
   #addToPreviousSongs(songs) {
     if (Array.isArray(songs)) {
@@ -1345,7 +1422,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 +1455,7 @@ var Queue = class extends DisTubeBase {
     } else {
       this.songs.splice(position, 0, song);
     }
+    this.queues?.schedulePreload?.(this);
     return this;
   }
   /**
@@ -1391,7 +1473,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 +1496,8 @@ 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);
       return this;
     } finally {
       this._taskQueue.resolve();
@@ -1476,11 +1562,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 +1607,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 +1653,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 +1727,7 @@ var Queue = class extends DisTubeBase {
    * @returns Nothing
    */
   remove() {
+    this._clearPreload();
     this.paused = true;
     this.stopped = true;
     this.songs = [];
@@ -2307,6 +2401,11 @@ var Options = class {
    * @default 10000
    */
   stuckThreshold;
+  /**
+   * The preload options of the DisTube instance.
+   * @default { enabled: false, threshold: 15 }
+   */
+  preload;
   /**
    * The FFmpeg options of the DisTube instance.
    */
@@ -2332,10 +2431,34 @@ var Options = class {
     this.joinNewVoiceChannel = opts.joinNewVoiceChannel;
     this.unhandledError = opts.unhandledError;
     this.stuckThreshold = opts.stuckThreshold;
+    this.preload = this.#preloadOption(opts.preload);
     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
+    };
+  }
   #validateOptions(options = this) {
     const booleanOptions = /* @__PURE__ */ new Set([
       "emitNewSongOnly",
@@ -2347,7 +2470,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"]);
     const optionalOptions = /* @__PURE__ */ new Set(["customFilters"]);
     for (const [key, value] of Object.entries(options)) {
       if (value === void 0 && optionalOptions.has(key)) continue;
@@ -2735,7 +2858,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 +2959,109 @@ 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);
+    } 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 +3071,27 @@ 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);
-    } 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]);
+      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;
       }
-      await this.#handlePlayingError(queue, error);
+      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));
+      this.debug(`[${queue.id}] Preload failed for ${nextSong}: ${error.message}`);
+      this.emit("preloadError" /* PRELOAD_ERROR */, queue, nextSong, error);
     }
   }
 };
@@ -3879,6 +4107,7 @@ export {
   AUDIO_CHANNELS,
   AUDIO_SAMPLE_RATE,
   BaseManager,
+  DEFAULT_PRELOAD_THRESHOLD_SECS,
   DEFAULT_VOLUME,
   DisTube,
   DisTubeBase,