Gateways

Gateways let existing control set-ups talk to a Freedome dome, and let Freedome drive other systems, as a migration path. Everything is off by default ([gateways.*], [[drivers.*]]). A listener has a role and a CIDR allow-list; a port that cannot be opened marks that listener only.

What compatibility means here. Nothing on this page has run against the real product. Each target says what it was tested against. docsOnly: true in GET /api/v1/gateways means the same.

Target	Our part	Tested against
Screenberry JSON API	inbound HTTP, TCP, UDP, OSC, serial; outbound HTTP	fixtures from the public page, our own emulator; serial not run
WATCHOUT 6 text protocol	inbound TCP, UDP	fixtures from Dataton’s public page
WATCHOUT 7 REST	outbound	the requests built, no server
disguise transport API	outbound	the requests built, no server
MPCDI	freedome-dome mpcdi import / export	round trips of our own files; no VESA sample, no VIOSO file
Domemaster folders (Cinema 4D, Sky-Skan, Digistar, Spitz renders)	freedome-dome convert	synthetic folders
TouchDesigner, Cinema 4D script, Blendy	crates/fd-gateways/integrations/	never run in the product
Resolume	outbound	mock, below
fulldome.pro	our own adapter, kept in legacy/	waits for the test dome: its fixtures and rewrite are not done

[gateways.screenberry]
enabled = true          # http :8180, tcp :8181, udp :8182, osc :8183 address /jsonApi

[[drivers.watchout]]
name = "stage"
url = "http://10.0.0.50:3019"

The raw commands of outbound drivers are {"op": …}: play, pause, stop, jump, jump_cue, input, state for WATCHOUT; play, stop, gototime, gotosection, returntostart, transports for disguise; any Screenberry cmd.

GET /api/v1/gateways lists the configured gateways; OSC show controllers use the native OSC space.

Resolume Arena / Avenue (outbound driver)

Status: written from Resolume’s public documents and tested against a mock only (docsOnly: true). It has not run against a real Resolume yet. Sources and open points: fixtures/resolume/SOURCE.

Channel	Used for	Resolume default
OSC over UDP	continuous parameters and triggers	input port 7000
REST /api/v1	changes between scenes, composition reads	web server port 8080
WebSocket /api/v1	composition structure, subscribed parameters	same port as REST

[[drivers.resolume]]
name = "resolume"
host = "10.0.0.70"

In Resolume turn on Preferences > OSC > OSC Input and Preferences > Webserver.

Same machine. Resolume’s defaults are also ours, so one side has to move. Keep Resolume on its defaults and move the media server: config/resolume-same-host.toml sets http.listen to 8090 and osc.listen_udp / osc.listen_tcp to 7010. Clients of our API then use those ports. With a host on loopback the server refuses to start while a port collides and names the key to change. It cannot tell that a LAN address is this machine, so with such a host the check does not run.

Values. OSC floats are normalised: 0..1 covers the parameter’s whole range, so 100 % scale is 0.1 when the range is 0–1000 %. Scene outputs outside 0..1 are refused.

Rate limit. max_msgs_per_s (default 500) and burst (32) bound what reaches Resolume over all addresses; osc_max_rate_hz (unset by default) also limits each address. Below the limits a value leaves at once. Above it, values of one address merge and the newest is sent; triggers stay in order and go first. The default is our choice, not a figure from Resolume.

Status. up = REST and WebSocket work; degraded = REST works, WebSocket does not; down = no answer on the web port. Reconnect uses exponential backoff with jitter. OSC does not depend on any of this: it keeps sending, because the OSC input and the web server are separate switches in Resolume.

Audio-reactive scenes

The [audio_reactive] section maps audio analysis onto gateways. A scene is a JSON document in the contract’s format (docs/audio-reactive.md): each mapping is continuous or trigger, reads one metric of one input and writes one target. Curves here: exp = t², log = log10(1 + 9t), s-curve = smoothstep. Selecting a scene is refused when a float output leaves 0..1, because Resolume would pin the parameter at the end of its range. Shipped presets: vocal-aura, percussion-wave (crates/fd-app/presets/audio_reactive/). Their addresses fit a composition with the layers described in each preset; adjust them or add your own files through scenes_dir. Scenes stored through the API survive a restart, and a preset deleted through the API stays deleted.

patchGateway with config changes the Resolume driver while it runs: host, oscPort, restPort, ws, oscMaxRateHz, x-maxMsgsPerS, x-burst, x-bundle. OSC, REST and the WebSocket move to the new peer at once, and the settings are kept in the server’s database: from then on they win over [[drivers.resolume]].

source = "ananta" reads live frames from anantadigital-engined over gRPC (endpoint); inputs are set with PUT /venues/{id}/audio/analysis. source = "test_double" is synthetic: no audio is involved, and the log says so at start.