> technical stuff > the API > nodes channel

nodes channel

the nodes channel opens communication with all WebSocket nodes in a veadotube instance.

if you’re using veadotube, these nodes will have both a display name and an ID, as well as the node type itself, all which you can create and configure.

if you’re using veadotube mini, which uses the node system behind the scenes, these nodes are always exposed:

• push-to-talk: a boolean-type node of id mini that controls whether to activate the microphone or not;
• avatar state: a stateEvents-type node of id mini that controls the current avatar state of the loaded Mini avatar.

getting the node list

to get a complete list of exposed nodes through the WebSocket, you send a list event. you may also send listen or unlisten events to automatically receive the list when it changes. examples:

• nodes: {
    "event": "list"
  }
  

• nodes: {
    "event": "listen",
    "token": "<some random token, optional>"
  }
  

• nodes: {
    "event": "unlisten",
    "token": "<same token as the listen event>"
  }
  

• nodes: {
    "event": "list",
    "entries": [
        { "type": "boolean", "id": "mini", "name": "push-to-talk" },
        { "type": "stateEvents", "id": "mini", "name": "avatar state" }
    ]
  }
  

for the command line, you can request a line-separated list of nodes (their type and id, space-separated), and then request the display name of that node separately.

• ./veadotube -i 0 nodes
  

• boolean mini
  stateEvents mini
  

• ./veadotube -i 0 nodes boolean mini
  

• push-to-talk
  

node events

to communicate with a node through the WebSocket, you’ll be sending and receiving payload events, where the payload object structure will vary depending on the node type. for example:

• nodes: {
    "event": "payload",
    "type": "<node type>",
    "id": "<node id>",
    "payload": {
        ...
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "<node type>",
    "id": "<node id>",
    "name": "<node display name>",
    "payload": {
        ...
    }
  }
  

for all node types, you can send a listen/unlisten event, so that you’ll automatically receive new events when the current node state changes:

• nodes: {
    "event": "payload",
    "type": "<node type>",
    "id": "<node id>",
    "payload": {
        "event": "listen",
        "token": "<some random token, optional>"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "<node type>",
    "id": "<node id>",
    "payload": {
        "event": "unlisten",
        "token": "<same token as the listen event>"
    }
  }
  

boolean nodes

for boolean nodes, you can get their current value, which will either be true or false (or an empty object, in case no value has been set). it may also return 1 for true and 0 for false.

you can also set a new value by either setting it specifically to either true or false, or by telling it to toggle it (so if it is currently true it should become false and vice-versa).

to get a value through the WebSocket:

• nodes: {
    "event": "payload",
    "type": "boolean",
    "id": "<node id>",
    "payload": {
        "event": "get"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "boolean",
    "id": "<node id>",
    "name": "<node display name>",
    "payload": true
  }
  

• nodes: {
    "event": "payload",
    "type": "boolean",
    "id": "<node id>",
    "name": "<node display name>",
    "payload": false
  }
  

to set a new value through the WebSocket:

• nodes: {
    "event": "payload",
    "type": "boolean",
    "id": "<node id>",
    "payload": {
        "event": "set",
        "value": true
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "boolean",
    "id": "<node id>",
    "payload": {
        "event": "set",
        "value": false
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "boolean",
    "id": "<node id>",
    "payload": {
        "event": "toggle"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "boolean",
    "id": "<node id>",
    "payload": {
        "event": "clear"
    }
  }
  

to get or set values through the command line:

• ./veadotube -i 0 nodes boolean [id] get
  

• 0
  

• 1
  

• ./veadotube -i 0 nodes boolean [id] set 0
  

• ./veadotube -i 0 nodes boolean [id] set 1
  

• ./veadotube -i 0 nodes boolean [id] toggle
  

• ./veadotube -i 0 nodes boolean [id] clear
  

number nodes

for number nodes, you can get their current value or set a new one. number values can also include their range (minimum and maximum possible values).

when setting a new value, you can either set to a specific number, or to add to the current number. you can also include a new possible range; if a range is not included in the message, the previous range will be kept if you’re adding to the current number, and discarded if you’re setting to a specific number.

to get a value through the WebSocket:

• nodes: {
    "event": "payload",
    "type": "number",
    "id": "<node id>",
    "payload": {
        "event": "get"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "number",
    "id": "<node id>",
    "name": "<node display name>",
    "payload": { // when there's no range defined
        "value": 3
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "number",
    "id": "<node id>",
    "name": "<node display name>",
    "payload": { // when there's a range defined
        "value": 3,
        "min": 0,
        "max": 10
    }
  }
  

to set a new value through the WebSocket:

• nodes: {
    "event": "payload",
    "type": "number",
    "id": "<node id>",
    "payload": {
        "event": "set",
        "value": 2 // no range
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "number",
    "id": "<node id>",
    "payload": {
        "event": "set",
        "value": { // with range
            "value": 2,
            "min": 0,
            "max": 10
        }
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "number",
    "id": "<node id>",
    "payload": {
        "event": "add",
        "value": -1 // current range will be preserved
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "number",
    "id": "<node id>",
    "payload": {
        "event": "add",
        "value": { // new range is declared
            "value": -1,
            "min": 0,
            "max": 10
        }
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "number",
    "id": "<node id>",
    "payload": {
        "event": "clear"
    }
  }
  

same examples, but for the command line:

• ./veadotube -i 0 nodes number [id] get
  

• 3
  

• 3 0 10
  

• ./veadotube -i 0 nodes number [id] set 2
  

• ./veadotube -i 0 nodes number [id] set 2 0 10
  

• ./veadotube -i 0 nodes number [id] add -1
  

• ./veadotube -i 0 nodes number [id] add -1 0 10
  

• ./veadotube -i 0 nodes number [id] clear
  

stateEvents nodes

stateEvents nodes control a state stack. said stack works similar to a stack in computing:

• a stack is a list of states. the state on top of the stack is considered as the current state;
• pushing a state to the stack puts that state on top of it;
• popping a state from the stack removes it from the list;
• toggling a state on the stack removes it if it’s on the list, or puts it on top of the stack otherwise;
• clearing the stack removes all states – if a stack requires at least one state, only the state on the top is preserved;
• setting a state to the stack clears the list of states and makes that one state the only state in the list.

to get a list of possible states through the WebSocket:

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "payload": {
        "event": "list"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "name": "<node display name>",
    "payload": {
        "event": "list",
        "states": [
            { "id": "<state id>", "name": "<state name>", "thumbHash": "<hash for the thumbnail image>" },
            { "id": "<state id>", "name": "<state name>", "thumbHash": "<hash for the thumbnail image>" },
            ...
        ]
    }
  }
  

both the state id and name are always the same, except in veadotube mini 2.0a and older, where state ids and names were different from each other, and thumbnail hashes weren’t present.

to get the thumbnail image for a given state:

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "payload": {
        "event": "thumb",
        "state": "<state id>"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "name": "<node display name>",
    "payload": {
        "event": "thumb",
        "state": "<state id>",
        "hash": "<hash for the thumbnail image>",
        "width": 128,
        "height": 128,
        "png": "<base64 encoded image data>"
    }
  }
  

to peek on the current state on top of the stack:

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "payload": {
        "event": "peek"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "name": "<node display name>",
    "payload": {
        "event": "peek",
        "state": "<state id>"
    }
  }
  

to modify the state stack:

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "payload": {
        "event": "set",
        "state": "<state id>"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "payload": {
        "event": "push",
        "state": "<state id>"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "payload": {
        "event": "pop",
        "state": "<state id>"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "payload": {
        "event": "toggle",
        "state": "<state id>"
    }
  }
  

• nodes: {
    "event": "payload",
    "type": "stateEvents",
    "id": "<node id>",
    "payload": {
        "event": "clear"
    }
  }
  

the same examples but for the command line:

• ./veadotube -i 0 nodes stateEvents [id] list
  

• #1
  #2
  #3
  #4
  #5
  

• ./veadotube -i 0 nodes stateEvents [id] thumb "#1"
  

• [base64 image data]
  

• ./veadotube -i 0 nodes stateEvents [id] peek
  

• #1
  

• ./veadotube -i 0 nodes stateEvents [id] set "#1"
  

• ./veadotube -i 0 nodes stateEvents [id] push "#1"
  

• ./veadotube -i 0 nodes stateEvents [id] pop "#1"
  

• ./veadotube -i 0 nodes stateEvents [id] toggle "#1"
  

• ./veadotube -i 0 nodes stateEvents [id] clear