@kattowo/distube 6.0.1 → 6.1.0

package/dist/index.d.ts

@@ -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,20 @@ 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;
+};
 /**
  * DisTube options
  */
@@ -276,6 +384,29 @@ 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;
+    };
     /**
      * FFmpeg options
      */
@@ -321,7 +452,7 @@ interface SongInfo<T = unknown> {
      */
     plugin: DisTubePlugin | null;
     /**
-     * The identifier of the source of the song, e.g. `youtube`.
+     * The identifier of the source of the song, e.g. `my-source`.
      */
     source: string;
     /**
@@ -405,7 +536,7 @@ interface SongInfo<T = unknown> {
  */
 interface PlaylistInfo {
     /**
-     * The identifier of the source of the playlist, e.g. `youtube`.
+     * The identifier of the source of the playlist, e.g. `my-source`.
      */
     source: string;
     /**
@@ -714,6 +845,10 @@ 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;
 /**
  * The default options of a {@link DisTube} instance.
  *
@@ -730,6 +865,7 @@ declare const defaultOptions: {
     joinNewVoiceChannel: true;
     unhandledError: "log";
     stuckThreshold: number;
+    preload: false;
 };
 
 /**
@@ -1112,6 +1248,11 @@ declare class Options {
      * @default 10000
      */
     stuckThreshold: number;
+    /**
+     * The preload options of the DisTube instance.
+     * @default { enabled: false, threshold: 15 }
+     */
+    preload: PreloadOptions;
     /**
      * The FFmpeg options of the DisTube instance.
      */
@@ -1477,6 +1618,16 @@ 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>;
 }
 
 /**
@@ -2224,6 +2375,37 @@ 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;
+    /**
+     * Clear any preloaded song and cancel pending preload timer.
+     * @internal
+     */
+    _clearPreload(): void;
     /**
      * Create a queue for the guild
      * @param distube     - DisTube
@@ -2651,7 +2833,7 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @returns The DisTube instance
      * @example
      * ```ts
-     * const distube = await DisTube.create(client, { plugins: [new YoutubePlugin()] });
+     * const distube = await DisTube.create(client, { plugins: [new MyPlugin()] });
      * ```
      */
     static create(client: Client, opts?: DisTubeOptions): Promise<DisTube>;
@@ -2716,12 +2898,12 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      *
      * It matches the {@link Plugin.source} of the plugin, or one of its
      * {@link Plugin.aliases}. The identifier of the class is used when the
-     * plugin does not define a source (`YoutubePlugin` -> `youtube`).
+     * plugin does not define a source (`MyPlugin` -> `myplugin`).
      * @param source - The identifier of the source
      * @returns The plugin, or `undefined` when there is none
      * @example
      * ```ts
-     * const plugin = distube.getPlugin("youtube");
+     * const plugin = distube.getPlugin("myplugin");
      * ```
      */
     getPlugin(source: string): DisTubePlugin | undefined;
@@ -2844,7 +3026,7 @@ declare abstract class Plugin {
      * The identifier of the source of the plugin.
      *
      * It defaults to the name of the class, lowercased, without the `Plugin`
-     * suffix (`YoutubePlugin` -> `youtube`).
+     * suffix (`MyPlugin` -> `myplugin`).
      *
      * It is used to route a search to a plugin, and to find a plugin with
      * {@link DisTube#getPlugin}.
@@ -2983,7 +3165,7 @@ declare abstract class ExtractorPlugin extends Plugin {
     abstract resolve<T>(url: string, options: ResolveOptions<T>): Awaitable<Song<T> | Playlist<T>>;
     /**
      * Get the stream url from {@link Song#url}. Returns {@link Song#url} by default.
-     * Not needed if the plugin plays song from YouTube.
+     * Not needed if the plugin plays the song itself.
      * @param song - Input song
      * @returns The url of the audio stream
      */
@@ -3056,7 +3238,7 @@ declare abstract class PlayableExtractorPlugin extends ExtractorPlugin {
     abstract resolve<T>(url: string, options: ResolveOptions<T>): Awaitable<Song<T> | Playlist<T>>;
     /**
      * Get the stream url from {@link Song#url}. Returns {@link Song#url} by default.
-     * Not needed if the plugin plays song from YouTube.
+     * Not needed if the plugin plays the song itself.
      * @param song - Input song
      * @returns The url of the audio stream
      */
@@ -3258,5 +3440,5 @@ declare const checkEncryptionLibraries: () => Promise<boolean>;
 
 // @ts-ignore
 export = DisTube;
-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, 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, 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_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, 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 };