the API

you can communicate with veadotube programs by either:

connecting to their WebSocket servers;
using command line arguments;
sending a GET request to the same address as the WebSocket server.

when communicating, your message will be going through and back a specific channel. each channel represents a different feature in veadotube, and the message format will vary for each.

below are the different ways you can communicate with veadotube, and in the subpages you may find how each channel behaves.

veadotube instances

there can be more than one veadotube open (e.g. veadotube and veadotube mini at the same time, or multiple veadotube minis).

you can find a list of currently open instances listed as files inside the instances folder in the data folder. each file represents a different instance; the file name is the instance id, which can be parsed into three segments separated by dashes:

instance type, which should be veado for veadotube and mini for veadotube mini;
launch timestamp, hex number, always 16 characters;
process id, hex number, always 8 characters.

for example, a veadotube mini instance could have an instance id of mini-08dd3cd72f015bb9-000681a2.

the file contents can be parsed as a JSON object. it looks like this:

            {
	"time": 1739023315, // a Unix timestamp
	"name": "veadotube mini", // display name for the instance
	"id": "mini-08dd3cd72f015bb9-000681a2", // instance id, again
	"version": "2.1", // program version
	"language": "en", // program language
	"server": "127.0.0.1:2424" // HTTP (WebSocket or GET) address, if available
}

          

you should ignore instances with invalid JSON objects or where the Unix timestamp is older than 10 seconds from the current time.

connecting to the WebSocket server

connecting to the WebSocket server is the same as any other WebSocket servers, except that veadotube expects clients to pass a display name for the client itself. the server will reject unnamed clients.

let’s say you’re hosting at 127.0.0.1:2424, and you’re writing a Stream Deck plugin (which you shouldn’t need to); the address you’re gonna try and connect would look something like ws://127.0.0.1:2424?n=Stream%20Deck. veadotube will establish connection and list it as a “Stream Deck” that’s connected to the program.

all messages that go through the WebSocket are prefixed with an id that represents which channel this message is being sent through, followed by a colon.

for example, a message that comes from or goes to the nodes channel, whose content is JSON-encoded data, would look like this, even if the entire message by itself doesn’t conform to JSON:

```
nodes: {
  "event": "list"
}
```

using the command line

you can also use the command line to send one-off messages (and get their response) to a veadotube instance, without having to maintain connection to a WebSocket server.

for this guide, we’ll assume you opened Terminal on the same directory as the executable, and that you’re using veadotube, as ./veadotube. if you’re using veadotube mini, you can use ./veadotube-mini instead. you may also put your veadotube programs in your PATH and use either veadotube or veadotube-mini from any directory.

to list currently open instances of veadotube programs:

```
./veadotube -i
```

this will give you a line-separated list of instance ids, but only those with open servers. the list is always ordered based on which instance was opened first.

the parameter passed to -i tells the program which instance you’re selecting. for example:

./veadotube -i 0 # first instance on the list

./veadotube -i 1 # second instance on the list

./veadotube -i 2 # third instance on the list

                ./veadotube -i -1 # last instance on the list

              

                ./veadotube -i -2 # second to last instance on the list

              

./veadotube -i mini-08dd3cd72f015bb9-000681a2 # a specific instance

./veadotube -i 127.0.0.1:2424 # a specific address

by calling only that, the program should output the address for the instance, which is redundant if you’re already passing the address itself.

if the server is not found, it should output an error telling the user the instance couldn’t be found.

to send a message to a specific channel, you pass the name as the first argument after the instance selection, and then whatever other arguments the channel requires. for example, a message being sent to the nodes channel would look like this:

```
./veadotube -i 0 nodes boolean mini
```

using GET requests

the way the command line works is by simply making a GET request to the HTTP server that serves WebSocket connections.

you can call it by yourself too, of course! let’s say you wanna make the same nodes boolean mini call as above, to a veadotube instance with a server open at 127.0.0.1:2424. you’d be sending a GET request to the following address:

http://127.0.0.1:2424/?cmd0=nodes&cmd1=boolean&cmd2=mini

this would get you a response where the content is the output itself, and the Veadotube-Command header would either return Success or Error.

channels

each subpage here lists the message structure for each channel, for both WebSocket and command line.