discord-player 6.0.0-dev.0 → 6.0.0-dev.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020-present Androz
+Copyright (c) 2020 Androz2091
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,4 +1,5 @@
 # Discord Player
+
 Complete framework to facilitate music commands using **[discord.js](https://discord.js.org)**.
 
 [![downloadsBadge](https://img.shields.io/npm/dt/discord-player?style=for-the-badge)](https://npmjs.com/discord-player)
@@ -7,8 +8,6 @@ Complete framework to facilitate music commands using **[discord.js](https://dis
 [![wakatime](https://wakatime.com/badge/github/Androz2091/discord-player.svg)](https://wakatime.com/badge/github/Androz2091/discord-player)
 [![CodeFactor](https://www.codefactor.io/repository/github/androz2091/discord-player/badge/v5)](https://www.codefactor.io/repository/github/androz2091/discord-player/overview/v5)
 
-> ⚠️ Discord Player v6 (Discord.js v14) WIP
-
 ## Installation
 
 ### Install **[discord-player](https://npmjs.com/package/discord-player)**
@@ -20,26 +19,40 @@ $ npm install --save discord-player
 ### Install **[@discordjs/opus](https://npmjs.com/package/@discordjs/opus)**
 
 ```sh
-$ npm install --save @discordjs/opus
+$ npm install --save @discordjs/opus # Native bindings via napi
+
+# or
+$ npm install --save opusscript # WASM bindings
 ```
 
-### Install FFmpeg or Avconv
-- Official FFMPEG Website: **[https://www.ffmpeg.org/download.html](https://www.ffmpeg.org/download.html)**
+### Install streaming library (if you want to play from youtube)
+
+```sh
+$ npm install --save play-dl # discord-player prefers play-dl over ytdl-core if both of them are installed
 
-- Node Module (FFMPEG): **[https://npmjs.com/package/ffmpeg-static](https://npmjs.com/package/ffmpeg-static)**
+# or
+$ npm install --save ytdl-core
+```
+
+### Install FFmpeg or Avconv
 
-- Avconv: **[https://libav.org/download](https://libav.org/download)**
+-   Official FFMPEG Website: **[https://www.ffmpeg.org/download.html](https://www.ffmpeg.org/download.html)**
+-   Node Module (FFMPEG): **[https://npmjs.com/package/ffmpeg-static](https://npmjs.com/package/ffmpeg-static)**
+-   Avconv: **[https://libav.org/download](https://libav.org/download)**
 
 # Features
-- Simple & easy to use 🤘
-- Beginner friendly 😱
-- Audio filters 🎸
-- Lightweight ☁️
-- Custom extractors support 🌌
-- Multiple sources support ✌
-- Play in multiple servers at the same time 🚗
-- Does not inject anything to discord.js or your discord.js client 💉
-- Allows you to have full control over what is going to be streamed 👑
+
+-   Simple & easy to use 🤘
+-   Beginner friendly 😱
+-   Audio filters 🎸
+-   Lavalink compatible 15 band equalizer 🎚️
+-   Digital biquad filters support
+-   Lightweight ☁️
+-   Custom extractors support 🌌
+-   Multiple sources support ✌
+-   Play in multiple servers at the same time 🚗
+-   Does not inject anything to discord.js or your discord.js client 💉
+-   Allows you to have full control over what is going to be streamed 👑
 
 ## [Documentation](https://discord-player.js.org)
 
@@ -48,161 +61,204 @@ $ npm install --save @discordjs/opus
 First of all, you will need to register slash commands:
 
 ```js
-const { REST } = require("@discordjs/rest");
-const { Routes } = require("discord-api-types/v9");
-
-const commands = [{
-    name: "play",
-    description: "Plays a song!",
-    options: [
-        {
-            name: "query",
-            type: "STRING",
-            description: "The song you want to play",
-            required: true
-        }
-    ]
-}]; 
+const { REST } = require('@discordjs/rest');
+const { Routes, ApplicationCommandOptionType } = require('discord.js');
+
+const commands = [
+    {
+        name: 'play',
+        description: 'Plays a song!',
+        options: [
+            {
+                name: 'query',
+                type: ApplicationCommandOptionType.String,
+                description: 'The song you want to play',
+                required: true
+            }
+        ]
+    }
+];
 
-const rest = new REST({ version: "9" }).setToken(process.env.DISCORD_TOKEN);
+const rest = new REST({ version: '10' }).setToken('BOT_TOKEN');
 
 (async () => {
-  try {
-    console.log("Started refreshing application [/] commands.");
-
-    await rest.put(
-      Routes.applicationGuildCommands(CLIENT_ID, GUILD_ID),
-      { body: commands },
-    );
-
-    console.log("Successfully reloaded application [/] commands.");
-  } catch (error) {
-    console.error(error);
-  }
+    try {
+        console.log('Started refreshing application [/] commands.');
+
+        await rest.put(Routes.applicationGuildCommands(CLIENT_ID, GUILD_ID), { body: commands });
+
+        console.log('Successfully reloaded application [/] commands.');
+    } catch (error) {
+        console.error(error);
+    }
 })();
 ```
 
 Now you can implement your bot's logic:
 
 ```js
-const { Client, Intents } = require("discord.js");
-const client = new Discord.Client({ intents: [Intents.FLAGS.GUILDS, Intents.FLAGS.GUILD_MESSAGES, Intents.FLAGS.GUILD_VOICE_STATES] });
-const { Player } = require("discord-player");
+const { Client } = require('discord.js');
+const client = new Discord.Client({
+    intents: ['Guilds', 'GuildVoiceStates']
+});
+const { Player } = require('discord-player');
 
 // Create a new Player (you don't need any API Key)
 const player = new Player(client);
 
-// add the trackStart event so when a song will be played this message will be sent
-player.on("trackStart", (queue, track) => queue.metadata.channel.send(`🎶 | Now playing **${track.title}**!`))
+// add the start and finish event so when a song will be played this message will be sent
+player.events.on('playerStart', (queue, track) => queue.metadata.channel.send(`🎶 | Now playing **${track.title}**!`));
+player.events.on('playerFinish', (queue, track) => queue.metadata.channel.send(`🎶 | Now playing **${track.title}**!`));
 
-client.once("ready", () => {
+client.once('ready', () => {
     console.log("I'm ready !");
 });
 
-client.on("interactionCreate", async (interaction) => {
-    if (!interaction.isCommand()) return;
+client.on('interactionCreate', async (interaction) => {
+    if (!interaction.isChatInputCommand()) return;
 
     // /play track:Despacito
     // will play "Despacito" in the voice channel
-    if (interaction.commandName === "play") {
-        if (!interaction.member.voice.channelId) return await interaction.reply({ content: "You are not in a voice channel!", ephemeral: true });
-        if (interaction.guild.me.voice.channelId && interaction.member.voice.channelId !== interaction.guild.me.voice.channelId) return await interaction.reply({ content: "You are not in my voice channel!", ephemeral: true });
-        const query = interaction.options.get("query").value;
-        const queue = player.createQueue(interaction.guild, {
-            metadata: {
-                channel: interaction.channel
-            }
-        });
-        
-        // verify vc connection
+    if (interaction.commandName === 'play') {
+        const voiceChannel = interaction.member.voice.channelId;
+        if (!voiceChannel) return await interaction.reply({ content: 'You are not in a voice channel!', ephemeral: true });
+        if (interaction.guild.members.me.voice.channelId && voiceChannel !== interaction.guild.members.me.voice.channelId)
+            return await interaction.reply({ content: 'You are not in my voice channel!', ephemeral: true });
+        await interaction.deferReply({ ephemeral: true });
+        const query = interaction.options.getString('query');
+
         try {
-            if (!queue.connection) await queue.connect(interaction.member.voice.channel);
-        } catch {
-            queue.destroy();
-            return await interaction.reply({ content: "Could not join your voice channel!", ephemeral: true });
+            const res = await player.play(voiceChannel, query, {
+                nodeOptions: {
+                    metadata: {
+                        channel: interaction.channel
+                    }
+                }
+            });
+
+            return await interaction.followUp({ content: `⏱️ | Loading track **${res.track.title}**!` });
+        } catch(e) {
+            return await interaction.followUp({ content: `Could not play: ${e.message}`, ephemeral: true });
         }
-
-        await interaction.deferReply();
-        const track = await player.search(query, {
-            requestedBy: interaction.user
-        }).then(x => x.tracks[0]);
-        if (!track) return await interaction.followUp({ content: `❌ | Track **${query}** not found!` });
-
-        queue.play(track);
-
-        return await interaction.followUp({ content: `⏱️ | Loading track **${track.title}**!` });
     }
 });
 
-client.login(process.env.DISCORD_TOKEN);
+client.login('BOT_TOKEN');
 ```
 
-## Supported websites
+## Supported sources
+
+By default, discord-player supports the following sources:
 
-By default, discord-player supports **YouTube**, **Spotify** and **SoundCloud** streams only.
+-   Local file (You must set the search engine to `QueryType.FILE` in order to play local files)
+-   Raw attachments
+-   Spotify (Streamed from youtube)
+-   Apple Music (Streamed from youtube)
+-   Vimeo
+-   Reverbnation
+-   SoundCloud
 
-### Optional dependencies
+You can also force a specific extractor to resolve your search query. This is useful in some cases where you don't want to use other sources.
+You can do so by using `ext:<EXTRACTOR_IDENTIFIER>` in `searchEngine` value. Example:
+
+```js
+const result = await player.search(query, {
+    // always use soundcloud extractor
+    searchEngine: 'ext:com.discord-player.soundcloudextractor'
+});
+```
+
+### Adding more sources
 
 Discord Player provides an **Extractor API** that enables you to use your custom stream extractor with it. Some packages have been made by the community to add new features using this API.
 
-#### [@discord-player/extractor](https://github.com/Snowflake107/discord-player-extractors) (optional)
+## Audio Filters
+
+Discord Player supports various audio filters. There are 4 types of audio filters in discord-player.
 
-Optional package that adds support for `vimeo`, `reverbnation`, `facebook`, `attachment links` and `lyrics`.
-You just need to install it using `npm i --save @discord-player/extractor` (discord-player will automatically detect and use it).
+##### FFmpeg
 
-#### [@discord-player/downloader](https://github.com/DevSnowflake/discord-player-downloader) (optional)
+The most common and powerful method is FFmpeg. It supports a lot of audio filters. To set ffmpeg filter, you can do:
 
-`@discord-player/downloader` is an optional package that brings support for +700 websites. The documentation is available [here](https://github.com/DevSnowflake/discord-player-downloader).
+```js
+await queue.filters.ffmpeg.setFilters(['bassboost', 'nightcore']);
+```
 
-## Examples of bots made with Discord Player
+Note that there can be a delay between filters transition in this method.
 
-These bots are made by the community, they can help you build your own!
+##### Equalizer
 
-* **[Discord Music Bot](https://github.com/Androz2091/discord-music-bot)** by [Androz2091](https://github.com/Androz2091)
-* [Dodong](https://github.com/nizeic/Dodong) by [nizeic](https://github.com/nizeic)
-* [Musico](https://github.com/Whirl21/Musico) by [Whirl21](https://github.com/Whirl21)
-* [Eyesense-Music-Bot](https://github.com/naseif/Eyesense-Music-Bot) by [naseif](https://github.com/naseif)
-* [Music-bot](https://github.com/ZerioDev/Music-bot) by [ZerioDev](https://github.com/ZerioDev)
-* [AtlantaBot](https://github.com/Androz2091/AtlantaBot) by [Androz2091](https://github.com/Androz2091) (**outdated**)
-* [Discord-Music](https://github.com/inhydrox/discord-music) by [inhydrox](https://github.com/inhydrox) (**outdated**)
+This equalizer is very similar to Lavalink's 15 Band Equalizer. To use this, you can do:
+
+```js
+queue.filters.equalizer.setEQ([
+    { band: 0, gain: 0.25 },
+    { band: 1, gain: 0.25 },
+    { band: 2, gain: 0.25 }
+]);
+```
 
-## Advanced
+There is no delay between filter transition when using equalizer.
 
-### Smooth Volume
+##### Biquad
 
-Discord Player will by default try to implement this. If smooth volume does not work, you need to add this line at the top of your main file:
+This filter provides digital biquad filterer to the player. To use this, you can do:
 
 ```js
-// CJS
-require("discord-player/smoothVolume");
+import { BiquadFilterType } from 'discord-player';
 
-// ESM
-import "discord-player/smoothVolume"
+queue.filters.biquad.setFilter(BiquadFilterType.LowPass);
+// similarly, you can use other filters such as HighPass, BandPass, Notch, PeakEQ, LowShelf, HighShelf, etc.
 ```
 
-> ⚠️ Make sure that line is situated at the **TOP** of your **main** file.
+There is no delay between filter transition when using biquad filters.
 
-### Use cookies
+#### Mini Audio Filters
+
+This is another type of audio filters provider. It currently supports `Tremolo` and `8D` filters only. To use this, you can do:
+
+```js
+queue.filters.filters.setFilters(['8D']);
+```
+
+There is no delay between filters transition using this filter.
+
+## Example bots made with Discord Player
+
+These bots are made by the community, they can help you build your own!
+
+-   **[Discord Music Bot](https://github.com/Androz2091/discord-music-bot)** by [Androz2091](https://github.com/Androz2091)
+-   [Dodong](https://github.com/nizeic/Dodong) by [nizeic](https://github.com/nizeic)
+-   [Musico](https://github.com/Whirl21/Musico) by [Whirl21](https://github.com/Whirl21)
+-   [Melody](https://github.com/NerdyTechy/Melody) by [NerdyTechy](https://github.com/NerdyTechy)
+-   [Eyesense-Music-Bot](https://github.com/naseif/Eyesense-Music-Bot) by [naseif](https://github.com/naseif)
+-   [Music-bot](https://github.com/ZerioDev/Music-bot) by [ZerioDev](https://github.com/ZerioDev)
+-   [AtlantaBot](https://github.com/Androz2091/AtlantaBot) by [Androz2091](https://github.com/Androz2091) (**outdated**)
+-   [Discord-Music](https://github.com/inhydrox/discord-music) by [inhydrox](https://github.com/inhydrox) (**outdated**)
+
+### Use cookies with ytdl-core
 
 ```js
 const player = new Player(client, {
     ytdlOptions: {
         requestOptions: {
             headers: {
-                cookie: "YOUR_YOUTUBE_COOKIE"
+                cookie: 'YOUR_YOUTUBE_COOKIE'
             }
         }
     }
 });
 ```
 
+> Note: the above option is only used when ytdl-core is being used.
+
 ### Use custom proxies
 
 ```js
-const HttpsProxyAgent = require("https-proxy-agent");
+const HttpsProxyAgent = require('https-proxy-agent');
 
 // Remove "user:pass@" if you don't need to authenticate to your proxy.
-const proxy = "http://user:pass@111.111.111.111:8080";
+const proxy = 'http://user:pass@111.111.111.111:8080';
 const agent = HttpsProxyAgent(proxy);
 
 const player = new Player(client, {
@@ -217,26 +273,21 @@ const player = new Player(client, {
 
 ### Custom stream Engine
 
-Discord Player by default uses **[node-ytdl-core](https://github.com/fent/node-ytdl-core)** for youtube and some other extractors for other sources.
-If you need to modify this behavior without touching extractors, you need to use `createStream` functionality of discord player.
-Here's an example on how you can use **[play-dl](https://npmjs.com/package/play-dl)** to download youtube streams instead of using ytdl-core.
+Discord Player by default uses registered extractors to stream audio. If you need to override what needs to be streamed, you can use this hook.
 
 ```js
-const playdl = require("play-dl");
+const fs = require('fs');
 
 // other code
-const queue = player.createQueue(..., {
+const queue = player.nodes.create(..., {
     ...,
     async onBeforeCreateStream(track, source, _queue) {
-        // only trap youtube source
-        if (source === "youtube") {
-            // track here would be youtube track
-            return (await playdl.stream(track.url, { discordPlayerCompatibility : true })).stream;
-            // we must return readable stream or void (returning void means telling discord-player to look for default extractor)
+        if (track.title === 'some title') {
+            return fs.createReadStream('./playThisInstead.mp3');
         }
     }
 });
 ```
 
-`<Queue>.onBeforeCreateStream` is called before actually downloading the stream. It is a different concept from extractors, where you are **just** downloading
-streams. `source` here will be a video source. Streams from `onBeforeCreateStream` are then piped to `FFmpeg` and finally sent to Discord voice servers.
+`\<GuildQueue>.onBeforeCreateStream` is called before actually downloading the stream. It is a different concept from extractors, where you are **just** downloading
+streams. `source` here will be a track source. Streams from `onBeforeCreateStream` are then piped to `FFmpeg` and finally sent to Discord voice servers.