Writing nodes and plugins

A node is a plain Python class, and a plugin is a plain Python package of nodes. This page adds two nodes to the template's plugin, connects them in the graph, and runs them.

How a plugin is laid out

The template's plugin, user-nodes, is laid out like this:

Text
templates/default/plugins/
├── manifest.json            the plugins to enable
└── user-nodes/
    ├── pyproject.toml       the package's name and dependencies
    └── user_nodes/
        ├── __init__.py      registers the nodes in register_nodes(registry)
        └── nodes.py         Synthesizer and SpectrumAnalyzer

The folder's name uses hyphens (user-nodes) and the Python package's name underscores (user_nodes). When the engine starts, it loads the plugins that manifest.json enables and calls their register_nodes.

Plugins are loaded from source, and the dependencies in their pyproject.toml are not installed for you. The libraries a plugin uses must be in the engine's environment, which has NumPy and SciPy. To use another library, run uv add <package> in the engine's folder.

A node that takes values and sends them on

Write a node that multiplies a signal by a gain, in templates/default/plugins/user-nodes/user_nodes/gain.py.

Python
import numpy as np

from nonoha_core.data_type import DataType, PortValueType, PropertyDataType
from nonoha_core.node import BaseNode, NodeDoc
from nonoha_core.port import StaticTypeInputPort, StaticTypeOutputPort


class GainNode(BaseNode):
    @classmethod
    def describe(cls, properties=None):
        return NodeDoc(
            description="Multiplies a signal by a gain",
            category="Custom",
            inputs={"in": "Samples"},
            outputs={"out": "The samples times the gain"},
        )

    PROPERTIES = {
        "gain": {"description": "The factor to multiply by", "default_value": 0.5, "data_type": "f64"},
    }

    def __init__(self, name: str):
        super().__init__(name, "Gain")
        samples = PortValueType(DataType.Float32)
        self._input = StaticTypeInputPort("in", [samples])
        self._input.subscribe(id(self), self._on_input)
        self.inputs[self._input.name] = self._input
        self._output = StaticTypeOutputPort("out", [samples])
        self.outputs[self._output.name] = self._output

    def _on_input(self, values: list[np.ndarray]):
        # values[0]: a batch of samples, shape (batch,)
        self._output.dispatch([values[0] * np.float32(self.properties["gain"])])

    def set_properties(self, properties: dict[str, PropertyDataType]):
        if "gain" in properties:
            self.properties["gain"] = float(properties["gain"])
        if self.parent_graph is not None:
            self.parent_graph.notify_node_updated(self)
  • describe() returns the description shown in the list of nodes (the catalog).
  • PROPERTIES lists the properties and their defaults. A property with a data_type is also a property port (@gain).
  • __init__() creates the ports. Keep it free of side effects; start slow work or connections in activate() (below).
  • When a value arrives at the input port, _on_input is called. values[0] is a NumPy array with the batch dimension; for this port's type (f32) its shape is (batch,).
  • dispatch() sends an array to the output port, also with the batch dimension.
  • set_properties() is called when the graph loads, and when a property changes from the editor, the API, or a property port. Call notify_node_updated() at the end, and the engine saves the change to graph.json.

Register it

Add the node in register_nodes in user_nodes/__init__.py (an excerpt). The name you give register_node must match the one in super().__init__(name, "Gain").

Python
from .gain import GainNode


def register_nodes(registry: NodeRegistry):
    registry.register_node("Synthesizer", SynthesizerNode)
    registry.register_node("SpectrumAnalyzer", SpectrumAnalyzerNode)
    registry.register_node("Gain", GainNode)

Connect it in the graph

Stop the engine, then edit templates/default/flows/default.vnf/graphs/app.vng/graph.json. Add Gain to nodes:

JSON
"Gain_1": { "type": "Gain", "properties": { "gain": 0.5 } }

In edges, remove { "source": "Synthesizer_1.waveform", "target": ".waveform" }, which sends Synthesizer's waveform straight out, and add two edges that go through Gain:

JSON
{ "source": "Synthesizer_1.waveform", "target": "Gain_1.in" },
{ "source": "Gain_1.out", "target": ".waveform" }

Start the engine again, and the app's WAVEFORM panel shows half the amplitude. Gain also appears in the list of nodes (the catalog command, or /node-flow/catalog/nodes), with the input port in and the property port @gain.

A node that sends values on its own

This node doesn't wait for input: it sends a value at a regular interval. Write it in user_nodes/counter.py and add it to register_nodes the same way as Gain.

Python
import asyncio

import numpy as np

from nonoha_core.data_type import DataType, PortValueType, PropertyDataType
from nonoha_core.node import BaseNode, NodeDoc
from nonoha_core.port import StaticTypeOutputPort


class CounterNode(BaseNode):
    @classmethod
    def describe(cls, properties=None):
        return NodeDoc(
            description="Counts up at a regular interval",
            category="Custom",
            outputs={"count": "The current count"},
        )

    PROPERTIES = {
        "interval": {"description": "Seconds between counts", "default_value": 1.0, "data_type": "f64"},
    }

    def __init__(self, name: str):
        super().__init__(name, "Counter")
        self._output = StaticTypeOutputPort("count", [PortValueType(DataType.Float32)])
        self.outputs[self._output.name] = self._output
        self._count = 0
        self._task: asyncio.Task | None = None

    def activate(self):
        # The graph is running: start counting on its event loop
        self._task = asyncio.get_running_loop().create_task(self._count_up())

    async def _count_up(self):
        while True:
            await asyncio.sleep(self.properties["interval"])
            self._count += 1
            self._output.dispatch([np.array([self._count], dtype=np.float32)])
            # Nothing else sends what a timer dispatches: send it on now
            if self.parent_graph is not None:
                self.parent_graph.flush_outputs()

    def finalize(self):
        # The node is removed or the engine stops
        if self._task is not None:
            self._task.cancel()
            self._task = None

    def set_properties(self, properties: dict[str, PropertyDataType]):
        if "interval" in properties:
            self.properties["interval"] = float(properties["interval"])
        if self.parent_graph is not None:
            self.parent_graph.notify_node_updated(self)
  • activate() is called when the node is added to a running graph. It creates a task on the engine's event loop.
  • finalize() is called when the node is removed or the engine stops. It stops the task it started.
  • Values a node sends in response to an input are sent on by whatever sent that input. Values a node sends on its own schedule, such as a timer's, need flush_outputs() after dispatch() to go out right away.

Stop the engine, then add the node, a graph output port count, and the edge between them to the graph:

JSON
"nodes": { "Counter_1": { "type": "Counter", "properties": { "interval": 0.5 } } },
"outputs": { "count": { "types": ["f32"] } },
"edges": [{ "source": "Counter_1.count", "target": ".count" }]

These are only the parts to add: keep the nodes, outputs, and edges that are there. Your own web UI shows this output on a page.

Mind the shape of arrays

The arrays you send have the output port's type with the batch dimension in front: (batch,) for an f32 output port, (batch, N) for an f32[N] output port. On an f32[N] output port, when one computation makes one result of length N, add the batch dimension with result[np.newaxis] before you send it. Concepts lists the port types.

What to read next