obs.remote.kefir

OBS WebSocket integration based on Kefir streams and partial lenses for reactive applications.

---

OBS Remote

Contents

• Getting Started
• About the API
• Reference
  • OBS
    • Sessions
      • connect :: String -⁠> WebSocket
      • listen_ :: (WebSocket, (Object -⁠> Object)) -⁠> Observable
      • listen :: WebSocket -⁠> Observable
      • listenWithTransformer :: WebSocket -⁠> (Object -⁠> Object) -⁠> Observable
      • command_ :: (String, Object, WebSocket) -⁠> Observable
      • command :: String -⁠> WebSocket -⁠> Observable
      • commandWithArgs :: String -⁠> Object -⁠> WebSocket -⁠> Observable
  • Sockets
    • Core
      • createSocket_ :: (url, options) ~> WebSocket
      • createSocket :: url -> options ~> Socket
    • Listening to events
      • listenTo_ :: (socket, type) ~> Observable
      • listenToOnce_ :: (socket, type) ~> Observable
      • listenTo :: socket -> type ~> Observable
      • listenToOnce :: socket -> type ~> Observable
    • Sending commands
      • send_ :: (type, args, socket) ~> Observable
      • send2 :: (type, args) -> socket ~> Observable
      • send3 :: type -> args -> socket ~> Observable
  • Utilities
    • genFunc :: (String -⁠> Function) -⁠> (String -⁠> String)
    • inList :: a -⁠> POptic s a
    • getFromList :: Foldable f => a -⁠> f a -⁠> a
    • flatJoin :: [a] -⁠> String
    • getEvent :: ObsEvent -⁠> String
    • getRequest :: ObsRequest -⁠> String
    • splitPascal :: String -⁠> [String]
    • splitCamelCase :: String -⁠> [String]
    • camelCasePascal :: String -⁠> String
    • kebabCasePascal :: String -⁠> String
    • constCasePascal :: String -⁠> String
    • pascalCaseCamel :: String -⁠> String
    • pascalCaseKebab :: String -⁠> String
    • pascalCaseConst :: String -⁠> String
    • camelCaseKebab :: String -⁠> String
• Acknowledgements

---

Getting Started

The library has only named exports. This allows you to import as much or as little as you want from it. Either by doing

import * as socket from 'obs.remote.kefir';

or

import { createSocket, send } from 'obs.remote.kefir';

About the API

The public-facing API is with sanctuary-def, to allow run-time type checking. This helps out a lot when working with data that's coming from the outside and allows to fail fast when introduced with something we're not expecting.

Note that run-time type checking has performance implications. Checking is disabled in production, but if you find you want to disable type checking, it can be disabled with the DISABLE_TYPE_CHECKING environment variable set to 1;

stuf@local:~/project$ DISABLE_TYPE_CHECKING=1 node app.js

Reference

OBS

Contains functions for connecting to an OBS websocket, observing OBS events as well as sending commands to the OBS websocket.

const OBS = require('obs.remote.kefir/lib/obs');

Sessions

connect :: String -⁠> WebSocket

listen_ :: (WebSocket, (Object -⁠> Object)) -⁠> Observable

Listen to events from the given websocket, and uptionally apply a custom transforming function on the result.

This is the uncurried and unchecked version of the function.

listen :: WebSocket -⁠> Observable

Create an Observable from any events OBS emits.

All objects will be rewritten so that all kebab-case keys will be transformed into camelCase keys.

If you want to override the default transforming function, use listenWithTransformer instead.

Usually one creates an Observable from all events, and create new Observables by filtering the events by their event name. These can then be used on their own or by combining them to ensure some computation or action is taken when both events have occurred.

const obsEvents = listen(ws);
 
obsEvents.filter(R.whereEq({ updateType: 'transition-begin' }))
         .onValue(e => {
           // Do something when transition begins
         });
 
obsEvents.filter(R.whereEq({ updateType: 'preview-scene-changed' }))
         .onValue(e => {
           // Do something when the preview scene is changed
         });

listenWithTransformer :: WebSocket -⁠> (Object -⁠> Object) -⁠> Observable

Create an Observable from any events OBS emits, and transform the event with the given function.

command_ :: (String, Object, WebSocket) -⁠> Observable

Send a command with optional arguments to the given websocket. Uncurried.

command :: String -⁠> WebSocket -⁠> Observable

Send a command without arguments to the given websocket. Curried, takes two arguments.

commandWithArgs :: String -⁠> Object -⁠> WebSocket -⁠> Observable

Send a command with arguments to the given websocket. Curried, takes three arguments.

shouldDisableChecks :: String -⁠> String -⁠> Boolean

createEnv :: () -⁠> Function

Handling websockets per se does not require anything extra, besides using a library such as ws if you're working in a non-browser environment.

This library exposes a number of functions that can be used for handling websockets through Kefir observables, instead of using callbacks or Promises.

The functions this module exposes are meant for low-level handling of websockets. For controlling OBS specifically, refer to the OBS module.

const socket = require('obs.remote.kefir/lib/socket');

Core

createSocket_ :: (String, Object) -⁠> WebSocket

Create a new websocket connection to the given url and options.

const ws = createSocket('ws://localhost:4000');

createSocket :: String -⁠> Object -⁠> WebSocket

Curried version of createSocket_. Creates a websocket.

const newLocalSocket = createSocket('ws://localhost:4000');
const ws = newLocalSocket({ options: {} });

Listening to Events

listenTo_ :: String -⁠> WebSocket -⁠> Observable

Listen for events of a certain type from the given socket.

const messages = listenTo_('message', ws);
messages.onValue(msg => {
  // Do something
})

listenTo :: String -⁠> WebSocket -⁠> Observable

Curried version of listenTo_

Listen to events of a certain type from the given socket. Often used as a helper for listening to an event from a bunch of sockets.

const messagesFrom = listenTo('message');
const messages = messagesFrom(webSocket);
const otherMessages = messagesFrom(anotherWebSocket);

Note that you can use R.flip or S.flip to create a function that you can use to register different event listeners from a single websocket.

const listenFrom = S.flip(listenTo);
const listenFor = listenFrom(ws);
const messages = listenFor('message'); // Observable of messages emitted from websocket
const errors = listenFor('error'); // Observable of errors emitted from websocket

listenToOnce_ :: (String, WebSocket) -⁠> Observable

Create an Observable of events, but emits only a single event, then ends.

It's identical to doing:

listenTo(socket, 'open').take(1).onValue(v => {
  // Do something
})

listenToOnce :: String -⁠> WebSocket -⁠> Observable

Curried version of listenToOnce_. Like with listenTo can be used to easily create Observables of a single event.

It's identical to doing:

const listenOnceFrom = S.flip(listenToOnce);
const onceForEvent = listenOnceFrom(ws);
 
onceForEvent('message').onValue(v => {
  // Do something
});

Sending Commands

send_ :: (String, Object, WebSocket) -⁠> Observable

Send socket a message of given type with optional arguments.

send2 :: String -⁠> WebSocket -⁠> Observable

Curried binary version of send_

send3 :: String -⁠> Object -⁠> WebSocket -⁠> Observable

Curried ternary version of send_

OBS types

ObsRequest

Represents a Request in OBS.

ObsEvent

Represents an Event in OBS.

Observable

KefirObservable

Represents a Kefir Observable instance.

KefirProperty

Represents a Kefir Property instance.

KefirStream

Represents a Kefir Stream instance.

WebSocket

Represents an instance of WebSocket

Contains some generic utilities for handling string tokens of different kinds, and conversion functions for them—e.g. for creating isomorphisms on tokens, to avoid having to manually convert tokens back and forth when interfacing with OBS.

genFunc :: (String -⁠> Function) -⁠> (String -⁠> String)

inList :: a -⁠> POptic s a

getFromList :: Foldable f => a -⁠> f a -⁠> a

Find the item x from the given list of xs and return it.

flatJoin :: [a] -⁠> String

Utility for joining nested arrays of strings into a string.

getEvent :: ObsEvent -⁠> String

Get the string representation of the given OBS event type.

getRequest :: ObsRequest -⁠> String

Get the string representation of the given OBS request type.

splitPascal :: String -⁠> [String]

Split a pascal-cased string into an array of words.

splitCamelCase :: String -⁠> [String]

Split a camelcased string into an array of words.

camelCasePascal :: String -⁠> String

Get the camel-case version of a pascal-cased string.

camelCasePascal('FooBar'); // => 'fooBar'
 
<h4 name="kebabCasePascal"><code><a href="https://github.com/stuf/obs.remote.kefir/blob/master/lib/util.js#L90">kebabCasePascal :: String -⁠> String</a></code></h4>
 
Get the kebab-case version of a pascal-cased string.
 
```js
kebabCasePascal('FooBar'); // => 'foo-bar'

constCasePascal :: String -⁠> String

Get the "const-cased" version of a pascal-cased string.

constCasePascal('FooBar'); // => 'FOO_BAR'

pascalCaseCamel :: String -⁠> String

pascalCaseKebab :: String -⁠> String

pascalCaseConst :: String -⁠> String

camelCaseKebab :: String -⁠> String

Acknowledgements

• You ♡