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"

def main
  r_client =
    OBSWS::Requests::Client.new(
      host: "localhost",
      port: 4455,
      password: "strongpassword"
    )

  r_client.run do
    # Toggle the mute state of your Mic input
    r_client.toggle_input_mute("Mic/Aux")
  end
end

main if $0 == __FILE__

Requests

Method names for requests match the API calls but snake cased. run accepts a block that closes the socket once you are done.

example:

r_client.run do
  # GetVersion
  resp = r_client.get_version

  # SetCurrentProgramScene
  r_client.set_current_program_scene("BRB")
end

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 see the raw messages set log level to debug

example:

require "obsws"

OBSWS::LOGGER.debug!
...

Tests

To run all tests:

bundle exec rake -v

Official Documentation

For the full documentation:

• OBS Websocket SDK