Skip to content
Sidechain Software

Making Machines Talk - OSC Reference

That’s all well and good, but who in this industry actually wants to talk to people? TheatreChat’s true power is that all messages are simply sent over OSC. There’s no weirdness going on under the hood to make it happen, just standard networking that any OSC-capable device should be able to manage.

Sending Messages

There are four things you’ll need to configure on your device to get it to send chat messages:

  • IP Address: You’ll want to set this to 255.255.255.255 unless you know what your doing. This is a special IP address that will send your chat messages to any device that’s listening on the network.
  • Port: TheatreChat uses port 27900, so ensure your device is configured to send on that port
  • Address: The OSC address to send a TheatreChat message is /theatrechat/message/channel-id. Replace channel-id with the ID of the channel you wish to send to.
  • Arguments: TheatreChat messages have two string (ie. text) arguments. The first one specifies the name of the sender, and the second is the message itself.

Once you’ve finished configuring your device, an OSC message to TheatreChat should look something like this:

/theatrechat/message/test-channel "Alice" "Hello, world!"
                     |__________|  |___|   |___________|
                      Channel ID   Name       Message

Flashing the Screen

In a similar way, it is possible to make the screens of all channel members flash. Simply send the OSC message /theatrechat/flash/test-channel with a single text argument with the name of your device (which should be the same as the sender name for messages). This argument isn’t currently displayed in the TheatreChat app, but is included in case it is needed in the future.

If you have an advanced use case, you can also send flash messages to a specific IP address to only flash that user’s screen. Note that flash messages are channel-specific, and will only flash the entire screen if the end user has that channel open. Otherwise, only the sidebar button will flash. If the user has not added a channel that is flashed the message is ignored by TheatreChat.

Clearing the Screen

It is now possible to remotely clear the chat history of a channel over OSC. This is useful when you want to disappear a message for a mixer after a certain period of time, or if you’re primarily using a device such as a Stream Deck to control TheatreChat.

To clear a channel, send the command /theatrechat/clear with a single text argument specifying the ID of the channel to clear. When sending this message, it is strongly recommended that you configure a separate network output (if such is possible on your device) with a different target IP to other TheatreChat messages. Sending this command as a broadcast (eg. using the IP address 255.255.255.255) will clear that channel for everybody on the network. If this is what you want, go right ahead! But in most cases you’ll likely want to target a specific IP address to clear the history on a single device.

Use Cases

There’s a variety of simple and complex use cases for this integration.

  • Stream Deck Keypad: Use a Stream Deck to send chat messages using Companion and the generic OSC driver
  • Console Keys: Many consoles (including DiGiCo consoles as of v1926) can send OSC on the click of a macro button, allowing you to send TheatreChat messages
  • Chat Alerts: Some consoles and apps will allow you to do things when OSC is received, meaning you could give a visual indication that a message has been received
  • Event Notifications: With Companion, switch an actor’s mic to a backup and notify your A2 all in one button press (thanks to Andy Leviss for this one)
  • QLab Scripting: Use QLab to send a chat message to record the time something was fired, or fire a cue at interval that uses scripting to determine the start time of Act 2, and post that to chat.

There’s infinite possibilities, and we’ve love to hear what you’ve been cooking! Join the Discord and show off your work and we might add it to this list!