obs-websocket 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 60bbb3f01fc0e188ac097d94be7e06b44c75ff002fbe472a3a1ab250c546c466
+  data.tar.gz: b09a363ab96faa4cfd516d5f76f6f5d101e4b562be3bb6d53deddc5b4c2db20c
+SHA512:
+  metadata.gz: 7bc1716e17df1452b8a666c4362b64189d64825f1a114348c9625cb8420601f28022b32ed1379d539c694575e84905ee8e127d017be6c6255975a2d4ef06ec77
+  data.tar.gz: 6643bb0a4b17ca827a5e31ff2e30560adaa05babebbdb10932ab9dba44465a2c6f5c443cede4d8ab1a10c6e2472be95a41f656d7443f421fd098a55c36b4e8ca

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# ChangeLog
+
+## UNRELEASED
+
+## v0.1.0 (2021-0524)
+- Initial release

data/HACKING.md

@@ -0,0 +1,13 @@
+# Hacking ruby-obs-websocket
+
+All contributions including patches and bug reports are welcome at GitHub <https://github.com/hanazuki/ruby-obs-websocket>.
+
+## Packaging and release
+
+### Update obs/websocket/protocol.rb
+
+When a new version of obs-websocket is released or the codegen script is modified, take the following steps to generate the updated protocol definition.
+
+1. Change `API_VERSION` in `Rakefile`.
+2. Run `rake codegen`
+3. Commit (and release).

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Kasumi Hanazuki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,7 @@
+# OBS::WebSocket
+
+OBS::WebSocket is a [Ruby](https://www.ruby-lang.org) library to remotely controls [OBS Studio](https://obsproject.com/) using [obs-websocket](https://github.com/Palakis/obs-websocket) API.
+
+## Usage
+
+See examples/ for a runnable code example.

data/examples/websocket-driver/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'obs-websocket', path: '../..'
+gem 'websocket-driver'

data/examples/websocket-driver/Gemfile.lock

@@ -0,0 +1,23 @@
+PATH
+  remote: ../..
+  specs:
+    obs-websocket (0.1.0)
+      concurrent-ruby (~> 1.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    concurrent-ruby (1.1.8)
+    websocket-driver (0.7.3)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  obs-websocket!
+  websocket-driver
+
+BUNDLED WITH
+   2.2.15

data/examples/websocket-driver/main.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# SPDX-License-Identifier: MIT
+
+ENV['BUNDLE_GEMFILE'] = File.join(__dir__, 'Gemfile')
+require 'bundler/setup'
+
+require 'obs/websocket'
+require 'socket'
+require 'uri'
+require 'websocket/driver'
+
+class Main
+  def run(uri, password)
+    connect(URI.parse(uri))
+
+    # To initialize OBS::WebSocket, pass a WebSocket connection.
+    obs = OBS::WebSocket::Client.new(@driver)
+
+    obs.on_open do
+      obs.authenticate!(password).value!
+
+      # Request methods return Future values that can be waited for by `value!`.
+      version = obs.get_version.value!
+      puts "OBS version: #{version.obs_studio_version}; OBS-websocket version: #{version.obs_websocket_version}"
+
+      # Pass request parameters using keyword arguments. Composite types are mapped to Hash objects.
+      obs.broadcast_custom_message(
+        realm: 'helloworld',
+        data: {greeting: 'Hello, World!'}
+      ).wait!
+    rescue => e
+      $stderr.puts e.message
+      obs.close
+    end
+
+    # Listen for events using `on_*` methods. The event payload is yielded to the block.
+    obs.on_broadcast_custom_message do |ev|
+      puts ev.data['greeting']
+      obs.close
+    end
+
+    obs.on_close(executor: :immediate) do |code, reason|
+      puts "Bye! (code: #{code})"
+    end
+
+    start_driver
+  end
+
+  private
+
+  def connect(uri)
+    fail ArgumentError, 'Only supports ws:// URI' unless uri.scheme == 'ws'
+
+    @socket = TCPSocket.new(uri.host, uri.port || 80)
+    @driver = WebSocket::Driver.client(SocketWrapper.new(uri.to_s, @socket))
+  end
+
+  def start_driver
+    @driver.start
+
+    loop do
+      @driver.parse(@socket.readpartial(4096))
+    rescue EOFError
+      break
+    end
+  end
+
+  class SocketWrapper
+    def initialize(url, socket)
+      @url = url
+      @socket = socket
+    end
+
+    attr_reader :url
+
+    def write(s)
+      @socket.write(s)
+    end
+  end
+end
+
+if $0 == __FILE__
+  if ARGV.size != 2
+    $stderr.puts "Usage: #{File.basename __FILE__} ws://HOST:PORT PASSWORD"
+    exit 1
+  end
+
+  Main.new.run(*ARGV)
+end

data/lib/obs-websocket.rb

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+
+require_relative 'obs/websocket'

data/lib/obs/websocket.rb

@@ -0,0 +1,443 @@
+# SPDX-License-Identifier: MIT
+
+require 'concurrent'
+require 'digest/sha2'
+require 'json'
+require 'securerandom'
+
+require_relative 'websocket/version'
+
+module OBS
+  module WebSocket
+    class Error < StandardError; end
+
+    class RequestError < Error; end
+
+    # Shortcut for {OBS::WebSocket::Client#initialize}
+    #
+    # @see OBS::WebSocket::Client#initialize
+    def self.new(*args, **kwargs)
+      Client.new(*args, **kwargs)
+    end
+
+    # OBS-websocket client.
+    class Client
+      # Creates an OBS-websocket client.
+      #
+      # <tt>websocket</tt> object must respond to the following methods:
+      # - <tt>text(str)</tt>: send a text frame
+      # - <tt>on(event, &block)</tt>: add an event handler
+      # - <tt>close()</tt>: close the connection
+      #
+      # @param websocket [Object] the websocket object
+      # @param executor the executor on which the callbacks are invoked
+      def initialize(websocket, executor: :io)
+        @websocket = websocket
+        @response_dispatcher = ResponseDispatcher.new
+        @event_dispatcher = EventDispatcher.new
+        @executor = executor
+        @on_open = Concurrent::Promises.resolvable_event
+        @on_close = Concurrent::Promises.resolvable_future
+
+        websocket.on(:open) do
+          @on_open.resolve
+        end
+
+        websocket.on(:close) do |event|
+          @on_close.resolve(true, [event.code, event.reason])
+        end
+
+        websocket.on(:message) do |event|
+          handle_message(JSON.parse(event.data))
+        end
+
+        websocket.on(:error) do |event|
+          $stderr.puts "Error: #{event.code} #{event.reason}"
+        end
+      end
+
+      # Authenticates the client to the server using the password.
+      #
+      # @param password [String] the password
+      # @return [Future<:ok>]
+      def authenticate!(password)
+        get_auth_required.then do |h|
+          if h.auth_required
+            token = auth_token(
+              password: password,
+              salt: h.salt,
+              challenge: h.challenge,
+            )
+            authenticate(auth: token).then { :ok }
+          else
+            :ok
+          end
+        end.flat
+      end
+
+      # Adds an event handler for connection establishment.
+      #
+      # @param executor the executor on which the callback is invoked
+      # @yield Called when obs-websocket connection is established.
+      # @return [Event]
+      def on_open(executor: @executor, &listener)
+        if listener
+          @on_open.chain_on(executor, &listener)
+        else
+          @on_open.with_default_executor(executor)
+        end
+      end
+
+      # Adds an event handler for connection termination.
+      #
+      # @param executor the executor on which the callback is invoked
+      # @yield Called when obs-websocket connection is terminated.
+      # @return [Future]
+      def on_close(executor: @executor, &listener)
+        if listener
+          @on_close.then_on(executor, &listener)
+        else
+          @on_close.with_default_executor(executor)
+        end
+      end
+
+      # Adds an event handler for obs-websocket event.
+      #
+      # @param type [String] type of obs-websocket event to listen for
+      # @param executor the executor on which the callback is invoked
+      # @yield Called when the specified type of obs-websocket event is received.
+      # @yieldparam event [Event] the event object
+      # @return [void]
+      def on(type, executor: @executor, &listener)
+        @event_dispatcher.register(executor, type, listener)
+        nil
+      end
+
+      # Close the connection.
+      #
+      # @return [void]
+      def close
+        @websocket.close
+      end
+
+      private
+
+      def auth_token(password:, salt:, challenge:)
+        Digest::SHA256.base64digest(Digest::SHA256.base64digest(password + salt) + challenge)
+      end
+
+      def send_request(request)
+        message_id, future = @response_dispatcher.register(@executor, request)
+        @websocket.text(JSON.dump({**request.to_h, 'message-id' => message_id}))
+        future
+      end
+
+      def handle_message(payload)
+        if message_id = payload['message-id']
+          @response_dispatcher.dispatch(message_id, payload)
+        elsif update_type = payload['update-type']
+          @event_dispatcher.dispatch(update_type, payload)
+        else
+          fail 'Unknown message'
+        end
+     end
+    end
+
+    class EventDispatcher
+      def initialize
+        @listeners = Hash.new {|h, k| h[k] = []}
+      end
+
+      def register(executor, type, listener)
+        @listeners[type].push([executor, listener])
+      end
+
+      def dispatch(update_type, payload)
+        event = Protocol::Event.create(update_type, payload).freeze
+        @listeners[update_type].each do |(executor, listener)|
+          Concurrent::Promises.future_on(executor, event, &listener).run
+        end
+      end
+    end
+
+    class ResponseDispatcher
+      def initialize
+        @ongoing_requests = {}
+      end
+
+      def register(executor, request)
+        message_id = new_message_id
+        future = Concurrent::Promises.resolvable_future_on(executor)
+
+        @ongoing_requests[message_id] = {
+          request: request,
+          future: future,
+        }
+
+        [message_id, future.with_hidden_resolvable]
+      end
+
+      def dispatch(message_id, payload)
+        if h = @ongoing_requests.delete(message_id)
+          request = h[:request]
+          future = h[:future]
+
+          case payload['status']
+          when 'ok'
+            response_class = request.class.const_get(:Response)
+            future.fulfill(response_class.new(payload))
+          when 'error'
+            future.reject(RequestError.new(payload['error']))
+          else
+            fail 'Unknown status'
+          end
+        end
+      end
+
+      private
+
+      def new_message_id
+        SecureRandom.uuid
+      end
+    end
+
+    module Protocol
+      class Type
+        def initialize(**kwargs, &block)
+          kwargs.each do |k, v|
+            instance_variable_set(:"@#{k}", v)
+          end
+          instance_eval(&block)
+        end
+
+        attr_reader :name
+      end
+
+      module Types
+        Boolean = Type.new(name: 'Boolean') do
+          def as_ruby(b)
+            !!b
+          end
+
+          def as_json(b)
+            !!b
+          end
+        end
+
+        Integer = Type.new(name: 'Int') do
+          def as_ruby(i)
+            i.to_i
+          end
+
+          def as_json(i)
+            i.to_i
+          end
+        end
+
+        Float = Type.new(name: 'Double') do
+          def as_ruby(f)
+            f.to_f
+          end
+
+          def as_json(f)
+            f.to_f
+          end
+        end
+        Numeric = Float
+
+        String = Type.new(name: 'String') do
+          def as_ruby(s)
+            s.to_s
+          end
+
+          def as_json(s)
+            s.to_s
+          end
+        end
+
+        Optional = Class.new do
+          def [](element_type)
+            Type.new(name: "Optional[#{element_type.name}]", element_type: element_type) do
+              def as_ruby(v)
+                return unless v
+                @element_type.as_ruby(v)
+              end
+
+              def as_json(v)
+                return unless v
+                @element_type.as_json(v)
+              end
+            end
+          end
+        end.new
+
+        Array = Class.new do
+          def [](element_type)
+            Type.new(name: "Array[#{element_type.name}]", element_type: element_type) do
+              def as_ruby(a)
+                a.to_a.map {|v| @element_type.as_ruby(v) }
+              end
+
+              def as_json(a)
+                a.to_a.map {|v| @element_type.as_json(v) }
+              end
+            end
+          end
+        end.new
+
+        Object = Type.new(name: 'Object') do
+          def as_ruby(o)
+            o.to_h
+          end
+
+          def as_json(o)
+            o.to_h
+          end
+
+          def [](fields)
+            Type.new(name: "Object[#{fields.keys.map(&:to_s).join(', ')}]", fields: fields) do
+              def as_ruby(o)
+                @fields.to_h do |name, field|
+                  json_name = field[:json_name]
+                  type = field[:type]
+                  [name, type.as_ruby(o[json_name])]
+                end
+              end
+
+              def as_json(a)
+                @fields.to_h do |name, field|
+                  json_name = field[:json_name]
+                  type = field[:type]
+                  [json_name, type.as_ruby(o[name])]
+                end
+              end
+            end
+          end
+        end
+
+        StringOrObject = Type.new(name: 'Object') do
+          def as_ruby(o)
+            String === o ? o : o.to_h
+          end
+
+          def as_json(o)
+            o.respond_to?(:to_str) ? o.to_str : o.to_h
+          end
+
+          def [](fields)
+            Type.new(name: "Object[#{fields.keys.map(&:to_s).join(', ')}]", fields: fields) do
+              def as_ruby(o)
+                return o if String === o
+
+                @fields.to_h do |name, field|
+                  json_name = field[:json_name]
+                  type = field[:type]
+                  [name, type.as_ruby(o[json_name])]
+                end
+              end
+
+              def as_json(a)
+                return o.to_str if o.respond_to?(:to_str)
+
+                @fields.to_h do |name, field|
+                  json_name = field[:json_name]
+                  type = field[:type]
+                  [json_name, type.as_ruby(o[name])]
+                end
+              end
+            end
+          end
+        end
+      end
+
+      class ServerMessage
+      end
+
+      class ClientMessage
+      end
+
+      class Event < ServerMessage
+        CLASSES_BY_JSON_NAME = {}
+        private_constant :CLASSES_BY_JSON_NAME
+
+        def self.json_name(json_name)
+          CLASSES_BY_JSON_NAME[json_name] = self
+        end
+
+        def self.create(type, payload)
+          cls = CLASSES_BY_JSON_NAME[type] || UnknownEvent
+          cls.new(payload)
+        end
+
+        def initialize(json)
+          @json = json
+        end
+
+        private def get_field(name, type)
+          type.as_ruby(@json[name])
+        end
+
+        def to_h
+          @json
+        end
+
+        def update_type
+          get_field('update-type', Types::String)
+        end
+        def stream_timecode;
+          get_field('stream-timecode', Types::Optional[Types::String])
+        end
+        def rec_timecode
+          get_field('rec-timecode', Types::Optional[Types::String])
+        end
+      end
+
+      class UnknownEvent < Event
+      end
+
+      class Request < ClientMessage
+        class << self
+          def json_name(json_name)
+            @json_name = json_name
+          end
+
+          def params(params = {})
+            (@params ||= {}).update(params)
+          end
+        end
+
+        def initialize(args)
+          @json = self.class.instance_variable_get(:@params).to_h do |name, v|
+            type = v[:type]
+            json_name = v[:json_name]
+            [json_name, type.as_json(args[name])]
+          end
+          @json['request-type'] = self.class.instance_variable_get(:@json_name)
+        end
+
+        def to_h
+          @json
+        end
+      end
+
+      class Response < ServerMessage
+        def initialize(json)
+          @json = json
+        end
+
+        def to_h
+          @json
+        end
+
+        private def get_field(name, type)
+          type.as_ruby(@json[name])
+        end
+      end
+    end
+
+    require_relative 'websocket/protocol'
+
+    Client.include Protocol::Event::Mixin
+    Client.include Protocol::Request::Mixin
+  end
+end