AD-DA.ca, Open Sound Control (OSC)

Plugin Description

The AD-DA.ca OSC plugin adds Open Sound Control send and receive workflows to Q-SYS designs over UDP. It can build reusable OSC command libraries, trigger commands from control pin activity, receive and parse incoming OSC messages, and optionally bridge those messages into Q-SYS Named Components and Named Controls.

This plugin is intended for systems that need flexible OSC transport between Q-SYS and external devices or software such as QLab, Yamaha consoles, lighting systems, and custom controllers.

Key capabilities:

Send OSC commands from manual triggers or input events.
Receive and filter OSC messages by address pattern, with OSC 1.0 wildcards.
See replies from the destination device on the Send mode Log page.
Reuse command libraries through import/export text data.
Substitute input values into OSC addresses and arguments with placeholders such as {1}.
Forward incoming UDP packets to follower instances or external destinations.
Use internal OSC libraries to address Q-SYS Named Components and Named Controls directly.

Important notes:

UDP only. TCP is not supported.
OSC bundles are not supported.
When Send mode binds a local UDP port, that sender instance becomes the effective leader for that port and can relay traffic to follower-style listeners through notifications.

Configuration Overview

Plugin version

This document is written for the plugin:

AD-DA.ca OSC V1.4.0.0

QDS compatibility

This plugin has been developed and tested on:

Q-SYS Designer version 10.4

Release note

2026-09 : 1.4.0.0

Refreshed UI: section headers, consistent spacing and cleaner buttons on every page.
Added an About page showing license validity, build version, support contact and documentation link, with License and DocURL output pins.
Added a Log page in Send mode showing OSC replies from the destination device.
Added OSC 1.0 wildcards inside an address part in Receive mode: *, ?, [a-z] ranges, [!...] negation and {a,b} alternatives.
Debug Print property now offers None, RX, TX, RX/TX, Function Calls and All.
Fixed negative INT32 argument values not being sent.
An Invalid INT32 value fault is now shown when an INT32 argument is not a number.
Fixed the Prefix being applied twice to Named Components and Named Controls addresses.
Fixed Receive mode ignoring the selected network interface.
Fixed the log keeping one entry fewer than Log Count, and not shrinking when Log Count is lowered.
Fixed a script error when a ? wildcard is matched against a shorter address.

2025-11 : 1.3.1.0

Updated UI layout and help screenshots.
Added debounce and input event handling controls in Send mode.
Added UDP bind port support and packet forwarding options.
Added Named Components and Named Controls receive libraries.
Added multicast support in Receive mode.
Added Yamaha-specific argument conversion types.

2025-10-03 : 1.3.0.0

Changed NIC Selection (Receive Mode) from ALL to ANY
Fixed network compatibility issues for QDS 10.0.X Emulation Mode
Resolved combobox and listbox integer text field issues for QDS 10.0.X
Added support for new license types
Added support for Boolean type arguments (true and false)
New argument type "INPUT TO BOOLEAN" - converts "false" or 0 to boolean false, converts "true" or 1 to boolean true. Useful for converting input {1} to T/F, like a mute button. Accepts as true: true, "TRUE", "true", 1, 1.0, "1", "1.0"
Added unique UUID to newly created command names to ensure unique names
Fixed UI glitches in the command's library page
Enhanced Internal Components and Named Controls Library - now supports multiple argument types:
- If arg type is string, modifies the .String of the control
- If arg type is boolean (true or false), changes the .Boolean of the control
- If arg type is FLOAT, affects the .Position of the control
- If arg type is INT32, affects the .Value of the control
- If arg type is string and the string is "Trigger", triggers the control
Enhanced Command Library functionality - clearing the field now deletes/resets the command library. Entering "TEMPLATE" loads a library with examples (loaded by default on first plugin use)
Added ability to bind UDP port when sending messages to ensure destination can reply on a known port
Send Mode now sends via Notification incoming messages when BIND PORT is enabled
Added message forwarding functionality with Forward to IP Address and Forward Port controls
Receiver in Follower mode now only receives messages from selected PORT
Receiver in Follower mode no longer disables port controls
Enhanced message logging - all incoming messages are now printed in the log for better troubleshooting

2024-09-25 : 1.2.0.0

Initial release to Asset Manager
Breaking changes: control's name has changed
New UI / Pages
Add Duplicate function in command library
Add Test function in command library

2024-06-21 : 1.1.0.0

Add OSC receive function
Add the ability to control Named Components and Named Controls via OSC messages.
Add the ability to import/export the command's library in Send mode.

2024-06-12 : 1.0.0.0

Initial Release

Properties

License

Type: String
Default value: Empty
Description: License key activated for the main core.

Licenses are issued on a "per core" basis, as in each core needs its own license to run as many instances of the plugin as needed on this particular core and licenses are not transferable from core to core.

License keys can be added while in Offline mode, in the Properties pane on the right. To purchase licenses, go to https://ad-da.ca.

The plugin can be emulated for free, allowing you to prepare everything without requiring you to have access to a core.

License Backup

Type: String
Default value: Empty
Description: License key activated for the backup core.

If your main Q-SYS Core fails, the backup Core automatically takes over without needing a license to function as a temporary replacement. However, if the design boots from the backup Core, a valid license is required. Additionally, if the backup Core is restarted (due to power loss or other reasons), the plugin instances cannot initialize without a valid license.

Mode

Type: Enum
Choices: Send, Receive
Default value: Send
Description: Selects whether the instance builds and transmits OSC commands or listens for and parses incoming OSC traffic.

Send Count

Type: Integer
Range: 4 to 32
Default value: 4
Description: Number of Send [x] command slots exposed in Send mode.

Input Count

Type: Integer
Range: 4 to 32
Default value: 4
Description: Number of Input [x] rows exposed in Send mode.

Receiver Mode

Type: Enum
Choices: Leader, Follower
Default value: Leader
Description: Defines how a Receive mode instance gets UDP packets when multiple plugin instances need the same source port.

Notes:

Leader opens the UDP port directly and distributes packets locally to followers.
Follower does not bind the UDP socket. It subscribes to packets already received by a leader on the selected port.
Use Follower only when another OSC instance is already acting as leader for the same incoming port.

OSC Address Count

Type: Integer
Range: 4 to 32
Default value: 4
Description: Number of OSC address match rows exposed in Receive mode.

Argument Count

Type: Integer
Range: 4 to 32
Default value: 4
Description: Number of argument outputs exposed for each receive address row.

Debug Print

Type: Enum
Choices: None, RX, TX, RX/TX, Function Calls, All
Default value: None
Description: Selects what the plugin prints in the Q-SYS debug console for troubleshooting.

Choices:

None: No debug output.
RX: Prints received OSC messages.
TX: Prints sent commands and forwarded packets.
RX/TX: Prints both received and sent traffic.
Function Calls: Prints the plugin's main actions as they run.
All: Prints everything above, plus connection details.

Controls

General

Status

Control name: Status
Type: Indicator
Controls Pin: Output
Description: Displays plugin runtime state.

Typical values:

OK: Plugin is initialized and running.
FAULT: Socket, network, or runtime error prevented operation.
MISSING: License is missing or invalid.

Log Page

The Log page is available in both modes. In Send mode it shows replies from the destination device. In Receive mode it shows all incoming traffic.

Log

Control name: Log
Type: Text
Controls Pin: Input / Output
Description: Displays the log content, newest entry first.

In Receive mode, incoming traffic is logged for troubleshooting, including messages outside the configured match list.

In Send mode, replies are logged whether or not InterfacePortBind is enabled. Packets that cannot be decoded, such as OSC bundles, are logged as unsupported.

LogLength

Control name: LogLength
Type: Knob Integer
Controls Pin: Input / Output
Default value: 25
Range: 10 to 100
Description: Sets how many log lines are retained.

LogClear

Control name: LogClear
Type: Button Trigger
Controls Pin: Input / Output
Description: Clears the log immediately.

About Page

The About page is available in both modes. It shows the license validity, the plugin build version, the support contact and the documentation link.

License

Control name: License
Type: Indicator Status
Controls Pin: Output
Description: Displays the license validity.

Typical values:

Valid: A valid license is installed for this core.
Invalid: The license is missing or invalid.
Emulating: The design runs in Emulation mode, where no license is required.

DocURL

Control name: DocURL
Type: Indicator Text
Controls Pin: Output
Description: Link to this plugin's documentation.

Send Mode

Send Page

SendCommand [x]

Control name: SendCommand [x]
Type: Text
Controls Pin: Input / Output
Description: Assigns a command library entry to each send slot.

SendTrigger [x]

Control name: SendTrigger [x]
Type: Button Trigger
Controls Pin: Input / Output
Description: Sends the command assigned to SendCommand [x].

Input Page

Input [x]

Control name: Input [x]
Type: Indicator Text
Controls Pin: Input
Description: Receives the raw input value used by command address and argument placeholders.

InputTrigger [x]

Control name: InputTrigger [x]
Type: Button Toggle
Controls Pin: Input / Output
Description: Enables or disables command transmission when Input [x] changes.

InputDebounce [x]

Control name: InputDebounce [x]
Type: Button Toggle
Controls Pin: Input / Output
Description: Filters rapid value changes on Input [x] to reduce unnecessary command bursts.

This is useful when an input is driven by a knob or slider that produces many intermediate values.

InputTriggerButton [x]

Control name: InputTriggerButton [x]
Type: Knob Integer
Controls Pin: Input / Output
Range: 1 to Send Count
Description: Selects which send slot is triggered when the corresponding input event handler is enabled.

Library Page

CommandData

Control name: CommandData
Type: Text
Controls Pin: Input / Output
Default value: *{ template library }*
Description: Serialized command library field used for import, export, reset, and template loading.

Pasting a saved library string loads the command library.

Clearing the field resets the library.

Entering TEMPLATE loads the bundled example library.

CommandList

Control name: CommandList
Type: Text
Controls Pin: None
Description: Selects the active command entry in the current command library.

CommandAdd

Control name: CommandAdd
Type: Button Trigger
Controls Pin: None
Description: Creates a new command entry with a unique identifier.

CommandDel

Control name: CommandDel
Type: Button Trigger
Controls Pin: None
Description: Deletes the currently selected command entry.

CommandDuplicate

Control name: CommandDuplicate
Type: Button Trigger
Controls Pin: None
Description: Creates a copy of the currently selected command entry.

CommandTest

Control name: CommandTest
Type: Button Trigger
Controls Pin: None
Description: Sends the currently selected command immediately for validation.

CommandName

Control name: CommandName
Type: Text
Controls Pin: None
Description: Human-readable name for the selected command.

CommandAddress

Control name: CommandAddress
Type: Text
Controls Pin: None
Description: OSC address to send for the selected command.

Address placeholders such as {1} insert values from Input [1] at send time.

CommandArgList

Control name: CommandArgList
Type: Text
Controls Pin: None
Description: Selects which argument entry is being edited for the active command.

CommandArgAdd

Control name: CommandArgAdd
Type: Button Trigger
Controls Pin: None
Description: Adds a new argument row to the active command.

CommandArgDel

Control name: CommandArgDel
Type: Button Trigger
Controls Pin: None
Description: Deletes the selected argument row from the active command.

CommandArgType

Control name: CommandArgType
Type: Text
Controls Pin: None
Description: Sets the outgoing OSC argument type for the selected argument row.

Supported values:

INT32
FLOAT
STRING
TRUE
FALSE
INPUT TO BOOLEAN
INPUT TO YAMAHA GAIN
MUTE TO BOOLEAN
MUTE TO INT32

CommandArgValue

Control name: CommandArgValue
Type: Text
Controls Pin: None
Description: Value template for the selected argument row.

Placeholders such as {2} insert values from Input [2].

INPUT TO BOOLEAN converts common string and numeric placeholder values into OSC boolean output.

Setup Page

DestinationIP

Control name: DestinationIP
Type: Text
Controls Pin: Input / Output
Description: Target IP address for outgoing OSC messages.

Multicast destination addresses automatically force bind-port behavior.

DestinationPort

Control name: DestinationPort
Type: Knob Integer
Controls Pin: Input / Output
Default value: 8000
Range: 1 to 65535
Description: Target UDP port for outgoing OSC messages.

Interface

Control name: Interface
Type: Text
Controls Pin: Input / Output
Description: Local network interface used for sending or for binding a reply port.

Any allows the plugin to use the default route.

InterfacePort

Control name: InterfacePort
Type: Knob Integer
Controls Pin: Input / Output
Default value: 8000
Range: 1 to 65535
Description: Local UDP port to bind when reply handling or packet forwarding is required.

InterfacePortBind

Control name: InterfacePortBind
Type: Button Toggle
Controls Pin: Input / Output
Description: Enables local UDP port binding in Send mode.

When enabled, the sender can receive replies on a known port.

When enabled, incoming packets on that bound port are published to local followers and can also be forwarded externally.

ForwardIP

Control name: ForwardIP
Type: Text
Controls Pin: Input / Output
Description: Optional destination IP address for forwarding packets received by the bound sender socket.

ForwardPort

Control name: ForwardPort
Type: Knob Integer
Controls Pin: Input / Output
Default value: 8001
Range: 1 to 65535
Description: UDP port paired with ForwardIP for packet forwarding.

Receive Mode

OSC Address Page

Prefix

Control name: Prefix
Type: Text
Controls Pin: Input / Output
Description: Shared prefix prepended to every receive address row.

This is useful when many messages share the same root path.

Address [x]

Control name: Address [x]
Type: Text
Controls Pin: Input / Output
Description: OSC address pattern to match for receive row [x].

The full pattern is Prefix + Address [x].

OSC 1.0 wildcards can be used inside each part of the address:

* matches any number of characters, e.g. /ch*.
? matches exactly one character, e.g. /ch/0?/mix.
[abc] matches one of the listed characters, and [a-z] one character in the range.
[!abc] matches any character except the listed ones.
{fader,mute} matches one of the listed words.

A * as the last part of the address also matches deeper addresses.

AddressReceived [x]

Control name: AddressReceived [x]
Type: Indicator Text
Controls Pin: Output
Description: Displays the most recent OSC address received for row [x].

AddressReceivedLed [x]

Control name: AddressReceivedLed [x]
Type: Indicator LED
Controls Pin: Output
Description: Pulses when row [x] matches an incoming OSC message.

AddressHold [x]

Control name: AddressHold [x]
Type: Button Toggle
Controls Pin: Input / Output
Description: Holds the last matched address and argument values for row [x].

Address [x] Arg [y]

Control name: Address [x] Arg [y]
Type: Indicator Text
Controls Pin: Output
Description: Displays the parsed OSC argument [y] from the last message that matched row [x].

The number of available argument outputs per row is controlled by the Argument Count property.

Receive Network Setup

Interface

Control name: Interface
Type: Text
Controls Pin: Input / Output
Description: Local interface used by a leader receiver.

In Follower mode this control is disabled because the instance does not bind the socket itself.

Port

Control name: Port
Type: Knob Integer
Controls Pin: Input / Output
Default value: 8000
Range: 1 to 65535
Description: UDP port used for listening or for follower subscription routing.

MulticastIP

Control name: MulticastIP
Type: Text
Controls Pin: Input / Output
Description: Optional multicast group joined by a leader receiver.

ForwardIP

Control name: ForwardIP
Type: Text
Controls Pin: Input / Output
Description: Optional destination IP address for forwarding incoming packets.

ForwardPort

CmdComp

Control name: CmdComp
Type: Button Toggle
Controls Pin: Input / Output
Description: Enables Named Components library handling for incoming OSC messages.

CmdCtrl

Control name: CmdCtrl
Type: Button Toggle
Controls Pin: Input / Output
Description: Enables Named Controls library handling for incoming OSC messages.

Send Behavior

Command library workflow

Commands are stored as serialized JSON in CommandData.
Each command contains one OSC address and zero or more typed arguments.
CommandTest sends the selected command without needing an external trigger.
New commands are created with unique identifiers so duplicates stay independent.

Placeholder substitution

Address and argument values may reference send inputs with placeholders such as {1}, {2}, and {3}.
Placeholder values are taken from the corresponding Input [x] control pin at the moment the command is sent.

Input-driven sending

InputTrigger [x] enables automatic send behavior for that input row.
InputTriggerButton [x] chooses which send slot is fired by that input row.
InputDebounce [x] reduces excessive send events from fast-changing controls.

Outgoing argument types

INT32, FLOAT, and STRING map to standard OSC types.
TRUE and FALSE emit OSC boolean values.
INPUT TO BOOLEAN converts common string and numeric values to OSC booleans.
Yamaha-specific conversions are available for console workflows that need formatted or translated values.
An INT32 argument that is not a number stops the send and shows an Invalid INT32 value fault.

Replies

Replies from the destination device are shown on the Log page.
Most devices reply to the port the message was sent from, so replies are received with or without InterfacePortBind.
Enable InterfacePortBind when the device replies to a fixed port.

Bind-port behavior

When InterfacePortBind is off, the plugin sends from an automatically allocated socket.
When InterfacePortBind is on, the plugin binds InterfacePort locally before sending.
A bound sender can receive replies, publish those packets to followers on the same core, and optionally forward them to ForwardIP:ForwardPort.
Multicast destinations force bind-port operation automatically.

Receive Behavior

Leader and follower operation

Leader opens the local UDP port and receives packets directly.
Follower subscribes to packets already received by a leader on the same configured port.
This avoids multiple listeners competing for the same UDP port on the same core.

Address matching

Each row listens to Prefix + Address [x].
OSC 1.0 wildcards (*, ?, [a-z], [!...], {a,b}) can be used inside each part of the address.
A successful match updates the received address text, LED, and argument outputs for that row.

Hold behavior

With AddressHold [x] enabled, the most recent matched values remain available until a later valid match replaces them.

Logging and forwarding

The log page captures incoming traffic for troubleshooting.
A leader receiver can forward raw UDP packets to ForwardIP:ForwardPort.
Followers receive locally published packets only for the configured Port.

Multicast

If MulticastIP is populated, a leader receiver joins that multicast group after opening the local port.
Followers do not join multicast directly.

Internal OSC Libraries

When a Prefix is set, it applies to both libraries: for example <prefix>/Comp/<comp_name>/<ctrl_name>.

Named Components library

Enable CmdComp to let incoming OSC messages address Q-SYS Named Components directly.

Syntax: /Comp/<comp_name>/<ctrl_name> <value_as_string>

Rules:

Spaces are not allowed in <comp_name>, <ctrl_name>, or <value_as_string>.
If the control type resolves to string, the plugin writes .String.
If the value resolves to boolean, the plugin writes .Boolean.
If the value resolves to float, the plugin writes .Position.
If the value resolves to integer, the plugin writes .Value.
If the string value is Trigger, the target control is triggered.

Named Controls library

Enable CmdCtrl to let incoming OSC messages address Q-SYS Named Controls directly.

Syntax: /Ctrl/<ctrl_name> <value_as_string>

Rules:

Spaces are not allowed in <ctrl_name> or <value_as_string>.
The same type-handling rules used by the Named Components library also apply here.

Q-SYS naming notes

In older Q-SYS Designer versions, rename the component block directly while offline.
In Q-SYS Designer 9.5 and newer, use the component Code Name and ensure Script Access is set appropriately.
Named Controls must be added to the Q-SYS Named Controls list before OSC messages can target them.

Support

For support, contact support@ad-da.ca. The support contact and documentation link are also shown on the plugin's About page.