document voice

package.json

@@ -36,9 +36,6 @@
     "fs-extra": "^0.30.0",
     "jsdoc-parse": "^1.2.7"
   },
-  "optionalDependencies": {
-    "node-opus": "^0.1.11"
-  },
   "engines": {
     "node": ">=0.12.7"
   },

src/client/voice/VoiceConnection.js

@@ -66,6 +66,11 @@ class VoiceConnection extends EventEmitter {
    */
   _onError(e) {
     this._reject(e);
+    /**
+     * Emitted whenever the connection encounters a fatal error.
+     * @event VoiceConnection#error
+     * @param {Error} error the encountered error
+     */
     this.emit('error', e);
     this._shutdown(e);
   }
@@ -103,6 +108,11 @@ class VoiceConnection extends EventEmitter {
     if (this.udp) {
       this.udp._shutdown();
     }
+    /**
+     * Emit once the voice connection has disconnected.
+     * @event VoiceConnection#disconnected
+     * @param {Error} error the error, if any
+     */
     this.emit('disconnected', e);
   }
 
@@ -123,6 +133,10 @@ class VoiceConnection extends EventEmitter {
     this.websocket.on('ready', secretKey => {
       this.data.secret = secretKey;
       this.ready = true;
+      /**
+       * Emitted once the connection is ready (joining voice channels resolves when the connection is ready anyway)
+       * @event VoiceConnection#ready
+       */
       this.emit('ready');
       this._resolve(this);
     });
@@ -131,6 +145,40 @@ class VoiceConnection extends EventEmitter {
       guild._memberSpeakUpdate(data.user_id, data.speaking);
     });
   }
+
+  /**
+   * Play the given file in the voice connection
+   * @param {String} filepath the path to the file
+   * @returns {StreamDispatcher}
+   * @example
+   * // play files natively
+   * voiceChannel.join()
+   *  .then(connection => {
+   *    const dispatcher = connection.playFile('C:/Users/Discord/Desktop/music.mp3');
+   *  })
+   *  .catch(console.log);
+   */
+  playFile(file) {
+    return this.player.playFile(file);
+  }
+
+  /**
+   * Play the given stream in the voice connection
+   * @param {ReadableStream} stream the audio stream to play
+   * @returns {StreamDispatcher}
+   * @example
+   * // play streams using ytdl-core
+   * const ytdl = require('ytdl-core');
+   * voiceChannel.join()
+   *  .then(connection => {
+   *    const stream = ytdl('https://www.youtube.com/watch?v=XAWgeLF9EVQ', {filter : 'audioonly'});
+   *    const dispatcher = connection.playStream(stream);
+   *  })
+   *  .catch(console.log);
+   */
+  playStream(stream) {
+    return this.player.playStream(stream);
+  }
 }
 
 module.exports = VoiceConnection;

src/client/voice/dispatcher/StreamDispatcher.js

@@ -4,6 +4,10 @@ const NaCl = require('tweetnacl');
 const nonce = new Buffer(24);
 nonce.fill(0);
 
+/**
+ * The class that sends voice packet data to the voice connection.
+ * @extends {EventEmitter}
+ */
 class StreamDispatcher extends EventEmitter {
   constructor(player, stream) {
     super();
@@ -16,6 +20,11 @@ class StreamDispatcher extends EventEmitter {
     this._triggered = false;
   }
 
+  /**
+  * Emitted when the dispatcher starts/stops speaking
+  * @event StreamDispatcher#speaking
+  * @param {Boolean} value whether or not the dispatcher is speaking
+  */
   _setSpeaking(value) {
     this.speaking = value;
     this.emit('speaking', value);
@@ -91,11 +100,21 @@ class StreamDispatcher extends EventEmitter {
     }
   }
 
+  /**
+  * Emitted once the stream has ended. Attach a `once` listener to this.
+  * @event StreamDispatcher#end
+  */
   _triggerEnd() {
     this.emit('end');
   }
 
+  /**
+  * Emitted once the stream has encountered an error. Attach a `once` listener to this. Also emits `end`.
+  * @event StreamDispatcher#error
+  * @param {Error} error the error encountered
+  */
   _triggerError(e) {
+    this.emit('end');
     this.emit('error', e);
   }
 
@@ -103,6 +122,12 @@ class StreamDispatcher extends EventEmitter {
     if (this._triggered) {
       return;
     }
+
+    /**
+    * Emitted when the stream wants to give debug information.
+    * @event StreamDispatcher#debug
+    * @param {String} information the debug information
+    */
     this.emit('debug', `triggered terminal state ${state} - stream is now dead`);
     this._triggered = true;
     this._setSpeaking(false);
@@ -145,14 +170,26 @@ class StreamDispatcher extends EventEmitter {
     }
   }
 
+  /**
+   * Stops the current stream permanently and emits an `end` event.
+   * @returns {null}
+   */
   end() {
     this._triggerTerminalState('end', 'user requested');
   }
 
+  /**
+   * Stops sending voice packets to the voice connection (stream may still progress however)
+   * @returns {null}
+   */
   pause() {
     this._pause(true);
   }
 
+  /**
+   * Resumes sending voice packets to the voice connection (may be further on in the stream than when paused)
+   * @returns {null}
+   */
   resume() {
     this._pause(false);
   }

src/structures/VoiceChannel.js

@@ -56,6 +56,13 @@ class VoiceChannel extends GuildChannel {
     return this.client.voice.joinChannel(this);
   }
 
+  /**
+   * Leaves this voice channel
+   * @returns {null}
+   * @example
+   * // leave a voice channel
+   * voiceChannel.leave();
+   */
   leave() {
     const exists = this.client.voice.connections.get(this.guild.id);
     if (exists) {