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
  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

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