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:
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 SpectrumAnalyzerThe 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.
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).PROPERTIESlists the properties and their defaults. A property with adata_typeis also a property port (@gain).__init__()creates the ports. Keep it free of side effects; start slow work or connections inactivate()(below).- When a value arrives at the input port,
_on_inputis 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. Callnotify_node_updated()at the end, and the engine saves the change tograph.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").
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:
"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:
{ "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.
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()afterdispatch()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:
"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
- Your own web UI: drive Gain and Counter from a page.
- nonoha-engine's AGENTS.md collects the rules for writing nodes.