Voice fixes, better API adherence, bitrate control, documentation

* Fixing silence frame.

* Messed that one up while fighting with the borrow checker. Sorry!

* Initial machinery for playback position tracking

* Mix multiple input AudioType::Opus streams

* Encode for stereo, use nicer "soft clip"

* First stab at docs for Audio.

* Better-er docs for voice::Audio etc.

* Bitrate control.

* Fix #270, Better handling of the voice api

We were mostly doing the voice API wrong, I've changed OpCode names to
be correct. We now listenfor both Ready and Hello at connection init,
and do soft checks for Heartbeat ACKs.

* Adding missing voice opcodes, related structs

* Also removes events for messages which cannot be received.

* @Zeyla's recommended changes.

* New docstrings now have correct style for referring to functions.
* Docstrings also have room to breathe (!)
* Rand dependency now properly moved behind the `voice` feature.
* Slightly cleaner checks at voice connection initialisation.
* Various idiomatic changes throughout.

* Prevent compilation of Audio docs example.

Likely too much machinery in the background to get a working Handler, I
think.

* Re-fixing the docstrings.

* Fixing travis for Audio docs.

1 files changed, 61 insertions, 17 deletions

diff --git a/src/model/event.rs b/src/model/event.rs
index 04169a6..093adcd 100644
--- a/src/model/event.rs
+++ b/src/model/event.rs
@@ -1790,14 +1790,19 @@ impl<'de> Deserialize<'de> for EventType {
 #[allow(missing_docs)]
 #[derive(Clone, Copy, Debug, Deserialize, Serialize)]
 pub struct VoiceHeartbeat {
-    pub heartbeat_interval: u64,
+    pub nonce: u64,
+}
+
+#[allow(missing_docs)]
+#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
+pub struct VoiceHeartbeatAck {
+    pub nonce: u64,
 }
 
 #[allow(missing_docs)]
 #[derive(Clone, Debug, Deserialize, Serialize)]
-pub struct VoiceHello {
+pub struct VoiceReady {
     pub heartbeat_interval: u64,
-    pub ip: String,
     pub modes: Vec<String>,
     pub port: u16,
     pub ssrc: u32,
@@ -1805,6 +1810,12 @@ pub struct VoiceHello {
 
 #[allow(missing_docs)]
 #[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct VoiceHello {
+    pub heartbeat_interval: u64,
+}
+
+#[allow(missing_docs)]
+#[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct VoiceSessionDescription {
     pub mode: String,
     pub secret_key: Vec<u8>,
@@ -1818,25 +1829,48 @@ pub struct VoiceSpeaking {
     pub user_id: UserId,
 }
 
+#[allow(missing_docs)]
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct VoiceResume {
+    pub server_id: String,
+    pub session_id: String,
+    pub token: String,
+}
+
+#[allow(missing_docs)]
+#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
+pub struct VoiceClientDisconnect {
+    pub user_id: UserId,
+}
+
 /// A representation of data received for [`voice`] events.
 ///
 /// [`voice`]: ../../voice/index.html
 #[derive(Clone, Debug, Serialize)]
 #[serde(untagged)]
 pub enum VoiceEvent {
-    /// A voice heartbeat.
-    Heartbeat(VoiceHeartbeat),
-    /// A "hello" was received with initial voice data, such as the
-    /// [`heartbeat_interval`].
+    /// Server's response to the client's Identify operation.
+    /// Contains session-specific information, e.g.
+    /// [`ssrc`] and supported encryption modes.
     ///
-    /// [`heartbeat_interval`]: struct.VoiceHello.html#structfield.heartbeat_interval
-    Hello(VoiceHello),
-    /// A simple keepalive event.
-    KeepAlive,
+    /// [`ssrc`]: struct.VoiceReady.html#structfield.ssrc
+    Ready(VoiceReady),
     /// A voice event describing the current session.
-    Ready(VoiceSessionDescription),
+    SessionDescription(VoiceSessionDescription),
     /// A voice event denoting that someone is speaking.
     Speaking(VoiceSpeaking),
+    /// Acknowledgement from the server for a prior voice heartbeat.
+    HeartbeatAck(VoiceHeartbeatAck),
+    /// A "hello" was received with initial voice data, such as the
+    /// true [`heartbeat_interval`].
+    ///
+    /// [`heartbeat_interval`]: struct.VoiceHello.html#structfield.heartbeat_interval
+    Hello(VoiceHello),
+    /// Message received if a Resume reques was successful.
+    Resumed,
+    /// Status update in the current channel, indicating that a user has
+    /// disconnected.
+    ClientDisconnect(VoiceClientDisconnect),
     /// An unknown voice event not registered.
     Unknown(VoiceOpCode, Value),
 }
@@ -1857,28 +1891,38 @@ impl<'de> Deserialize<'de> for VoiceEvent {
             .map_err(DeError::custom)?;
 
         Ok(match op {
-            VoiceOpCode::Heartbeat => {
+            VoiceOpCode::HeartbeatAck => {
                 let v = serde_json::from_value(v).map_err(DeError::custom)?;
 
-                VoiceEvent::Heartbeat(v)
+                VoiceEvent::HeartbeatAck(v)
+            },
+            VoiceOpCode::Ready => {
+                let v = VoiceReady::deserialize(v).map_err(DeError::custom)?;
+
+                VoiceEvent::Ready(v)
             },
             VoiceOpCode::Hello => {
-                let v = VoiceHello::deserialize(v).map_err(DeError::custom)?;
+                let v = serde_json::from_value(v).map_err(DeError::custom)?;
 
                 VoiceEvent::Hello(v)
             },
-            VoiceOpCode::KeepAlive => VoiceEvent::KeepAlive,
             VoiceOpCode::SessionDescription => {
                 let v = VoiceSessionDescription::deserialize(v)
                     .map_err(DeError::custom)?;
 
-                VoiceEvent::Ready(v)
+                VoiceEvent::SessionDescription(v)
             },
             VoiceOpCode::Speaking => {
                 let v = VoiceSpeaking::deserialize(v).map_err(DeError::custom)?;
 
                 VoiceEvent::Speaking(v)
             },
+            VoiceOpCode::Resumed => VoiceEvent::Resumed,
+            VoiceOpCode::ClientDisconnect => {
+                let v = VoiceClientDisconnect::deserialize(v).map_err(DeError::custom)?;
+
+                VoiceEvent::ClientDisconnect(v)
+            },
             other => VoiceEvent::Unknown(other, v),
         })
     }