Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs : Added new pages for actions, events & hooks (#1676)
* Minor fixes for Avcon, Grammar and Formatting * Adding Events doc new page * Common Actions doc new page * Minor change * esm -> cjs * Hooks docs new page
- Loading branch information
Showing
7 changed files
with
403 additions
and
78 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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!'); | ||
}); | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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(); | ||
``` |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.