discord-player 6.6.3-dev.0 → 6.6.3

package/README.md

@@ -41,17 +41,33 @@ $ npm install --save @discord-player/extractor # extractors provider
 
 #### Opus Library
 
-Since Discord only accepts opus packets, you need to install the opus library. Choose one of the following options:
+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:
 
 ```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
 
-FFmpeg or Avconv is required for media transcoding. You can obtain it from [https://ffmpeg.org](https://ffmpeg.org) or install it via npm (we recommend against using ffmpeg-static or other binaries):
+FFmpeg or Avconv is required for media transcoding. You can obtain it from [https://ffmpeg.org](https://ffmpeg.org) or via npm.
+
+> We do not recommend installing ffmpeg via npm because binaries pulled from npm is known to be unstable. It is recommended to install it from the official source.
 
 ```bash
 $ npm install --save ffmpeg-static
@@ -67,30 +83,31 @@ $ npm install --save ffmpeg-binaries
 
 #### Streaming Library
 
-If you want to add support for YouTube playback, you need to install a streaming library. Choose one of the following options:
+YouTube streaming is not supported without installing one of the following package. If you want to add support for YouTube playback, you need to install a streaming library. This step is not needed if you do not plan on using youtube source.
 
 ```bash
-$ npm install --save ytdl-core
+$ npm install --save youtube-ext
 # or
 $ npm install --save play-dl
 # or
 $ npm install --save @distube/ytdl-core
 # or
 $ npm install --save yt-stream
+# or
+$ npm install --save ytdl-core
 ```
 
+We recommend using `youtube-ext` for better performance.
+
 Once you have completed these installations, let's proceed with writing a simple music bot.
 
 ### Setup
 
 Let's create a main player instance. This instance handles and keeps track of all the queues and its components.
 
-```js
+```js index.js
 const { Player } = require('discord-player');
 
-// get some extractors if you want to handpick sources
-const { SpotifyExtractor, SoundCloudExtractor } = require('@discord-player/extractor');
-
 const client = new Discord.Client({
     // Make sure you have 'GuildVoiceStates' intent enabled
     intents: ['GuildVoiceStates' /* Other intents */]
@@ -99,17 +116,13 @@ const client = new Discord.Client({
 // this is the entrypoint for discord-player based application
 const player = new Player(client);
 
-// This method will load all the extractors from the @discord-player/extractor package
-await player.extractors.loadDefault();
-
-// If you dont want to use all of the extractors and register only the required ones manually, use
-await player.extractors.register(SpotifyExtractor, {});
-await player.extractors.register(SoundCloudExtractor, {});
+// Now, lets load all the default extractors, except 'YouTubeExtractor'. You can remove the filter if you want to load all the extractors.
+await player.extractors.loadDefault((ext) => ext !== 'YouTubeExtractor');
 ```
 
 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:
 
-```js
+```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
@@ -117,10 +130,13 @@ player.events.on('playerStart', (queue, track) => {
 });
 ```
 
-Let's move on to the command part. You can define the command as per your requirements. We will only focus on the command handler part:
+Let's move on to the command part. You can define the command as per your requirements. We will only focus on the command part:
+
+```js play.js
+const { useMainPlayer } = require('discord-player');
 
-```js
-async function execute(interaction) {
+export async function execute(interaction) {
+    const player = useMainPlayer();
     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

package/dist/index.d.ts

@@ -1535,7 +1535,7 @@ declare class BaseExtractor<T extends object = object> {
      * Get related tracks for the given track
      * @param track The track source
      */
-    getRelatedTracks(track: Track): Promise<ExtractorInfo>;
+    getRelatedTracks(track: Track, history: GuildQueueHistory): Promise<ExtractorInfo>;
     /**
      * A stream middleware to handle streams before passing it to the player
      * @param stream The incoming stream
@@ -1559,6 +1559,10 @@ declare class BaseExtractor<T extends object = object> {
      * @param message The debug message
      */
     debug(message: string): boolean;
+    /**
+     * IP rotator instance, if available
+     */
+    get routePlanner(): IPRotator | null;
 }
 type NextFunction = (error?: Error | null, stream?: Readable) => void;
 interface ExtractorInfo {
@@ -1726,6 +1730,44 @@ declare class VoiceUtils {
     getConnection(guild: Snowflake, group?: string): VoiceConnection | undefined;
 }
 
+declare class IPBlock {
+    block: string;
+    usage: number;
+    readonly cidr: string;
+    readonly cidrSize: number;
+    constructor(block: string);
+    consume(): void;
+}
+interface IPRotationConfig {
+    /**
+     * IP blocks to use
+     */
+    blocks: string[];
+    /**
+     * IPs to exclude
+     */
+    exclude?: string[];
+    /**
+     * Max retries to find an IP that is not excluded
+     */
+    maxRetries?: number;
+}
+declare class IPRotator {
+    #private;
+    config: IPRotationConfig;
+    blocks: IPBlock[];
+    failures: Map<string, number>;
+    MAX_NEXT_RETRIES: number;
+    constructor(config: IPRotationConfig);
+    getIP(): {
+        ip: string;
+        family: 4 | 6;
+    };
+    isFailedOrExcluded(ip: string): boolean;
+    addFailed(ip: string): void;
+    static getRandomIP(address: string, start?: number, end?: number): string;
+}
+
 interface PlayerNodeInitializationResult<T = unknown> {
     track: Track;
     extractor: BaseExtractor | null;
@@ -1752,6 +1794,7 @@ declare class Player extends PlayerEventsEmitter<PlayerEvents> {
     readonly voiceUtils: VoiceUtils;
     extractors: ExtractorExecutionContext;
     events: PlayerEventsEmitter<GuildQueueEvents<any>>;
+    routePlanner: IPRotator | null;
     /**
      * Creates new Discord Player
      * @param {Client} client The Discord Client
@@ -2020,6 +2063,7 @@ interface QueueFilters {
     dim?: boolean;
     earrape?: boolean;
     lofi?: boolean;
+    silenceremove?: boolean;
 }
 /**
  * The track source:
@@ -2180,12 +2224,14 @@ type QueryExtractorSearch = `ext:${string}`;
  * @property {string[]} [blockExtractors[]] List of the extractors to block
  * @property {boolean} [ignoreCache] If it should ignore query cache lookup
  * @property {SearchQueryType} [fallbackSearchEngine='autoSearch'] Fallback search engine to use
+ * @property {any} [requestOptions] The request options
  */
 interface SearchOptions {
     requestedBy?: UserResolvable;
     searchEngine?: SearchQueryType | QueryExtractorSearch;
     blockExtractors?: string[];
     ignoreCache?: boolean;
+    requestOptions?: any;
     fallbackSearchEngine?: (typeof QueryType)[keyof typeof QueryType];
 }
 /**
@@ -2298,6 +2344,7 @@ interface PlaylistJSON {
  * @property {boolean} [ignoreInstance] Ignore player instance
  * @property {boolean} [useLegacyFFmpeg] Use legacy version of ffmpeg
  * @property {BridgeProvider} [bridgeProvider] Set bridge provider
+ * @property {object} [ipconfig] IP rotator config
  */
 interface PlayerInitOptions {
     ytdlOptions?: downloadOptions;
@@ -2310,6 +2357,7 @@ interface PlayerInitOptions {
     ignoreInstance?: boolean;
     useLegacyFFmpeg?: boolean;
     bridgeProvider?: BridgeProvider;
+    ipconfig?: IPRotationConfig;
 }
 
 declare class AudioFilters {
@@ -2549,4 +2597,4 @@ declare function createHook<T extends HookDeclaration<(...args: any[]) => any>>(
 
 declare const version: string;
 
-export { AFilterGraph, AsyncQueue, AsyncQueueAcquisitionOptions, AsyncQueueEntry, AsyncQueueExceptionHandler, AudioFilters, BaseExtractor, CreateStreamOps, DiscordPlayerQueryResultCache, EqualizerConfigurationPreset, ExtractorExecutionContext, ExtractorExecutionEvents, ExtractorExecutionFN, ExtractorExecutionResult, ExtractorInfo, ExtractorSearchContext, FFMPEG_ARGS_PIPED, FFMPEG_ARGS_STRING, FFMPEG_SRATE_REGEX, FFmpegFilterer, FFmpegStreamOptions, FilterGraph, FiltersName, GuildNodeCreateOptions, GuildNodeInit, GuildNodeManager, GuildQueue, GuildQueueAFiltersCache, GuildQueueAudioFilters, GuildQueueEvent, GuildQueueEvents, GuildQueueHistory, GuildQueuePlayerNode, GuildQueueStatistics, GuildQueueStatisticsMetadata, HookDeclaration, HookDeclarationContext, NextFunction, NodeResolvable, OnAfterCreateStreamHandler, OnBeforeCreateStreamHandler, 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, RawTrackInit, ResolvedQuery, ResourcePlayOptions, SearchOptions, SearchQueryType, SearchResult, SearchResultData, StreamConfig, StreamDispatcher, TimeData, TimelineDispatcherOptions, Track, TrackJSON, TrackLike, TrackResolvable, TrackSource, TypeUtil, Util, VALIDATE_QUEUE_CAP, VoiceConnectConfig, VoiceEvents, VoiceReceiverNode, VoiceReceiverOptions, VoiceStateHandler, VoiceUtils, WithMetadata, createFFmpegStream, createHook, onAfterCreateStream, onBeforeCreateStream, useHistory, useMainPlayer, useMasterPlayer, useMetadata, usePlayer, useQueue, useTimeline, useVolume, version };
+export { AFilterGraph, AsyncQueue, AsyncQueueAcquisitionOptions, AsyncQueueEntry, AsyncQueueExceptionHandler, AudioFilters, BaseExtractor, CreateStreamOps, DiscordPlayerQueryResultCache, EqualizerConfigurationPreset, ExtractorExecutionContext, ExtractorExecutionEvents, ExtractorExecutionFN, ExtractorExecutionResult, ExtractorInfo, ExtractorSearchContext, FFMPEG_ARGS_PIPED, FFMPEG_ARGS_STRING, FFMPEG_SRATE_REGEX, FFmpegFilterer, FFmpegStreamOptions, FilterGraph, FiltersName, GuildNodeCreateOptions, GuildNodeInit, GuildNodeManager, GuildQueue, GuildQueueAFiltersCache, GuildQueueAudioFilters, GuildQueueEvent, GuildQueueEvents, GuildQueueHistory, GuildQueuePlayerNode, GuildQueueStatistics, GuildQueueStatisticsMetadata, HookDeclaration, HookDeclarationContext, IPBlock, IPRotationConfig, IPRotator, NextFunction, NodeResolvable, OnAfterCreateStreamHandler, OnBeforeCreateStreamHandler, 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, RawTrackInit, ResolvedQuery, ResourcePlayOptions, SearchOptions, SearchQueryType, SearchResult, SearchResultData, StreamConfig, StreamDispatcher, TimeData, TimelineDispatcherOptions, Track, TrackJSON, TrackLike, TrackResolvable, TrackSource, TypeUtil, Util, VALIDATE_QUEUE_CAP, VoiceConnectConfig, VoiceEvents, VoiceReceiverNode, VoiceReceiverOptions, VoiceStateHandler, VoiceUtils, WithMetadata, createFFmpegStream, createHook, onAfterCreateStream, onBeforeCreateStream, useHistory, useMainPlayer, useMasterPlayer, useMetadata, usePlayer, useQueue, useTimeline, useVolume, version };