rubycord 1.0.0

data/lib/rubycord/voice/voice_bot.rb

@@ -0,0 +1,408 @@
+require "bigdecimal/util"
+
+require "rubycord/voice/encoder"
+require "rubycord/voice/network"
+require "rubycord/logger"
+
+# Voice support
+module Rubycord::Voice
+  # How long one voice packet should ideally be (20ms as defined by Discord)
+  IDEAL_LENGTH = 20.0
+
+  # How many bytes of data to read (1920 bytes * 2 channels) from audio PCM data
+  DATA_LENGTH = 1920 * 2
+
+  # 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.
+  #
+  # rubycord 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
+    # @return [Channel] the current voice channel
+    attr_reader :channel
+
+    # @!visibility private
+    attr_writer :channel
+
+    # @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
+
+    # rubycord 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 (20ms).
+    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 = 20ms) 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
+
+    # Disable the debug message for length adjustment specifically, as it can get quite spammy with very low intervals
+    # @see #adjust_interval
+    # @return [true, false] whether length adjustment debug messages should be printed
+    attr_accessor :adjust_debug
+
+    # If this value is set, no length adjustments will ever be done and this value will always be used as the length
+    # (i.e. packets will be sent every N seconds). Be careful not to set it too low as to not spam Discord's servers.
+    # The ideal length is 20ms (accessible by the {Rubycord::Voice::IDEAL_LENGTH} constant), this value should be
+    # slightly lower than that because encoding + sending takes time. Note that sending DCA files is significantly
+    # faster than sending regular audio files (usually about four times as fast), so you might want to set this value
+    # to something else if you're sending a DCA file.
+    # @return [Float] the packet length that should be used instead of calculating it during the adjustments, in ms.
+    attr_accessor :length_override
+
+    # The factor the audio's volume should be multiplied with. `1` is no change in volume, `0` is completely silent,
+    # `0.5` is half the default volume and `2` is twice the default.
+    # @return [Float] the volume for audio playback, `1.0` by default.
+    attr_accessor :volume
+
+    # @!visibility private
+    def initialize(channel, bot, token, session, endpoint)
+      @bot = bot
+      @channel = channel
+
+      @ws = VoiceWS.new(channel, bot, token, session, endpoint)
+      @udp = @ws.udp
+
+      @sequence = @time = 0
+      @skips = 0
+
+      @adjust_interval = 100
+      @adjust_offset = 10
+      @adjust_average = false
+      @adjust_debug = true
+
+      @volume = 1.0
+      @playing = false
+
+      @encoder = Encoder.new
+      @ws.connect
+    rescue => e
+      Rubycord::LOGGER.log_exception(e)
+      raise
+    end
+
+    # @return [true, false] whether audio data sent will be encrypted.
+    # @deprecated Discord no longer supports unencrypted voice communication.
+    def encrypted?
+      true
+    end
+
+    # Set the filter volume. This volume is applied as a filter for decoded audio data. It has the advantage that using
+    # it is much faster than regular volume, but it can only be changed before starting to play something.
+    # @param value [Integer] The value to set the volume to. For possible values, see {#volume}
+    def filter_volume=(value)
+      @encoder.filter_volume = value
+    end
+
+    # @see #filter_volume=
+    # @return [Integer] the volume used as a filter for ffmpeg/avconv.
+    def filter_volume
+      @encoder.filter_volume
+    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
+
+    # @see #play
+    # @return [true, false] Whether it is playing sound or not.
+    def playing?
+      @playing
+    end
+
+    alias_method :isplaying?, :playing?
+
+    # Continue playback. This change may take up to 100ms to take effect, which is usually negligible.
+    def continue
+      @paused = false
+    end
+
+    # Skips to a later time in the song. It's impossible to go back without replaying the song.
+    # @param secs [Float] How many seconds to skip forwards. Skipping will always be done in discrete intervals of
+    #   0.05 seconds, so if the given amount is smaller than that, it will be rounded up.
+    def skip(secs)
+      @skips += (secs * (1000 / IDEAL_LENGTH)).ceil
+    end
+
+    # Sets whether or not the bot is speaking (green circle around user).
+    # @param value [true, false, Integer] whether or not the bot should be speaking, or a bitmask denoting the audio type
+    # @note https://discord.com/developers/docs/topics/voice-connections#speaking for information on the speaking bitmask
+    def speaking=(value)
+      @playing = value
+      @ws.send_speaking(value)
+    end
+
+    # Stops the current playback entirely.
+    # @param wait_for_confirmation [true, false] Whether the method should wait for confirmation from the playback
+    #   method that the playback has actually stopped.
+    def stop_playing(wait_for_confirmation = false)
+      @was_playing_before = @playing
+      @speaking = false
+      @playing = false
+      sleep IDEAL_LENGTH / 1000.0 if @was_playing_before
+
+      return unless wait_for_confirmation
+
+      @has_stopped_playing = false
+      sleep IDEAL_LENGTH / 1000.0 until @has_stopped_playing
+      @has_stopped_playing = false
+    end
+
+    # Permanently disconnects from the voice channel; to reconnect you will have to call {Bot#voice_connect} again.
+    def destroy
+      stop_playing
+      @bot.voice_destroy(@channel.server.id, false)
+      @ws.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 rubycord 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(true) if @playing
+      @retry_attempts = 3
+      @first_packet = true
+
+      play_internal do
+        buf = nil
+
+        # Read some data from the buffer
+        begin
+          buf = encoded_io.readpartial(DATA_LENGTH) if encoded_io
+        rescue EOFError
+          raise IOError, "File or stream not found!" if @first_packet
+
+          @bot.debug("EOF while reading, breaking immediately")
+          next :stop
+        end
+
+        # Check whether the buffer has enough data
+        if !buf || buf.length != DATA_LENGTH
+          @bot.debug("No data is available! Retrying #{@retry_attempts} more times")
+          next :stop if @retry_attempts.zero?
+
+          @retry_attempts -= 1
+          next
+        end
+
+        # Adjust volume
+        buf = @encoder.adjust_volume(buf, @volume) if @volume.to_d != BigDecimal("1.0")
+
+        @first_packet = false
+
+        # Encode data
+        @encoder.encode(buf)
+      end
+
+      # If the stream is a process, kill it
+      if encoded_io&.pid
+        Rubycord::LOGGER.debug("Killing ffmpeg process with pid #{encoded_io.pid.inspect}")
+
+        begin
+          pid = encoded_io.pid
+          # Windows does not support TERM as a kill signal, so we use KILL. `Process.waitpid` verifies that our
+          # child process has not already completed.
+          Process.kill(Gem.win_platform? ? "KILL" : "TERM", pid) if Process.waitpid(pid, Process::WNOHANG).nil?
+        rescue => e
+          Rubycord::LOGGER.warn("Failed to kill ffmpeg process! You *might* have a process leak now.")
+          Rubycord::LOGGER.warn("Reason: #{e}")
+        end
+      end
+
+      # Close the stream
+      encoded_io.close
+    end
+
+    # Plays an encoded audio file of arbitrary format to the channel.
+    # @see Encoder#encode_file
+    # @see #play
+    def play_file(file, options = "")
+      play @encoder.encode_file(file, options)
+    end
+
+    # Plays a stream of encoded audio data of arbitrary format to the channel.
+    # @see Encoder#encode_io
+    # @see #play
+    def play_io(io, options = "")
+      play @encoder.encode_io(io, options)
+    end
+
+    # Plays a stream of audio data in the DCA format. This format has the advantage that no recoding has to be
+    # done - the file contains the data exactly as Discord needs it.
+    # @note DCA playback will not be affected by the volume modifier ({#volume}) because the modifier operates on raw
+    #   PCM, not opus data. Modifying the volume of DCA data would involve decoding it, multiplying the samples and
+    #   re-encoding it, which defeats its entire purpose (no recoding).
+    # @see https://github.com/bwmarrin/dca
+    # @see #play
+    def play_dca(file)
+      stop_playing(true) if @playing
+
+      @bot.debug "Reading DCA file #{file}"
+      input_stream = File.open(file)
+
+      magic = input_stream.read(4)
+      raise ArgumentError, "Not a DCA1 file! The file might have been corrupted, please recreate it." unless magic == "DCA1"
+
+      # Read the metadata header, then read the metadata and discard it as we don't care about it
+      metadata_header = input_stream.read(4).unpack1("l<")
+      input_stream.read(metadata_header)
+
+      # Play the data, without re-encoding it to opus
+      play_internal do
+        begin
+          # Read header
+          header_str = input_stream.read(2)
+
+          unless header_str
+            @bot.debug "Finished DCA parsing (header is nil)"
+            next :stop
+          end
+
+          header = header_str.unpack1("s<")
+
+          raise "Negative header in DCA file! Your file is likely corrupted." if header.negative?
+        rescue EOFError
+          @bot.debug "Finished DCA parsing (EOFError)"
+          next :stop
+        end
+
+        # Read bytes
+        input_stream.read(header)
+      end
+    end
+
+    alias_method :play_stream, :play_io
+
+    private
+
+    # Plays the data from the IO stream as Discord requires it
+    def play_internal
+      count = 0
+      @playing = true
+
+      # Default play length (ms), will be adjusted later
+      @length = IDEAL_LENGTH
+
+      self.speaking = true
+      loop do
+        # Starting from the tenth packet, perform length adjustment every 100 packets (2 seconds)
+        should_adjust_this_packet = (count % @adjust_interval == @adjust_offset)
+
+        # If we should adjust, start now
+        @length_adjust = Time.now.nsec if should_adjust_this_packet
+
+        break unless @playing
+
+        # If we should skip, get some data, discard it and go to the next iteration
+        if @skips.positive?
+          @skips -= 1
+          yield
+          next
+        end
+
+        # Track packet count, sequence and time (Discord requires this)
+        count += 1
+        increment_packet_headers
+
+        # Get packet data
+        buf = yield
+
+        # Stop doing anything if the stop signal was sent
+        break if buf == :stop
+
+        # Proceed to the next packet if we got nil
+        next unless buf
+
+        # Track intermediate adjustment so we can measure how much encoding contributes to the total time
+        @intermediate_adjust = Time.now.nsec if should_adjust_this_packet
+
+        # Send the packet
+        @udp.send_audio(buf, @sequence, @time)
+
+        # Set the stream time (for tracking how long we've been playing)
+        @stream_time = count * @length / 1000
+
+        if @length_override # Don't do adjustment because the user has manually specified an override value
+          @length = @length_override
+        elsif @length_adjust # Perform length adjustment
+          # Define the time once so it doesn't get inaccurate
+          now = Time.now.nsec
+
+          # Difference between length_adjust and now in ms
+          ms_diff = (now - @length_adjust) / 1_000_000.0
+          if ms_diff >= 0
+            @length = if @adjust_average
+              (IDEAL_LENGTH - ms_diff + @length) / 2.0
+            else
+              IDEAL_LENGTH - ms_diff
+            end
+
+            # Track the time it took to encode
+            encode_ms = (@intermediate_adjust - @length_adjust) / 1_000_000.0
+            @bot.debug("Length adjustment: new length #{@length} (measured #{ms_diff}, #{(100 * encode_ms) / ms_diff}% encoding)") if @adjust_debug
+          end
+          @length_adjust = nil
+        end
+
+        # If paused, wait
+        sleep 0.1 while @paused
+
+        if @length.positive?
+          # Wait `length` ms, then send the next packet
+          sleep @length / 1000.0
+        else
+          Rubycord::LOGGER.warn("Audio encoding and sending together took longer than Discord expects one packet to be (20 ms)! This may be indicative of network problems.")
+        end
+      end
+
+      @bot.debug("Sending five silent frames to clear out buffers")
+
+      5.times do
+        increment_packet_headers
+        @udp.send_audio(Encoder::OPUS_SILENCE, @sequence, @time)
+
+        # Length adjustments don't matter here, we can just wait 20ms since nobody is going to hear it anyway
+        sleep IDEAL_LENGTH / 1000.0
+      end
+
+      @bot.debug("Performing final cleanup after stream ended")
+
+      # Final clean-up
+      stop_playing
+
+      # Notify any stop_playing methods running right now that we have actually stopped
+      @has_stopped_playing = true
+    end
+
+    # Increment sequence and time
+    def increment_packet_headers
+      (@sequence + 10 < 65_535) ? @sequence += 1 : @sequence = 0
+      (@time + 9600 < 4_294_967_295) ? @time += 960 : @time = 0
+    end
+  end
+end

data/lib/rubycord/webhooks/builder.rb

@@ -0,0 +1,100 @@
+require "rubycord/webhooks/embeds"
+
+module Rubycord::Webhooks
+  # A class that acts as a builder for a webhook message object.
+  class Builder
+    def initialize(content: "", username: nil, avatar_url: nil, tts: false, file: nil, embeds: [], allowed_mentions: nil)
+      @content = content
+      @username = username
+      @avatar_url = avatar_url
+      @tts = tts
+      @file = file
+      @embeds = embeds
+      @allowed_mentions = allowed_mentions
+    end
+
+    # The content of the message. May be 2000 characters long at most.
+    # @return [String] the content of the message.
+    attr_accessor :content
+
+    # The username the webhook will display as. If this is not set, the default username set in the webhook's settings
+    # will be used instead.
+    # @return [String] the username.
+    attr_accessor :username
+
+    # The URL of an image file to be used as an avatar. If this is not set, the default avatar from the webhook's
+    # settings will be used instead.
+    # @return [String] the avatar URL.
+    attr_accessor :avatar_url
+
+    # Whether this message should use TTS or not. By default, it doesn't.
+    # @return [true, false] the TTS status.
+    attr_accessor :tts
+
+    # Sets a file to be sent together with the message. Mutually exclusive with embeds; a webhook message can contain
+    # either a file to be sent or an embed.
+    # @param file [File] A file to be sent.
+    def file=(file)
+      raise ArgumentError, "Embeds and files are mutually exclusive!" unless @embeds.empty?
+
+      @file = file
+    end
+
+    # Adds an embed to this message.
+    # @param embed [Embed] The embed to add.
+    def <<(embed)
+      raise ArgumentError, "Embeds and files are mutually exclusive!" if @file
+
+      @embeds << embed
+    end
+
+    # Convenience method to add an embed using a block-style builder pattern
+    # @example Add an embed to a message
+    #   builder.add_embed do |embed|
+    #     embed.title = 'Testing'
+    #     embed.image = Rubycord::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
+    #   end
+    # @param embed [Embed, nil] The embed to start the building process with, or nil if one should be created anew.
+    # @return [Embed] The created embed.
+    def add_embed(embed = nil)
+      embed ||= Embed.new
+      yield(embed)
+      self << embed
+      embed
+    end
+
+    # @return [File, nil] the file attached to this message.
+    attr_reader :file
+
+    # @return [Array<Embed>] the embeds attached to this message.
+    attr_reader :embeds
+
+    # @return [Rubycord::AllowedMentions, Hash] Mentions that are allowed to ping in this message.
+    # @see https://discord.com/developers/docs/resources/channel#allowed-mentions-object
+    attr_accessor :allowed_mentions
+
+    # @return [Hash] a hash representation of the created message, for JSON format.
+    def to_json_hash
+      {
+        content: @content,
+        username: @username,
+        avatar_url: @avatar_url,
+        tts: @tts,
+        embeds: @embeds.map(&:to_hash),
+        allowed_mentions: @allowed_mentions&.to_hash
+      }
+    end
+
+    # @return [Hash] a hash representation of the created message, for multipart format.
+    def to_multipart_hash
+      {
+        content: @content,
+        username: @username,
+        avatar_url: @avatar_url,
+        tts: @tts,
+        file: @file,
+        allowed_mentions: @allowed_mentions&.to_hash
+      }
+    end
+  end
+end

data/lib/rubycord/webhooks/client.rb

@@ -0,0 +1,132 @@
+require "rest-client"
+require "json"
+
+require "rubycord/webhooks/builder"
+
+module Rubycord::Webhooks
+  # A client for a particular webhook added to a Discord channel.
+  class Client
+    # Create a new webhook
+    # @param url [String] The URL to post messages to.
+    # @param id [Integer] The webhook's ID. Will only be used if `url` is not
+    #   set.
+    # @param token [String] The webhook's authorisation token. Will only be used
+    #   if `url` is not set.
+    def initialize(url: nil, id: nil, token: nil)
+      @url = url || generate_url(id, token)
+    end
+
+    # Executes the webhook this client points to with the given data.
+    # @param builder [Builder, nil] The builder to start out with, or nil if one should be created anew.
+    # @param wait [true, false] Whether Discord should wait for the message to be successfully received by clients, or
+    #   whether it should return immediately after sending the message.
+    # @yield [builder] Gives the builder to the block to add additional steps, or to do the entire building process.
+    # @yieldparam builder [Builder] The builder given as a parameter which is used as the initial step to start from.
+    # @example Execute the webhook with an already existing builder
+    #   builder = Rubycord::Webhooks::Builder.new # ...
+    #   client.execute(builder)
+    # @example Execute the webhook by building a new message
+    #   client.execute do |builder|
+    #     builder.content = 'Testing'
+    #     builder.username = 'rubycord'
+    #     builder.add_embed do |embed|
+    #       embed.timestamp = Time.now
+    #       embed.title = 'Testing'
+    #       embed.image = Rubycord::Webhooks::EmbedImage.new(url: 'https://i.imgur.com/PcMltU7.jpg')
+    #     end
+    #   end
+    # @return [RestClient::Response] the response returned by Discord.
+    def execute(builder = nil, wait = false, components = nil)
+      raise TypeError, "builder needs to be nil or like a Rubycord::Webhooks::Builder!" if
+        !(builder.respond_to?(:file) && builder.respond_to?(:to_multipart_hash)) && !builder.respond_to?(:to_json_hash) && !builder.nil?
+
+      builder ||= Builder.new
+      view = View.new
+
+      yield(builder, view) if block_given?
+
+      components ||= view
+
+      if builder.file
+        post_multipart(builder, components, wait)
+      else
+        post_json(builder, components, wait)
+      end
+    end
+
+    # Modify this webhook's properties.
+    # @param name [String, nil] The default name.
+    # @param avatar [String, #read, nil] The new avatar, in base64-encoded JPG format.
+    # @param channel_id [String, Integer, nil] The channel to move the webhook to.
+    # @return [RestClient::Response] the response returned by Discord.
+    def modify(name: nil, avatar: nil, channel_id: nil)
+      RestClient.patch(@url, {name: name, avatar: avatarise(avatar), channel_id: channel_id}.compact.to_json, content_type: :json)
+    end
+
+    # Delete this webhook.
+    # @param reason [String, nil] The reason this webhook was deleted.
+    # @return [RestClient::Response] the response returned by Discord.
+    # @note This is permanent and cannot be undone.
+    def delete(reason: nil)
+      RestClient.delete(@url, "X-Audit-Log-Reason": reason)
+    end
+
+    # Edit a message from this webhook.
+    # @param message_id [String, Integer] The ID of the message to edit.
+    # @param builder [Builder, nil] The builder to start out with, or nil if one should be created anew.
+    # @param content [String] The message content.
+    # @param embeds [Array<Embed, Hash>]
+    # @param allowed_mentions [Hash]
+    # @return [RestClient::Response] the response returned by Discord.
+    # @example Edit message content
+    #   client.edit_message(message_id, content: 'goodbye world!')
+    # @example Edit a message via builder
+    #   client.edit_message(message_id) do |builder|
+    #     builder.add_embed do |e|
+    #       e.description = 'Hello World!'
+    #     end
+    #   end
+    # @note Not all builder options are available when editing.
+    def edit_message(message_id, builder: nil, content: nil, embeds: nil, allowed_mentions: nil)
+      builder ||= Builder.new
+
+      yield builder if block_given?
+
+      data = builder.to_json_hash.merge({content: content, embeds: embeds, allowed_mentions: allowed_mentions}.compact)
+      RestClient.patch("#{@url}/messages/#{message_id}", data.compact.to_json, content_type: :json)
+    end
+
+    # Delete a message created by this webhook.
+    # @param message_id [String, Integer] The ID of the message to delete.
+    # @return [RestClient::Response] the response returned by Discord.
+    def delete_message(message_id)
+      RestClient.delete("#{@url}/messages/#{message_id}")
+    end
+
+    private
+
+    # Convert an avatar to API ready data.
+    # @param avatar [String, #read] Avatar data.
+    def avatarise(avatar)
+      if avatar.respond_to? :read
+        "data:image/jpg;base64,#{Base64.strict_encode64(avatar.read)}"
+      else
+        avatar
+      end
+    end
+
+    def post_json(builder, components, wait)
+      data = builder.to_json_hash.merge({components: components.to_a})
+      RestClient.post(@url + (wait ? "?wait=true" : ""), data.to_json, content_type: :json)
+    end
+
+    def post_multipart(builder, components, wait)
+      data = builder.to_multipart_hash.merge({components: components.to_a})
+      RestClient.post(@url + (wait ? "?wait=true" : ""), data)
+    end
+
+    def generate_url(id, token)
+      "https://discord.com/api/v9/webhooks/#{id}/#{token}"
+    end
+  end
+end