obs.remote.kefir v2.1.2

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

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.

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
         });

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

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

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

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

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

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

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

Curried version of createSocket_. Creates a websocket.

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

Listening to Events

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

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

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

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

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 socket a message of given type with optional arguments.

Curried binary version of send_

Curried ternary version of send_

OBS types

Represents a Request in OBS.

Represents an Event in OBS.

Observable

Represents a Kefir Observable instance.

Represents a Kefir Property instance.

Represents a Kefir Stream instance.

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.

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

Utility for joining nested arrays of strings into a string.

Get the string representation of the given OBS event type.

Get the string representation of the given OBS request type.

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

Split a camelcased string into an array of words.

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'

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

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

Acknowledgements

• You ♡