Version: 6.0.0

# Node-RED

[Node-RED](https://nodered.org) 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](https://manual.spaceage.tv/6.0.0/integrations/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

1.  In the Node-RED editor, open the menu and choose **Manage palette**.
2.  On the **Install** tab, search for `node-red-contrib-visibox` and 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](https://manual.spaceage.tv/6.0.0/integrations/api/#available-actions), 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](https://manual.spaceage.tv/6.0.0/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](https://manual.spaceage.tv/6.0.0/integrations/remote-pairing/). 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](https://manual.spaceage.tv/6.0.0/integrations/api/) for every action and its parameters.
*   [OSC](https://manual.spaceage.tv/6.0.0/integrations/osc/), which Node-RED can also send.
*   [Remote Pairing](https://manual.spaceage.tv/6.0.0/integrations/remote-pairing/) for pairing codes and paired devices.

Source: https://manual.spaceage.tv/6.0.0/integrations/node-red/