distube 5.1.2 → 5.2.1

package/dist/index.d.mts

@@ -308,7 +308,26 @@ type FFmpegOptions = {
 };
 
 declare const version: string;
-
+/**
+ * Audio configuration constants
+ */
+declare const AUDIO_SAMPLE_RATE = 48000;
+declare const AUDIO_CHANNELS = 2;
+/**
+ * Default volume percentage (0-100)
+ */
+declare const DEFAULT_VOLUME = 50;
+/**
+ * Timeout constants (in milliseconds)
+ */
+declare const JOIN_TIMEOUT_MS = 30000;
+declare const RECONNECT_TIMEOUT_MS = 5000;
+declare const RECONNECT_MAX_ATTEMPTS = 5;
+/**
+ * HTTP redirect status codes
+ */
+declare const HTTP_REDIRECT_CODES: Set<number>;
+declare const MAX_REDIRECT_DEPTH = 5;
 /**
  * Default DisTube audio filters.
  */
@@ -567,6 +586,10 @@ declare class DisTubeStream extends TypedEmitter<{
     process?: ChildProcess;
     stream: VolumeTransformer;
     audioResource: AudioResource;
+    /**
+     * The seek time in seconds that this stream started from
+     */
+    readonly seekTime: number;
     /**
      * Create a DisTubeStream to play with {@link DisTubeVoice}
      * @param url     - Stream URL
@@ -632,9 +655,13 @@ declare class DisTubeVoice extends TypedEmitter<DisTubeVoiceEvents> {
      */
     get volume(): number;
     /**
-     * Playback duration of the audio resource in seconds
+     * Playback duration of the audio resource in seconds (time since playback started)
      */
     get playbackDuration(): number;
+    /**
+     * Current playback time in seconds, accounting for seek offset
+     */
+    get playbackTime(): number;
     pause(): void;
     unpause(): void;
     /**
@@ -829,7 +856,10 @@ declare class Queue extends DisTubeBase {
      */
     stopped: boolean;
     /**
-     * Whether or not the stream is currently playing.
+     * Whether or not the queue is active.
+     *
+     * Note: This remains `true` when paused. It only becomes `false` when stopped.
+     * @deprecated Use `!queue.paused` to check if audio is playing. Will be removed in v6.0.
      */
     playing: boolean;
     /**
@@ -856,18 +886,22 @@ declare class Queue extends DisTubeBase {
     textChannel?: GuildTextBasedChannel;
     /**
      * What time in the song to begin (in seconds).
+     * @internal
      */
     _beginTime: number;
     /**
      * Whether or not the queue is being updated manually (skip, jump, previous)
+     * @internal
      */
     _manualUpdate: boolean;
     /**
      * Task queuing system
+     * @internal
      */
     _taskQueue: TaskQueue;
     /**
      * {@link DisTubeVoice} listener
+     * @internal
      */
     _listeners?: DisTubeVoiceEvents;
     /**
@@ -918,11 +952,13 @@ declare class Queue extends DisTubeBase {
      */
     addToQueue(song: Song | Song[], position?: number): Queue;
     /**
-     * @returns `true` if the queue is playing
+     * @returns `true` if the queue is active (not stopped)
+     * @deprecated Use `!queue.paused` to check if audio is playing. Will be removed in v6.0.
      */
     isPlaying(): boolean;
     /**
      * @returns `true` if the queue is paused
+     * @deprecated Use `queue.paused` property instead. Will be removed in v6.0.
      */
     isPaused(): boolean;
     /**
@@ -980,7 +1016,13 @@ declare class Queue extends DisTubeBase {
      * @param time - Time in seconds
      * @returns The guild queue
      */
-    seek(time: number): Queue;
+    seek(time: number): Promise<Queue>;
+    /**
+     * Internal implementation of addRelatedSong without task queue protection.
+     * Used by methods that already hold the task queue lock.
+     * @internal
+     */
+    _addRelatedSong(song?: Song): Promise<Song>;
     /**
      * Add a related song of the playing song to the queue
      * @param song - The song to get related songs from. Defaults to the current playing song.
@@ -1160,17 +1202,20 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * Pause the guild stream
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).pause()` instead. Will be removed in v6.0.
      */
     pause(guild: GuildIdResolvable): Promise<Queue>;
     /**
      * Resume the guild stream
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).resume()` instead. Will be removed in v6.0.
      */
     resume(guild: GuildIdResolvable): Promise<Queue>;
     /**
      * Stop the guild stream
      * @param guild - The type can be resolved to give a {@link Queue}
+     * @deprecated Use `distube.getQueue(guild).stop()` instead. Will be removed in v6.0.
      */
     stop(guild: GuildIdResolvable): Promise<void>;
     /**
@@ -1178,6 +1223,7 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @param guild   - The type can be resolved to give a {@link Queue}
      * @param percent - The percentage of volume you want to set
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).setVolume(percent)` instead. Will be removed in v6.0.
      */
     setVolume(guild: GuildIdResolvable, percent: number): Queue;
     /**
@@ -1186,18 +1232,21 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * play a related song.</info>
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The new Song will be played
+     * @deprecated Use `distube.getQueue(guild).skip(options)` instead. Will be removed in v6.0.
      */
     skip(guild: GuildIdResolvable, options?: JumpOptions): Promise<Song>;
     /**
      * Play the previous song
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The new Song will be played
+     * @deprecated Use `distube.getQueue(guild).previous()` instead. Will be removed in v6.0.
      */
     previous(guild: GuildIdResolvable): Promise<Song>;
     /**
      * Shuffle the guild queue songs
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).shuffle()` instead. Will be removed in v6.0.
      */
     shuffle(guild: GuildIdResolvable): Promise<Queue>;
     /**
@@ -1206,6 +1255,7 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @param guild - The type can be resolved to give a {@link Queue}
      * @param num   - The song number to play
      * @returns The new Song will be played
+     * @deprecated Use `distube.getQueue(guild).jump(num, options)` instead. Will be removed in v6.0.
      */
     jump(guild: GuildIdResolvable, num: number, options?: JumpOptions): Promise<Song>;
     /**
@@ -1214,18 +1264,21 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @param guild - The type can be resolved to give a {@link Queue}
      * @param mode  - The repeat modes (toggle if `undefined`)
      * @returns The new repeat mode
+     * @deprecated Use `distube.getQueue(guild).setRepeatMode(mode)` instead. Will be removed in v6.0.
      */
     setRepeatMode(guild: GuildIdResolvable, mode?: RepeatMode): RepeatMode;
     /**
      * Toggle autoplay mode
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns Autoplay mode state
+     * @deprecated Use `distube.getQueue(guild).toggleAutoplay()` instead. Will be removed in v6.0.
      */
     toggleAutoplay(guild: GuildIdResolvable): boolean;
     /**
      * Add related song to the queue
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).addRelatedSong()` instead. Will be removed in v6.0.
      */
     addRelatedSong(guild: GuildIdResolvable): Promise<Song>;
     /**
@@ -1233,8 +1286,9 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @param guild - The type can be resolved to give a {@link Queue}
      * @param time  - Time in seconds
      * @returns Seeked queue
+     * @deprecated Use `distube.getQueue(guild).seek(time)` instead. Will be removed in v6.0.
      */
-    seek(guild: GuildIdResolvable, time: number): Queue;
+    seek(guild: GuildIdResolvable, time: number): Promise<Queue>;
     /**
      * Emit error event
      * @param error   - error
@@ -1496,4 +1550,4 @@ type Falsy = undefined | null | false | 0 | "";
 declare const isTruthy: <T>(x: T | Falsy) => x is T;
 declare const checkEncryptionLibraries: () => Promise<boolean>;
 
-export { type Awaitable, BaseManager, type CustomPlaylistOptions, DisTube, DisTubeBase, DisTubeError, type DisTubeEvents, DisTubeHandler, type DisTubeOptions, type DisTubePlugin, DisTubeStream, DisTubeVoice, type DisTubeVoiceEvents, DisTubeVoiceManager, Events, ExtractorPlugin, type FFmpegArg, type FFmpegArgs, type FFmpegOptions, type Falsy, type Filter, FilterManager, type FilterResolvable, type Filters, GuildIdManager, type GuildIdResolvable, InfoExtractorPlugin, type JumpOptions, type KeyOf, Options, type PlayHandlerOptions, type PlayOptions, PlayableExtractorPlugin, Playlist, type PlaylistInfo, Plugin, PluginType, Queue, QueueManager, type RelatedSong, RepeatMode, type ResolveOptions, type ResolvePlaylistOptions, Song, type SongInfo, type StreamOptions, TaskQueue, type TypedDisTubeEvents, checkEncryptionLibraries, checkFFmpeg, checkIntents, checkInvalidKey, DisTube as default, defaultFilters, defaultOptions, formatDuration, isClientInstance, isGuildInstance, isMemberInstance, isMessageInstance, isNsfwChannel, isObject, isSnowflake, isSupportedVoiceChannel, isTextChannelInstance, isTruthy, isURL, isVoiceChannelEmpty, objectKeys, resolveGuildId, version };
+export { AUDIO_CHANNELS, AUDIO_SAMPLE_RATE, type Awaitable, BaseManager, type CustomPlaylistOptions, DEFAULT_VOLUME, DisTube, DisTubeBase, DisTubeError, type DisTubeEvents, DisTubeHandler, type DisTubeOptions, type DisTubePlugin, DisTubeStream, DisTubeVoice, type DisTubeVoiceEvents, DisTubeVoiceManager, Events, ExtractorPlugin, type FFmpegArg, type FFmpegArgs, type FFmpegOptions, type Falsy, type Filter, FilterManager, type FilterResolvable, type Filters, GuildIdManager, type GuildIdResolvable, HTTP_REDIRECT_CODES, InfoExtractorPlugin, InfoExtractorPlugin as InfoExtratorPlugin, JOIN_TIMEOUT_MS, type JumpOptions, type KeyOf, MAX_REDIRECT_DEPTH, Options, type PlayHandlerOptions, type PlayOptions, PlayableExtractorPlugin, PlayableExtractorPlugin as PlayableExtratorPlugin, Playlist, type PlaylistInfo, Plugin, PluginType, Queue, QueueManager, RECONNECT_MAX_ATTEMPTS, RECONNECT_TIMEOUT_MS, type RelatedSong, RepeatMode, type ResolveOptions, type ResolvePlaylistOptions, Song, type SongInfo, type StreamOptions, TaskQueue, type TypedDisTubeEvents, checkEncryptionLibraries, checkFFmpeg, checkIntents, checkInvalidKey, DisTube as default, defaultFilters, defaultOptions, formatDuration, isClientInstance, isGuildInstance, isMemberInstance, isMessageInstance, isNsfwChannel, isObject, isSnowflake, isSupportedVoiceChannel, isTextChannelInstance, isTruthy, isURL, isVoiceChannelEmpty, objectKeys, resolveGuildId, version };

package/dist/index.d.ts

@@ -308,7 +308,26 @@ type FFmpegOptions = {
 };
 
 declare const version: string;
-
+/**
+ * Audio configuration constants
+ */
+declare const AUDIO_SAMPLE_RATE = 48000;
+declare const AUDIO_CHANNELS = 2;
+/**
+ * Default volume percentage (0-100)
+ */
+declare const DEFAULT_VOLUME = 50;
+/**
+ * Timeout constants (in milliseconds)
+ */
+declare const JOIN_TIMEOUT_MS = 30000;
+declare const RECONNECT_TIMEOUT_MS = 5000;
+declare const RECONNECT_MAX_ATTEMPTS = 5;
+/**
+ * HTTP redirect status codes
+ */
+declare const HTTP_REDIRECT_CODES: Set<number>;
+declare const MAX_REDIRECT_DEPTH = 5;
 /**
  * Default DisTube audio filters.
  */
@@ -567,6 +586,10 @@ declare class DisTubeStream extends TypedEmitter<{
     process?: ChildProcess;
     stream: VolumeTransformer;
     audioResource: AudioResource;
+    /**
+     * The seek time in seconds that this stream started from
+     */
+    readonly seekTime: number;
     /**
      * Create a DisTubeStream to play with {@link DisTubeVoice}
      * @param url     - Stream URL
@@ -632,9 +655,13 @@ declare class DisTubeVoice extends TypedEmitter<DisTubeVoiceEvents> {
      */
     get volume(): number;
     /**
-     * Playback duration of the audio resource in seconds
+     * Playback duration of the audio resource in seconds (time since playback started)
      */
     get playbackDuration(): number;
+    /**
+     * Current playback time in seconds, accounting for seek offset
+     */
+    get playbackTime(): number;
     pause(): void;
     unpause(): void;
     /**
@@ -829,7 +856,10 @@ declare class Queue extends DisTubeBase {
      */
     stopped: boolean;
     /**
-     * Whether or not the stream is currently playing.
+     * Whether or not the queue is active.
+     *
+     * Note: This remains `true` when paused. It only becomes `false` when stopped.
+     * @deprecated Use `!queue.paused` to check if audio is playing. Will be removed in v6.0.
      */
     playing: boolean;
     /**
@@ -856,18 +886,22 @@ declare class Queue extends DisTubeBase {
     textChannel?: GuildTextBasedChannel;
     /**
      * What time in the song to begin (in seconds).
+     * @internal
      */
     _beginTime: number;
     /**
      * Whether or not the queue is being updated manually (skip, jump, previous)
+     * @internal
      */
     _manualUpdate: boolean;
     /**
      * Task queuing system
+     * @internal
      */
     _taskQueue: TaskQueue;
     /**
      * {@link DisTubeVoice} listener
+     * @internal
      */
     _listeners?: DisTubeVoiceEvents;
     /**
@@ -918,11 +952,13 @@ declare class Queue extends DisTubeBase {
      */
     addToQueue(song: Song | Song[], position?: number): Queue;
     /**
-     * @returns `true` if the queue is playing
+     * @returns `true` if the queue is active (not stopped)
+     * @deprecated Use `!queue.paused` to check if audio is playing. Will be removed in v6.0.
      */
     isPlaying(): boolean;
     /**
      * @returns `true` if the queue is paused
+     * @deprecated Use `queue.paused` property instead. Will be removed in v6.0.
      */
     isPaused(): boolean;
     /**
@@ -980,7 +1016,13 @@ declare class Queue extends DisTubeBase {
      * @param time - Time in seconds
      * @returns The guild queue
      */
-    seek(time: number): Queue;
+    seek(time: number): Promise<Queue>;
+    /**
+     * Internal implementation of addRelatedSong without task queue protection.
+     * Used by methods that already hold the task queue lock.
+     * @internal
+     */
+    _addRelatedSong(song?: Song): Promise<Song>;
     /**
      * Add a related song of the playing song to the queue
      * @param song - The song to get related songs from. Defaults to the current playing song.
@@ -1160,17 +1202,20 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * Pause the guild stream
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).pause()` instead. Will be removed in v6.0.
      */
     pause(guild: GuildIdResolvable): Promise<Queue>;
     /**
      * Resume the guild stream
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).resume()` instead. Will be removed in v6.0.
      */
     resume(guild: GuildIdResolvable): Promise<Queue>;
     /**
      * Stop the guild stream
      * @param guild - The type can be resolved to give a {@link Queue}
+     * @deprecated Use `distube.getQueue(guild).stop()` instead. Will be removed in v6.0.
      */
     stop(guild: GuildIdResolvable): Promise<void>;
     /**
@@ -1178,6 +1223,7 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @param guild   - The type can be resolved to give a {@link Queue}
      * @param percent - The percentage of volume you want to set
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).setVolume(percent)` instead. Will be removed in v6.0.
      */
     setVolume(guild: GuildIdResolvable, percent: number): Queue;
     /**
@@ -1186,18 +1232,21 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * play a related song.</info>
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The new Song will be played
+     * @deprecated Use `distube.getQueue(guild).skip(options)` instead. Will be removed in v6.0.
      */
     skip(guild: GuildIdResolvable, options?: JumpOptions): Promise<Song>;
     /**
      * Play the previous song
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The new Song will be played
+     * @deprecated Use `distube.getQueue(guild).previous()` instead. Will be removed in v6.0.
      */
     previous(guild: GuildIdResolvable): Promise<Song>;
     /**
      * Shuffle the guild queue songs
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).shuffle()` instead. Will be removed in v6.0.
      */
     shuffle(guild: GuildIdResolvable): Promise<Queue>;
     /**
@@ -1206,6 +1255,7 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @param guild - The type can be resolved to give a {@link Queue}
      * @param num   - The song number to play
      * @returns The new Song will be played
+     * @deprecated Use `distube.getQueue(guild).jump(num, options)` instead. Will be removed in v6.0.
      */
     jump(guild: GuildIdResolvable, num: number, options?: JumpOptions): Promise<Song>;
     /**
@@ -1214,18 +1264,21 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @param guild - The type can be resolved to give a {@link Queue}
      * @param mode  - The repeat modes (toggle if `undefined`)
      * @returns The new repeat mode
+     * @deprecated Use `distube.getQueue(guild).setRepeatMode(mode)` instead. Will be removed in v6.0.
      */
     setRepeatMode(guild: GuildIdResolvable, mode?: RepeatMode): RepeatMode;
     /**
      * Toggle autoplay mode
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns Autoplay mode state
+     * @deprecated Use `distube.getQueue(guild).toggleAutoplay()` instead. Will be removed in v6.0.
      */
     toggleAutoplay(guild: GuildIdResolvable): boolean;
     /**
      * Add related song to the queue
      * @param guild - The type can be resolved to give a {@link Queue}
      * @returns The guild queue
+     * @deprecated Use `distube.getQueue(guild).addRelatedSong()` instead. Will be removed in v6.0.
      */
     addRelatedSong(guild: GuildIdResolvable): Promise<Song>;
     /**
@@ -1233,8 +1286,9 @@ declare class DisTube extends TypedEmitter<TypedDisTubeEvents> {
      * @param guild - The type can be resolved to give a {@link Queue}
      * @param time  - Time in seconds
      * @returns Seeked queue
+     * @deprecated Use `distube.getQueue(guild).seek(time)` instead. Will be removed in v6.0.
      */
-    seek(guild: GuildIdResolvable, time: number): Queue;
+    seek(guild: GuildIdResolvable, time: number): Promise<Queue>;
     /**
      * Emit error event
      * @param error   - error
@@ -1498,4 +1552,4 @@ declare const checkEncryptionLibraries: () => Promise<boolean>;
 
 // @ts-ignore
 export = DisTube;
-export { type Awaitable, BaseManager, type CustomPlaylistOptions, DisTube, DisTubeBase, DisTubeError, type DisTubeEvents, DisTubeHandler, type DisTubeOptions, type DisTubePlugin, DisTubeStream, DisTubeVoice, type DisTubeVoiceEvents, DisTubeVoiceManager, Events, ExtractorPlugin, type FFmpegArg, type FFmpegArgs, type FFmpegOptions, type Falsy, type Filter, FilterManager, type FilterResolvable, type Filters, GuildIdManager, type GuildIdResolvable, InfoExtractorPlugin, type JumpOptions, type KeyOf, Options, type PlayHandlerOptions, type PlayOptions, PlayableExtractorPlugin, Playlist, type PlaylistInfo, Plugin, PluginType, Queue, QueueManager, type RelatedSong, RepeatMode, type ResolveOptions, type ResolvePlaylistOptions, Song, type SongInfo, type StreamOptions, TaskQueue, type TypedDisTubeEvents, checkEncryptionLibraries, checkFFmpeg, checkIntents, checkInvalidKey, defaultFilters, defaultOptions, formatDuration, isClientInstance, isGuildInstance, isMemberInstance, isMessageInstance, isNsfwChannel, isObject, isSnowflake, isSupportedVoiceChannel, isTextChannelInstance, isTruthy, isURL, isVoiceChannelEmpty, objectKeys, resolveGuildId, version };
+export { AUDIO_CHANNELS, AUDIO_SAMPLE_RATE, type Awaitable, BaseManager, type CustomPlaylistOptions, DEFAULT_VOLUME, DisTube, DisTubeBase, DisTubeError, type DisTubeEvents, DisTubeHandler, type DisTubeOptions, type DisTubePlugin, DisTubeStream, DisTubeVoice, type DisTubeVoiceEvents, DisTubeVoiceManager, Events, ExtractorPlugin, type FFmpegArg, type FFmpegArgs, type FFmpegOptions, type Falsy, type Filter, FilterManager, type FilterResolvable, type Filters, GuildIdManager, type GuildIdResolvable, HTTP_REDIRECT_CODES, InfoExtractorPlugin, InfoExtractorPlugin as InfoExtratorPlugin, JOIN_TIMEOUT_MS, type JumpOptions, type KeyOf, MAX_REDIRECT_DEPTH, Options, type PlayHandlerOptions, type PlayOptions, PlayableExtractorPlugin, PlayableExtractorPlugin as PlayableExtratorPlugin, Playlist, type PlaylistInfo, Plugin, PluginType, Queue, QueueManager, RECONNECT_MAX_ATTEMPTS, RECONNECT_TIMEOUT_MS, type RelatedSong, RepeatMode, type ResolveOptions, type ResolvePlaylistOptions, Song, type SongInfo, type StreamOptions, TaskQueue, type TypedDisTubeEvents, checkEncryptionLibraries, checkFFmpeg, checkIntents, checkInvalidKey, defaultFilters, defaultOptions, formatDuration, isClientInstance, isGuildInstance, isMemberInstance, isMessageInstance, isNsfwChannel, isObject, isSnowflake, isSupportedVoiceChannel, isTextChannelInstance, isTruthy, isURL, isVoiceChannelEmpty, objectKeys, resolveGuildId, version };