discord-player 7.0.0-dev.2 → 7.0.0-dev.4

package/README.md

@@ -8,26 +8,24 @@ Discord Player is a robust framework for developing Discord Music bots using Jav
 
 # Why Choose Discord Player?
 
--   Beginner-friendly with easy-to-understand features
--   TypeScript support
--   Offers hackable APIs.
--   Supports audio player sharing
--   Quick and easy setup process
--   Wide range of player management features
--   Offers 64+ built-in audio filter presets
--   Highly customizable according to your needs
--   Automatic queue management
--   Query caching support
--   Extensible sources through the Extractors API
--   Object-oriented design
--   Built-in stats tracker
--   Offers easy debugging methods
--   Out-of-the-box voice states handling
--   IP Rotation support
--   Easy serialization and deserialization
--   Limited support for [Eris](https://npmjs.com/eris)
-
-> Eris compat mode does not support `VoiceStateUpdate` handler. You need to handle it manually.
+- Beginner-friendly with easy-to-understand features
+- TypeScript support
+- Offers hackable APIs.
+- Supports audio player sharing
+- Quick and easy setup process
+- Wide range of player management features
+- Offers 64+ built-in audio filter presets
+- Highly customizable according to your needs
+- Automatic queue management
+- Query caching support
+- Extensible sources through the Extractors API
+- Object-oriented design
+- Built-in stats tracker
+- Offers easy debugging methods
+- Out-of-the-box voice states handling
+- IP Rotation support
+- Easy serialization and deserialization
+- Limited support for [Eris](https://npmjs.com/eris)
 
 ## Installation
 
@@ -42,30 +40,12 @@ $ npm install --save discord-player # main library
 $ npm install --save @discord-player/extractor # extractors provider
 ```
 
-> Discord Player recognizes `@discord-player/extractor` and loads it automatically by default. Just invoke `await player.extractors.loadDefault()`.
-
 #### Opus Library
 
-Since Discord only accepts opus packets, you need to install the opus library. Discord Player supports multiple opus libraries, such as:
-
--   [mediaplex](https://npmjs.com/mediaplex)
--   [@discordjs/opus](https://npmjs.com/@discordjs/opus)
--   [opusscript](https://npmjs.com/opusscript)
--   [@evan/opus](https://npmjs.com/@evan/opus)
--   [node-opus](https://npmjs.com/node-opus)
-
-Among these, mediaplex is the recommended library as it adds more functionalities to discord-player than just libopus interface. You can install opus libraries by running:
+We recommend mediaplex for libopus. Mediaplex also helps with audio metadata extraction.
 
 ```bash
 $ npm install --save mediaplex
-# or
-$ npm install --save @discordjs/opus
-# or
-$ npm install --save opusscript
-# or
-$ npm install --save @evan/opus
-# or
-$ npm install --save node-opus
 ```
 
 #### FFmpeg or Avconv
@@ -92,17 +72,18 @@ Let's create a main player instance. This instance handles and keeps track of al
 
 ```js index.js
 const { Player } = require('discord-player');
+const { DefaultExtractors } = require('@discord-player/extractor');
 
 const client = new Discord.Client({
-    // Make sure you have 'GuildVoiceStates' intent enabled
-    intents: ['GuildVoiceStates' /* Other intents */]
+  // Make sure you have 'GuildVoiceStates' intent enabled
+  intents: ['GuildVoiceStates' /* Other intents */],
 });
 
 // this is the entrypoint for discord-player based application
 const player = new Player(client);
 
 // Now, lets load all the default extractors, except 'YouTubeExtractor'. You can remove the filter if you want to include youtube.
-await player.extractors.loadDefault((ext) => ext !== 'YouTubeExtractor');
+await player.extractors.loadMulti(DefaultExtractors);
 ```
 
 Discord Player is mostly events based. It emits different events based on the context and actions. Let's add a basic event listener to notify the user when a track starts to play:
@@ -110,8 +91,8 @@ Discord Player is mostly events based. It emits different events based on the co
 ```js index.js
 // this event is emitted whenever discord-player starts to play a track
 player.events.on('playerStart', (queue, track) => {
-    // we will later define queue.metadata object while creating the queue
-    queue.metadata.channel.send(`Started playing **${track.cleanTitle}**!`);
+  // we will later define queue.metadata object while creating the queue
+  queue.metadata.channel.send(`Started playing **${track.cleanTitle}**!`);
 });
 ```
 
@@ -149,27 +130,27 @@ Let's move on to the command part. You can define the command as per your requir
 const { useMainPlayer } = require('discord-player');
 
 export async function execute(interaction) {
-    const player = useMainPlayer(); // get player instance
-    const channel = interaction.member.voice.channel;
-    if (!channel) return interaction.reply('You are not connected to a voice channel!'); // make sure we have a voice channel
-    const query = interaction.options.getString('query', true); // we need input/query to play
-
-    // let's defer the interaction as things can take time to process
-    await interaction.deferReply();
-
-    try {
-        const { track } = await player.play(channel, query, {
-            nodeOptions: {
-                // nodeOptions are the options for guild node (aka your queue in simple word)
-                metadata: interaction // we can access this metadata object using queue.metadata later on
-            }
-        });
-
-        return interaction.followUp(`**${track.cleanTitle}** enqueued!`);
-    } catch (e) {
-        // let's return error if something failed
-        return interaction.followUp(`Something went wrong: ${e}`);
-    }
+  const player = useMainPlayer(); // get player instance
+  const channel = interaction.member.voice.channel;
+  if (!channel) return interaction.reply('You are not connected to a voice channel!'); // make sure we have a voice channel
+  const query = interaction.options.getString('query', true); // we need input/query to play
+
+  // let's defer the interaction as things can take time to process
+  await interaction.deferReply();
+
+  try {
+    const { track } = await player.play(channel, query, {
+      nodeOptions: {
+        // nodeOptions are the options for guild node (aka your queue in simple word)
+        metadata: interaction, // we can access this metadata object using queue.metadata later on
+      },
+    });
+
+    return interaction.followUp(`**${track.cleanTitle}** enqueued!`);
+  } catch (e) {
+    // let's return error if something failed
+    return interaction.followUp(`Something went wrong: ${e}`);
+  }
 }
 ```
 

package/dist/index.d.ts

@@ -7,11 +7,10 @@ import { EqualizerBand, BiquadFilters, PCMFilters, FiltersChain } from '@discord
 export { AF_NIGHTCORE_RATE, AF_VAPORWAVE_RATE, BASS_EQ_BANDS, FilterType as BiquadFilterType, BiquadFilters, FiltersChain, AudioFilters as PCMAudioFilters, PCMFilters, Q_BUTTERWORTH, VolumeTransformer } from '@discord-player/equalizer';
 import * as stream from 'stream';
 import { Readable, Duplex } from 'stream';
-import * as _discord_player_extractor from '@discord-player/extractor';
-import { BridgeProvider } from '@discord-player/extractor';
 import { RequestOptions } from 'http';
 import { StreamType, AudioPlayerError, AudioResource, VoiceConnection, AudioPlayer, AudioPlayerStatus } from 'discord-voip';
 export { AudioPlayer, CreateAudioPlayerOptions, JoinConfig, JoinVoiceChannelOptions, createAudioPlayer, getVoiceConnection, getVoiceConnections, joinVoiceChannel } from 'discord-voip';
+import { BridgeProvider } from '@discord-player/extractor';
 import { FFmpegLib } from '@discord-player/ffmpeg';
 export * from '@discord-player/ffmpeg';
 
@@ -954,147 +953,118 @@ declare const GuildQueueEvent: {
     /**
      * Emitted when audio track is added to the queue
      */
-    readonly audioTrackAdd: "audioTrackAdd";
     readonly AudioTrackAdd: "audioTrackAdd";
     /**
      * Emitted when audio tracks were added to the queue
      */
-    readonly audioTracksAdd: "audioTracksAdd";
     readonly AudioTracksAdd: "audioTracksAdd";
     /**
      * Emitted when audio track is removed from the queue
      */
-    readonly audioTrackRemove: "audioTrackRemove";
     readonly AudioTrackRemove: "audioTrackRemove";
     /**
      * Emitted when audio tracks are removed from the queue
      */
-    readonly audioTracksRemove: "audioTracksRemove";
     readonly AudioTracksRemove: "audioTracksRemove";
     /**
      * Emitted when a connection is created
      */
-    readonly connection: "connection";
     readonly Connection: "connection";
     /**
      * Emitted when a voice connection is destroyed
      */
-    readonly connectionDestroyed: "connectionDestroyed";
     readonly ConnectionDestroyed: "connectionDestroyed";
     /**
      * Emitted when the bot is disconnected from the channel
      */
-    readonly disconnect: "disconnect";
     readonly Disconnect: "disconnect";
     /**
      * Emitted when the queue sends a debug info
      */
-    readonly debug: "debug";
     readonly Debug: "debug";
     /**
      * Emitted when the queue encounters error
      */
-    readonly error: "error";
     readonly Error: "error";
     /**
      * Emitted when the voice channel is empty
      */
-    readonly emptyChannel: "emptyChannel";
     readonly EmptyChannel: "emptyChannel";
     /**
      * Emitted when the queue is empty
      */
-    readonly emptyQueue: "emptyQueue";
     readonly EmptyQueue: "emptyQueue";
     /**
      * Emitted when the audio player starts streaming audio track
      */
-    readonly playerStart: "playerStart";
     readonly PlayerStart: "playerStart";
     /**
      * Emitted when the audio player errors while streaming audio track
      */
-    readonly playerError: "playerError";
     readonly PlayerError: "playerError";
     /**
      * Emitted when the audio player finishes streaming audio track
      */
-    readonly playerFinish: "playerFinish";
     readonly PlayerFinish: "playerFinish";
     /**
      * Emitted when the audio player skips current track
      */
-    readonly playerSkip: "playerSkip";
     readonly PlayerSkip: "playerSkip";
     /**
      * Emitted when the audio player is triggered
      */
-    readonly playerTrigger: "playerTrigger";
     readonly PlayerTrigger: "playerTrigger";
     /**
      * Emitted when the voice state is updated. Consuming this event may disable default voice state update handler if `Player.isVoiceStateHandlerLocked()` returns `false`.
      */
-    readonly voiceStateUpdate: "voiceStateUpdate";
     readonly VoiceStateUpdate: "voiceStateUpdate";
     /**
      * Emitted when volume is updated
      */
-    readonly volumeChange: "volumeChange";
     readonly VolumeChange: "volumeChange";
     /**
      * Emitted when player is paused
      */
-    readonly playerPause: "playerPause";
     readonly PlayerPause: "playerPause";
     /**
      * Emitted when player is resumed
      */
-    readonly playerResume: "playerResume";
     readonly PlayerResume: "playerResume";
     /**
      * Biquad Filters Update
      */
-    readonly biquadFiltersUpdate: "biquadFiltersUpdate";
     readonly BiquadFiltersUpdate: "biquadFiltersUpdate";
     /**
      * Equalizer Update
      */
-    readonly equalizerUpdate: "equalizerUpdate";
     readonly EqualizerUpdate: "equalizerUpdate";
     /**
      * DSP update
      */
-    readonly dspUpdate: "dspUpdate";
     readonly DSPUpdate: "dspUpdate";
     /**
      * Audio Filters Update
      */
-    readonly audioFiltersUpdate: "audioFiltersUpdate";
     readonly AudioFiltersUpdate: "audioFiltersUpdate";
     /**
      * Audio player will play next track
      */
-    readonly willPlayTrack: "willPlayTrack";
     readonly WillPlayTrack: "willPlayTrack";
     /**
      * Emitted when a voice channel is repopulated
      */
-    readonly channelPopulate: "channelPopulate";
     readonly ChannelPopulate: "channelPopulate";
     /**
      * Emitted when a queue is successfully created
      */
-    readonly queueCreate: "queueCreate";
     readonly QueueCreate: "queueCreate";
     /**
      * Emitted when a queue is deleted
      */
-    readonly queueDelete: "queueDelete";
     readonly QueueDelete: "queueDelete";
     /**
      * Emitted when a queue is trying to add similar track for autoplay
      */
-    readonly willAutoPlay: "willAutoPlay";
     readonly WillAutoPlay: "willAutoPlay";
 };
 type GuildQueueEvent = (typeof GuildQueueEvent)[keyof typeof GuildQueueEvent];
@@ -1815,8 +1785,8 @@ declare function useHistory<Meta = unknown>(): GuildQueueHistory<Meta> | null;
 declare function usePlayer<Meta = unknown>(): GuildQueuePlayerNode<Meta> | null;
 
 /**
- * Fetch guild queue
- * @param node Guild queue node resolvable
+ * Fetch guild queue.
+ * @param node Guild queue node resolvable. Defaults to inferred guild from context.
  */
 declare function useQueue<Meta = unknown>(): GuildQueue<Meta> | null;
 
@@ -1835,13 +1805,9 @@ declare function useMetadata<T = unknown>(): MetadataDispatch<T>;
 
 interface TimelineDispatcherOptions {
     ignoreFilters: boolean;
+    node: NodeResolvable;
 }
-/**
- * Fetch or manipulate current track
- * @param node Guild queue node resolvable
- * @param options Options for timeline dispatcher
- */
-declare function useTimeline(options?: Partial<TimelineDispatcherOptions>): {
+interface GuildQueueTimeline {
     readonly timestamp: PlayerTimestamp;
     readonly volume: number;
     readonly paused: boolean;
@@ -1850,7 +1816,12 @@ declare function useTimeline(options?: Partial<TimelineDispatcherOptions>): {
     resume(): boolean;
     setVolume(vol: number): boolean;
     setPosition(time: number): Promise<boolean>;
-} | null;
+}
+/**
+ * Fetch or manipulate current track
+ * @param options Options for timeline dispatcher
+ */
+declare function useTimeline(): GuildQueueTimeline | null;
 
 /**
  * Global onAfterCreateStream handler
@@ -1872,10 +1843,6 @@ type VolumeDispatch = readonly [() => number, (volume: number | SetterFN) => boo
  */
 declare function useVolume(): VolumeDispatch;
 
-declare const knownExtractorKeys: readonly ["SpotifyExtractor", "AppleMusicExtractor", "SoundCloudExtractor", "VimeoExtractor", "ReverbnationExtractor", "AttachmentExtractor"];
-type ExtractorLoaderOptionDict = {
-    [K in (typeof knownExtractorKeys)[number]]?: ConstructorParameters<typeof _discord_player_extractor[K]>[1];
-};
 interface ExtractorSession {
     id: string;
     attemptedExtractors: Set<string>;
@@ -1929,13 +1896,14 @@ declare class ExtractorExecutionContext extends PlayerEventsEmitter<ExtractorExe
      * Get the current execution context
      */
     getContext(): ExtractorSession | null;
+    loadDefault(): Promise<void>;
     /**
-     * Load default extractors from `@discord-player/extractor`
+     * Load a bundle of extractors.
+     * @example import { DefaultExtractors } from '@discord-player/extractor';
+     *
+     * await player.extractors.loadMulti(DefaultExtractors);
      */
-    loadDefault(filter?: (ext: (typeof knownExtractorKeys)[number]) => boolean | null, options?: ExtractorLoaderOptionDict): Promise<{
-        success: boolean;
-        error: Error;
-    } | {
+    loadMulti<O extends object, T extends (typeof BaseExtractor<O>)[], R extends Record<T[number]['identifier'], ConstructorParameters<T[number]>[1]>>(bundle: T, options?: R): Promise<{
         success: boolean;
         error: null;
     }>;
@@ -2554,7 +2522,7 @@ declare class GuildNodeManager<Meta = unknown> {
      * Resolve queue
      * @param node Queue resolvable
      */
-    resolve<T = Meta>(node: NodeResolvable): GuildQueue<unknown> | undefined;
+    resolve<T = Meta>(node: NodeResolvable): GuildQueue<T> | undefined;
     /**
      * Resolve queue id
      * @param node Queue resolvable
@@ -3053,6 +3021,10 @@ interface PlayerInitOptions {
      * Configure ffmpeg path
      */
     ffmpegPath?: string;
+    /**
+     * Whether to override the fallback context. Defaults to `true`.
+     */
+    overrideFallbackContext?: boolean;
 }
 
 declare class AudioFilters {
@@ -3254,6 +3226,7 @@ interface DependenciesReport {
         'libsodium-wrappers': MaybeNull<string>;
         'sodium-javascript': MaybeNull<string>;
         '@stablelib/xchacha20poly1305': MaybeNull<string>;
+        '@nobel/ciphers': MaybeNull<string>;
     };
     ffmpeg: FFmpegReport;
 }
@@ -3294,4 +3267,4 @@ declare const DependencyReportGenerator: {
 
 declare const version: string;
 
-export { AFilterGraph, AsyncQueue, AsyncQueueAcquisitionOptions, AsyncQueueEntry, AsyncQueueExceptionHandler, AudioFilters, BaseExtractor, Context, ContextReceiver, CreateStreamOps, DependenciesReport, DependencyReportGenerator, DiscordPlayerQueryResultCache, Encodable, EqualizerConfigurationPreset, ExtractorExecutionContext, ExtractorExecutionEvents, ExtractorExecutionFN, ExtractorExecutionResult, ExtractorInfo, ExtractorLoaderOptionDict, ExtractorResolvable, ExtractorSearchContext, ExtractorSession, ExtractorStreamable, FFMPEG_ARGS_PIPED, FFMPEG_ARGS_STRING, FFMPEG_SRATE_REGEX, FFmpegFilterer, FFmpegReport, FFmpegStreamOptions, FilterGraph, FiltersName, GuildNodeCreateOptions, GuildNodeInit, GuildNodeManager, GuildQueue, GuildQueueAFiltersCache, GuildQueueAudioFilters, GuildQueueEvent, GuildQueueEvents, GuildQueueHistory, GuildQueuePlayerNode, GuildQueueStatistics, GuildQueueStatisticsMetadata, LrcGetParams, LrcGetResult, LrcLib, LrcSearchParams, LrcSearchResult, MaybeNull, MetadataDispatch, NextFunction, NodeResolvable, OnAfterCreateStreamHandler, OnBeforeCreateStreamHandler, PackageJSON, PlayOptions, Player, PlayerEvent, PlayerEvents, PlayerEventsEmitter, PlayerInitOptions, PlayerNodeInitializationResult, PlayerNodeInitializerOptions, PlayerProgressbarOptions, PlayerSearchResult, PlayerTimestamp, PlayerTriggeredReason, Playlist, PlaylistInitData, PlaylistJSON, PostProcessedResult, QueryCache, QueryCacheOptions, QueryCacheProvider, QueryCacheResolverContext, QueryExtractorSearch, QueryResolver, QueryType, QueueFilters, QueueRepeatMode, RawTrackData, RequestEntity, ResolvedQuery, ResourcePlayOptions, Runtime, RuntimeType, SearchOptions, SearchQueryType, SearchResult, SearchResultData, SequentialBucket, SerializedPlaylist, SerializedTrack, SerializedType, SetterFN$1 as SetterFN, SkipOptions, StreamConfig, StreamDispatcher, TimeData, TimelineDispatcherOptions, Track, TrackJSON, TrackLike, TrackResolvable, TrackSkipReason, TrackSource, TypeUtil, Util, VALIDATE_QUEUE_CAP, VoiceConnectConfig, VoiceEvents, VoiceStateHandler, VoiceUtils, WithMetadata, createContext, createErisCompat, createFFmpegStream, decode, deserialize, encode, isErisProxy, onAfterCreateStream, onBeforeCreateStream, serialize, tryIntoThumbnailString, useContext, useHistory, useMainPlayer, useMetadata, usePlayer, useQueue, useTimeline, useVolume, version };
+export { AFilterGraph, AsyncQueue, AsyncQueueAcquisitionOptions, AsyncQueueEntry, AsyncQueueExceptionHandler, AudioFilters, BaseExtractor, Context, ContextReceiver, CreateStreamOps, DependenciesReport, DependencyReportGenerator, DiscordPlayerQueryResultCache, Encodable, EqualizerConfigurationPreset, ExtractorExecutionContext, ExtractorExecutionEvents, ExtractorExecutionFN, ExtractorExecutionResult, ExtractorInfo, ExtractorResolvable, ExtractorSearchContext, ExtractorSession, ExtractorStreamable, FFMPEG_ARGS_PIPED, FFMPEG_ARGS_STRING, FFMPEG_SRATE_REGEX, FFmpegFilterer, FFmpegReport, FFmpegStreamOptions, FilterGraph, FiltersName, GuildNodeCreateOptions, GuildNodeInit, GuildNodeManager, GuildQueue, GuildQueueAFiltersCache, GuildQueueAudioFilters, GuildQueueEvent, GuildQueueEvents, GuildQueueHistory, GuildQueuePlayerNode, GuildQueueStatistics, GuildQueueStatisticsMetadata, GuildQueueTimeline, LrcGetParams, LrcGetResult, LrcLib, LrcSearchParams, LrcSearchResult, MaybeNull, MetadataDispatch, NextFunction, NodeResolvable, OnAfterCreateStreamHandler, OnBeforeCreateStreamHandler, PackageJSON, PlayOptions, Player, PlayerEvent, PlayerEvents, PlayerEventsEmitter, PlayerInitOptions, PlayerNodeInitializationResult, PlayerNodeInitializerOptions, PlayerProgressbarOptions, PlayerSearchResult, PlayerTimestamp, PlayerTriggeredReason, Playlist, PlaylistInitData, PlaylistJSON, PostProcessedResult, QueryCache, QueryCacheOptions, QueryCacheProvider, QueryCacheResolverContext, QueryExtractorSearch, QueryResolver, QueryType, QueueFilters, QueueRepeatMode, RawTrackData, RequestEntity, ResolvedQuery, ResourcePlayOptions, Runtime, RuntimeType, SearchOptions, SearchQueryType, SearchResult, SearchResultData, SequentialBucket, SerializedPlaylist, SerializedTrack, SerializedType, SetterFN$1 as SetterFN, SkipOptions, StreamConfig, StreamDispatcher, TimeData, TimelineDispatcherOptions, Track, TrackJSON, TrackLike, TrackResolvable, TrackSkipReason, TrackSource, TypeUtil, Util, VALIDATE_QUEUE_CAP, VoiceConnectConfig, VoiceEvents, VoiceStateHandler, VoiceUtils, WithMetadata, createContext, createErisCompat, createFFmpegStream, decode, deserialize, encode, isErisProxy, onAfterCreateStream, onBeforeCreateStream, serialize, tryIntoThumbnailString, useContext, useHistory, useMainPlayer, useMetadata, usePlayer, useQueue, useTimeline, useVolume, version };