Docs : Added new pages for actions, events & hooks

docs/examples/adding_events.md

@@ -0,0 +1,91 @@
+# Adding events to your bot
+
+Player state changes get emitted as events. You can attach to a particular listener to keep track of them.
+
+List of all available events : [Link](https://discord-player.js.org/docs/types/discord-player/guildqueueevent)
+
+The most commonly used listeners and their sample implementation are listed below :
+
+Add these in your _index.js_ where you initialized the Discord Player instance
+
+## Debug events
+
+```js
+player.on('debug', async (message) => {
+    // Emitted when the player sends debug info
+    // Useful for seeing what dependencies, extractors, etc are loaded
+    console.log(`General player debug event: ${message}`);
+});
+
+player.events.on('debug', async (queue, message) => {
+    // Emitted when the player queue sends debug info
+    // Useful for seeing what state the current queue is at
+    console.log(`Player debug event: ${message}`);
+});
+```
+
+## Error events
+
+```js
+player.events.on('error', (queue, error) => {
+    // Emitted when the player queue encounters error
+    console.log(`General player error event: ${error.message}`);
+    console.log(error);
+});
+
+player.events.on('playerError', (queue, error) => {
+    // Emitted when the audio player errors while streaming audio track
+    console.log(`Player error event: ${error.message}`);
+    console.log(error);
+});
+```
+
+## General events
+
+`queue.metadata.send()` is used here to send a message to the interaction channel.
+
+_NOTE : For this example to work, you will need to pass `interaction.channel` as the metadata while executing the play command. Check the example below._
+
+```js
+await player.play(channel, query, {
+    nodeOptions: {
+        metadata: interaction.channel
+    }
+});
+```
+
+```js
+player.events.on('playerStart', (queue, track) => {
+    // Emitted when the player starts to play a song
+    queue.metadata.send(`Started playing: **${track.title}**`);
+});
+
+player.events.on('audioTrackAdd', (queue, track) => {
+    // Emitted when the player adds a single song to its queue
+    queue.metadata.send(`Track **${track.title}** queued`);
+});
+
+player.events.on('audioTracksAdd', (queue, track) => {
+    // Emitted when the player adds multiple songs to its queue
+    queue.metadata.send(`Multiple Track's queued`);
+});
+
+player.events.on('playerSkip', (queue, track) => {
+    // Emitted when the audio player fails to load the stream for a song
+    queue.metadata.send(`Skipping **${track.title}** due to an issue!`);
+});
+
+player.events.on('disconnect', (queue) => {
+    // Emitted when the bot leaves the voice channel
+    queue.metadata.send('Looks like my job here is done, leaving now!');
+});
+player.events.on('emptyChannel', (queue) => {
+    // Emitted when the voice channel has been empty for the set threshold
+    // Bot will automatically leave the voice channel with this event
+    queue.metadata.send(`Leaving because no vc activity for the past 5 minutes`);
+});
+player.events.on('emptyQueue', (queue) => {
+    // Emitted when the player queue has finished
+    queue.metadata.send('Queue finished!');
+});
+```

docs/examples/autocomplete_search.md

@@ -8,7 +8,7 @@ client.on("ready", function (readyClient) {
 
     //Discord Player Initialization
 	const { Player } = require("discord-player");
-	const player = new Player(client);
+	const player = new Player(readyClient);
 
 });
 

docs/examples/common_actions.md

@@ -0,0 +1,131 @@
+# Common Actions on Player/Queue
+
+Here are few basic examples on how to implement various actions.
+
+This guide assumes that you already initialized the player in your `index.js` or corresponding file.
+
+Also this does not perform checks on the current status of the queue. Refer to one of the [example bots](https://github.com/Androz2091/discord-player/issues/1638) for more detailed info.
+
+## Getting the player instance from anywhere
+
+```js
+const { useMasterPlayer } = require("discord-player");
+...
+const player = useMasterPlayer();
+```
+
+## Playing a new track
+
+```js
+const { useMasterPlayer } = require("discord-player");
+...
+const player = useMasterPlayer();
+await player.play(interaction.member.voice.channel, query);
+
+```
+
+## Inserting a new track to a specific position in queue
+
+```js
+const { useQueue, useMasterPlayer } = require("discord-player");
+...
+const player = useMasterPlayer();
+const queue = useQueue(interaction.guild.id);
+const searchResult = await player.search(query, { requestedBy: interaction.user });
+queue.insertTrack(searchResult.tracks[0], position); //Remember queue index starts from 0, not 1
+```
+
+## Removing a track from the queue
+
+```js
+const { useQueue } = require("discord-player");
+...
+const queue = useQueue(interaction.guild.id);
+queue.removeTrack(trackNumber); //Remember queue index starts from 0, not 1
+```
+
+## Getting the current queue
+
+```js
+const { useQueue } = require("discord-player");
+...
+const queue = useQueue(interaction.guild.id);
+const tracks = queue.tracks.toArray(); //Converts the queue into a array of tracks
+const currentTrack = queue.currentTrack; //Gets the current track being played
+```
+
+## Pausing the queue
+
+_This example shows how you can toggle the pause state for a queue with a single command_
+
+```js
+const { useQueue } = require("discord-player");
+...
+const queue = useQueue(interaction.guild.id);
+queue.node.setPaused(!queue.node.isPaused());//isPaused() returns true if that player is already paused
+```
+
+## Going back a track
+
+_If your queue is being looped then there won't be any tracks in history_
+
+```js
+const { useHistory } = require("discord-player");
+...
+const history = useHistory(interaction.guild.id);
+await history.previous();
+```
+
+## Skipping a track
+
+```js
+const { useQueue } = require("discord-player");
+...
+const queue = useQueue(interaction.guild.id);
+queue.node.skip()
+```
+
+## Shuffling the queue
+
+```js
+const { useQueue } = require("discord-player");
+...
+const queue = useQueue(interaction.guild.id);
+queue.tracks.shuffle();
+```
+
+## Looping the queue
+
+_These are the various options for Loop Modes_
+
+| Mode     | Value | Description                                                   |
+| -------- | ----- | ------------------------------------------------------------- |
+| Off      | 0     | Default mode with no loop active                              |
+| Track    | 1     | Loops the current track                                       |
+| Queue    | 2     | Loops the current queue                                       |
+| Autoplay | 3     | Play related songs automatically based on your existing queue |
+
+```js
+const { useQueue } = require("discord-player");
+...
+const queue = useQueue(interaction.guild.id);
+queue.setRepeatMode(mode); //Pass the value for the mode here
+```
+
+## Changing the volume of the player
+
+```js
+const { useQueue } = require("discord-player");
+...
+const queue = useQueue(interaction.guild.id);
+queue.node.setVolume(volume); //Pass the value for the volume here
+```
+
+## Stopping the queue
+
+```js
+const { useQueue } = require("discord-player");
+...
+const queue = useQueue(interaction.guild.id);
+queue.delete();
+```

docs/faq/common_errors.md

@@ -7,7 +7,7 @@ $ npm install @discordjs/opus
 # or
 $ npm install opusscript
 # or
-$ npm install node-opus 
+$ npm install node-opus
 ```
 
 # FFmpeg/Avconv not found
@@ -18,14 +18,14 @@ Make sure you have `FFmpeg` or `Avconv` available on your system.
 
 -   Download from official FFmpeg website: **[www.ffmpeg.org/download.html](https://www.ffmpeg.org/download.html)**
 -   Node Module (ffmpeg-static): **[npmjs.com/package/ffmpeg-static](https://npmjs.com/package/ffmpeg-static)**
--   Avconv: **[npmjs.org/package/avconv](https://npmjs.org/package/avconv)**
+-   Avconv: If you want to use Avconv instead of FFmpeg, install it on your system or place Avconv executable at the root of your project.
 
 # "something" is not working
 
-- Try attaching `debug` listener to `player.events` to see if something strange is going on. 
+-   Try attaching `debug` listener to `player.events` to see if something strange is going on.
 
-- If you are getting weird errors like something is not a constructor or version.split is not a function or something similar, please try the following:
+-   If you are getting weird errors like something is not a constructor or version.split is not a function or something similar, please try the following:
 
     Remove `node_modules`, `package-lock.json` or any lockfiles you have, run `npm cache clean --force` or similar command equivalent to your package manager and then run `npm install` (or the install command of your package manager)
 
-- If you are unable to solve the problem, please join our official support server 👉 [https://androz2091.fr/discord](https://androz2091.fr/discord)
+-   If you are unable to solve the problem, please join our official support server 👉 [https://androz2091.fr/discord](https://androz2091.fr/discord)