Node-RED
Node-RED wires programs and devices together with flows you draw in a browser. The Visibox nodes put Visibox into those flows. A flow can fire a Clip when a sensor trips, change Songs on a timer, set a Real-Time Control from a dashboard slider, or react the moment a Song starts.
Where Companion is for buttons a person presses, Node-RED is for things that should happen on their own.
Before you start
- Node-RED 3.0 or later, running on Node.js 20 or later.
- Visibox 6.0 or later, on the same computer or on the same network.
Installing
- In the Node-RED editor, open the menu and choose Manage palette.
- On the Install tab, search for
node-red-contrib-visiboxand click install.
The nodes appear in the palette under Visibox.
To start from a working flow, open the menu, choose Import > Examples > node-red-contrib-visibox, and pick Visibox starter. It adds a tab with buttons for Play / Stop, Pause / Resume, Next song, Next clip, Mute toggle, setting Control A, and reading the state, all wired to a shared connection called Local Visibox.
Connecting to Visibox
Every Visibox node points at one shared Server setting. Open it from any Visibox node with the pencil button beside Server.
| Field | What it is |
|---|---|
| Host | The computer running Visibox. 127.0.0.1 when it is the same computer. |
| WS Port | 17734 unless you changed it. |
| HTTP Port | 17736 unless you changed it. |
| Pairing Code | A six-digit code from Visibox, for a Node-RED on another computer. |
Deploy, and Visibox asks to let Node-RED in:
- On the same computer, leave Pairing Code empty. Visibox shows a prompt asking to allow Node-RED. Click Allow.
- On another computer, choose Pair with Remote… in Visibox (on Mac, from the Visibox menu; on Windows, from the File menu), type the code into Pairing Code, and deploy. The code works once and expires after 5 minutes.
Visibox hands Node-RED a token, and Node-RED keeps it for every later restart. To pair again, enter a new code and deploy.
Every Visibox node shows its connection under it: green when connected, yellow while connecting, red when it cannot reach Visibox or was refused.
The nodes
visibox action
Sends any Visibox action. Pick it from the Action list and add its Params, or send the action in the message as msg.payload.action with msg.payload.params as a list. The node passes on whether it worked, with success and, if not, the error Visibox gave. A refused action also raises an error a catch node can pick up.
The action names are the ones in the API, such as PLAY_CLIP_BY_INDEX_IN or NEXT_SONG_IN.
visibox playback
The transport without looking anything up: Play, Stop, Pause, Resume, Play/Stop Toggle, Pause/Resume Toggle, Panic, Mute Toggle, or Fullscreen Toggle. Any message that arrives fires it. A msg.payload.control such as stop overrides the one you picked.
visibox control
Drives Real-Time Control in one of three modes:
- Set Control sets a Control by its letter, as a percentage.
- Adjust Control by moves a Control up or down from where this node last put it.
- Set Target Param sets one parameter by its Target ID, such as
master/volume.
Send a number as msg.payload and it becomes the value, which is how a dashboard slider drives a Control.
visibox state
Sends a message every time something changes in Visibox: playback, the Project, the output level, mute, or full screen. Send it any message and it reports the current state straight away. msg.payload carries:
| Property | What it holds |
|---|---|
connected | Whether Node-RED is connected to Visibox. |
playbackStatus | playing, paused, or stopped. |
projectTitle | The open Project. |
activeSongName, activeSongIndex | The active Song and its position, counting from 0. |
activeClipName, activeClipIndex | The active Clip and its position, counting from 0. |
activeClipProgress | How far through the active Clip, from 0 to 1. |
outputLevel | The output level, from 0 to 1. |
outputMuted, outputFullscreen | true or false. |
A switch node on playbackStatus is the usual way to start something when a Song starts or stops.
Troubleshooting
Nodes say auth failed. The pairing code was wrong or already used, or Node-RED was removed from Paired Devices in Settings > Remote. Enter a new code and deploy, or on the same computer, deploy and click Allow when Visibox asks.
Nodes stay red. Check that Visibox is open, that Host is the right address, and that a firewall is not blocking ports 17734 and 17736.
Adjust Control by jumps. Visibox does not report where a Control sits, so the node counts from the last value it sent. Set the Control once to give it a starting point.
See Also
- Visibox API for every action and its parameters.
- OSC, which Node-RED can also send.
- Remote Pairing for pairing codes and paired devices.