The OSC remote

OSC (Open Sound Control) is a network command language widely used in show control: tablet apps, programmable button boxes, cue-playback or video software can send OSC messages. DreamShow receives them to fire GO, change scene, go to blackout, force DMX channels… and sends its state (current scene, blackout, GO possible) back to the devices that write to it, so they can display it.

To open it: menu DMX > OSC remote….

An OSC message is made up of an address that looks like a path (/dreamshow/go) and, sometimes, arguments (numbers or text). It travels over UDP to an IP address and a port.

The window

• Enable OSC reception: puts DreamShow in listening mode. Off by default, because it opens a network port.
• Only from this PC (127.0.0.1), for example Companion installed here: only accepts messages coming from a program installed on this same PC. Devices on the network can no longer reach DreamShow, and Windows asks no firewall question.
• Listening port: the port on which DreamShow receives, 8000 by default.
• Feedback port: the port on which DreamShow sends its state back to the devices, 9000 by default.
• Also send feedback to (IP, optional): an IP address to which the state is sent permanently, even if that device has not sent anything yet. Empty = only the devices that have written.
• Apply: checks the values (ports from 1 to 65535, valid IP address), saves them and restarts listening. Nothing changes before Apply.
• The status line: “OSC off”, or “OSC: listening on port 8000 — this PC's address to enter in the device: 192.168.1.10”, or “OSC: port 8000 is already in use or refused (…)” if another program occupies that port.
• Addresses understood: the reminder of the commands (detailed below).
• Messages received: the last messages that arrived (the 60 most recent, the newest at the top), with the time and the IP address of the sender. An unknown /dreamshow/… address is flagged there by “unknown address: …”.
• Close: closes the window; listening carries on.

Once enabled, OSC listening restarts automatically each time DreamShow is launched.

The commands received

All addresses start with /dreamshow/. Upper and lower case do not matter, and a final slash / is tolerated. Grouped messages (OSC “bundles”) are accepted; their timestamp is ignored, everything is executed at once.

Details:

• Buttons (go, back, prev, pause, play, reset, tap): many devices send 1 on press and 0 on release. DreamShow only acts on the press: with no argument, or with a value of 0.5 or more. A value below 0.5 is ignored.
• Values accepted: integers, decimal numbers, numbers written as text, and true / false (true = 1).
• /dreamshow/scene n: the number is rounded; a scene that does not exist is ignored.
• /dreamshow/fader u c v: universe and channel counted from 1. The value v goes from 0 to 255; if it is sent as a decimal number between 0.0 and 1.0 (as with a tablet fader), it is converted to 0 to 255. The channel is taken as with DMX > DMX faders…: it overrides the cue list and the blackout until it is released.
• /dreamshow/release with no universe or channel (or with a single number, for example 1 sent by a button) gives back all channels.
• /dreamshow/key name: the name is text, the key the block is waiting for, for example Space, A or F1. See Waits.

Behaviour depending on the mode:

• In Show mode (cue window open): go only goes off if GO is possible (same rule as the greyed-out GO button); back, prev and scene jump to the scene without a fade and make it play.
• In the editor: go acts like the space bar (including the effect of the Disengage auto-fade box); back, prev and scene jump to the scene without changing the play or pause state.
• pause, play and reset act in both cases, even during a performance.
• live changes nothing to the output in Show mode: the output is always active there.

State feedback

DreamShow sends its state back:

• to each device that has sent it a message in the last ten minutes, at that device's IP address and on the Feedback port (9000 by default, not the port the message came from);
• and, if it is filled in, to the Also send feedback to address.

It sends it after each command received, and as soon as the state changes (checked four times a second). /dreamshow/refresh forces a complete send.

The text “Ready” follows the language of the interface.

Examples

The steps below describe what DreamShow expects. How to create a button or a message in each application depends on that application: refer to its documentation.

A tablet with TouchOSC

1. In DreamShow, tick Enable OSC reception, leave the port at 8000, Apply. Note the PC's address displayed.
2. In the tablet's app, set the OSC connection: host = the PC's address, send port = 8000, receive port = 9000.
3. Create a button that sends /dreamshow/go, another /dreamshow/back, a third /dreamshow/blackout.
4. For an intensity fader, make it send /dreamshow/fader with the arguments universe, channel, then the fader's value (0.0 to 1.0).
5. To display the scene name, bind a label to the address /dreamshow/scene/name; to light the GO button when GO is possible, bind it to /dreamshow/go/allowed.

A button box with Companion on the same PC

1. In DreamShow, tick Enable OSC reception and Only from this PC (127.0.0.1), for example Companion installed here, then Apply.
2. In Companion, set up OSC sending to host 127.0.0.1, port 8000.
3. Assign each key a message: /dreamshow/go, /dreamshow/back, /dreamshow/blackout, /dreamshow/scene with the scene number…
4. For Companion to receive the state, make it listen on the feedback port (9000); DreamShow replies to it as soon as it has sent a first message.

Firing GO from a QLab cue list

1. In DreamShow, enable OSC reception on port 8000 (without ticking “Only from this PC” if QLab runs on another computer).
2. In QLab, create a network cue that sends the OSC message /dreamshow/go to the DreamShow PC's address, port 8000.
3. Place this cue in QLab's cue list: each time it goes off, DreamShow does a GO (if GO is possible in Show mode).
4. To go to a specific scene: /dreamshow/scene 5.

   The names of menus and settings change from one version of TouchOSC, Companion or QLab to another: refer to their documentation to find where to enter the address, the port and the OSC message. On the DreamShow side, only the PC's address, the port (8000 by default) and the messages listed above matter.

Good to know

• On first use, the Windows firewall may ask you to allow DreamShow on the network: accept, unless you only use Only from this PC.
• The Messages received list lets you check that a device is sending, and what: if nothing appears, the problem is on the network side (IP address, port, firewall).
• The same commands are used by MIDI controllers and the web remote.
• Sound-to-light also sends its automatic GOs by this same path: they obey the same rules.

See also

• The web remote
• MIDI controllers
• Show mode and the cue window
• DMX values and DMX faders
• Waits (key, time, date, sun)