adds Events::Client.on method

allows registering blocks to be called back later

examples, readme updated

minor bump

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    obsws (0.5.3)
+    obsws (0.5.8)
       waitutil (~> 0.2.1)
       websocket-driver (~> 0.7.5)
 

README.md

@@ -30,12 +30,16 @@ Pass `host`, `port` and `password` as keyword arguments.
 require "obsws"
 
 class Main
+  INPUT = "Mic/Aux"
+
   def run
     OBSWS::Requests::Client
       .new(host: "localhost", port: 4455, password: "strongpassword")
       .run do |client|
-        # Toggle the mute state of your Mic input
+      # Toggle the mute state of your Mic input and print its new mute state
-        client.toggle_input_mute("Mic/Aux")
+      client.toggle_input_mute(INPUT)
+      resp = client.get_input_mute(INPUT)
+      puts "Input '#{INPUT}' was set to #{resp.input_muted}"
     end
   end
 end
@@ -63,7 +67,7 @@ For a full list of requests refer to [Requests](https://github.com/obsproject/ob
 
 ### Events
 
-Register `on_` callback methods. Method names should match the api event but snake cased.
+Register blocks with the Event client using the `on` method. The event data will be passed to the block.
 
 example:
 
@@ -71,23 +75,14 @@ example:
 class Observer
     def initialize
         @e_client = OBSWS::Events::Client.new(host: "localhost", port: 4455, password: "strongpassword")
-        # register callback methods with the Event client
+        # register blocks on event types.
-        @e_client.register(
+        @e_client.on(:current_program_scene_changed) do |data|
-          [
-            method(:on_current_program_scene_changed),
-            method(:on_input_mute_state_changed)
-          ]
-        )
-    end
-
-    # define "on_" event methods.
-    def on_current_program_scene_changed(data)
           ...
         end
-    def on_input_mute_state_changed(data)
+        @e_client.on(:input_mute_state_changed) do |data|
           ...
         end
-    ...
+    end
 end
 ```
 
@@ -115,7 +110,9 @@ If a connection attempt fails or times out an `OBSWSConnectionError` will be rai
 
 If a request fails an `OBSWSRequestError` will be raised with a status code.
 
-- The request name and code are retrievable through attributes {OBSWSRequestError}.req_name and {OBSWSRequestError}.code
+- The request name and code are retrievable through the following attributes:
+  - `req_name`
+  - `code`
 
 For a full list of status codes refer to [Codes](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requeststatus)
 

examples/events/main.rb

@@ -1,21 +1,28 @@
 require_relative "../../lib/obsws"
 require "yaml"
 
-
 class Main
-  attr_reader :running
-
   def initialize(**kwargs)
     @r_client = OBSWS::Requests::Client.new(**kwargs)
     @e_client = OBSWS::Events::Client.new(**kwargs)
-    @e_client.add_observer(self)
 
-    puts infostring
+    @e_client.on(:current_program_scene_changed) do |data|
-    @running = true
+      puts "Switched to scene #{data.scene_name}"
+    end
+    @e_client.on(:scene_created) do |data|
+      puts "scene #{data.scene_name} has been created"
+    end
+    @e_client.on(:input_mute_state_changed) do |data|
+      puts "#{data.input_name} mute toggled"
+    end
+    @e_client.on(:exit_started) do
+      puts "OBS closing!"
+      @r_client.close
+      @e_client.close
+      @running = false
     end
 
-  def run
+    puts infostring
-    sleep(0.1) while running
   end
 
   def infostring
@@ -26,23 +33,9 @@ class Main
     ].join(" ")
   end
 
-  def on_current_program_scene_changed(data)
+  def run
-    puts "Switched to scene #{data.scene_name}"
+    @running = true
-  end
+    sleep(0.1) while @running
-
-  def on_scene_created(data)
-    puts "scene #{data.scene_name} has been created"
-  end
-
-  def on_input_mute_state_changed(data)
-    puts "#{data.input_name} mute toggled"
-  end
-
-  def on_exit_started
-    puts "OBS closing!"
-    @r_client.close
-    @e_client.close
-    @running = false
   end
 end
 

examples/levels/main.rb

@@ -13,26 +13,13 @@ class Main
   def initialize(**kwargs)
     subs = OBSWS::Events::SUBS::LOW_VOLUME | OBSWS::Events::SUBS::INPUTVOLUMEMETERS
     @e_client = OBSWS::Events::Client.new(subs:, **kwargs)
-    @e_client.register(
-      [
-        method(:on_input_mute_state_changed),
-        method(:on_input_volume_meters)
-      ]
-    )
-  end
 
-  def run
+    @e_client.on(:input_mute_state_changed) do |data|
-    puts "press <Enter> to quit"
-    loop { break if gets.chomp.empty? }
-  end
-
-  def on_input_mute_state_changed(data)
       if data.input_name == DEVICE
         puts "#{DEVICE} mute toggled"
       end
     end
-
+    @e_client.on(:input_volume_meters) do |data|
-  def on_input_volume_meters(data)
       fget = ->(x) { (x > 0) ? (20 * Math.log(x, 10)).round(1) : -200.0 }
 
       data.inputs.each do |d|
@@ -45,6 +32,12 @@ class Main
     end
   end
 
+  def run
+    puts "press <Enter> to quit"
+    loop { break if gets.chomp.empty? }
+  end
+end
+
 def conn_from_yaml
   YAML.load_file("obs.yml", symbolize_names: true)[:connection]
 end

lib/obsws.rb

@@ -1,9 +1,10 @@
 require "digest/sha2"
 require "json"
-require "waitutil"
-require "socket"
-require "websocket/driver"
 require "logger"
+require "securerandom"
+require "socket"
+require "waitutil"
+require "websocket/driver"
 
 require_relative "obsws/logger"
 require_relative "obsws/driver"
@@ -24,19 +25,12 @@ module OBSWS
   class OBSWSRequestError < OBSWSError
     attr_reader :req_name, :code
 
-    def initialize(req_name, code, msg)
+    def initialize(req_name, code, comment)
       @req_name = req_name
       @code = code
-      @msg = msg
+      message = "Request #{@req_name} returned code #{@code}."
+      message << " With message: #{comment}" if comment
       super(message)
     end
-
-    def message
-      msg = [
-        "Request #{@req_name} returned code #{@code}."
-      ]
-      msg << "With message: #{@msg}" if @msg
-      msg.join(" ")
-    end
   end
 end

lib/obsws/base.rb

@@ -1,10 +1,27 @@
 module OBSWS
+  class Identified
+    attr_accessor :state
+
+    def initialize
+      @state = :pending
+    end
+
+    def error_message
+      case @state
+      when :passwordless
+        "auth enabled but no password provided"
+      else
+        "failed to identify client with the websocket server"
+      end
+    end
+  end
+
   class Base
     include Logging
     include Driver::Director
     include Mixin::OPCodes
 
-    attr_reader :closed
+    attr_reader :closed, :identified
     attr_writer :updater
 
     def initialize(**kwargs)
@@ -12,13 +29,13 @@ module OBSWS
       port = kwargs[:port] || 4455
       @password = kwargs[:password] || ""
       @subs = kwargs[:subs] || 0
-      @connect_timeout = kwargs[:connect_timeout] || 3
+      @identified = Identified.new
       setup_driver(host, port) and start_driver
       WaitUtil.wait_for_condition(
         "successful identification",
         delay_sec: 0.01,
-        timeout_sec: @connect_timeout
+        timeout_sec: kwargs[:connect_timeout] || 3
-      ) { @identified }
+      ) { @identified.state != :pending }
     end
 
     private
@@ -39,7 +56,8 @@ module OBSWS
       }
       if auth
         if @password.empty?
-          raise OBSWSError("auth enabled but no password provided")
+          @identified.state = :passwordless
+          return
         end
         logger.info("initiating authentication")
         payload[:d][:authentication] = auth_token(**auth)
@@ -52,7 +70,7 @@ module OBSWS
       when Mixin::OPCodes::HELLO
         identify(data[:d][:authentication])
       when Mixin::OPCodes::IDENTIFIED
-        @identified = true
+        @identified.state = :identified
       when Mixin::OPCodes::EVENT, Mixin::OPCodes::REQUESTRESPONSE
         @updater.call(data[:op], data[:d])
       end

lib/obsws/event.rb

@@ -28,49 +28,46 @@ module OBSWS
       ALL = LOW_VOLUME | HIGH_VOLUME
     end
 
-    module Callbacks
+    module EventDirector
       include Util::String
 
       def observers
-        @observers ||= []
+        @observers ||= {}
       end
 
-      def add_observer(observer)
+      def on(event, method = nil, &block)
-        observer = [observer] unless observer.respond_to? :each
+        (observers[event] ||= []) << (block || method)
-        observer.each { |o| observers << o unless observers.include? o }
       end
 
-      def remove_observer(observer)
+      def register(cbs)
-        observer = [observer] unless observer.respond_to? :each
+        cbs = [cbs] unless cbs.respond_to? :each
-        observers.reject! { |o| observer.include? o }
+        cbs.each { |cb| on(cb.name[3..].to_sym, cb) }
       end
 
-      private def notify_observers(event, data)
+      def deregister(cbs)
-        observers.each do |o|
+        cbs = [cbs] unless cbs.respond_to? :each
-          if o.is_a? Method
+        cbs.each { |cb| observers[cb.name[3..].to_sym]&.reject! { |o| cbs.include? o } }
-            if o.name.to_s == "on_#{snakecase(event)}"
-              data.empty? ? o.call : o.call(data)
-            end
-          elsif o.respond_to? "on_#{snakecase(event)}"
-            data.empty? ? o.send("on_#{snakecase(event)}") : o.send("on_#{snakecase(event)}", data)
-          end
-        end
       end
 
-      alias_method :callbacks, :observers
+      def fire(event, data)
-      alias_method :register, :add_observer
+        observers[snakecase(event).to_sym]&.each { |block| data.empty? ? block.call : block.call(data) }
-      alias_method :deregister, :remove_observer
+      end
     end
 
     class Client
       include Logging
-      include Callbacks
+      include EventDirector
       include Mixin::TearDown
       include Mixin::OPCodes
 
       def initialize(**kwargs)
         kwargs[:subs] ||= SUBS::LOW_VOLUME
         @base_client = Base.new(**kwargs)
+        unless @base_client.identified.state == :identified
+          err_msg = @base_client.identified.error_message
+          logger.error(err_msg)
+          raise OBSWSConnectionError.new(err_msg)
+        end
         logger.info("#{self} successfully identified with server")
       rescue Errno::ECONNREFUSED, WaitUtil::TimeoutError => e
         msg = "#{e.class.name}: #{e.message}"
@@ -82,7 +79,7 @@ module OBSWS
             logger.debug("received: #{data}")
             event = data[:eventType]
             data = data.fetch(:eventData, {})
-            notify_observers(event, Mixin::Data.new(data, data.keys))
+            fire(event, Mixin::Data.new(data, data.keys))
           end
         }
       end

lib/obsws/req.rb

@@ -7,6 +7,11 @@ module OBSWS
 
       def initialize(**kwargs)
         @base_client = Base.new(**kwargs)
+        unless @base_client.identified.state == :identified
+          err_msg = @base_client.identified.error_message
+          logger.error(err_msg)
+          raise OBSWSConnectionError.new(err_msg)
+        end
         logger.info("#{self} successfully identified with server")
       rescue Errno::ECONNREFUSED, WaitUtil::TimeoutError => e
         logger.error("#{e.class.name}: #{e.message}")
@@ -35,13 +40,13 @@ module OBSWS
       end
 
       def call(req, data = nil)
-        id = rand(1..1000)
+        uuid = SecureRandom.uuid
-        @base_client.req(id, req, data)
+        @base_client.req(uuid, req, data)
         WaitUtil.wait_for_condition(
           "reponse id to match request id",
           delay_sec: 0.001,
           timeout_sec: 3
-        ) { @response[:requestId] == id }
+        ) { @response[:requestId] == uuid }
         unless @response[:requestStatus][:result]
           raise OBSWSRequestError.new(@response[:requestType], @response[:requestStatus][:code], @response[:requestStatus][:comment])
         end

lib/obsws/version.rb

@@ -7,11 +7,11 @@ module OBSWS
     end
 
     def minor
-      5
+      6
     end
 
     def patch
-      4
+      0
     end
 
     def to_a

main.rb

@@ -1,14 +1,16 @@
 require "obsws"
 
 class Main
+  INPUT = "Mic/Aux"
+
   def run
-    OBSWS::Requests::Client.new(
+    OBSWS::Requests::Client
-      host: "localhost",
+      .new(host: "localhost", port: 4455, password: "strongpassword")
-      port: 4455,
+      .run do |client|
-      password: "strongpassword"
+      # Toggle the mute state of your Mic input and print its new mute state
-    ).run do |client|
+      client.toggle_input_mute(INPUT)
-      # Toggle the mute state of your Mic input
+      resp = client.get_input_mute(INPUT)
-      client.toggle_input_mute("Mic/Aux")
+      puts "Input '#{INPUT}' was set to #{resp.input_muted}"
     end
   end
 end

test/obsws/test_attrs.rb

@@ -1,6 +1,6 @@
 require_relative "../minitest_helper"
 
-class AttrsTest < OBSWSTest
+class AttrsTest < Minitest::Test
   def test_get_version_attrs
     resp = OBSWSTest.r_client.get_version
     assert resp.attrs ==

test/obsws/test_error.rb

@@ -2,16 +2,35 @@ require_relative "../minitest_helper"
 
 class OBSWSConnectionErrorTest < Minitest::Test
   def test_it_raises_an_obsws_connection_error_on_wrong_password
-    e = assert_raises(OBSWS::OBSWSConnectionError) { OBSWS::Requests::Client.new(host: "localhost", port: 4455, password: "wrongpassword", connect_timeout: 1).new }
+    e = assert_raises(OBSWS::OBSWSConnectionError) do
-    assert_equal(e.message, "Timed out waiting for successful identification (1 seconds elapsed)")
+      OBSWS::Requests::Client
+        .new(host: "localhost", port: 4455, password: "wrongpassword", connect_timeout: 0.1)
+    end
+    assert_equal("Timed out waiting for successful identification (0.1 seconds elapsed)", e.message)
+  end
+
+  def test_it_raises_an_obsws_connection_error_on_auth_enabled_but_no_password_provided_for_request_client
+    e = assert_raises(OBSWS::OBSWSConnectionError) do
+      OBSWS::Requests::Client
+        .new(host: "localhost", port: 4455, password: "")
+    end
+    assert_equal("auth enabled but no password provided", e.message)
+  end
+
+  def test_it_raises_an_obsws_connection_error_on_auth_enabled_but_no_password_provided_for_event_client
+    e = assert_raises(OBSWS::OBSWSConnectionError) do
+      OBSWS::Events::Client
+        .new(host: "localhost", port: 4455, password: "")
+    end
+    assert_equal("auth enabled but no password provided", e.message)
   end
 end
 
 class OBSWSRequestErrorTest < Minitest::Test
   def test_it_raises_an_obsws_request_error_on_invalid_request
     e = assert_raises(OBSWS::OBSWSRequestError) { OBSWSTest.r_client.toggle_input_mute("unknown") }
-    assert_equal(e.req_name, "ToggleInputMute")
+    assert_equal("ToggleInputMute", e.req_name)
-    assert_equal(e.code, 600)
+    assert_equal(600, e.code)
-    assert_equal(e.message, "Request ToggleInputMute returned code 600. With message: No source was found by the name of `unknown`.")
+    assert_equal("Request ToggleInputMute returned code 600. With message: No source was found by the name of `unknown`.", e.message)
   end
 end

test/obsws/test_request.rb

@@ -1,6 +1,6 @@
 require_relative "../minitest_helper"
 
-class RequestTest < OBSWSTest
+class RequestTest < Minitest::Test
   def test_it_checks_obs_major_version
     resp = OBSWSTest.r_client.get_version
     ver = resp.obs_version.split(".").map(&:to_i)