@kattowo/distube 6.2.0 → 6.2.2

package/dist/index.d.mts

@@ -343,7 +343,49 @@ type CrossfadeOptions = {
      * @default 5
      */
     warmup: number;
+    /**
+     * Prepare the fading-out song's playback input for the crossfade FFmpeg
+     * process. It is invoked right before the transition stream is spawned,
+     * with the song's stream url and the position (in seconds, counted from the
+     * beginning of the song) where the fade window begins.
+     *
+     * Streaming inputs that cannot fast-seek (for example HLS playlists) force
+     * FFmpeg to re-download the whole stream and discard everything before the
+     * seek position, which can miss the swap window on slow sources. The
+     * adapter can return a replacement input that starts near the boundary —
+     * a local playlist trimmed to the fade position, for example — along with
+     * the seek offset inside it and its own FFmpeg input options. Return `null`
+     * or `undefined` to use the url as-is.
+     */
+    preparePrimaryInput?: PrepareCrossfadeInput;
+};
+/**
+ * The replacement input returned by {@link CrossfadeOptions.preparePrimaryInput}.
+ */
+type PreparedCrossfadeInput = {
+    /**
+     * The replacement input url or path, for example a local playlist file
+     * trimmed to start at the fade boundary.
+     */
+    url: string;
+    /**
+     * The initial seek of the replacement input, in seconds relative to it.
+     * When omitted, the input is assumed to start exactly at the fade boundary.
+     */
+    seek?: number;
+    /**
+     * FFmpeg input options of the replacement input. They replace the default
+     * input options, which are tuned for http(s) streaming urls.
+     */
+    inputArgs?: FFmpegArg;
 };
+/**
+ * The {@link CrossfadeOptions.preparePrimaryInput} adapter type.
+ */
+type PrepareCrossfadeInput = (url: string, boundary: {
+    seek: number;
+    song: Song;
+}) => Awaitable<PreparedCrossfadeInput | null | undefined>;
 /**
  * DisTube options
  */
@@ -447,6 +489,9 @@ type DisTubeOptions = {
      * - `curve`: the FFmpeg `acrossfade` fade curve (@default "qsin")
      * - `warmup`: seconds before the fade window when the transition stream is
      *   spawned to warm up its buffers (@default 5)
+     * - `preparePrimaryInput`: an optional adapter preparing the fading-out
+     *   song's FFmpeg input before the transition stream is spawned. Useful for
+     *   streaming inputs that cannot fast-seek ({@link CrossfadeOptions.preparePrimaryInput}).
      * @default { duration: 0, curve: "qsin", warmup: 5 }
      */
     crossfade?: {
@@ -462,6 +507,11 @@ type DisTubeOptions = {
          * Seconds before the fade window when the transition stream is spawned.
          */
         warmup?: number;
+        /**
+         * Optional adapter preparing the fading-out song's FFmpeg input
+         * ({@link CrossfadeOptions.preparePrimaryInput}).
+         */
+        preparePrimaryInput?: PrepareCrossfadeInput;
     };
     /**
      * FFmpeg options
@@ -1408,6 +1458,14 @@ interface CrossfadeStreamOptions {
      * @default "qsin"
      */
     inCurve?: string;
+    /**
+     * FFmpeg input options of the first (fading out) input. When set, they
+     * replace the default input options, which are tuned for http(s) streaming
+     * urls. Use it for inputs that need different flags — a local playlist
+     * file, for example, requires the `protocol_whitelist` option and no
+     * reconnect flags.
+     */
+    primaryInputArgs?: FFmpegArg;
 }
 /**
  * Check that FFmpeg is installed and can be spawned.
@@ -1444,6 +1502,15 @@ declare class DisTubeStream extends TypedEmitter<{
      * The seek time in seconds that this stream started from
      */
     readonly seekTime: number;
+    /**
+     * 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(): boolean;
     /**
      * Create a DisTubeStream to play with {@link DisTubeVoice}
      * @param url     - Stream URL
@@ -3614,4 +3681,4 @@ declare function handleUnhandledError(error: Error, behavior?: UnhandledErrorBeh
 declare const checkEncryptionLibraries: () => Promise<boolean>;
 
 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, DisTubeError, DisTubeHandler, DisTubeStream, DisTubeVoice, DisTubeVoiceManager, Events, ExtractorPlugin, FilterManager, GuildIdManager, HTTP_REDIRECT_CODES, InfoExtractorPlugin, JOIN_TIMEOUT_MS, MAX_CROSSFADE_DURATION_SECS, MAX_REDIRECT_DEPTH, Options, PlayableExtractorPlugin, Playlist, Plugin, PluginError, PluginErrorCode, PluginType, Queue, QueueManager, RECONNECT_MAX_ATTEMPTS, RECONNECT_TIMEOUT_MS, RepeatMode, STUCK_THRESHOLD_MS, SearchResult, SearchResultType, Song, StreamServer, TaskQueue, checkEncryptionLibraries, checkFFmpeg, checkIntents, checkInvalidKey, DisTube as default, defaultFilters, defaultOptions, formatDuration, handleUnhandledError, isClientInstance, isGuildInstance, isMemberInstance, isMessageInstance, isNsfwChannel, isObject, isSnowflake, isSupportedVoiceChannel, isTextChannelInstance, isTruthy, isURL, isVoiceChannelEmpty, objectKeys, resolveGuildId, version };
-export type { Awaitable, CrossfadeOptions, CrossfadeStreamOptions, CustomPlaylistOptions, DisTubeEvents, DisTubeOptions, DisTubePlugin, DisTubeVoiceEvents, Disposable, FFmpegArg, FFmpegArgs, FFmpegOptions, Falsy, Filter, FilterResolvable, Filters, GuildIdResolvable, JumpOptions, KeyOf, PlayHandlerOptions, PlayOptions, PlaylistInfo, PreloadOptions, RelatedSong, ResolveOptions, ResolvePlaylistOptions, SearchOptions, SongInfo, StreamHandler, StreamOptions, StreamRequest, StreamResponse, StreamServerOptions, TypedDisTubeEvents, UnhandledErrorBehavior };
+export type { Awaitable, CrossfadeOptions, CrossfadeStreamOptions, CustomPlaylistOptions, DisTubeEvents, DisTubeOptions, DisTubePlugin, DisTubeVoiceEvents, Disposable, FFmpegArg, FFmpegArgs, FFmpegOptions, Falsy, Filter, FilterResolvable, Filters, GuildIdResolvable, JumpOptions, KeyOf, PlayHandlerOptions, PlayOptions, PlaylistInfo, PreloadOptions, PrepareCrossfadeInput, PreparedCrossfadeInput, RelatedSong, ResolveOptions, ResolvePlaylistOptions, SearchOptions, SongInfo, StreamHandler, StreamOptions, StreamRequest, StreamResponse, StreamServerOptions, TypedDisTubeEvents, UnhandledErrorBehavior };

package/dist/index.d.ts

@@ -343,7 +343,49 @@ type CrossfadeOptions = {
      * @default 5
      */
     warmup: number;
+    /**
+     * Prepare the fading-out song's playback input for the crossfade FFmpeg
+     * process. It is invoked right before the transition stream is spawned,
+     * with the song's stream url and the position (in seconds, counted from the
+     * beginning of the song) where the fade window begins.
+     *
+     * Streaming inputs that cannot fast-seek (for example HLS playlists) force
+     * FFmpeg to re-download the whole stream and discard everything before the
+     * seek position, which can miss the swap window on slow sources. The
+     * adapter can return a replacement input that starts near the boundary —
+     * a local playlist trimmed to the fade position, for example — along with
+     * the seek offset inside it and its own FFmpeg input options. Return `null`
+     * or `undefined` to use the url as-is.
+     */
+    preparePrimaryInput?: PrepareCrossfadeInput;
+};
+/**
+ * The replacement input returned by {@link CrossfadeOptions.preparePrimaryInput}.
+ */
+type PreparedCrossfadeInput = {
+    /**
+     * The replacement input url or path, for example a local playlist file
+     * trimmed to start at the fade boundary.
+     */
+    url: string;
+    /**
+     * The initial seek of the replacement input, in seconds relative to it.
+     * When omitted, the input is assumed to start exactly at the fade boundary.
+     */
+    seek?: number;
+    /**
+     * FFmpeg input options of the replacement input. They replace the default
+     * input options, which are tuned for http(s) streaming urls.
+     */
+    inputArgs?: FFmpegArg;
 };
+/**
+ * The {@link CrossfadeOptions.preparePrimaryInput} adapter type.
+ */
+type PrepareCrossfadeInput = (url: string, boundary: {
+    seek: number;
+    song: Song;
+}) => Awaitable<PreparedCrossfadeInput | null | undefined>;
 /**
  * DisTube options
  */
@@ -447,6 +489,9 @@ type DisTubeOptions = {
      * - `curve`: the FFmpeg `acrossfade` fade curve (@default "qsin")
      * - `warmup`: seconds before the fade window when the transition stream is
      *   spawned to warm up its buffers (@default 5)
+     * - `preparePrimaryInput`: an optional adapter preparing the fading-out
+     *   song's FFmpeg input before the transition stream is spawned. Useful for
+     *   streaming inputs that cannot fast-seek ({@link CrossfadeOptions.preparePrimaryInput}).
      * @default { duration: 0, curve: "qsin", warmup: 5 }
      */
     crossfade?: {
@@ -462,6 +507,11 @@ type DisTubeOptions = {
          * Seconds before the fade window when the transition stream is spawned.
          */
         warmup?: number;
+        /**
+         * Optional adapter preparing the fading-out song's FFmpeg input
+         * ({@link CrossfadeOptions.preparePrimaryInput}).
+         */
+        preparePrimaryInput?: PrepareCrossfadeInput;
     };
     /**
      * FFmpeg options
@@ -1408,6 +1458,14 @@ interface CrossfadeStreamOptions {
      * @default "qsin"
      */
     inCurve?: string;
+    /**
+     * FFmpeg input options of the first (fading out) input. When set, they
+     * replace the default input options, which are tuned for http(s) streaming
+     * urls. Use it for inputs that need different flags — a local playlist
+     * file, for example, requires the `protocol_whitelist` option and no
+     * reconnect flags.
+     */
+    primaryInputArgs?: FFmpegArg;
 }
 /**
  * Check that FFmpeg is installed and can be spawned.
@@ -1444,6 +1502,15 @@ declare class DisTubeStream extends TypedEmitter<{
      * The seek time in seconds that this stream started from
      */
     readonly seekTime: number;
+    /**
+     * 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(): boolean;
     /**
      * Create a DisTubeStream to play with {@link DisTubeVoice}
      * @param url     - Stream URL
@@ -3616,4 +3683,4 @@ declare const checkEncryptionLibraries: () => Promise<boolean>;
 // @ts-ignore
 export = DisTube;
 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, DisTubeError, DisTubeHandler, DisTubeStream, DisTubeVoice, DisTubeVoiceManager, Events, ExtractorPlugin, FilterManager, GuildIdManager, HTTP_REDIRECT_CODES, InfoExtractorPlugin, JOIN_TIMEOUT_MS, MAX_CROSSFADE_DURATION_SECS, MAX_REDIRECT_DEPTH, Options, PlayableExtractorPlugin, Playlist, Plugin, PluginError, PluginErrorCode, PluginType, Queue, QueueManager, RECONNECT_MAX_ATTEMPTS, RECONNECT_TIMEOUT_MS, RepeatMode, STUCK_THRESHOLD_MS, SearchResult, SearchResultType, Song, StreamServer, TaskQueue, checkEncryptionLibraries, checkFFmpeg, checkIntents, checkInvalidKey, defaultFilters, defaultOptions, formatDuration, handleUnhandledError, isClientInstance, isGuildInstance, isMemberInstance, isMessageInstance, isNsfwChannel, isObject, isSnowflake, isSupportedVoiceChannel, isTextChannelInstance, isTruthy, isURL, isVoiceChannelEmpty, objectKeys, resolveGuildId, version };
-export type { Awaitable, CrossfadeOptions, CrossfadeStreamOptions, CustomPlaylistOptions, DisTubeEvents, DisTubeOptions, DisTubePlugin, DisTubeVoiceEvents, Disposable, FFmpegArg, FFmpegArgs, FFmpegOptions, Falsy, Filter, FilterResolvable, Filters, GuildIdResolvable, JumpOptions, KeyOf, PlayHandlerOptions, PlayOptions, PlaylistInfo, PreloadOptions, RelatedSong, ResolveOptions, ResolvePlaylistOptions, SearchOptions, SongInfo, StreamHandler, StreamOptions, StreamRequest, StreamResponse, StreamServerOptions, TypedDisTubeEvents, UnhandledErrorBehavior };
+export type { Awaitable, CrossfadeOptions, CrossfadeStreamOptions, CustomPlaylistOptions, DisTubeEvents, DisTubeOptions, DisTubePlugin, DisTubeVoiceEvents, Disposable, FFmpegArg, FFmpegArgs, FFmpegOptions, Falsy, Filter, FilterResolvable, Filters, GuildIdResolvable, JumpOptions, KeyOf, PlayHandlerOptions, PlayOptions, PlaylistInfo, PreloadOptions, PrepareCrossfadeInput, PreparedCrossfadeInput, RelatedSong, ResolveOptions, ResolvePlaylistOptions, SearchOptions, SongInfo, StreamHandler, StreamOptions, StreamRequest, StreamResponse, StreamServerOptions, TypedDisTubeEvents, UnhandledErrorBehavior };

package/dist/index.js

@@ -102,7 +102,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/constant.ts
-var version = "6.2.0";
+var version = "6.2.2";
 var AUDIO_SAMPLE_RATE = 48e3;
 var AUDIO_CHANNELS = 2;
 var DEFAULT_VOLUME = 50;
@@ -2641,8 +2641,8 @@ var Options = class {
     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;
+    checkInvalidKey(value, ["duration", "curve", "warmup", "preparePrimaryInput"], "DisTubeOptions.crossfade");
+    const { duration, curve, warmup, preparePrimaryInput } = value;
     if (duration !== void 0 && (typeof duration !== "number" || Number.isNaN(duration) || duration < 0)) {
       throw new DisTubeError(
         "INVALID_TYPE",
@@ -2665,10 +2665,19 @@ var Options = class {
     if (warmup !== void 0 && (typeof warmup !== "number" || Number.isNaN(warmup) || warmup < 0)) {
       throw new DisTubeError("INVALID_TYPE", "number >= 0", warmup, "DisTubeOptions.crossfade.warmup");
     }
+    if (preparePrimaryInput !== void 0 && typeof preparePrimaryInput !== "function") {
+      throw new DisTubeError(
+        "INVALID_TYPE",
+        "function",
+        preparePrimaryInput,
+        "DisTubeOptions.crossfade.preparePrimaryInput"
+      );
+    }
     return {
       duration: duration ?? DEFAULT_CROSSFADE_DURATION_SECS,
       curve: curve ?? DEFAULT_CROSSFADE_CURVE,
-      warmup: warmup ?? DEFAULT_CROSSFADE_WARMUP_SECS
+      warmup: warmup ?? DEFAULT_CROSSFADE_WARMUP_SECS,
+      preparePrimaryInput
     };
   }
   #validateOptions(options = this) {
@@ -2793,6 +2802,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
@@ -2880,13 +2900,15 @@ var DisTubeStream = class extends import_tiny_typed_emitter2.TypedEmitter {
     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,
+      ...crossfade.primaryInputArgs ?? {
+        reconnect: 1,
+        reconnect_streamed: 1,
+        reconnect_delay_max: 5,
+        analyzeduration: 0,
+        ...ffmpeg.args.input
+      },
       ss: typeof primarySeek === "number" && primarySeek > 0 ? primarySeek.toString() : null,
       i: url
     };
@@ -3465,7 +3487,28 @@ var QueueManager = class extends GuildIdManager {
       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, {
+      const boundarySeek = Math.max(0, songDuration - fade);
+      let primaryUrl = primary.stream.url;
+      let primarySeek = boundarySeek;
+      let primaryInputArgs;
+      const prepare = this.options.crossfade.preparePrimaryInput;
+      if (prepare) {
+        try {
+          const prepared = await prepare(primary.stream.url, { seek: boundarySeek, song });
+          if (prepared?.url) {
+            primaryUrl = prepared.url;
+            if (typeof prepared.seek === "number" && Number.isFinite(prepared.seek) && prepared.seek >= 0) {
+              primarySeek = prepared.seek;
+            }
+            primaryInputArgs = prepared.inputArgs;
+            this.debug(`[${queue.id}] Crossfade primary input prepared by the adapter`);
+          }
+        } catch (e) {
+          const errorMessage = e instanceof Error ? e.message : String(e);
+          this.debug(`[${queue.id}] Crossfade primary input preparation failed: ${errorMessage}`);
+        }
+      }
+      transitionStream = new DisTubeStream(primaryUrl, {
         ffmpeg: {
           path: this.options.ffmpeg.path,
           args: {
@@ -3476,10 +3519,11 @@ var QueueManager = class extends GuildIdManager {
         },
         crossfade: {
           duration: fade,
-          primarySeek: Math.max(0, songDuration - fade),
+          primarySeek,
           secondaryUrl: secondary.stream.url,
           inCurve: this.options.crossfade.curve,
-          outCurve: this.options.crossfade.curve
+          outCurve: this.options.crossfade.curve,
+          primaryInputArgs
         }
       });
       transitionStream.on("debug", (data) => this.emit("ffmpegDebug" /* FFMPEG_DEBUG */, `[${queue.id}] [crossfade] ${data}`));
@@ -3489,7 +3533,7 @@ var QueueManager = class extends GuildIdManager {
       }
       queue._crossfadeWarmup = transitionStream;
       transitionStream.spawn();
-      const boundaryMs = Math.max(0, (remaining - fade) * 1e3);
+      const boundaryMs = Math.max(0, (songDuration - queue.currentTime - fade) * 1e3);
       queue._crossfadeTimeout = setTimeout(() => {
         queue._crossfadeTimeout = void 0;
         void this.#crossfadeSwapTask(queue, transitionStream);
@@ -3527,6 +3571,10 @@ var QueueManager = class extends GuildIdManager {
         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;