Macros

Macros are custom actions, defined as scripts, that fire on a trigger. Triggers can be event-based (e.g. when the system powers on) or time-based (optionally restricted to specific days). Common applications include automatically powering rooms at set times, recalling DSP presets when rooms link, and triggering default routes on startup.

Macros consist of two components: triggers (event based or time based) and actions (what executes when triggered). Macros are created at the template level, with room-level editing available if enabled in the template’s Room Options.

📝 Note

This article covers the actions available for everyday room automation. If you have a use case that isn’t covered here, contact your Account Manager — our engineers can help design the right triggers and actions for your room.

Macro Structure

Each macro is made up of the following fields:

Field	Description
ID	The unique identifier for the macro.
Name	A name for easy reference.
Disable	When enabled, the macro is ignored during room operation.
Manually Triggerable	When enabled, the macro can be triggered manually from the UI. Note: Not all user interfaces are capable of manually triggering macros. Contact your Account Manager for details regarding compatibility and potential costs.
Triggers	The triggers that set off the macro (time-based or event-based), each with its own unique ID.
Actions	The actions the macro executes when triggered.

Triggers

A macro fires when one or more of its triggers are met. Triggers are either time-based or event-based, and a macro can mix both — it fires when any trigger condition is met.

Time Based Triggers

These activate at specified times. Each time trigger has the following fields:

Field	Description
ID	The unique identifier for the trigger.
Disable	When enabled, this trigger is ignored.
Time	The 24-hour time (`HH:mm:ss`) at which the macro triggers.
Days	The day(s) of the week on which the macro triggers. Accepts comma-delimited weekday names, or `Weekday` / `Weekend`. If omitted, triggers every day.

Event Based Triggers

Event triggers monitor room or device state changes. Each event trigger has the following fields:

Field	Description
ID	The unique identifier for the trigger.
Disable	When enabled, this trigger is ignored.
Guid	The GUID of the object generating the event (e.g. `room`, or a device ID).
Property	The object property this event relates to.
Key	For properties with multiple values (e.g. one per destination type), the key by which the value is accessed.
Index	For list properties, the index by which the value is accessed.
Value	The property value which, if matched, triggers the macro.

Common Event Triggers

Commonly used event triggers are listed below. Most use the room Guid; some come from specific subsystems with their own Guid.

📝 Note

No current event trigger uses the Index field, so it is omitted from the table below. It remains available for any list-based properties added in future.

Guid	Property	Key	Value	Description
room	PowerIsOn	—	`true`	Triggered when the room’s RoomMode property is not “Off”
room	PowerIsOn	—	`false`	Triggered when the room’s RoomMode property is “Off”
room	RoomMode	—	`Presentation`	The room mode typically set when the room powers on
room	RoomMode	—	`Reset`	Triggered when room “reset” is triggered from the UI
room	SourceIsSelected	AV Source ID (e.g. `source.pc`)	`true`	Triggered when the source is routed to ANY destination
room	SourceIsSelected	AV Source ID (e.g. `source.pc`)	`false`	Triggered when the source is no longer routed to ANY destination
room	SourceSelect	Destination Type (e.g. `Main` / `Preview`)	AV Source ID (e.g. `source.pc`)	Triggered when a source is routed to a destination type
room	SourceHasSync	AV Source ID (e.g. `source.pc`)	`true`	Triggered when a source has input sync detected on any of its defined Video Sync Devices
room	SourceHasSync	AV Source ID (e.g. `source.pc`)	`false`	Triggered when a source that previously had input sync has lost it
room	RoomOccupied	—	`true`	Triggered when the room’s sensors have detected occupancy
room	RoomOccupied	—	`false`	Triggered when the room’s sensors are not detecting occupancy
room	Ready	—	`true`	Triggered when the room is initialised
room.link.manager	CurrentLinkStatus	—	`primary`	Triggered when this room links as the primary room
room.link.manager	CurrentLinkStatus	—	`secondary`	Triggered when this room links as a secondary room
room.link.manager	CurrentLinkStatus	—	`unlinked`	Triggered when this room unlinks
audio.manager	ChannelAudioMute	Channel ID	`true` / `false`	Triggered when an audio channel is muted or unmuted
audio.manager	ChannelAudioLevel	Channel ID	Level value	Triggered when an audio channel’s level changes to the given value
sensor.manager	EwisTriggered	—	`true`	Triggered when an EWIS (emergency warning) signal is received
record.manager	RecorderTransportState	—	`record` / `pause` / `stop`	Triggered when the recorder changes transport state

Actions

Each action defines what executes when the macro fires, using the following fields:

Field	Description
ID	The unique identifier for the action.
Disable	When enabled, this action is ignored.
Script	The lambda expression that defines the action.
Device ID	For scripts that use the `device` keyword, the ID of the device the action targets.
Delay	The delay, in seconds, between the trigger(s) firing and the action executing.

Actions are written as a prefix and a function call, for example room.SetSourceSelect("source.pc", "Main"). The prefix selects what the action controls (room, audio, video, etc.). Device-specific actions use the device prefix and require the action’s Device ID field to be set.

Action scripts can only use the following value types:

Type	How to write it	Example
Text	Wrap in double quotes	`"Presentation"`
Number	Write the number directly	`80`
Yes / No	`true` or `false`	`true`
Empty / None	`null`	`null`

All parameters listed for a function must be provided.

Common Actions

These cover everyday room automation.

Room (`room`)

Function	Parameters	Description
`SetRoomMode`	mode (text)	Changes the room to the specified mode (e.g. “Presentation”, “Off”, “Reset”).
`SetSourceSelect`	sourceId (text), destinationType (text)	Routes a source to a destination type (e.g. “Main”, “Projector”).
`SetDestinationGroupSourceSelect`	destinationGroupId (text), sourceId (text)	Routes a source to all destinations in a group.
`SetPreview`	sourceId (text)	Routes a source to all preview monitors.
`SetMainVolume`	volume (number)	Sets the main speaker volume level (0–100).
`Toggle`	toggleId (text)	Toggles a configured switch on or off.
`TriggerMacro`	macroId (text)	Triggers another macro by its ID.

Audio (`audio`)

Function	Parameters	Description
`SetAudioLevel`	channelId (text), level (number)	Sets the volume level (0–100) on a specific audio channel.
`SetAudioMute`	channelId (text), mute (yes/no)	Mutes or unmutes a specific audio channel.
`MuteAllAudio`	(none)	Mutes every audio channel in the room.
`ResetRoomAudio`	(none)	Resets all audio channels to their default levels and mute states.
`ResetMicrophoneAudioLevels`	(none)	Resets all microphone channels to their default levels.
`SetCeilingMicMute`	mute (yes/no)	Mutes or unmutes all ceiling microphones.
`PresetRecall`	channelId (text), presetId (text)	Recalls a saved audio preset on a specific channel.
`SetSourceLevelDefaults`	(none)	Resets all source audio levels to their configured defaults.

Program Audio (`programaudio`)

Function	Parameters	Description
`SetSourceMute`	sourceId (text), mute (yes/no)	Mutes or unmutes all program audio channels assigned to a source.

Microphones (`microphones`)

Function	Parameters	Description
`SetChannelLevel`	channelId (text), level (number), forceReset (yes/no)	Sets the level on a specific microphone channel. Set forceReset to `true` to re-apply the level even if it appears unchanged.
`SetChannelMute`	channelId (text), mute (yes/no)	Mutes or unmutes a specific microphone channel.

Video (`video`)

Function	Parameters	Description
`VideoRoute`	sourceId (text), displayType (text)	Routes a video source to a display type.
`VideoBreak`	displayType (text), type (text)	Clears the video route on a display type. Pass `null` for type if not needed.
`SetDisplayImageMute`	displayId (text), imageMute (yes/no), screenFollow (yes/no)	Mutes or unmutes a display’s image. Set screenFollow to `true` to also retract/extend the projection screen.
`OnImageMuteAll`	(none)	Image-mutes all displays.
`OnImageUnmuteAll`	(none)	Image-unmutes all displays.
`IndividualDisplayVideoMuteOn`	deviceId (text)	Enables video mute on a single display.
`IndividualDisplayVideoMuteOff`	deviceId (text)	Disables video mute on a single display.
`VideoMuteOn`	displayType (text)	Enables video mute on all displays of a type.
`VideoMuteOff`	displayType (text)	Disables video mute on all displays of a type.
`SetDisplayVideoFreeze`	displayId (text), freeze (yes/no)	Freezes or unfreezes the video on a display.
`SetDisplayVideoFreezeByType`	destinationType (text), freeze (yes/no)	Freezes or unfreezes all displays of a type.
`ActivateAllMotors`	(none)	Activates (extends) all motorised devices defined against displays, e.g. lowering projection screens.
`DeactivateAllMotors`	(none)	Deactivates (retracts) all motorised devices defined against displays, e.g. raising projection screens.
`SetContentScene`	contentId (text), sceneId (text)	Activates a content scene on a video wall group.

Camera (`camera`)

Function	Parameters	Description
`PresetRecall`	id (text), preset (text)	Recalls a camera preset by camera source ID and preset name or ID.
`SetAutoSelectState`	autoSelect (yes/no)	Enables or disables automatic camera selection.
`SetAllCamerasTrackingOff`	(none)	Disables tracking on all cameras.
`PowerOnCameras`	allCameras (yes/no)	Powers on cameras. `true` for all; `false` for only those set to power on by default.
`PowerOffCameras`	(none)	Powers off all cameras.
`SetCameraPower`	cameraId (text), power (yes/no)	Powers an individual camera on or off.

Lighting (`lighting`)

Function	Parameters	Description
`PresetRecall`	presetId (text)	Recalls a lighting preset by its ID.
`SetFaderLevel`	faderId (text), level (number), channelId (text)	Sets the brightness level (0–100) on a lighting fader. Pass `""` for channelId to apply to all channels.
`Toggle`	toggleId (text)	Toggles a lighting circuit on or off.

Other Managers

Function	Parameters	Description
`bluetooth.SetBluetoothControl`	operation (text), bluetoothControlId (text)	Performs a Bluetooth operation: “pair”, “disconnect”, or “cancel”.
`iptv.SetIptvControl`	guid (text), control (text), value (text)	Sends a channel command: “up”, “down”, or “set” with a channel ID. Pass `""` for value with “up”/“down”.
`iptv.PowerOnAllIptvs`	(none)	Powers on all set-top box devices.
`iptv.PowerOffAllIptvs`	(none)	Powers off all set-top box devices.
`documentcamera.SetDocumentCameraSelected`	documentCameraSourceId (text)	Sets which document camera is currently selected.
`documentcamera.PowerOnAllDocumentCameras`	(none)	Powers on all document cameras.
`documentcamera.PowerOffAllDocumentCameras`	(none)	Powers off all document cameras.
`timer.SetTimerMode`	timerId (text), modeId (text)	Changes a timer’s mode (e.g. timer, stopwatch).
`timer.SetTimerColour`	timerId (text), colourId (text)	Changes a timer’s display colour.

Device Actions (`device`)

Device actions target the device set in the action’s Device ID field. The available functions depend on the device type.

Display (Projector, LCD, Display)

Function	Parameters	Description
`SetPowerOn`	(none)	Powers on the display and sets the default volume and input.
`SetPowerOff`	(none)	Powers off the display.
`PollPowerOn`	(none)	Polls the display for its power state; if off, sends a power on command.
`SetVideoInput`	input (text)	Switches the display to a specific video input.
`SetVideoMute`	mute (yes/no)	Mutes or unmutes the display’s video.

Camera

Function	Parameters	Description
`SetPowerOn` / `SetPowerOff`	(none)	Powers the camera on or off.
`SetTrackingOn` / `SetTrackingOff`	(none)	Enables or disables automatic tracking.
`PresetRecall`	preset (text)	Recalls a saved camera preset.

Document Camera

Function	Parameters	Description
`SetPowerOn` / `SetPowerOff`	(none)	Powers the document camera on or off.
`ZoomToValue`	zoomLevel (number)	Zooms to a specific level.
`ToggleAutoFocus`	(none)	Toggles auto-focus on or off.
`LampOn` / `LampOff` / `LampToggle`	(none)	Turns the lamp on, off, or toggles it.
`PresetRecall`	preset (text)	Recalls a saved preset.

Set-Top Box (TV, IPTV, Set Top Box)

Function	Parameters	Description
`SetPowerOn` / `SetPowerOff`	(none)	Powers the set-top box on or off.
`Reboot`	(none)	Reboots the set-top box.
`ChannelUp` / `ChannelDown`	(none)	Changes to the next or previous channel.
`ChannelRecall`	channel (text)	Tunes directly to a specific channel.

Timer / Clock

Function	Parameters	Description
`SetTimer`	duration (number)	Sets the timer duration in seconds.
`StartTimer` / `StopTimer` / `PauseTimer` / `ResetTimer`	(none)	Starts, stops, pauses, or resets the timer.
`SetMode`	mode (text)	Switches the operating mode (e.g. “clock”, “timer”, “stopwatch”).
`ExtendTime` / `ReduceTime`	(none) or seconds (number)	Extends or reduces the timer by the default step, or by the given seconds.
`SetColour`	colour (text)	Sets the display colour (e.g. “#FF0000”).

Motor / Projection Screen (Screen, Motor, Motorised Screen)

Function	Parameters	Description
`Extend`	(none)	Lowers the projection screen.
`Retract`	(none)	Raises the projection screen.
`Stop`	(none)	Stops the screen movement.

Bluetooth

Function	Parameters	Description
`Pair`	(none) or channel (text)	Initiates Bluetooth pairing, optionally on a specific channel.
`CancelPair`	(none) or channel (text)	Cancels the current pairing attempt, optionally on a specific channel.
`CloseConnection`	(none)	Disconnects the active Bluetooth connection.

Lighting Controller

Function	Parameters	Description
`PresetRecall`	guid (text)	Recalls a lighting preset.
`SetFaderLevel`	guid (text), level (number)	Sets the brightness level (0–100) for a lighting channel.
`Toggle`	guid (text), toggle (yes/no)	Turns a lighting group on or off.

Touch Panel LED

Function	Parameters	Description
`SetColour`	r (number), g (number), b (number), ledType (text)	Sets the LED at `ledType` to the given RGB colour. Example: `device.SetColour(0, 255, 0, "front")`.
`Flash`	r, g, b, repeatCount, onInterval, offInterval (numbers), ledType (text)	Flashes the LED between the RGB colour and off for the given cycles, then reverts. Example: `device.Flash(255, 0, 0, 10, 5, 5, "front")`.

📝 Note

Qbic touch panels have valid LED positions front and side. A position of all targets all LEDs. SetColour with all terminates any aligned flashing command.

Preset Device (any device that supports presets)

Function	Parameters	Description
`PresetRecall`	preset (text)	Recalls a saved preset.

Advanced Actions

⚠️ Warning

These actions control low-level AV-over-IP plumbing and raw device behaviour. Use them only if you understand your room’s encoder/decoder and device topology — incorrect values can break routing.

Room Routing & Streams (`room`)

Function	Parameters	Description
`SetDestGroupSourceIfPrimary`	destGroupId (text), sourceId (text)	Routes a source to a destination group, only if this room is the primary in a linked setup.
`SetDestGroupSourceIfSecondary`	destGroupId (text), sourceId (text)	Routes a source to a destination group, only if this room is the secondary in a linked setup.
`SetDevicePowerOn`	deviceId (text)	Powers on a device by its ID.
`SetDevicePowerOff`	deviceId (text)	Powers off a device by its ID.
`SetDecoderVideoStream`	streamId (text)	Sets the video stream on all decoders.
`RouteEncoderDecoderStreamByDeviceId`	encoderId (text), decoderId (text)	Routes both video and audio from an encoder to a decoder.
`RouteEncoderDecoderVideoStreamByDeviceId`	encoderId (text), decoderId (text)	Routes only the video stream from an encoder to a decoder.
`RouteEncoderDecoderAudioStreamByDeviceId`	encoderId (text), decoderId (text)	Routes only the audio stream from an encoder to a decoder.
`PairUsb`	remoteDeviceId (text), localDeviceId (text)	Pairs USB peripherals between a remote and local device.
`PairUsb`	remoteDeviceId (text), localDeviceId (text), index (number)	Pairs USB peripherals at a specific port index.
`SetVideoMuteTimed`	deviceId (text), timeout (number), windowStartTime (text), windowEndTime (text)	Mutes a display’s video for a duration, but only within the specified time window.

📝 Note

Remote Device is generally connected to USB peripherals (e.g. keyboard, mouse); Local Device is generally connected to a PC.

Advanced Audio & Video

Function	Parameters	Description
`audio.SetSinkControl`	sinkId (text), action (text)	Controls a microphone receiver (“pair” or “cancel”).
`audio.TriggerLinkMute`	linked (yes/no), roomLinkId (text)	Mutes or unmutes the room link audio block. Pass `""` for roomLinkId to target all.
`video.RouteAvStream`	encoderId (text), decoderId (text)	Routes video and audio streams from an encoder to a decoder.
`video.SetAudioStream`	encoderId (text), decoderId (text)	Routes only the audio stream from an encoder to a decoder.
`video.PerformUsbRoutes`	destinationType (text), newSourceId (text), previousSourceId (text)	Routes USB connections based on a source change.
`video.SetDestinationDisabled`	destinationId (text), disabled (yes/no)	Disables or enables an AV destination. When disabled, it triggers its shutdown behaviour and is not routed to.

Advanced Device Actions (`device`)

DSP (Audio Processor)

Function	Parameters	Description
`SetVolumeLevel`	guid (text), volumePercent (number)	Sets the volume level on a specific fader.
`SetVolumeMute`	guid (text), mute (yes/no)	Mutes or unmutes a specific fader.
`PresetRecall`	preset (text)	Recalls a DSP preset.

Encoder / Decoder

Function	Parameters	Description
`SetVideoStream`	stream (text)	Sets the decoder video stream (pass `""` to clear).
`SetAudioStream`	stream (text)	Sets the decoder audio stream (pass `""` to clear).
`SetVideoMute`	mute (yes/no)	Mutes or unmutes the video.
`SetVolumeMute`	mute (yes/no)	Mutes or unmutes the audio.
`Reboot`	(none)	Reboots the device.

Switcher

Function	Parameters	Description
`SetVolumeLevel`	level (number)	Sets the switcher’s audio volume level.
`SetVolumeMute`	mute (yes/no)	Mutes or unmutes the switcher’s audio.
`SetAudioVideoInput`	input (text)	Routes the switcher to the given AudioVideo input.

Examples and Common Use Cases

Below are complete macro configuration examples showing the JSON structure, trigger conditions, and action scripts.

Automatic Lighting on Shutdown

Turn off the lights every night at 11:00 PM, with a short delay to allow shutdown processes to complete.

{
    "ID": "lights.off",
    "Name": "Nightly Lights Off",
    "Triggers": {
        "Time Triggers": [
            { "ID": "trigger.nightly", "Time": "23:00:00" }
        ]
    },
    "Actions": [
        { "ID": "lights.off", "Script": "lighting.PresetRecall(\"preset.off\")", "Delay": 5 }
    ]
}

Route Audio When a Source is Selected

When the Apple TV is selected on the “Audio” destination, route its encoder’s audio stream to the video wall decoder.

{
    "ID": "macro.audio.route.apple.tv",
    "Name": "Route Audio Apple TV",
    "Triggers": {
        "Event Triggers": [
            {
                "ID": "macro.trigger.apple.tv",
                "Guid": "room",
                "Property": "SourceSelect",
                "Key": "Audio",
                "Value": "source.apple.tv"
            }
        ]
    },
    "Actions": [
        { "ID": "action.1", "Script": "video.SetAudioStream(\"dev.encoder.apple.tv\", \"dev.decoder.videowall.primary\")" }
    ]
}

Set Presentation Lighting When a Source is Routed

When a source is selected on the “Audience Left” destination, recall the presentation lighting preset.

{
    "ID": "macro.lights.presentation",
    "Name": "Presentation Lighting",
    "Triggers": {
        "Event Triggers": [
            {
                "ID": "trigger.1",
                "Guid": "room",
                "Property": "SourceSelect",
                "Key": "Audience Left",
                "Value": "source.pc.left"
            }
        ]
    },
    "Actions": [
        { "ID": "action.1", "Script": "lighting.PresetRecall(\"preset.presentation\")" }
    ]
}

Trigger One Macro from Another

Chain macros together. When the room mode changes to “Off”, trigger a separate cleanup macro.

{
    "ID": "macro.shutdown.chain",
    "Name": "Shutdown Chain",
    "Triggers": {
        "Event Triggers": [
            { "ID": "trigger.1", "Guid": "room", "Property": "RoomMode", "Value": "Off" }
        ]
    },
    "Actions": [
        { "ID": "action.1", "Script": "room.TriggerMacro(\"macro.cleanup\")" }
    ]
}

Tips

Escaping quotes: Macro scripts are JSON strings, so double quotes inside a script must be escaped with a backslash (\") when uploading JSON.
Delays: Use delays to sequence actions that depend on each other (e.g. wait for a display to power on before routing a source).
Chaining macros: Use room.TriggerMacro("macro.id") to call one macro from another, keeping complex automations modular.
Multiple triggers: A single macro can have both event and time triggers — it fires when any trigger condition is met.
Device actions: When using device. functions, always set the action’s Device ID field to the target device’s ID.

Macro Structure

Triggers

Time Based Triggers

Event Based Triggers

Common Event Triggers

Actions

Common Actions

Room (room)

Audio (audio)

Program Audio (programaudio)

Microphones (microphones)

Video (video)

Camera (camera)

Lighting (lighting)

Other Managers

Device Actions (device)

Advanced Actions

Room Routing & Streams (room)

Advanced Audio & Video

Advanced Device Actions (device)

Examples and Common Use Cases

Automatic Lighting on Shutdown

Route Audio When a Source is Selected

Set Presentation Lighting When a Source is Routed

Trigger One Macro from Another

Tips

Related Articles

Room (`room`)

Audio (`audio`)

Program Audio (`programaudio`)

Microphones (`microphones`)

Video (`video`)

Camera (`camera`)

Lighting (`lighting`)

Device Actions (`device`)

Room Routing & Streams (`room`)

Advanced Device Actions (`device`)