@kattowo/distube 6.0.2 → 6.2.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as discord_js from 'discord.js';
-import { Snowflake, Message, GuildTextBasedChannel, VoiceBasedChannel, VoiceState, Guild, GuildMember, Interaction, Collection, Client, ClientOptions } from 'discord.js';
+import { VoiceBasedChannel, Snowflake, Message, GuildTextBasedChannel, VoiceState, Guild, GuildMember, Interaction, Collection, Client, ClientOptions } from 'discord.js';
 import { AudioResource, AudioPlayer, VoiceConnection } from '@discordjs/voice';
 import { TypedEmitter } from 'tiny-typed-emitter';
 import { ChildProcess } from 'node:child_process';
@@ -83,7 +83,51 @@ declare enum Events {
     /**
      * Emitted to provide debug information from DisTube's operation.
      */
-    DEBUG = "debug"
+    DEBUG = "debug",
+    /**
+     * Emitted when a guild stream is paused.
+     */
+    PAUSE_SONG = "pauseSong",
+    /**
+     * Emitted when a paused guild stream is resumed.
+     */
+    RESUME_SONG = "resumeSong",
+    /**
+     * Emitted when a guild stream is seeked to a new position.
+     */
+    SEEK_SONG = "seekSong",
+    /**
+     * Emitted when the volume of a guild stream is changed.
+     */
+    SET_VOLUME = "setVolume",
+    /**
+     * Emitted after the songs of a {@link Queue} have been shuffled.
+     */
+    SHUFFLE_QUEUE = "shuffleQueue",
+    /**
+     * Emitted when a song is skipped.
+     */
+    SKIP_SONG = "skipSong",
+    /**
+     * Emitted when the audio filters of a {@link Queue} are changed.
+     */
+    CHANGE_FILTER = "changeFilter",
+    /**
+     * Emitted when the bot is moved to another voice channel.
+     */
+    VOICE_CHANNEL_CHANGE = "voiceChannelChange",
+    /**
+     * Emitted when DisTube starts pre-buffering / pre-fetching the next song in a {@link Queue}.
+     */
+    PRELOAD_SONG = "preloadSong",
+    /**
+     * Emitted when the next song in a {@link Queue} has been pre-buffered and is ready.
+     */
+    PRELOADED_SONG = "preloadedSong",
+    /**
+     * Emitted when pre-buffering the next song in a {@link Queue} fails.
+     */
+    PRELOAD_ERROR = "preloadError"
 }
 /**
  * The arguments of every {@link Events} event.
@@ -146,6 +190,50 @@ type DisTubeEvents = {
      * Emitted when a song starts playing.
      */
     [Events.PLAY_SONG]: [queue: Queue, song: Song];
+    /**
+     * Emitted when a guild stream is paused.
+     */
+    [Events.PAUSE_SONG]: [queue: Queue, song: Song];
+    /**
+     * Emitted when a paused guild stream is resumed.
+     */
+    [Events.RESUME_SONG]: [queue: Queue, song: Song];
+    /**
+     * Emitted when a guild stream is seeked to a new position.
+     */
+    [Events.SEEK_SONG]: [queue: Queue, song: Song, position: number];
+    /**
+     * Emitted when the volume of a guild stream is changed.
+     */
+    [Events.SET_VOLUME]: [queue: Queue, volume: number, oldVolume: number];
+    /**
+     * Emitted after the songs of a {@link Queue} have been shuffled.
+     */
+    [Events.SHUFFLE_QUEUE]: [queue: Queue, songs: Song[]];
+    /**
+     * Emitted when a song is skipped.
+     */
+    [Events.SKIP_SONG]: [queue: Queue, song: Song];
+    /**
+     * Emitted when the audio filters of a {@link Queue} are changed.
+     */
+    [Events.CHANGE_FILTER]: [queue: Queue, newFilters: string[], oldFilters: string[]];
+    /**
+     * Emitted when the bot is moved to another voice channel.
+     */
+    [Events.VOICE_CHANNEL_CHANGE]: [queue: Queue, oldChannel: VoiceBasedChannel, newChannel: VoiceBasedChannel];
+    /**
+     * Emitted when DisTube starts pre-buffering / pre-fetching the next song in a {@link Queue}.
+     */
+    [Events.PRELOAD_SONG]: [queue: Queue, song: Song];
+    /**
+     * Emitted when the next song in a {@link Queue} has been pre-buffered and is ready.
+     */
+    [Events.PRELOADED_SONG]: [queue: Queue, song: Song];
+    /**
+     * Emitted when pre-buffering the next song in a {@link Queue} fails.
+     */
+    [Events.PRELOAD_ERROR]: [queue: Queue, song: Song, error: Error];
 };
 /**
  * The typed event listeners of a {@link DisTube} instance.
@@ -174,6 +262,12 @@ type DisTubeVoiceEvents = {
      * Emitted when the audio player becomes idle, i.e. the song is finished.
      */
     finish: () => Awaitable;
+    /**
+     * Emitted when the connection moves to another voice channel.
+     * @param oldChannel - The previous voice channel
+     * @param newChannel - The new voice channel
+     */
+    channelChange: (oldChannel: VoiceBasedChannel, newChannel: VoiceBasedChannel) => Awaitable;
 };
 /**
  * An FFmpeg audio filter object
@@ -213,6 +307,43 @@ type FilterResolvable = string | Filter;
  * @see {@link defaultFilters}
  */
 type Filters = Record<string, string>;
+/**
+ * The validated {@link DisTubeOptions.preload} options of a {@link DisTube} instance.
+ */
+type PreloadOptions = {
+    /**
+     * Whether or not preloading is enabled.
+     */
+    enabled: boolean;
+    /**
+     * The number of seconds remaining in the currently playing song before
+     * preloading starts.
+     */
+    threshold: number;
+};
+/**
+ * The validated {@link DisTubeOptions.crossfade} options of a {@link DisTube}
+ * instance.
+ */
+type CrossfadeOptions = {
+    /**
+     * The default crossfade duration (in seconds) applied to new queues. `0`
+     * disables the crossfade. A {@link Queue} can override it at runtime through
+     * its `crossfade` property.
+     */
+    duration: number;
+    /**
+     * The FFmpeg `acrossfade` fade curve applied to both sides of the transition.
+     * @default "qsin" (equal-power)
+     */
+    curve: string;
+    /**
+     * How long (in seconds) before the fade window begins the merged transition
+     * stream is spawned, so its buffers are warm and the fade starts on time.
+     * @default 5
+     */
+    warmup: number;
+};
 /**
  * DisTube options
  */
@@ -276,6 +407,62 @@ type DisTubeOptions = {
      * @default 10000
      */
     stuckThreshold?: number;
+    /**
+     * Pre-fetch stream information and prepare the stream for the next song in
+     * the queue before the current song finishes playing, to reduce the delay
+     * between two songs.
+     *
+     * Can be a simple `boolean` to toggle it with the default threshold, or an
+     * object to configure it:
+     * - `enabled`: whether or not preloading is enabled (@default false)
+     * - `threshold`: the number of seconds remaining in the currently playing
+     *   song before preloading starts (@default 15)
+     * @default false
+     */
+    preload?: boolean | {
+        /**
+         * Whether or not preloading is enabled.
+         */
+        enabled?: boolean;
+        /**
+         * The number of seconds remaining in the currently playing song before
+         * preloading starts.
+         */
+        threshold?: number;
+    };
+    /**
+     * Crossfade the end of the current song with the beginning of the next one,
+     * instead of a hard switch between two streams.
+     *
+     * The transition is a single FFmpeg process that mixes both songs with an
+     * `acrossfade` filter, so the fade is seamless (no gaps, no extra decode
+     * round-trips). Because the fade length must be prepared in advance, the
+     * next song's stream is resolved even when preloading is disabled.
+     *
+     * Can be an object to configure it:
+     * - `duration`: the default crossfade duration in seconds for new queues
+     *   (@default 0). Each {@link Queue} can override it at runtime with its
+     *   `crossfade` property, which is what bots typically bind to a guild
+     *   setting.
+     * - `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)
+     * @default { duration: 0, curve: "qsin", warmup: 5 }
+     */
+    crossfade?: {
+        /**
+         * The default crossfade duration (in seconds) for new queues (0 disables).
+         */
+        duration?: number;
+        /**
+         * The FFmpeg `acrossfade` fade curve applied to both songs.
+         */
+        curve?: string;
+        /**
+         * Seconds before the fade window when the transition stream is spawned.
+         */
+        warmup?: number;
+    };
     /**
      * FFmpeg options
      */
@@ -714,6 +901,36 @@ declare const MAX_REDIRECT_DEPTH = 5;
  * Default DisTube audio filters.
  */
 declare const defaultFilters: Filters;
+/**
+ * Default number of seconds remaining in the currently playing song before preloading starts.
+ */
+declare const DEFAULT_PRELOAD_THRESHOLD_SECS = 15;
+/**
+ * Default crossfade duration in seconds for a {@link Queue} (0 disables the crossfade).
+ */
+declare const DEFAULT_CROSSFADE_DURATION_SECS = 0;
+/**
+ * Maximum crossfade duration in seconds a {@link Queue} may request.
+ */
+declare const MAX_CROSSFADE_DURATION_SECS = 12;
+/**
+ * Default FFmpeg `acrossfade` fade curve of the crossfade transition.
+ *
+ * `qsin` is an equal-power curve: the two songs mix without the -3dB dip of a
+ * linear (triangular) curve.
+ */
+declare const DEFAULT_CROSSFADE_CURVE = "qsin";
+/**
+ * Default number of seconds before the fade window when the merged crossfade
+ * transition stream is spawned to warm up its buffers.
+ */
+declare const DEFAULT_CROSSFADE_WARMUP_SECS = 5;
+/**
+ * How far (in seconds) the playback position may drift from the expected
+ * crossfade boundary before the transition is aborted and the regular
+ * song-switch takes over.
+ */
+declare const CROSSFADE_DRIFT_TOLERANCE_SECS = 0.75;
 /**
  * The default options of a {@link DisTube} instance.
  *
@@ -730,6 +947,12 @@ declare const defaultOptions: {
     joinNewVoiceChannel: true;
     unhandledError: "log";
     stuckThreshold: number;
+    preload: false;
+    crossfade: {
+        duration: number;
+        curve: string;
+        warmup: number;
+    };
 };
 
 /**
@@ -1112,6 +1335,16 @@ declare class Options {
      * @default 10000
      */
     stuckThreshold: number;
+    /**
+     * The preload options of the DisTube instance.
+     * @default { enabled: false, threshold: 15 }
+     */
+    preload: PreloadOptions;
+    /**
+     * The crossfade options of the DisTube instance.
+     * @default { duration: 0, curve: "qsin", warmup: 5 }
+     */
+    crossfade: CrossfadeOptions;
     /**
      * The FFmpeg options of the DisTube instance.
      */
@@ -1138,6 +1371,43 @@ interface StreamOptions {
      * @default 0
      */
     seek?: number;
+    /**
+     * Crossfade transition options.
+     *
+     * When set, the stream mixes the primary URL (the song that is fading out,
+     * seeked to its final `duration` seconds) and the secondary URL (the song
+     * that is fading in) with an FFmpeg `acrossfade` filter graph, so the two
+     * songs crossfade seamlessly in a single FFmpeg process.
+     */
+    crossfade?: CrossfadeStreamOptions;
+}
+/**
+ * Options describing a crossfade transition stream
+ */
+interface CrossfadeStreamOptions {
+    /**
+     * The fade duration in seconds.
+     */
+    duration: number;
+    /**
+     * The initial seek of the first (fading out) input, in seconds. It must be
+     * the position where the fade window begins (`song duration - duration`).
+     */
+    primarySeek: number;
+    /**
+     * The stream URL of the second (fading in) input.
+     */
+    secondaryUrl: string;
+    /**
+     * The FFmpeg `acrossfade` fade curve of the first (fading out) input.
+     * @default "qsin"
+     */
+    outCurve?: string;
+    /**
+     * The FFmpeg `acrossfade` fade curve of the second (fading in) input.
+     * @default "qsin"
+     */
+    inCurve?: string;
 }
 /**
  * Check that FFmpeg is installed and can be spawned.
@@ -1477,6 +1747,26 @@ declare class QueueManager extends GuildIdManager<Queue> {
     playSong(queue: Queue, emitPlaySong?: boolean, options?: {
         keepSongOnError?: boolean;
     }): Promise<void>;
+    /**
+     * Schedule preloading the next song in the queue before the current song finishes.
+     * @param queue - The guild queue
+     */
+    schedulePreload(queue: Queue): void;
+    /**
+     * Preload the next song in the queue.
+     * @param queue - The guild queue
+     */
+    preloadNextSong(queue: Queue): Promise<void>;
+    /**
+     * 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): void;
 }
 
 /**
@@ -2224,6 +2514,53 @@ declare class Queue extends DisTubeBase {
      * @internal
      */
     _listeners?: DisTubeVoiceEvents;
+    /**
+     * Preload timer
+     * @internal
+     */
+    _preloadTimeout?: NodeJS.Timeout;
+    /**
+     * Preloaded song
+     * @internal
+     */
+    _preloadedSong?: Song;
+    /**
+     * Preloaded stream
+     * @internal
+     */
+    _preloadedStream?: DisTubeStream;
+    /**
+     * In-flight preload task
+     * @internal
+     */
+    _preloading?: Promise<void>;
+    /**
+     * Bumped whenever the preloaded state is invalidated, so an in-flight
+     * preload task can detect that its result is no longer needed.
+     * @internal
+     */
+    _preloadGeneration: number;
+    /**
+     * Crossfade boundary timer
+     * @internal
+     */
+    _crossfadeTimeout?: NodeJS.Timeout;
+    /**
+     * The merged transition stream that is warming up before the fade window
+     * starts
+     * @internal
+     */
+    _crossfadeWarmup?: DisTubeStream;
+    /**
+     * Clear any preloaded song and cancel pending preload timer.
+     * @internal
+     */
+    _clearPreload(): void;
+    /**
+     * Cancel a pending crossfade and kill its warming-up transition stream.
+     * @internal
+     */
+    _crossfadeCancel(): void;
     /**
      * Create a queue for the guild
      * @param distube     - DisTube
@@ -2258,6 +2595,17 @@ declare class Queue extends DisTubeBase {
      * What time in the song is playing (in seconds).
      */
     get currentTime(): number;
+    /**
+     * 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(): number;
+    set crossfade(value: number);
     /**
      * Formatted {@link Queue#currentTime} string.
      */
@@ -2416,6 +2764,15 @@ declare class Queue extends DisTubeBase {
      * @throws {@link DisTubeError} When the queue has been stopped
      */
     play(emitPlaySong?: boolean): Promise<void>;
+    /**
+     * 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(): void;
     /**
      * Restart the current stream with the current FFmpeg arguments, keeping the
      * playback position.
@@ -3256,5 +3613,5 @@ declare function handleUnhandledError(error: Error, behavior?: UnhandledErrorBeh
  */
 declare const checkEncryptionLibraries: () => Promise<boolean>;
 
-export { AUDIO_CHANNELS, AUDIO_SAMPLE_RATE, BaseManager, DEFAULT_VOLUME, DisTube, DisTubeBase, DisTubeError, DisTubeHandler, DisTubeStream, DisTubeVoice, DisTubeVoiceManager, Events, ExtractorPlugin, FilterManager, GuildIdManager, HTTP_REDIRECT_CODES, InfoExtractorPlugin, JOIN_TIMEOUT_MS, 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, CustomPlaylistOptions, DisTubeEvents, DisTubeOptions, DisTubePlugin, DisTubeVoiceEvents, Disposable, FFmpegArg, FFmpegArgs, FFmpegOptions, Falsy, Filter, FilterResolvable, Filters, GuildIdResolvable, JumpOptions, KeyOf, PlayHandlerOptions, PlayOptions, PlaylistInfo, RelatedSong, ResolveOptions, ResolvePlaylistOptions, SearchOptions, SongInfo, StreamHandler, StreamOptions, StreamRequest, StreamResponse, StreamServerOptions, TypedDisTubeEvents, UnhandledErrorBehavior };
+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 };