mirror of
https://github.com/onyx-and-iris/obsws-ruby.git
synced 2024-11-15 18:50:47 +00:00
141 lines
3.1 KiB
Markdown
141 lines
3.1 KiB
Markdown
[](https://badge.fury.io/rb/obsws)
|
|
[](https://github.com/onyx-and-iris/obsws-ruby/blob/dev/LICENSE)
|
|
[](https://github.com/standardrb/standard)
|
|
|
|
# A Ruby wrapper around OBS Studio WebSocket v5.0
|
|
|
|
## Requirements
|
|
|
|
- [OBS Studio](https://obsproject.com/)
|
|
- [OBS Websocket v5 Plugin](https://github.com/obsproject/obs-websocket/releases/tag/5.0.0)
|
|
- 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.
|
|
|
|
```ruby
|
|
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:
|
|
|
|
```ruby
|
|
# GetVersion
|
|
resp = r_client.get_version
|
|
|
|
# SetCurrentProgramScene
|
|
r_client.set_current_program_scene("BRB")
|
|
```
|
|
|
|
For a full list of requests refer to [Requests](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requests)
|
|
|
|
### Events
|
|
|
|
Register an observer class and define `on_` methods for events. Method names should match the api event but snake cased.
|
|
|
|
example:
|
|
|
|
```ruby
|
|
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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#events)
|
|
|
|
### Attributes
|
|
|
|
For both request responses and event data you may inspect the available attributes using `attrs`.
|
|
|
|
example:
|
|
|
|
```ruby
|
|
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](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#requeststatus)
|
|
|
|
### Logging
|
|
|
|
To see the raw messages set log level to debug
|
|
|
|
example:
|
|
|
|
```ruby
|
|
require "obsws"
|
|
|
|
OBSWS::LOGGER.debug!
|
|
...
|
|
```
|
|
|
|
### Tests
|
|
|
|
To run all tests:
|
|
|
|
```
|
|
bundle exec rake -v
|
|
```
|
|
|
|
### Official Documentation
|
|
|
|
For the full documentation:
|
|
|
|
- [OBS Websocket SDK](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md#obs-websocket-501-protocol)
|