mirror of
https://github.com/onyx-and-iris/obsws-ruby.git
synced 2024-11-15 18:50:47 +00:00
onyx-and-iris
aafcd185d0
add full request payload to logger. raise OBSWSError if auth enabled but no password provided add example tasks to rake file add logging section to README
144 lines
3.1 KiB
Markdown
144 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/prettier/plugin-ruby)
|
|
|
|
# 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"
|
|
|
|
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:
|
|
|
|
```ruby
|
|
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](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)
|