owo

README.md

@@ -17,7 +17,7 @@
 </div>
 
 ## About
-discord.js is a powerful node.js module that allows you to interact with the
+discord.js is a powerful [node.js](https://nodejs.org) module that allows you to interact with the
 [Discord API](https://discordapp.com/developers/docs/intro) very easily.
 
 - Object-oriented
@@ -27,7 +27,7 @@ discord.js is a powerful node.js module that allows you to interact with the
 
 ## Installation
 **Node.js 6.0.0 or newer is required.**  
-Ignore any warnings about unmet peer dependencies, as they're optional.
+Ignore any warnings about unmet peer dependencies, as they're all optional.
 
 Without voice support: `npm install discord.js --save`  
 With voice support ([node-opus](https://www.npmjs.com/package/node-opus)): `npm install discord.js node-opus --save`  
@@ -39,8 +39,9 @@ Using opusscript is only recommended for development environments where node-opu
 For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers.
 
 ### Optional packages
-- [bufferutil](https://www.npmjs.com/package/bufferutil) to greatly speed up the `ws` WebSocket connection (`npm install bufferutil --save`)
+- [bufferutil](https://www.npmjs.com/package/bufferutil) to greatly speed up the WebSocket when *not* using uws (`npm install bufferutil --save`)
 - [erlpack](https://github.com/hammerandchisel/erlpack) for significantly faster WebSocket data (de)serialisation (`npm install hammerandchisel/erlpack --save`)
+- [sodium](https://www.npmjs.com/package/sodium) for faster voice packet encryption/decryption (`npm install sodium --save`)
 - [uws](https://www.npmjs.com/package/uws) for a much faster WebSocket connection (`npm install uws --save`)  
   **Note:** This package does not handle disconnects entirely correctly, which causes automatic reconnection to Discord to not function.
   If you use this package, it may be wise to destroy + recreate the client entirely or restart the process upon disconnect.
@@ -77,7 +78,7 @@ A bot template using discord.js can be generated using [generator-discordbot](ht
 ## Contributing
 Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the
 [documentation](https://discord.js.org/#/docs).  
-See [the contribution guide](CONTRIBUTING.md) if you'd like to submit a PR.
+See [the contribution guide](https://github.com/hydrabolt/discord.js/blob/master/CONTRIBUTING.md) if you'd like to submit a PR.
 
 ## Help
 If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle

docs/examples/avatars.js

@@ -5,7 +5,7 @@
 // import the discord.js module
 const Discord = require('discord.js');
 
-// create an instance of a Discord Client, and call it bot
+// create an instance of a Discord Client
 const client = new Discord.Client();
 
 // the token of your bot - https://discordapp.com/developers/applications/me

docs/examples/greeting.js

@@ -0,0 +1,33 @@
+/*
+  A bot that welcomes new guild members when they join
+*/
+
+// import the discord.js module
+const Discord = require('discord.js');
+
+// create an instance of a Discord Client
+const client = new Discord.Client();
+
+// the token of your bot - https://discordapp.com/developers/applications/me
+const token = 'your bot token here';
+
+// the ID of the channel in which the bot will greet new users
+const channelID = 'your channel ID here';
+
+// the ready event is vital, it means that your bot will only start reacting to information
+// from Discord _after_ ready is emitted.
+client.on('ready', () => {
+  console.log('I am ready!');
+});
+
+// create an event listener for new guild members
+client.on('guildMemberAdd', member => {
+  // get the channel by its ID
+  const channel = client.channels.get(channelID);
+
+  // send the message, mentioning the member
+  channel.sendMessage(`Welcome to the server, ${member}!`);
+});
+
+// log our bot in
+client.login(token);

docs/general/welcome.md

@@ -21,7 +21,7 @@ Welcome to the discord.js v11 documentation.
 v11 contains loads of new and improved features, optimisations, and bug fixes.
 
 ## About
-discord.js is a powerful node.js module that allows you to interact with the
+discord.js is a powerful [node.js](https://nodejs.org) module that allows you to interact with the
 [Discord API](https://discordapp.com/developers/docs/intro) very easily.
 
 - Object-oriented
@@ -31,7 +31,7 @@ discord.js is a powerful node.js module that allows you to interact with the
 
 ## Installation
 **Node.js 6.0.0 or newer is required.**  
-Ignore any warnings about unmet peer dependencies, as they're optional.
+Ignore any warnings about unmet peer dependencies, as they're all optional.
 
 Without voice support: `npm install discord.js --save`  
 With voice support ([node-opus](https://www.npmjs.com/package/node-opus)): `npm install discord.js node-opus --save`  
@@ -43,8 +43,9 @@ Using opusscript is only recommended for development environments where node-opu
 For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers.
 
 ### Optional packages
-- [bufferutil](https://www.npmjs.com/package/bufferutil) to greatly speed up the `ws` WebSocket connection (`npm install bufferutil --save`)
+- [bufferutil](https://www.npmjs.com/package/bufferutil) to greatly speed up the WebSocket when *not* using uws (`npm install bufferutil --save`)
 - [erlpack](https://github.com/hammerandchisel/erlpack) for significantly faster WebSocket data (de)serialisation (`npm install hammerandchisel/erlpack --save`)
+- [sodium](https://www.npmjs.com/package/sodium) for faster voice packet encryption/decryption (`npm install sodium --save`)
 - [uws](https://www.npmjs.com/package/uws) for a much faster WebSocket connection (`npm install uws --save`)  
   **Note:** This package does not handle disconnects entirely correctly, which causes automatic reconnection to Discord to not function.
   If you use this package, it may be wise to destroy + recreate the client entirely or restart the process upon disconnect.
@@ -81,7 +82,7 @@ A bot template using discord.js can be generated using [generator-discordbot](ht
 ## Contributing
 Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the
 [documentation](https://discord.js.org/#/docs).  
-See [the contribution guide](CONTRIBUTING.md) if you'd like to submit a PR.
+See [the contribution guide](https://github.com/hydrabolt/discord.js/blob/master/CONTRIBUTING.md) if you'd like to submit a PR.
 
 ## Help
 If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle

docs/index.yml

@@ -8,6 +8,8 @@
       path: faq.md
 - name: Topics
   files:
+    - name: Voice
+      path: voice.md
     - name: Web builds
       path: web.md
 - name: Examples
@@ -16,5 +18,7 @@
       path: ping.js
     - name: Avatars
       path: avatars.js
+    - name: Server greeting
+      path: greeting.js
     - name: Webhook
       path: webhook.js

docs/topics/voice.md

@@ -0,0 +1,109 @@
+# 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 --global ffmpeg-binaries`
+* an opus encoder, choose one from below:
+  * `npm install opusscript`
+  * `npm install node-opus`
+* a good network connection
+
+## 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:

package.json

@@ -35,6 +35,7 @@
     "@types/node": "^7.0.0",
     "long": "^3.2.0",
     "pako": "^1.0.0",
+    "prism-media": "hydrabolt/prism-media",
     "superagent": "^3.4.0",
     "tweetnacl": "^0.14.0",
     "ws": "^2.0.0"
@@ -44,6 +45,7 @@
     "erlpack": "hammerandchisel/erlpack",
     "node-opus": "^0.2.0",
     "opusscript": "^0.0.2",
+    "sodium": "^2.0.1",
     "uws": "^0.12.0"
   },
   "devDependencies": {
@@ -60,9 +62,11 @@
     "ws": false,
     "uws": false,
     "erlpack": false,
+    "prism-media": false,
     "opusscript": false,
     "node-opus": false,
     "tweetnacl": false,
+    "sodium": false,
     "src/sharding/Shard.js": false,
     "src/sharding/ShardClientUtil.js": false,
     "src/sharding/ShardingManager.js": false,
@@ -75,12 +79,13 @@
     "src/client/voice/pcm/ConverterEngineList.js": false,
     "src/client/voice/pcm/FfmpegConverterEngine.js": false,
     "src/client/voice/player/AudioPlayer.js": false,
-    "src/client/voice/player/BasePlayer.js": false,
-    "src/client/voice/player/DefaultPlayer.js": false,
     "src/client/voice/receiver/VoiceReadable.js": false,
     "src/client/voice/receiver/VoiceReceiver.js": false,
+    "src/client/voice/util/Secretbox.js": false,
     "src/client/voice/util/SecretKey.js": false,
+    "src/client/voice/util/VolumeInterface.js": false,
     "src/client/voice/ClientVoiceManager.js": false,
+    "src/client/voice/VoiceBroadcast.js": false,
     "src/client/voice/VoiceConnection.js": false,
     "src/client/voice/VoiceUDPClient.js": false,
     "src/client/voice/VoiceWebSocket.js": false