obsws-ruby/README.md

A Ruby wrapper around OBS Studio WebSocket v5.0

Requirements

• OBS Studio
• OBS Websocket v5 Plugin
  • With the release of OBS Studio version 28, Websocket plugin is included by default. But it should be manually installed for earlier versions of OBS.
• Ruby 3.0 or greater

Installation

Bundler

bundle add 'obsws'
bundle install

Gem

gem install 'obsws'

Use

Example main.rb

Pass host, port and password as keyword arguments.

require "obsws"

class Main
  def run
    OBSWS::Requests::Client
      .new(host: "localhost", port: 4455, password: "strongpassword")
      .run do |client|
        # Toggle the mute state of your Mic input
        client.toggle_input_mute("Mic/Aux")
      end
  end
end

Main.new.run if $PROGRAM_NAME == __FILE__

Passing OBSWS::Requests::Client.run a block closes the socket once the block returns.

Requests

Method names for requests match the API calls but snake cased.

example:

# GetVersion
resp = r_client.get_version

# SetCurrentProgramScene
r_client.set_current_program_scene("BRB")

For a full list of requests refer to Requests

Events

Register an observer class and define on_ methods for events. Method names should match the api event but snake cased.

example:

class Observer
    def initialize
        @e_client = OBSWS::Events::Client.new(**kwargs)
        # register class with the event client
        @e_client.add_observer(self)
    end

    # define "on_" event methods.
    def on_current_program_scene_changed
        ...
    end
    def on_input_mute_state_changed
        ...
    end
    ...
end

For a full list of events refer to Events

Attributes

For both request responses and event data you may inspect the available attributes using attrs.

example:

resp = cl.get_version
p resp.attrs

def on_scene_created(data):
    p data.attrs

Errors

If a request fails an OBSWSError will be raised with a status code.

For a full list of status codes refer to Codes

Logging

To enable logs set an environmental variable OBSWS_LOG_LEVEL to the appropriate level.

example in powershell:

$env:OBSWS_LOG_LEVEL="DEBUG"

Tests

To run all tests:

bundle exec rake -v

Official Documentation

For the full documentation:

• OBS Websocket SDK