OSC for lighting control: when to use it and how to structure mappings

Addresses, not magic

OSC is typed messages on a network. A sender transmits /wash/dimmer 0.42 and a receiver applies that number. There is no hidden intelligence. If the address is wrong, nothing happens. If two apps disagree about 0–1 versus 0–255, the wash jumps.

Use OSC when another app is already the operator surface, or when you want logs a human can read. Use MIDI when you have hardware faders. Use DMX when the destination is a fixture.

Design a tree and freeze it

Pick a stable address tree and write it down. /wash/dimmer, /wash/colour, /heads/spread, /fx/strobe/enable, /show/blackout. Group by system, not by the name of last week’s layout file.

Decide units once. Prefer 0–1 floats for continuous values and 0/1 for triggers, then convert at the edge if a fixture wants 0–255. Mixing conventions inside one tree is how you get a dimmer that only ever reaches 1% of output.

Version the document if you must change names. A tablet layout from last year will still fire /old/blackout unless you keep a compatibility alias.

Network habits

OSC is UDP or TCP depending on the stack. UDP is common and can drop packets. That is acceptable for a continuously updating fader. It is less acceptable for a one-shot “fire cue 12” unless you also have a local button.

Lock IPs and ports. Broadcast OSC on a shared LAN will surprise someone. Unicast to the lighting machine. Keep show-critical OSC on the wired lighting network, not on guest Wi-Fi, if those messages can blackout the room.

Safety and permissions

Anything that can blackout or strobe should also exist on a physical pad. Network control is extra, not the only kill.

If the OSC port is reachable from the wider venue network, treat it like an unlocked desk. Do not put unrestricted show control on a public SSID.

A small example tree

/show/blackout — 1 kills, 0 releases. /wash/dimmer — 0–1. /wash/temp — 0 warm, 1 cold. /accent/gate — 1 allows transients through. /heads/freeze — 1 holds position. That is enough for a club override tablet. Add addresses when a real job appears, not because the protocol can express a thousand paths.

Debugging OSC without folklore

Log the incoming address and arguments. If you see /wash/Dimmer instead of /wash/dimmer, you have a case-sensitivity bug, not a lighting bug. If you see a string "0.5" instead of a float, the receiver may ignore it.

Send from a known tool to the lighting machine first, then from the real tablet. Isolate whether the layout or the lighting app is wrong. Changing both at once is how you lose an hour.

Firewall again. OSC ports are not Art-Net 6454. Allow the exact port you documented. “I allowed lighting” in a GUI that only opened 6454 will not help.

Tablets and the floor manager

A tablet layout is how you give someone three buttons without giving them the editor. Keep the layout ugly and large. Pretty small toggles fail in a dark room with wet fingers.

If the tablet is on venue Wi-Fi, accept that it may lag. Do not put strobe-enable only on that tablet. Put it on MIDI as well. The tablet is for “safe wash” and “haze down,” not for the only kill in the building.

Write the OSC tree in the same folder as the DMX patch. When you replace the tablet app next year, you should not have to reverse-engineer the lighting file to learn that blackout is /show/kill tonight and /house/bo last year.

Do not OSC the fixtures directly

Some fixtures speak OSC. Most club gear does not. Translate at the lighting computer so the patch remains one DMX map. If you send OSC to one bar and Art-Net to the rest, you now have two patches to debug when the room looks uneven.

Keep OSC for humans and apps. Keep DMX for lamps. Mixing those jobs because a protocol can do both is how small rooms become unmaintainable.

A one-page spec

Host IP, port, address list, value ranges, and which messages are allowed to blackout. That page is the integration. Without it, every new tablet layout is archaeology.

If you cannot write the spec in fifteen lines, the tree is too clever. Cut addresses until a substitute can type them from memory.

Related

• MIDI vs OSC vs DMX →
• OSC lighting control →
• External I/O →