obsws-ruby/README.md

138 lines
3.1 KiB
Markdown
Raw Normal View History

2022-10-23 05:20:05 +01:00
[![Gem Version](https://badge.fury.io/rb/obsws.svg)](https://badge.fury.io/rb/obsws)
2022-10-23 05:25:47 +01:00
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/onyx-and-iris/obsws-ruby/blob/dev/LICENSE)
[![Ruby Code Style](https://img.shields.io/badge/code_style-standard-violet.svg)](https://github.com/standardrb/standard)
2022-10-22 22:30:40 +01:00
2023-07-26 16:12:38 +01:00
# Ruby Clients for OBS Studio WebSocket v5.0
2022-10-22 22:30:40 +01:00
## 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
2022-10-22 22:30:40 +01:00
2022-10-24 02:01:30 +01:00
## Installation
### Bundler
```
bundle add 'obsws'
bundle install
```
### Gem
`gem install 'obsws'`
2022-10-22 22:30:40 +01:00
## `Use`
#### Example `main.rb`
2023-07-21 06:37:14 +01:00
Pass `host`, `port` and `password` as keyword arguments.
2022-10-22 22:30:40 +01:00
```ruby
2022-10-22 22:35:55 +01:00
require "obsws"
2022-10-22 22:30:40 +01:00
2023-07-21 06:37:14 +01:00
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
2022-10-22 22:30:40 +01:00
end
2023-07-21 06:37:14 +01:00
Main.new.run if $PROGRAM_NAME == __FILE__
2022-10-22 22:30:40 +01:00
```
2023-07-21 06:37:14 +01:00
Passing OBSWS::Requests::Client.run a block closes the socket once the block returns.
2022-10-22 22:30:40 +01:00
### Requests
2023-07-21 06:37:14 +01:00
Method names for requests match the API calls but snake cased.
2022-10-22 22:30:40 +01:00
example:
```ruby
2023-07-21 06:37:14 +01:00
# GetVersion
resp = r_client.get_version
2022-10-22 22:30:40 +01:00
2023-07-21 06:37:14 +01:00
# SetCurrentProgramScene
r_client.set_current_program_scene("BRB")
2022-10-22 22:30:40 +01:00
```
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 enable logs set an environmental variable `OBSWS_LOG_LEVEL` to the appropriate level.
example in powershell:
```powershell
$env:OBSWS_LOG_LEVEL="DEBUG"
```
2022-10-22 22:30:40 +01:00
### 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)