Control API

What Kinetra exposes to other software on the network: the output server's URLs, OSC addresses and MIDI mappings.

This page is for people who connect other software or hardware to Kinetra. It lists everything the app exposes:

the output server (HTTP and WebSocket), which shows your screens and is read-only;
OSC, which controls Kinetra;
MIDI, which controls Kinetra from a controller.

Kinetra has no HTTP control API: other software can’t take, clear or change graphics over HTTP. Use OSC for that.

Output server

Kinetra runs a small web server while a project is open. Without an open project there is no server.


Address	`127.0.0.1` (this computer only). With Allow access from other devices on the network on, every network address of this computer.
Port	Set per project in Preferences › Network & API › Server. Default `7770` (Kinetra Canary: `7771`). Range 1024–65535.
Protocol	HTTP and WebSocket, IPv4.
Methods	`GET` only.
Access	No sign-in. With network access on, any device that can reach the port can view every route.

If the port is taken, the server doesn’t start and Kinetra shows Port 7770 is in use. It doesn’t pick another port by itself.

Routes

Route	What it returns
`GET /screen/<screen id>`	The screen’s page, for OBS, vMix, display outputs and other browser sources.
`GET /screen/<screen id>/preview`	The screen’s Studio mode Preview.
`GET /assets/<file name>`	A file from the project’s `assets/` folder. Supports range requests, for video.
`GET /health`	`{"ok": true, "version": "<app version>"}`, to check that Kinetra is running.
`GET /pattern`	A test pattern page, used by display outputs.
`GET /ws`	The WebSocket the screen pages use. See WebSocket.
`GET /renderer/…`, `GET /fonts/…`	Files the screen pages load.

Anything else answers 404.

Screen IDs are shown in the screen URLs that Kinetra copies, and in the project’s screens/ folder.

Screen page options

Option	Effect
`?debug`	Shows a small badge with the connection state: connecting, connected, reconnecting, unknown screen.

Screen pages load nothing from the internet. They reconnect to Kinetra by themselves if the connection drops.

Check that Kinetra is running

curl http://127.0.0.1:7770/health

{"ok": true, "version": "0.1.0"}

WebSocket

/ws pushes the live state of a screen to its page. It is read-only: the only message a client may send is a media-ready notice from a screen page.

Its message format is internal to Kinetra and changes between versions, so don’t build on it. To know what’s on air, use OSC feedback.

OSC

OSC runs the same actions as the buttons in Control, and follows the same rules (Live edit, Studio mode, PANIC).

Set up OSC in Preferences › Network & API › Server (Advanced mode). See MIDI and OSC.


Transport	UDP, IPv4
Port	Set per project with OSC port. Default `9000`. Range 1024–65535. Off by default (OSC control).
Who may send	This computer, always. Other computers only with Allow access from other devices on the network on and their IP address under Allowed computers (up to 32 addresses, no ranges). Other messages are dropped without a reply.
Message size	Up to 16 KB per packet. Bundles are run in order, up to 256 messages.
Arguments	int32, int64, float, double, string, char and bool are read.

Addresses

<s> is a screen ID, <l> a layer ID, <f> a flow (cue) ID and <src> a source ID. Copy real addresses from Preferences › Network & API › Server › Addresses.

Address	Argument	Does
`/kinetra/layer/<s>/<l>/take`	trigger	Takes the layer to air. If it’s on air with changes waiting, sends them. In Studio mode: cues it into Preview.
`/kinetra/layer/<s>/<l>/clear`	trigger	Clears the layer. In Studio mode: cues it out of Preview.
`/kinetra/layer/<s>/<l>/toggle`	trigger	Takes the layer if it’s off air, clears it if it’s on air.
`/kinetra/layer/<s>/<l>/update`	trigger	Sends the layer’s waiting changes to air. In Studio mode: takes the screen’s Preview to Program.
`/kinetra/layer/<s>/<l>/opacity`	level 0–1	Sets the layer’s opacity (0–100 %).
`/kinetra/layer/<s>/<l>/var/<key>`	level 0–1	Sets a range variable from its minimum (0) to its maximum (1).
`/kinetra/layer/<s>/<l>/play`	trigger	Plays a media layer.
`/kinetra/layer/<s>/<l>/pause`	trigger	Pauses a media layer.
`/kinetra/layer/<s>/<l>/stop`	trigger	Stops a media layer.
`/kinetra/layer/<s>/<l>/seek`	seconds	Moves a media layer to that time.
`/kinetra/flow/<f>/go`	trigger	Runs the cue. Works even with Automation off.
`/kinetra/source/<src>/next`	trigger	Steps the source to its next row.
`/kinetra/source/<src>/prev`	trigger	Steps the source to its previous row.
`/kinetra/screen/<s>/clear`	trigger	Clears every layer on the screen.
`/kinetra/clear-all`	trigger	Clears every screen.
`/kinetra/panic`	trigger	PANIC: cuts every screen off air at once.

Trigger arguments: the action runs unless the first argument is 0 or false. No argument also runs it. This way a button that sends 1 on press and 0 on release acts once.

Level arguments: the first argument, from 0 to 1. Values outside that range are ignored. No argument counts as 1.

Changes from opacity and variables follow Live edit and Studio mode like an operator’s edit, and are saved to the project.

Unknown addresses and unknown IDs are ignored. Kinetra doesn’t reply to OSC messages.

Examples

With liblo’s oscsend:

oscsend 127.0.0.1 9000 /kinetra/layer/SCREENID/LAYERID/take
oscsend 127.0.0.1 9000 /kinetra/layer/SCREENID/LAYERID/opacity f 0.5
oscsend 127.0.0.1 9000 /kinetra/flow/FLOWID/go
oscsend 127.0.0.1 9000 /kinetra/panic

With Python and python-osc:

from pythonosc.udp_client import SimpleUDPClient

kinetra = SimpleUDPClient("127.0.0.1", 9000)
kinetra.send_message("/kinetra/layer/SCREENID/LAYERID/toggle", 1)
kinetra.send_message("/kinetra/layer/SCREENID/LAYERID/var/speed", 0.75)

Feedback

Set Send on-air status to to host:port (port 1024–65535). Kinetra then sends, over UDP:

Address	Argument	When
`/kinetra/layer/<s>/<l>/onair`	int `1` or `0`	A layer goes on or off air. The full state of every layer is sent when you set the address and when a project opens.
`/kinetra/flow/<f>/running`	int `1` or `0`	A flow starts or stops running.

Feedback needs OSC control on.

OSC into flows

Every accepted OSC message, with any address, can start a flow with the OSC in trigger. The trigger’s address can use * for one part: /show/*/name matches /show/main/name but not /show/a/b/name. The first argument is passed to the flow as text. See Automation.

MIDI

MIDI controllers are mapped in Preferences › Network & API › MIDI & OSC. See MIDI and OSC.


Messages read	Note on, note off and Control Change, on channels 1–16. Other messages are ignored.
Buttons	Note on is a press. A CC presses when it rises past 64.
Faders and knobs	A CC value 0–127 sets opacity, a range variable, or a number field (to the raw 0–127 value).
Actions	The same as OSC above, except seek. Number fields can be set only over MIDI.
Conflicts	If two mappings match one message, neither runs.
Mappings	Up to 512, saved with the project in `controls.json`.
Lights	Note or CC back to the controller: on air, ready or off, with profiles for Generic, APC40, APC mini, Launchpad and X-Touch.
Platforms	Windows. Not on a Mac yet: see Kinetra on macOS.

A flow can also start from MIDI with the MIDI in trigger, which passes on the velocity or CC value.

What’s not available

Taking, clearing or changing graphics over HTTP.
Setting a text field from OSC directly. Use an OSC in flow with Set fields instead.
Studio mode’s T-bar from MIDI or OSC. /update takes the Preview with the default transition.