mirror of
https://github.com/discordjs/discord.js.git
synced 2026-03-09 16:13:31 +01:00
6ab46491c8
* Add internal support for @discordjs/opus * Remove redundant try/catch * fix: use setBitrate method in @discordjs/opus * chore: tidy up opus imports * fix: correct imports for DiscordJsOpusEngine * chore: update docs to prefer @discordjs/opus * chore: bump prism-media to 0.0.4 to allow ffmpeg-static
114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
# Introduction to Voice
|
|
Voice in discord.js can be used for many things, such as music bots, recording or relaying audio.
|
|
|
|
In discord.js, you can use voice by connecting to a `VoiceChannel` to obtain a `VoiceConnection`, where you can start streaming and receiving audio.
|
|
|
|
To get started, make sure you have:
|
|
* FFmpeg - `npm install ffmpeg-binaries`
|
|
* an opus encoder, choose one from below:
|
|
* `npm install opusscript`
|
|
* `npm install @discordjs/opus`
|
|
* a good network connection
|
|
|
|
The preferred opus engine is @discordjs/opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose @discordjs/opus.
|
|
Using opusscript is only recommended for development environments where @discordjs/opus is tough to get working.
|
|
For production bots, using @discordjs/opus should be considered a necessity, especially if they're going to be running on multiple servers.
|
|
|
|
## Joining a voice channel
|
|
The example below reacts to a message and joins the sender's voice channel, catching any errors. This is important
|
|
as it allows us to obtain a `VoiceConnection` that we can start to stream audio with.
|
|
|
|
```js
|
|
const Discord = require('discord.js');
|
|
const client = new Discord.Client();
|
|
|
|
client.login('token here');
|
|
|
|
client.on('message', message => {
|
|
// Voice only works in guilds, if the message does not come from a guild,
|
|
// we ignore it
|
|
if (!message.guild) return;
|
|
|
|
if (message.content === '/join') {
|
|
// Only try to join the sender's voice channel if they are in one themselves
|
|
if (message.member.voiceChannel) {
|
|
message.member.voiceChannel.join()
|
|
.then(connection => { // Connection is an instance of VoiceConnection
|
|
message.reply('I have successfully connected to the channel!');
|
|
})
|
|
.catch(console.log);
|
|
} else {
|
|
message.reply('You need to join a voice channel first!');
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
## Streaming to a Voice Channel
|
|
In the previous example, we looked at how to join a voice channel in order to obtain a `VoiceConnection`. Now that we
|
|
have obtained a voice connection, we can start streaming audio to it. The following example shows how to stream an mp3
|
|
file:
|
|
|
|
**Playing a file:**
|
|
```js
|
|
// To play a file, we need to give an absolute path to it
|
|
const dispatcher = connection.playFile('C:/Users/Discord/Desktop/myfile.mp3');
|
|
```
|
|
|
|
Your file doesn't have to be just an mp3; ffmpeg can convert videos and audios of many formats.
|
|
|
|
The `dispatcher` variable is an instance of a `StreamDispatcher`, which manages streaming a specific resource to a voice
|
|
channel. We can do many things with the dispatcher, such as finding out when the stream ends or changing the volume:
|
|
|
|
```js
|
|
dispatcher.on('end', () => {
|
|
// The song has finished
|
|
});
|
|
|
|
dispatcher.on('error', e => {
|
|
// Catch any errors that may arise
|
|
console.log(e);
|
|
});
|
|
|
|
dispatcher.setVolume(0.5); // Set the volume to 50%
|
|
dispatcher.setVolume(1); // Set the volume back to 100%
|
|
|
|
console.log(dispatcher.time); // The time in milliseconds that the stream dispatcher has been playing for
|
|
|
|
dispatcher.pause(); // Pause the stream
|
|
dispatcher.resume(); // Carry on playing
|
|
|
|
dispatcher.end(); // End the dispatcher, emits 'end' event
|
|
```
|
|
|
|
If you have an existing [ReadableStream](https://nodejs.org/api/stream.html#stream_readable_streams),
|
|
this can also be used:
|
|
|
|
**Playing a ReadableStream:**
|
|
```js
|
|
connection.playStream(myReadableStream);
|
|
|
|
// If you don't want to use absolute paths, you can use
|
|
// fs.createReadStream to circumvent it
|
|
|
|
const fs = require('fs');
|
|
const stream = fs.createReadStream('./test.mp3');
|
|
connection.playStream(stream);
|
|
```
|
|
|
|
It's important to note that creating a readable stream to a file is less efficient than simply using `connection.playFile()`.
|
|
|
|
**Playing anything else:**
|
|
|
|
For anything else, such as a URL to a file, you can use `connection.playArbitraryInput()`. You should consult the [ffmpeg protocol documentation](https://ffmpeg.org/ffmpeg-protocols.html) to see what you can use this for.
|
|
|
|
```js
|
|
// Play an mp3 from a URL
|
|
connection.playArbitraryInput('http://mysite.com/sound.mp3');
|
|
```
|
|
|
|
Again, playing a file from a URL like this is more performant than creating a ReadableStream to the file.
|
|
|
|
## Advanced Topics
|
|
soon:tm:
|