discordrb 1.5.4 → 1.6.0

data/lib/discordrb/permissions.rb

@@ -31,7 +31,7 @@ module Discordrb
       23 => :deafen_members,       # 8388608
       24 => :move_members,         # 16777216
       25 => :use_voice_activity    # 33554432
-    }
+    }.freeze
 
     Flags.each do |position, flag|
       attr_reader flag

data/lib/discordrb/token_cache.rb

@@ -5,7 +5,7 @@ require 'discordrb/api'
 
 # Discordrb
 module Discordrb
-  # Amount of bytes the key should be long (32 bytes = 256 bits -> AES256)
+  # Amount of bytes the token encryption key should be long (32 bytes = 256 bits -> AES256)
   KEYLEN = 32
 
   # Represents a cached token with encryption data
@@ -65,7 +65,6 @@ module Discordrb
       cipher.key = key
       @iv = cipher.random_iv
       @encrypted_token = cipher.update(token) + cipher.final
-      @encrypted_token
     end
 
     def test_token(token)
@@ -80,7 +79,7 @@ module Discordrb
     end
   end
 
-  # Path where the cache file will be stored
+  # Path where the token cache file will be stored
   CACHE_PATH = Dir.home + '/.discordrb_token_cache.json'
 
   # Represents a token file

data/lib/discordrb/version.rb

@@ -1,4 +1,5 @@
 # Discordrb and all its functionality, in this case only the version.
 module Discordrb
-  VERSION = '1.5.4'
+  # The current version of discordrb.
+  VERSION = '1.6.0'.freeze
 end

data/lib/discordrb/voice/encoder.rb

@@ -1,3 +1,4 @@
+# This makes opus an optional dependency
 begin
   require 'opus-ruby'
   OPUS_AVAILABLE = true
@@ -7,10 +8,26 @@ end
 
 # Discord voice chat support
 module Discordrb::Voice
-  # Wrapper class around opus-ruby
+  # This class conveniently abstracts opus and ffmpeg/avconv, for easy implementation of voice sending. It's not very
+  # useful for most users, but I guess it can be useful sometimes.
   class Encoder
-    attr_accessor :volume, :use_avconv
+    # The volume that should be used with future ffmpeg conversions. If ffmpeg is used, this can be specified as:
+    #
+    #  * A number, where `1` is no change in volume, `0` is completely silent, `0.5` is half the default volume and `2` is twice the default.
+    #  * A string representation of the above number.
+    #  * A string representing a change in gain given in decibels, in the format `-6dB` or `6dB`.
+    #
+    # If avconv is used (see #use_avconv) then it can only be given as a number from `0` to `1`, where `1` is no change
+    # and `0` is completely silent.
+    # @return [String, Number] the volume for future playbacks, `1.0` by default.
+    attr_accessor :volume
 
+    # Whether or not avconv should be used instead of ffmpeg. If possible, it is recommended to use ffmpeg instead,
+    # as it is better supported and has a wider range of possible volume settings (see #volume).
+    # @return [true, false] whether avconv should be used instead of ffmpeg.
+    attr_accessor :use_avconv
+
+    # Create a new encoder
     def initialize
       @sample_rate = 48_000
       @frame_size = 960
@@ -24,19 +41,32 @@ module Discordrb::Voice
       end
     end
 
+    # Encodes the given buffer using opus.
+    # @param buffer [String] An unencoded PCM (s16le) buffer.
+    # @return [String] A buffer encoded using opus.
     def encode(buffer)
       @opus.encode(buffer, 1920)
     end
 
+    # Destroys this encoder and the opus connection, preventing any future encodings.
     def destroy
       @opus.destroy
     end
 
+    # Encodes a given file (or rather, decodes it) using ffmpeg. This accepts pretty much any format, even videos with
+    # an audio track. For a list of supported formats, see https://ffmpeg.org/general.html#Audio-Codecs. It even accepts
+    # URLs, though encoding them is pretty slow - I recommend to make a stream of it and then use {#encode_io} instead.
+    # @param file [String] The path or URL to encode.
+    # @return [IO] the audio, encoded as s16le PCM
     def encode_file(file)
       command = "#{ffmpeg_command} -loglevel 0 -i \"#{file}\" -f s16le -ar 48000 -ac 2 #{ffmpeg_volume} pipe:1"
       IO.popen(command)
     end
 
+    # Encodes an arbitrary IO audio stream using ffmpeg. Accepts pretty much any media format, even videos with audio
+    # tracks. For a list of supported audio formats, see https://ffmpeg.org/general.html#Audio-Codecs.
+    # @param io [IO] The stream to encode.
+    # @return [IO] the audio, encoded as s16le PCM
     def encode_io(io)
       ret_io, writer = IO.pipe
       command = "#{ffmpeg_command} -loglevel 0 -i - -f s16le -ar 48000 -ac 2 #{ffmpeg_volume} pipe:1"

data/lib/discordrb/voice/network.rb

@@ -2,16 +2,35 @@ require 'websocket-client-simple'
 require 'resolv'
 require 'socket'
 require 'json'
+require 'rbnacl/libsodium'
 
 module Discordrb::Voice
-  # Represents a UDP connection to a voice server
+  # Signifies to Discord that encryption should be used
+  ENCRYPTED_MODE = 'xsalsa20_poly1305'
+
+  # Signifies to Discord that no encryption should be used
+  PLAIN_MODE = 'plain'
+
+  # Represents a UDP connection to a voice server. This connection is used to send the actual audio data.
   class VoiceUDP
-    # Only creates a socket as the discovery reply may come before the data is initialized.
+    # @return [true, false] whether or not UDP communications are encrypted.
+    attr_accessor :encrypted
+    alias_method :encrypted?, :encrypted
+
+    # Sets the secret key used for encryption
+    attr_writer :secret_key
+
+    # Creates a new UDP connection. Only creates a socket as the discovery reply may come before the data is
+    # initialized.
     def initialize
       @socket = UDPSocket.new
     end
 
-    # Initializes the data from opcode 2
+    # Initializes the UDP socket with data obtained from opcode 2.
+    # @param endpoint [String] The voice endpoint to connect to.
+    # @param port [Integer] The port to connect to.
+    # @param ssrc [Integer] The Super Secret Relay Code (SSRC). Discord uses this to identify different voice users
+    #   on the same endpoint.
     def connect(endpoint, port, ssrc)
       @endpoint = endpoint
       @endpoint = @endpoint[6..-1] if @endpoint.start_with? 'wss://'
@@ -22,6 +41,8 @@ module Discordrb::Voice
       @ssrc = ssrc
     end
 
+    # Waits for a UDP discovery reply, and returns the sent data.
+    # @return [Array(String, Integer)] the IP and port received from the discovery reply.
     def receive_discovery_reply
       # Wait for a UDP message
       message = @socket.recv(70)
@@ -30,11 +51,25 @@ module Discordrb::Voice
       [ip, port]
     end
 
+    # Makes an audio packet from a buffer and sends it to Discord.
+    # @param buf [String] The audio data to send, must be exactly one Opus frame
+    # @param sequence [Integer] The packet sequence number, incremented by one for subsequent packets
+    # @param time [Integer] When this packet should be played back, in no particular unit (essentially just the
+    #   sequence number multiplied by 960)
     def send_audio(buf, sequence, time)
-      packet = [0x80, 0x78, sequence, time, @ssrc].pack('CCnNN') + buf
-      send_packet(packet)
+      # Header of the audio packet
+      header = [0x80, 0x78, sequence, time, @ssrc].pack('CCnNN')
+
+      # Encrypt data, if necessary
+      if encrypted?
+        buf = encrypt_audio(header, buf)
+      end
+
+      send_packet(header + buf)
     end
 
+    # Sends the UDP discovery packet with the internally stored SSRC. Discord will send a reply afterwards which can
+    # be received using {#receive_discovery_reply}
     def send_discovery
       discovery_packet = [@ssrc].pack('N')
 
@@ -45,15 +80,38 @@ module Discordrb::Voice
 
     private
 
+    # Encrypts audio data using RbNaCl
+    # @param header [String] The header of the packet, to be used as the nonce
+    # @param buf [String] The encoded audio data to be encrypted
+    # @return [String] the audio data, encrypted
+    def encrypt_audio(header, buf)
+      fail 'No secret key found, despite encryption being enabled!' unless @secret_key
+      box = RbNaCl::SecretBox.new(@secret_key)
+
+      # The nonce is the header of the voice packet with 12 null bytes appended
+      nonce = header + ([0] * 12).pack('C*')
+
+      box.encrypt(nonce, buf)
+    end
+
     def send_packet(packet)
       @socket.send(packet, 0, @endpoint, @port)
     end
   end
 
-  # Represents a websocket connection to the voice server
+  # Represents a websocket client connection to the voice server. The websocket connection (sometimes called vWS) is
+  # used to manage general data about the connection, such as sending the speaking packet, which determines the green
+  # circle around users on Discord, and obtaining UDP connection info.
   class VoiceWS
+    # @return [VoiceUDP] the UDP voice connection over which the actual audio data is sent.
     attr_reader :udp
 
+    # Makes a new voice websocket client, but doesn't connect it (see {#connect} for that)
+    # @param channel [Channel] The voice channel to connect to
+    # @param bot [Bot] The regular bot to which this vWS is bound
+    # @param token [String] The authentication token which is also used for REST requests
+    # @param session [String] The voice session ID Discord sends over the regular websocket
+    # @param endpoint [String] The endpoint URL to connect to
     def initialize(channel, bot, token, session, endpoint)
       @channel = channel
       @bot = bot
@@ -67,6 +125,10 @@ module Discordrb::Voice
     end
 
     # Send a connection init packet (op 0)
+    # @param server_id [Integer] The ID of the server to connect to
+    # @param bot_user_id [Integer] The ID of the bot that is connecting
+    # @param session_id [String] The voice session ID
+    # @param token [String] The Discord authentication token
     def send_init(server_id, bot_user_id, session_id, token)
       @client.send({
         op: 0,
@@ -80,6 +142,9 @@ module Discordrb::Voice
     end
 
     # Sends the UDP connection packet (op 1)
+    # @param ip [String] The IP to bind UDP to
+    # @param port [Integer] The port to bind UDP to
+    # @param mode [Object] Which mode to use for the voice connection
     def send_udp_connection(ip, port, mode)
       @client.send({
         op: 1,
@@ -100,12 +165,13 @@ module Discordrb::Voice
       @bot.debug("Sending voice heartbeat at #{millis}")
 
       @client.send({
-        'op' => 3,
-        'd' => nil
+        op: 3,
+        d: nil
       }.to_json)
     end
 
     # Send a speaking packet (op 5). This determines the green circle around the avatar in the voice channel
+    # @param value [true, false] Whether or not the bot should be speaking
     def send_speaking(value)
       @bot.debug("Speaking: #{value}")
       @client.send({
@@ -118,11 +184,13 @@ module Discordrb::Voice
     end
 
     # Event handlers; public for websocket-simple to work correctly
+    # @!visibility private
     def websocket_open
       # Send the init packet
       send_init(@channel.server.id, @bot.bot_user.id, @session, @token)
     end
 
+    # @!visibility private
     def websocket_message(msg)
       @bot.debug("Received VWS message! #{msg}")
       packet = JSON.parse(msg)
@@ -135,15 +203,17 @@ module Discordrb::Voice
         @heartbeat_interval = @ws_data['heartbeat_interval']
         @ssrc = @ws_data['ssrc']
         @port = @ws_data['port']
-        @udp_mode = @ws_data['modes'][0]
+        @udp_mode = mode
 
         @udp.connect(@endpoint, @port, @ssrc)
         @udp.send_discovery
       when 4
-        # I'm not 100% sure what this packet does, but I'm keeping it for future compatibility.
+        # Opcode 4 sends the secret key used for encryption
         @ws_data = packet['d']
         @ready = true
-        @mode = @ws_data['mode']
+        @udp.secret_key = @ws_data['secret_key'].pack('C*')
+      else
+        # irrelevant opcode, ignore
       end
     end
 
@@ -178,12 +248,18 @@ module Discordrb::Voice
       send_udp_connection(ip, port, @udp_mode)
     end
 
+    # Disconnects the websocket and kills the thread
     def destroy
       @thread.kill if @thread
     end
 
     private
 
+    # @return [String] the mode string that signifies whether encryption should be used or not
+    def mode
+      @udp.encrypted? ? ENCRYPTED_MODE : PLAIN_MODE
+    end
+
     def heartbeat_loop
       loop do
         if @heartbeat_interval

data/lib/discordrb/voice/voice_bot.rb

@@ -3,21 +3,56 @@ require 'discordrb/voice/network'
 
 # Voice support
 module Discordrb::Voice
-  # How long one packet should ideally be (20 ms as defined by Discord)
+  # How long one voice packet should ideally be (20 ms as defined by Discord)
   IDEAL_LENGTH = 20.0
 
-  # How many bytes of data to read (1920 bytes * 2 channels)
+  # How many bytes of data to read (1920 bytes * 2 channels) from audio PCM data
   DATA_LENGTH = 1920 * 2
 
-  # A voice connection consisting of a UDP socket and a websocket client
+  # This class represents a connection to a Discord voice server and channel. It can be used to play audio files and
+  # streams and to control playback on currently playing tracks. The method {Bot#voice_connect} can be used to connect
+  # to a voice channel.
+  #
+  # discordrb does latency adjustments every now and then to improve playback quality. I made sure to put useful
+  # defaults for the adjustment parameters, but if the sound is patchy or too fast (or the speed varies a lot) you
+  # should check the parameters and adjust them to your connection: {VoiceBot#adjust_interval},
+  # {VoiceBot#adjust_offset}, and {VoiceBot#adjust_average}.
   class VoiceBot
-    attr_reader :stream_time, :encoder
-    attr_accessor :adjust_interval, :adjust_offset, :adjust_average
-
-    def initialize(channel, bot, token, session, endpoint)
+    # @return [Integer, nil] the amount of time the stream has been playing, or `nil` if nothing has been played yet.
+    attr_reader :stream_time
+
+    # @return [Encoder] the encoder used to encode audio files into the format required by Discord.
+    attr_reader :encoder
+
+    # discordrb will occasionally measure the time it takes to send a packet, and adjust future delay times based
+    # on that data. This makes voice playback more smooth, because if packets are sent too slowly, the audio will
+    # sound patchy, and if they're sent too quickly, packets will "pile up" and occasionally skip some data or
+    # play parts back too fast. How often these measurements should be done depends a lot on the system, and if it's
+    # done too quickly, especially on slow connections, the playback speed will vary wildly; if it's done too slowly
+    # however, small errors will cause quality problems for a longer time.
+    # @return [Integer] how frequently audio length adjustments should be done, in ideal packets (20 ms).
+    attr_accessor :adjust_interval
+
+    # This particular value is also important because ffmpeg may take longer to process the first few packets. It is
+    # recommended to set this to 10 at maximum, otherwise it will take too long to make the first adjustment, but it
+    # shouldn't be any higher than {#adjust_interval}, otherwise no adjustments will take place. If {#adjust_interval}
+    # is at a value higher than 10, this value should not be changed at all.
+    # @see #adjust_interval
+    # @return [Integer] the packet number (1 packet = 20 ms) at which length adjustments should start.
+    attr_accessor :adjust_offset
+
+    # This value determines whether or not the adjustment length should be averaged with the previous value. This may
+    # be useful on slower connections where latencies vary a lot. In general, it will make adjustments more smooth,
+    # but whether that is desired behaviour should be tried on a case-by-case basis.
+    # @see #adjust_interval
+    # @return [true, false] whether adjustment lengths should be averaged with the respective previous value.
+    attr_accessor :adjust_average
+
+    def initialize(channel, bot, token, session, endpoint, encrypted)
       @bot = bot
       @ws = VoiceWS.new(channel, bot, token, session, endpoint)
       @udp = @ws.udp
+      @udp.encrypted = encrypted
 
       @sequence = @time = 0
 
@@ -30,29 +65,41 @@ module Discordrb::Voice
     end
 
     # Set the volume. Only applies to future playbacks
+    # @see Encoder#volume=
     def volume=(value)
       @encoder.volume = value
     end
 
+    # @see Encoder#volume
+    # @return [Integer, String] the current encoder volume.
     def volume
       @encoder.volume
     end
 
-    # Pause playback
+    # @return [true, false] whether audio data sent will be encrypted.
+    def encrypted?
+      @udp.encrypted?
+    end
+
+    # Pause playback. This is not instant; it may take up to 20 ms for this change to take effect. (This is usually
+    # negligible.)
     def pause
       @paused = true
     end
 
-    # Continue playback
+    # Continue playback. This change may take up to 100 ms to take effect, which is usually negligible.
     def continue
       @paused = false
     end
 
+    # Sets whether or not the bot is speaking (green circle around user).
+    # @param value [true, false] whether or not the bot should be speaking.
     def speaking=(value)
       @playing = value
       @ws.send_speaking(value)
     end
 
+    # Stops the current playback entirely.
     def stop_playing
       @was_playing_before = @playing
       @speaking = false
@@ -61,22 +108,34 @@ module Discordrb::Voice
       sleep IDEAL_LENGTH / 1000.0 if @was_playing_before
     end
 
+    # Permanently disconnects from the voice channel; to reconnect you will have to call {Bot#voice_connect} again.
     def destroy
       stop_playing
       @ws.destroy
       @encoder.destroy
     end
 
+    # Plays a stream of raw data to the channel. All playback methods are blocking, i. e. they wait for the playback to
+    # finish before exiting the method. This doesn't cause a problem if you just use discordrb events/commands to
+    # play stuff, as these are fully threaded, but if you don't want this behaviour anyway, be sure to call these
+    # methods in separate threads.
+    # @param encoded_io [IO] A stream of raw PCM data (s16le)
     def play(encoded_io)
       stop_playing if @playing
       @io = encoded_io
       play_internal
     end
 
+    # Plays an encoded audio file of arbitrary format to the channel.
+    # @see Encoder#encode_file
+    # @see #play
     def play_file(file)
       play @encoder.encode_file(file)
     end
 
+    # Plays a stream of encoded audio data of arbitrary format to the channel.
+    # @see Encoder#encode_io
+    # @see #play
     def play_io(io)
       play @encoder.encode_io(io)
     end
@@ -116,12 +175,10 @@ module Discordrb::Voice
         # Check whether the buffer has enough data
         if !buf || buf.length != DATA_LENGTH
           @bot.debug("No data is available! Retrying #{@retry_attempts} more times")
-          if @retry_attempts == 0
-            break
-          else
-            @retry_attempts -= 1
-            next
-          end
+          break if @retry_attempts == 0
+
+          @retry_attempts -= 1
+          next
         end
 
         # Track packet count, sequence and time (Discord requires this)
@@ -140,11 +197,11 @@ module Discordrb::Voice
           # Difference between length_adjust and now in ms
           ms_diff = (Time.now.nsec - @length_adjust) / 1_000_000.0
           if ms_diff >= 0
-            if @adjust_average
-              @length = (IDEAL_LENGTH - ms_diff + @length) / 2.0
-            else
-              @length = IDEAL_LENGTH - ms_diff
-            end
+            @length = if @adjust_average
+                        (IDEAL_LENGTH - ms_diff + @length) / 2.0
+                      else
+                        IDEAL_LENGTH - ms_diff
+                      end
 
             @bot.debug("Length adjustment: new length #{@length}")
           end