Graph Configuration Schema

A Switchboard audio setup can be described entirely in JSON: which engine renders the audio, which nodes make up the graph, and how those nodes are wired together. This page is the complete reference for that document.

Two shapes are accepted:

Engine configuration — an engine plus the graph it renders. Use this when the JSON should describe the whole setup, including audio I/O.
Bare graph — just the graph. Use this when your application creates the engine itself and only loads the graph from JSON.

A machine-readable version is available as a JSON Schema: download switchboard-graph-config.json.

For the related schemas that describe object instances and their static type descriptors, see Object Schema and Object Type Schema.

At a glance

{
  "type": "Switchboard.Realtime",
  "config": {
    "graph": {
      "nodes": [
        { "id": "player", "type": "Switchboard.AudioPlayer", "config": { "audioFilePath": "@system/music.wav" } },
        { "id": "gain",   "type": "Switchboard.Gain",        "properties": { "gain": 0.5 } }
      ],
      "connections": [
        { "sourceNode": "player", "destinationNode": "gain" },
        { "sourceNode": "gain",   "destinationNode": "outputNode" }
      ]
    }
  }
}

Level	Required	Optional
Engine	`type`	`id`, `config`, `properties`
Graph	—	`nodes`, `connections`, `dataConnections`, graph parameters
Node	`type`	`id`, `config`, `properties`
Connection	`sourceNode`, `destinationNode`	`sourceBusIndex`, `destinationBusIndex`

`config` and `configuration`

config and configuration are accepted interchangeably wherever this page uses config. Prefer config — it is the form used throughout the SDK's own examples.

Engine configuration

`type`

Required. Selects the engine.

Engine	Canonical value	Also accepted	Availability
Realtime	`Switchboard.Realtime`	`Realtime`	macOS, Windows, Linux, iOS, Android
Offline	`Switchboard.Offline`	`Offline`	All platforms except Web and embedded targets
Manual	`Switchboard.Manual`	`Manual`	All platforms except Web
WebSocket	`Switchboard.WebSocket`	`WebSocket`	Builds with the WebSocket engine enabled

`id`

Optional identifier for the engine. Generated automatically when omitted.

`config`

Engine parameters. Every engine accepts graph; the remaining keys vary by engine and are listed below.

`properties`

Runtime properties applied after the engine is constructed. graph may be supplied here instead of under config.

Realtime engine

Renders a graph against the platform's live audio I/O.

Key	Type	Default	Description
`graph`	`object`	—	The audio graph to render.
`defaultStreamParameters`	`object`	—	Requested characteristics of the system audio stream. See below.
`microphoneEnabled`	`boolean`	`false`	Android only. Opens the audio input stream. Ignored elsewhere.

`defaultStreamParameters`

Every field is a request. The platform may open a stream that differs, so read back the actual values after starting rather than assuming these took effect.

Key	Type	Default	Description
`selectedInputDevice`	`object`	—	Input device to open. See Audio device.
`selectedOutputDevice`	`object`	—	Output device to open. See Audio device.
`numberOfInputChannels`	`integer`	`0`	Requested input channel count. `0` accepts the device's own channel count.
`numberOfOutputChannels`	`integer`	`0`	Requested output channel count. `0` accepts the device's own channel count.
`preferredBufferSize`	`integer`	`0`	Requested I/O buffer size in frames. `0` accepts the platform default.
`preferredSampleRate`	`integer`	`0`	Requested sample rate in Hz. `0` accepts the platform default.

Output channels beyond stereo

A Realtime engine opens the device with its default channel count. To drive more than two output channels — a multi-output interface, or a surround device — set numberOfOutputChannels explicitly. The graph must also produce that many channels: raise the graph's maxNumberOfChannels to match, or the extra channels will be silent.

{
  "type": "Switchboard.Realtime",
  "config": {
    "defaultStreamParameters": {
      "selectedOutputDevice": { "id": 135 },
      "numberOfOutputChannels": 4
    },
    "graph": {
      "maxNumberOfChannels": 4,
      "nodes": [ { "id": "generator", "type": "Switchboard.SineGenerator" } ],
      "connections": [ { "sourceNode": "generator", "destinationNode": "outputNode" } ]
    }
  }
}

Audio device

In a written configuration you normally supply only id. The remaining fields are populated by the SDK when it reports available devices back to you.

Key	Type	Description
`id`	`integer`	Platform device identifier.
`name`	`string`	Human-readable device name.
`inputChannels`	`integer`	Input channels the device provides.
`outputChannels`	`integer`	Output channels the device provides.
`isDefaultInput`	`boolean`	Whether this is the system default input.
`isDefaultOutput`	`boolean`	Whether this is the system default output.
`sampleRates`	`array`	Sample rates the device supports.
`currentSampleRate`	`integer`	Sample rate the device is running at.
`preferredSampleRate`	`integer`	Sample rate the device prefers.

caution

Device IDs are assigned by the operating system and are not stable across reboots or device hot-plugs. Hard-coding one makes a configuration non-portable; enumerate devices at runtime and match on name instead.

Offline engine

Renders a graph faster than real time, reading from and writing to audio files.

Key	Type	Default	Description
`graph`	`object`	—	The audio graph to render.
`inputFiles`	`array`	`[]`	Files fed into the graph's input node, in bus order.
`outputFiles`	`array`	`[]`	Files written from the graph's output node, in bus order.
`sampleRate`	`integer`	`0`	Sample rate of the render, in Hz. `0` derives it from the input files.
`bufferDurationMs`	`integer`	`10`	Duration of one render block, in milliseconds.
`maxNumberOfSecondsToRender`	`number`	`0`	Upper bound on render length. `0` renders until the inputs are exhausted.

Each entry in inputFiles and outputFiles is an object:

Key	Type	Default	Description
`filePath`	`string`	—	Required. Path to the file. Supports SDK path prefixes.
`codec`	`string`	`wav`	Container/codec of the file.
`numberOfChannels`	`integer`	`2`	Channel count of the file.
`sampleRate`	`integer`	`0`	Sample rate of the file in Hz. `0` leaves it undefined.

{
  "type": "Switchboard.Offline",
  "config": {
    "inputFiles":  [ { "filePath": "@system/input.wav" } ],
    "outputFiles": [ { "filePath": "@system/output.wav" } ],
    "graph": {
      "nodes": [ { "id": "gain", "type": "Switchboard.Gain", "properties": { "gain": 0.5 } } ],
      "connections": [
        { "sourceNode": "inputNode", "destinationNode": "gain" },
        { "sourceNode": "gain",      "destinationNode": "outputNode" }
      ]
    }
  }
}

Manual engine

Renders a graph only when the host asks for audio. The host owns the clock.

Key	Type	Default	Description
`graph`	`object`	—	The audio graph to render.

WebSocket engine

Renders a graph over a WebSocket transport.

Key	Type	Default	Description
`graph`	`object`	—	The audio graph to render.
`port`	`integer`	—	TCP port the engine listens on.
`sampleRate`	`integer`	—	Sample rate of the transported audio, in Hz.

The graph object

The graph holds the nodes and the wiring between them, plus parameters that size its internal buffers.

Key	Type	Default	Description
`nodes`	`array`	`[]`	Nodes belonging to the graph.
`connections`	`array`	`[]`	Audio bus connections between nodes.
`dataConnections`	`array`	`[]`	Event/data connections between node ports.
`maxNumberOfChannels`	`integer`	`2`	Maximum channels per internal audio bus. Sizes the pre-allocated buffer pool; must be at least as wide as the widest bus the graph produces.
`maxNumberOfFrames`	`integer`	`48000`	Maximum frames per internal audio bus. Must be at least the largest per-call frame count the graph processes.
`sampleRate`	`integer`	`0`	Fixed processing sample rate. `0` runs the graph at the caller's sample rate and creates no resampler.
`bufferSize`	`integer`	`512`	Fixed processing buffer size. Only applies when `sampleRate` is non-zero.
`numberOfInputs`	`integer`	`1`	Number of buses on the graph's implicit input node.
`numberOfOutputs`	`integer`	`1`	Number of buses on the graph's implicit output node.

Graph parameters may also be placed in a nested config block, which some of the SDK's examples do:

{
  "graph": {
    "config": { "sampleRate": 16000, "bufferSize": 512 },
    "nodes": [],
    "connections": []
  }
}

Both forms are equivalent. If the same key appears in both places, the outer value wins.

Implicit input and output nodes

Every graph has two nodes that already exist and must not be listed in nodes:

inputNode — carries audio into the graph
outputNode — carries audio out of the graph

Refer to them by those IDs in connections. Declaring a node with either ID, or with type Switchboard.InputNode or Switchboard.OutputNode, is an error.

Nodes

Key	Type	Description
`type`	`string`	Required. Fully-qualified node type, e.g. `Switchboard.AudioPlayer` or `Superpowered.Reverb`.
`id`	`string`	Identifier within the graph, referenced by connections.
`config`	`object`	Construction-time parameters. Applied while the node is being created.
`properties`	`object`	Runtime properties. Applied by assignment once the node exists.

The keys accepted inside config and properties are defined per node type. See the node reference for each type's parameters.

note

id is optional, but a node without one is assigned a generated ID and cannot be named in connections — so in practice every node you intend to wire up needs an explicit id.

`config` vs. `properties`

These are not aliases. config values are passed to the node's constructor, so they can influence how the node is built — buffer sizes, channel counts, file paths opened at construction. properties are applied afterwards through the same mechanism used at runtime, so they can be changed again later while the graph is running.

When a parameter appears in both lists for a node type, prefer config if it must be correct before the first audio block is processed, and properties if you also intend to change it later.

If a node type is unqualified — Gain rather than Switchboard.Gain — it is matched against every registered node factory in turn, and the first match wins. Qualify node types to keep a configuration unambiguous as extensions are added.

Connections

An audio connection carries audio from one node's output bus to another node's input bus.

Key	Type	Description
`sourceNode`	`string`	Required. ID of the source node.
`destinationNode`	`string`	Required. ID of the destination node.
`sourceBusIndex`	`integer`	Zero-based output bus on the source node. Defaults to the first unused output bus.
`destinationBusIndex`	`integer`	Zero-based input bus on the destination node. Defaults to the first unused input bus.

{ "sourceNode": "player", "destinationNode": "mixer", "destinationBusIndex": 1 }

Connecting one output bus to several destinations is allowed and splits the signal. Connecting two sources to the same destination bus is not — use a mixer node instead.

caution

The bus fields are named sourceBusIndex and destinationBusIndex. sourceBus and destinationBus are not recognised: a connection using those names is accepted without complaint and silently falls back to automatic bus assignment, which usually is not what was intended.

Data connections

Data connections carry events and values rather than audio, from a named output port on one node to a named input port on another.

Key	Type	Description
`source`	`string`	Required. Source port, as `nodeID.outputName`.
`destination`	`string`	Required. Destination port, as `nodeID.inputName`.

{
  "dataConnections": [
    { "source": "vad.speechStarted", "destination": "recorder.start" }
  ]
}

A data connection can also be written inside connections by using the dotted nodeID.portName form in sourceNode and destinationNode. Any entry whose sourceNode contains a . is treated as a data connection rather than an audio connection. Prefer the explicit dataConnections array — the dotted form makes an audio-looking entry behave differently, which is easy to misread.

Validation

The downloadable schema is strict: it rejects keys that the SDK does not recognise, which mirrors the runtime's own behaviour of rejecting unknown configuration keys. This is deliberate — the most common configuration mistake is a misspelled or misremembered key that is otherwise silently ignored.

Two intentional gaps:

The keys inside a node's config and properties are defined by that node's type descriptor, not by this schema, so they are not constrained here.
Node types contributed by extensions are not enumerated, so type is validated as a string rather than against a fixed list.

Reference the schema from a configuration file to get validation and completion in editors that support it:

{
  "$schema": "https://docs.switchboard.audio/schemas/switchboard-graph-config.json",
  "type": "Switchboard.Realtime",
  "config": { "graph": { "nodes": [], "connections": [] } }
}

Full JSON Schema

Download switchboard-graph-config.json

At a glance​

config and configuration​

Engine configuration​

type​

id​

config​

properties​

Realtime engine​

defaultStreamParameters​

Output channels beyond stereo​

Audio device​

Offline engine​

Manual engine​

WebSocket engine​

The graph object​

Implicit input and output nodes​

Nodes​

config vs. properties​

Connections​

Data connections​

Validation​

Full JSON Schema​