Open Sound Control

Open Sound Control (OSC) V1.3.0.0

Table of Contents

• Plugin version
• Release note
• QDS compatibility
• Plugin description
• Properties
• Controls
  • Send Mode
  • Receive Mode
  • Control Pins

Plugin Version

This document is written for the plugin:

• OSC V1.3

Release Note

• 2025-10-03: V1.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: V1.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: V1.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-09-12: V1.0.0.0

  • Initial release

QDS Compatibility

This plugin has been developed and tested on:

• Q-SYS Designer version 9.10.2
• Q-SYS Designer version 10.0.X (Emulation Mode supported as of V1.3.0.0)

Plugin Description

This plugin brings the power and versatility of the Open Sound Control (OSC) protocol to your fingertips using existing network infrastructures.

The Open Sound Control (OSC), recognized for its robustness and reliability, allows you to exchange commands with a variety of AV equipment or computer using QLab in a seamless and transparent manner.

Features:

• Send and Receive OSC commands
• Use input events to send OSC commands
• Insert multiple instances of the plugin
• Use custom IP Address and/or Connection Port for each instance
• Create custom OSC commands libraries that can be imported and exported easily
• Use inputs placeholders to inject inputs values into your custom OSC Commands
• Use internal OSC Libraries to interact directly with the Q-Sys environment
• Interact with external OSC Devices such as Q-Lab systems and internal components within Q-sys through connection pins or using scripts

Important Notes:

• This plugin is designed exclusively for use with the UDP protocol and does not support TCP
• This plugin does not support OSC bundle; attempting to use it will produce the error "attempt to call a nil value (field 'mod')" in the debug window

Properties

License

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 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. However, once you run your design on a core, you will need a license to run the plugin for more than 1 hour.

License Backup

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

Set the operating mode of the plugin.

Default value: Send
Accepted values:

• Send
• Receive

Send Count (Send Mode)

Set the number of "Command [x]" slots in the Send tab.

Default value: 4
Accepted values: 4 to 32

Input Count (Send Mode)

Set the number of "Input [x]" slots in the Input tab.

Default value: 4
Accepted values: 4 to 32

Receiver Mode (Receive mode)

Set the hierarchy of the plugin as to which one is leading, and which one are following in cases of multiple receiver plugins configuration.

Default value: Leader
Accepted values:

• Leader
• Follower

Function explanation: Leader and Follower UDP Listening Mode

In Q-SYS, a core cannot have two listeners on the same UDP port. This means that if multiple components need to receive messages from the same port, we need a mechanism to handle this.

To address this, the plugin includes a Leader and Follower receive mode:

Leader Mode: The leader is the primary listener on the specified UDP port. It is the only one directly listening for messages on the port.

Follower Mode: If multiple listeners need to receive messages from the same port, additional listeners should operate in follower mode. A follower connects to the leader to receive messages relayed by the leader. A follower cannot function independently and relies on the leader to get the messages.

Use Case: If you're not trying to listen to the same UDP port as another listener, simply leave the plugin in Leader mode to receive messages directly. No follower mode is necessary in this case.

By implementing this mode, the plugin ensures that multiple components can "listen" to the same UDP port while respecting the core's limitation of only one active listener per port.

Important Note (V1.3.0.0): Only one plugin can bind to a specific UDP port at a time. If the Sender plugin is configured to bind the port, then the Receiver plugin must be set to Follower mode to receive data through the Sender.

OSC Address Count (Receive mode)

Set the number of "OSC Address Pattern [x]" slots available in the OSC Address Tab.

Default value: 4
Accepted values: 4 to 32

Controls

Status

Indicates verbose actual status of the plugin.

• OK (Green): The plugin is running

Send Mode

Send

Send [x] Command

Drop down list used to assign an OSC command from the Commands Library to the corresponding command slot.

Send [x] Trigger

Trigger buttons used to manually send the assigned OSC commands.

Input

Input [x] Pin

Text fields showing the current value for each input's control pin.

Input [x] Debounce

Toggle button used to activate the "Debounce" function on the corresponding input pin. When activated, the input is filtered by an algorithm that adjust the way the input reacts to rotary or slider controls to limit the transmission of "in-between" OSC Commands while reaching for a specific value.

Input [x] Event Handler

Toggle button used to activate or deactivate the corresponding input action. When the "Send Command on Input Event" is activated, the assigned command will be sent on each event occurring on this input pin.

Input [x] Send Command Number

Number field used to assign the corresponding send command to each input event handler.

Commands Library

Command List

List all commands in current library in alphabetical order.

Commands Add

Button used to create a new command from scratch.

Commands Delete

Button used to delete the selected command.

Commands Duplicate

Button used to create a copy of the selected command.

Commands Test

Button used to send the Selected Command.

Selected Command

Commands Name

Text field used to give a name for the command.

Commands Address

Text field used to enter the "OSC Address" part of the OSC Address Pattern. The use of brackets placeholders allows grabbing the corresponding input value (ex: {1} = value of input 1).

Commands Arguments Add

Button used to add a new argument.

Commands Arguments List

Drop down list with all the current arguments for the selected command. The list starts empty, and a new number is assigned to each new argument.

Commands Arguments Delete

Button used to delete the current argument.

Commands Arguments Type

Drop down list used to set the argument's type (String, Float32, Integer, Boolean, INPUT TO BOOLEAN).

Commands Arguments Value

Text field used to enter the value for the active argument. The use of brackets placeholders allows grabbing the corresponding input value (ex: {1} = value of input 1).

Library

Text field used to export and import (backup and restore) the commands library. To export (backup) content, select all the text and use "Copy/Paste" to save the library to an external text file. To restore a library, simply grab the previously saved library text content and paste it in this field.

Libraries are intended to be Saved and Backup from and to external text files. To restore/load a library, simply paste the library string from your backup file to the library import/Export field and the plugin will then automatically read the content of the field and populate the corresponding fields in the library editor.

New in V1.3.0.0: Clearing this field will delete/reset the command library. Entering "TEMPLATE" will load a library with examples (this is loaded by default when the plugin is first used).

Setup

Connection Ip Address

Used to set the IP address of the target OSC device.

Connection Port

Used to set the communication port of the target OSC device.

Bind Port (New in V1.3.0.0)

When enabled, binds the UDP port when sending messages to ensure the destination can reply on a known port. Send via notifications incoming messages to Receive components in follower mode when BIND PORT is enabled.

Forward to IP Address

Used to set the IP address for message forwarding. In Send mode, the port must be bound to activate the forwarding function and a valid IP address must be entered.

Forward Port

Used to set the port for message forwarding. Works in conjunction with the Forward to IP Address setting.

Receive Mode

OSC Address

OSC Address Prefix

Text field allowing you to put a string that will be concatenated before each OSC Address Pattern to be filtered. This is particularly useful to simplify the OSC Address Pattern defined in the OSC Address Pattern [x] slots.

The use of "*" wildcard enables you to replace any entry, allowing you to target a specific portion of the received command while accepting any value for each wildcarded portion of the OSC Address.

OSC Address [x] Address

Text field allowing you to enter the OSC Address to listen to. The complete OSC Address is a concatenation of the prefix and the OSC Address Pattern.

OSC Address [x] Received

Text field showing the actual received OSC Address.

OSC Address [x] Hold

Toggle button used to activate or deactivate the "hold" function that will retain the last received OSC Command that match the corresponding OSC Address pattern.

OSC Address [x] Led

Led Indicator that will be lit momentarily when a valid OSC Address Pattern is received.

OSC Address [x] Args [x]

Text Display showing the actual argument [x] for each OSC Address Pattern. A maximum of 4 arguments can be displayed for each OSC Address Pattern slot.

Log

Log Clear

Button to erase all the log content.

Log Count

Number of log lines to retain.

Enhanced in V1.3.0.0: All incoming messages are now printed in the log for better troubleshooting, not only the configured ones.

Setup

Connection Interface

Used to set the IP address of the receiving interface.

Changed in V1.3.0.0: NIC Selection changed from ALL to ANY.

Connection Port

Used to set the communication port of the receiving interface.

Enhanced in V1.3.0.0: Receiver in Follower mode now only receives messages from selected PORT and no longer disables port controls.

Forward to IP Address

Used to set the IP address for message forwarding. In Receive mode, forwarding is only activated when a valid IP address is entered.

Forward Port

Used to set the port for message forwarding. Works in conjunction with the Forward to IP Address setting.

Named Components Library

Toggle button used to enable the Internal OSC Libraries function for direct interaction with the Q-SYS environment. When enabled, it allows users to bypass complicated schematic connections and long OSC address patterns by directly interacting with another component using the name that it's being assign to in the "Q-Sys Named Component library".

OSC Address Pattern requirement:

Important: (*) spaces aren't allowed in <comp_name>, <ctrl_name> and <value_as_string>. If the control inside the component contains spaces, you need to create a Named Control for this control without spaces and use the Named Control Library instead.

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

Where:

• /Comp/ - Indicates to the plugin that it will need to access the "Q-Sys Named Components Library" to locate the named component referenced by the next argument.
• <comp_name> - The name of the component (*).
• <ctrl_name> - The name of the control on the <comp_name> component (*).
• <value_as_string> - The first string argument received will be applied to <ctrl_name> control .String

Enhanced in V1.3.0.0: Enhanced argument type handling:

• 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
• Otherwise, if arg type is string, applies to the .String of the control

How to rename a component

• Q-SYS Designer 9.4 and lower: While in offline mode, simply rename the actual component block.
• Q-SYS Designer 9.5 and upper: While in offline mode, go to the Properties pane and change "Code Name" to the desired name and make sure "Script Access" is at "Script" or "All".

Named Controls Library

Toggle button used to enable the Internal OSC Libraries function for direct interaction with the Q-SYS environment. When enabled, it allows users to bypass complicated schematic connections and long OSC address patterns by interacting with the built-in "Q-Sys Named Controls library".

OSC Address Pattern requirement:

Important: (*) spaces aren't allowed in <ctrl_name> and <value_as_string>.

Syntax: /Ctrl/<ctrl_name> <value_as_string>

Where:

• /Ctrl/ - Indicates to the plugin that it will need to access the "Q-Sys Named Controls Library" to locate the named control referenced by the next argument.
• <ctrl_name> - The name of the control you want to interact with as indicated in the "Q-Sys Named Controls Library".
• <value_as_string> - The first string argument received will be applied to <ctrl_name> control .String

How to name a control?

In order for the external system to access the controls, they have to be named.

1. Make sure the design is in the design mode. (F7)
2. Click the Named Controls accordion bar in the left pane of the Q-SYS workspace. The Named Controls list displays and is empty in new designs.
3. Double-click the Schematic Element for which you want to make the controls available. The Control Panel displays.
4. Select one or more controls that you want to make available and drag them into the Named Controls list. You can press Ctrl+A to select all the controls. When you press Ctrl+A, all the non-control items are selected as well, but are ignored by Q-SYS when dragged into the list.
5. As you drag controls into the Named Controls list, the list is populated with the control's name, for example, CrossoverLowBandGain. The name is used by the external system to access this control.
6. To help you identify controls already in the Named Controls list, each control you place in the list is marked graphically in the Control Panel by a small gray circle on the lower right corner of the control in the Control Panel from which it came. This identifier is available only in the Design mode.
7. Rename the control if desired.

Control Pins

Pin Name	Value	String	Pins Available
Connection (Send Mode)
IP Address		(String)	Input / Output
Port		(String)	Input / Output
Forward to IP Address		(String)	Input / Output
Forward Port		(String)	Input / Output
Input (Send Mode)
Input [x] Debounce	0 1	false true	Input / Output
Input [x] Event Handler	0 1	false true	Input / Output
Input [x] Pin		(String)	Input
Input [x] Send Command Number		(String)	Input / Output
Send (Send Mode)
Send [x] Command		(String)	Input / Output
Send [x] Trigger		(String)	Input / Output
Connection (Receive Mode)
Interface		(String)	Input / Output
Port		(String)	Input / Output
Forward to IP Address		(String)	Input / Output
Forward Port		(String)	Input / Output
Log (Receive Mode)
Clear		(String)	Input / Output
Count		(Integer)	Input / Output
Data		(String)	Input / Output
OSC Address (Receive Mode)
OSC Address [x] Args [y]		(String)	Output
OSC Address [x] Address		(Integer)	Input / Output
OSC Address [x] Hold	0 1	false true	Input / Output
OSC Address [x] Led	0 1	false true	Output
OSC Address [x] Received	0 1	false true	Output
OSC Address Prefix		(String)	Input / Output
Setup (Receive Mode)
Named Components	0 1	false true	Output
Named Controls	0 1	false true	Output
General
Disable	0 1	false true	Input / Output
Library		(String)	Input / Output
Status		OK	Output

---

Support: support@ad-da.ca

Copyright © 2025 AD-DA.CA