diff --git a/README.md b/README.md index 3f80463..2470b7a 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,16 @@ npm install --save @discordjs/opus Install [FFMPEG](https://www.ffmpeg.org/download.html) and you're done! -## Player +## Features + +🤘 Easy to use! +🎸 You can apply some cool filters (bassboost, reverse, 8D, etc...) +🎼 Manage your server queues with simple functions (add songs, skip the current song, pause the music, resume it, etc...)! +🌐 Multi-servers support + +## Getting Started + +Here is the code you will need to get started with discord-player. Then, you will be able to use `client.player` everywhere in your code! ```js const Discord = require("discord.js"), @@ -42,57 +51,56 @@ client.on("ready", () => { console.log("I'm ready !"); }); +client.on("message", async (message) => { + + const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); + const command = args.shift().toLowerCase(); + + // !play Despacito + // will play "Despacito" in the member voice channel + + if(command === "play"){ + let track = await client.player.play(message.member.voice.channel, args[0], message.member.user.tag); + message.channel.send(`Currently playing ${track.name}! - Requested by ${track.requestedBy}`); + } + +}); + client.login(settings.token); ``` -You can pass a third parameter when instantiating the class Player: the **options** object: -**options.leaveOnEnd**: whether the bot should leave the voice channel when there is no more track in the queue. -**options.leaveOnStop**: whether the bot should leave the voice channel when the `stop()` function is used. -**options.leaveOnEmpty**: whether the bot should leave the voice channel if there is no more member in it. +## [Documentation](https://discord-player.js.org) -### Features Overview +You will find many examples in the documentation to understand how the package works! -You need to **init the guild queue using the play() function**, then you are able to manage the queue using the following functions: +### Methods overview -```js -// Play a track in the voice channel and init the guild queue -client.player.play(voiceChannel, trackName); +You need to **init the guild queue using the play() function**, then you are able to manage the queue and the music using the following functions. Click on a function name to get an example code and explanations. -// Add a track to the queue -client.player.addToQueue(guildID, trackName); -// Clear the queue -client.player.clearQueue(guildID); -// Get the queue -client.player.getQueue(guildID); -// Skip the current track -client.player.skip(guildID); -// Remove a track from the queue using the index number -client.player.remove(guildID, track); +#### Queue initialization -// Filters! -client.player.updateFilters(guildID, { - bassboost: true, - vaporwave: true -}) +* [play(voiceChannel, track, requestedBy)](https://discord-player.js.org/Player.html#play) - play a track in a server -// Pause -client.player.pause(guildID); -// Resume -client.player.resume(guildID); -// Stop -client.player.stop(guildID); +#### Queue management -// Check if music is playing in a guild -client.player.isPlaying(guildID); -// Get the currently playing trac -client.player.nowPlaying(guildID); +* [isPlaying(guildID)](https://discord-player.js.org/Player.html#isPlaying) - check if there is a queue for a specific server +#### Manage tracks in your queue -// Current track will be repeated indefinitely -client.player.setRepeatMode(guildID, true); -// Current track will no longer be repeated indefinitely -client.player.setRepeatMode(guildID, false); -``` +* [getQueue(guildID)](https://discord-player.js.org/Player.html#getQueue) - get the server queue +* [addToQueue(guildID, track, requestedBy)](https://discord-player.js.org/Player.html#addToQueue) - add a track to the server queue +* [clearQueue(guildID)](https://discord-player.js.org/Player.html#clearQueue) - clear the server queue +* [remove(guildID, track)](https://discord-player.js.org/Player.html#remove) - remove a track from the server queue +* [nowPlaying(guildID)](https://discord-player.js.org/Player.html#nowPlaying) - get the current track + +#### Manage music stream + +* [skip(guildID)](https://discord-player.js.org/Player.html#skip) - skip the current track +* [pause(guildID)](https://discord-player.js.org/Player.html#pause) - pause the current track +* [resume(guildID)](https://discord-player.js.org/Player.html#resume) - resume the current track +* [stop(guildID)](https://discord-player.js.org/Player.html#stop) - stop the current track +* [setFilters(data)](https://discord-player.js.org/Player.html#setFilters) - update filters (bassboost for example) +* [setRepeatMode(boolean)](https://discord-player.js.org/Player.html#setRepeatMode) - enable or disable repeat mode for the server ### Event messages @@ -113,465 +121,6 @@ client.player.getQueue(guildID) }); ``` -## Examples - -### Play - -To play a track, use the `client.player.play()` function. - -**Usage:** - -```js -client.player.play(voiceChannel, trackName, requestedBy); -``` - -**Example**: - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - // !play Despacito - // will play "Despacito" in the member voice channel - - if(command === 'play'){ - let track = await client.player.play(message.member.voice.channel, args[0], message.member.user.tag); - message.channel.send(`Currently playing ${track.name}! - Requested by ${track.requestedBy}`); - } - -``` - -### Pause - -To pause the current track, use the `client.player.pause()` function. - -**Usage:** - -```js -client.player.pause(guildID); -``` - -**Example**: - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'pause'){ - let track = await client.player.pause(message.guild.id); - message.channel.send(`${track.name} paused!`); - } - -}); -``` - -### Resume - -To resume the current track, use the `client.player.resume()` function. - -**Usage:** - -```js -client.player.resume(guildID); -``` - -**Example**: - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'resume'){ - let track = await client.player.resume(message.guild.id); - message.channel.send(`${track.name} resumed!`); - } - -}); -``` - -### Stop - -To stop the music, use the `client.player.stop()` function. - -**Usage:** - -```js -client.player.stop(guildID); -``` - -**Example**: - -```js -client.on('message', (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'stop'){ - client.player.stop(message.guild.id); - message.channel.send('Music stopped!'); - } - -}); -``` - -### SetVolume - -To update the volume, use the `client.player.setVolume()` function. - -**Usage:** - -```js -client.player.setVolume(guildID, percent); -``` - -**Example**: - -```js -client.on('message', (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'setvolume'){ - client.player.setVolume(message.guild.id, parseInt(args[0])); - message.channel.send(`Volume set to ${args[0]} !`); - } - -}); -``` - -### AddToQueue - -To add a track to the queue, use the `client.player.addToQueue()` function. - -**Usage:** - -```js -client.player.addToQueue(guildID, trackName); -``` - -**Example:** - -In this example, you will see how to add a track to the queue if one is already playing. - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'play'){ - let aTrackIsAlreadyPlaying = client.player.isPlaying(message.guild.id); - // If there's already a track playing - if(aTrackIsAlreadyPlaying){ - // Add the track to the queue - let track = await client.player.addToQueue(message.guild.id, args[0]); - message.channel.send(`${track.name} added to queue!`); - } else { - // Else, play the track - let track = await client.player.play(message.member.voice.channel, args[0]); - message.channel.send(`Currently playing ${track.name}!`); - } - } - -}); -``` - -### ClearQueue - -To clear the queue, use the `client.player.clearQueue()` function. - -**Usage:** - -```js -client.player.clearQueue(guildID); -``` - -**Example:** - -```js -client.on('message', (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'clear-queue'){ - client.player.clearQueue(message.guild.id); - message.channel.send('Queue cleared!'); - } - -}); -``` - -### GetQueue - -To get the server queue, use the `client.player.getQueue()` function. - -**Usage:** - -```js -client.player.getQueue(guildID); -``` - -**Example:** - -```js -client.on('message', (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'queue'){ - let queue = await client.player.getQueue(message.guild.id); - message.channel.send('Server queue:\n'+(queue.tracks.map((track, i) => { - return `${i === 0 ? 'Current' : `#${i+1}`} - ${track.name} | ${track.author}` - }).join('\n'))); - } - - /** - * Output: - * - * Server queue: - * Current - Despacito | Luis Fonsi - * #2 - Memories | Maroon 5 - * #3 - Dance Monkey | Tones And I - * #4 - Circles | Post Malone - */ - -}); -``` - -### Skip - -To skip the current track, use the `client.player.skip()` function. - -**Usage:** - -```js -client.player.skip(guildID); -``` - -**Example**: - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'skip'){ - let track = await client.player.skip(message.guild.id); - message.channel.send(`${track.name} skipped!`); - } - -}); -``` - -### Now Playing - -To get the currently playing track, use the `client.player.nowPlaying()` function. - -**Usage:** - -```js -client.player.nowPlaying(guildID); -``` - -**Example**: - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'now-playing'){ - let track = await client.player.nowPlaying(message.guild.id); - message.channel.send(`Currently playing ${track.name}...`); - } - -}); -``` - -### Repeat - -To repeat the current track, use the `client.player.setRepeatMode()` function. - -**Usage:** - -```js -client.player.setRepeatMode(guildID, boolean); -``` - -**Example**: - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'enable-repeat'){ - // Enable repeat mode - client.player.setRepeatMode(message.guild.id, true); - // Get the current track - let track = await client.player.nowPlaying(message.guild.id); - message.channel.send(`${track.name} will be repeated indefinitely!`); - } - - if(command === 'disable-repeat'){ - // Disable repeat mode - client.player.setRepeatMode(message.guild.id, false); - // Get the current track - let track = await client.player.nowPlaying(message.guild.id); - message.channel.send(`${track.name} will no longer be repeated indefinitely!`); - } - -}); -``` - -### Remove - -To remove a track from the queue, use the `client.player.remove()` function. - -**Usage:** - -```js -client.player.remove(guildID, track); -``` - -**Example:** - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'remove'){ - // Removes a track from the queue - client.player.remove(message.guild.id, args[0]).then(() => { - message.channel.send('Removed track!'); - }); - } -}); -``` - -### Filters - -You can apply some cool filters to your music! - -**Usage:** - -```js -client.player.updateFilters(guildID, { - bassboost: true, - '8D': true, - vaporwave: true, - nightcore: true, - phaser: true, - tremolo: true, - reverse: true, - treble: true, - normalizer: true, - surrounding: true - pulsator: true, - subboost: true -}); -``` - -**Example:** - -```js -client.on('message', async (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'bassboost'){ - const bassboostEnabled = client.player.getQueue(message.guild.id); - if(!bassboostEnabled){ - client.player.updateFilters(message.guild.id, { - bassboost: true - }); - message.channel.send("Bassboost effect has been enabled!"); - } else { - client.player.updateFilters(message.guild.id, { - bassboost: false - }); - message.channel.send("Bassboost effect has been disabled!"); - } - } - - // You can do the same for each filter! -}); -``` - -## Info Messages - -You can send a message when the queue ends or when the track changes: - -```js -client.on('message', (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - if(command === 'play'){ - let track = await client.player.play(message.member.voice.channel, args[0]); - track.queue.on('end', () => { - message.channel.send('The queue is empty, please add new tracks!'); - }); - track.queue.on('trackChanged', (oldTrack, newTrack, skipped, repeatMode) => { - if(repeatMode){ - message.channel.send(`Playing ${newTrack} again...`); - } else { - message.channel.send(`Now playing ${newTrack}...`); - } - }); - } - -``` - -## Handle errors - -There are 2 main errors that you can handle like this: - -```js -client.on('message', (message) => { - - const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); - const command = args.shift().toLowerCase(); - - // Error 1: - // Track not found - if(command === 'play'){ - client.player.play(message.member.voice.channel, args[0]).then((track) => { - message.channel.send(`Currently playing ${track.name}!`); - }).catch(() => { - message.channel.send(`No track found for ${args[0]}`); - }); - } - - // Error 2: - // Not playing - if(command === 'queue'){ - let playing = client.player.isPlaying(message.guild.id); - if(!playing) return message.channel.send(':x: No tracks currently playing!'); - // you are sure it works: - client.player.getQueue(message.guild.id); - } - -}); -``` - ## Examples of bots made with discord-player These bots are made by the community, they can help you build your own! diff --git a/src/Queue.js b/src/Queue.js index 0637842..f102c50 100644 --- a/src/Queue.js +++ b/src/Queue.js @@ -69,6 +69,24 @@ module.exports = Queue /** * Emitted when the queue is empty. * @event Queue#end + * + * @example + * client.on('message', (message) => { + * + * const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); + * const command = args.shift().toLowerCase(); + * + * if(command === 'play'){ + * + * let track = await client.player.play(message.member.voice.channel, args[0]); + * + * track.queue.on('end', () => { + * message.channel.send('The queue is empty, please add new tracks!'); + * }); + * + * } + * + * }); */ /** @@ -82,4 +100,26 @@ module.exports = Queue * @param {Track} oldTrack The old track (playing before) * @param {Track} newTrack The new track (currently playing) * @param {Boolean} skipped Whether the change is due to the skip() function + * + * @example + * client.on('message', (message) => { + * + * const args = message.content.slice(settings.prefix.length).trim().split(/ +/g); + * const command = args.shift().toLowerCase(); + * + * if(command === 'play'){ + * + * let track = await client.player.play(message.member.voice.channel, args[0]); + * + * track.queue.on('trackChanged', (oldTrack, newTrack, skipped, repeatMode) => { + * if(repeatMode){ + * message.channel.send(`Playing ${newTrack} again...`); + * } else { + * message.channel.send(`Now playing ${newTrack}...`); + * } + * }); + * + * } + * + * }); */