A SignalFlow project is one JSON file, <name>.signalflow.json. This page describes it for anyone who
writes drawings from a script: an equipment database, a patch list, a spreadsheet. It covers every key the app reads, what the
app fills in for you, and what will stay compatible. It describes SignalFlow 2.0.12 and later. A
JSON Schema sits next to it, and builtins.json lists
every built-in symbol with its port ids.
"version": 4. A change that would make a 2.x
file mean something different, or would stop an older 2.x build reading a newer file, waits for SignalFlow 3.0 and
"version": 5.meta, sheets, devices and cables pass
through its load and its save untouched."version": 4, but do not rely on it. The app reads a file by the keys it finds and refuses no file
for its version number. A version 3 file from SignalFlow 1.x opens too.A laptop sending HDMI to a projector, both on a switch, on one sheet. Every symbol here is built in, so the library is empty: the app supplies its own built-ins by their ids. Cable numbers, routes and the sheet's page frame are left for the app to fill in.
{
"version": 4,
"meta": { "project": "CONFERENCE ROOM", "drawnBy": "SCRIPT" },
"library": [],
"sheets": [{
"id": "s1", "name": "ROOM",
"devices": [
{ "id": "d-laptop", "defId": "pc-generic-laptop", "label": "PRESENTER", "x": 80, "y": 80 },
{ "id": "d-pj", "defId": "epson", "label": "PJ 1", "x": 480, "y": 80, "ip": "10.0.10.21" },
{ "id": "d-sw", "defId": "switch8", "label": "ROOM SWITCH", "x": 480, "y": 264 }
],
"links": [
{ "id": "l1", "a": { "dev": "d-laptop", "port": "p1" }, "b": { "dev": "d-pj", "port": "p0" }, "signal": "video" },
{ "id": "l2", "a": { "dev": "d-laptop", "port": "p3" }, "b": { "dev": "d-sw", "port": "p0" }, "signal": "network" },
{ "id": "l3", "a": { "dev": "d-pj", "port": "p1" }, "b": { "dev": "d-sw", "port": "p1" }, "signal": "network" }
]
}]
}
p1 on the laptop is its HDMI OUT and p0 on the projector its HDMI IN. Those ids come from
builtins.json. Open the file with File > Open in the app, or put it on a web server and open
https://mattvillis.github.io/signalflow/?open=<its url>. The server must allow cross-origin requests.
| Key | Type | When it is missing |
|---|---|---|
version | number | Not read. Write 4. |
meta | object | The drawing keeps the title block it had before the file was opened. Write it. See meta. |
library | array of symbols | The built-ins only. Write your own symbols here; [] is fine. |
sheets | array of sheets | One empty sheet called SHEET 1. |
active | number | The first sheet. This is the index of the sheet that opens. |
view | {x, y, k} | The view does not move. Screen = canvas × k + (x, y); k is the zoom, from 0.25 to 3. |
vlans | array | This machine's saved VLAN scheme, if there is one. See VLANs. |
styles | object | The standard drawing conventions. See Drawing conventions. |
focus | array of signal kinds | No ghosting. With kinds listed, the drawing opens showing only those, the rest faded. |
racks | array | No racks. See Racks. |
imageData | object | No pictures. See Pictures. |
Unknown top-level keys are ignored. Write the file as UTF-8. Coordinates are canvas units: at 100% a canvas unit is one screen pixel, and on a page frame 3 units are 1 mm of paper. y grows downwards.
An id is any string. The app's own ids look like d1xk2f3a: a prefix, then base-36 time and a counter. Nothing
reads that pattern, and the app does not re-key a file's ids.
num unique.The app does not repair duplicate ids. Two devices with one id make it pick one of them for every cable.
| Key | Type | Meaning |
|---|---|---|
project | string | Required when meta is written. The project name in the title block and in every file name. |
drawnBy | string | The title block's DRAWN BY. |
rev | string, ≤8 | The revision (2.0.11). |
status | string, ≤32 | The title block's STATUS (2.0.11). The app offers PRELIMINARY, FOR COMMENT, FOR CONSTRUCTION and AS BUILT; any text is allowed. |
revDate | "YYYY-MM-DD" | The title block's DATE (2.0.11). Without it, DATE is the day of the export. |
page | object or absent | The paper. Absent or null = no page frame. See below. |
units | "ft" or absent | Shows cable lengths in feet. Lengths are always stored in metres. |
logo | data URL | A client logo in the title block: PNG, JPEG or SVG as a data: URL. Keep it small: about 520 × 200 pixels is what the app stores. |
logoPos | "top", "left", "right" | Where the logo sits; default top. |
logoSize | number, 24–180 | The strip's height (top) or the column's width (left, right), in title-block units. Default 40 for top, 90 for left and right. |
logoAlign | "start", "center", "end" | For a top logo; default center. |
size: "A4", "A3" or "A2". A1 and A0 are written as
{"size": "A2", "paper": "A1"} and {"size": "A2", "paper": "A0"}, so a build from before 2.0.8 can still open
the file; it prints them scaled onto A2.orient: "portrait", or absent for landscape.Each sheet then has its own frame on that paper. See Sheets.
A symbol is a kind of device: its name, size and ports. A device on a sheet names its symbol by defId.
defId is neither built in nor in the file's library is
dropped when the file opens, with a note saying how many.| Key | Type | Meaning |
|---|---|---|
id | string | Required. Unique in the library. Avoid the built-ins' ids unless you mean to replace one. |
name | string, ≤36 | Required. Drawn in capitals in the symbol header. A make and model, e.g. "BARCO E2 GEN 2". |
ports | array of ports | Required (it may be empty). See Ports. |
width | number | The symbol's width in canvas units. The editors keep it between 130 and 280. Default 160. |
category | string | The library sidebar's folder. Default Custom. The built-in categories are Servers, Computers, Processing, LED, Extenders, KVM, Display, Cameras, Network, Audio, Control, Lighting, Power and Custom; any other name makes a new one. Network also turns off auto-IP for the device and offers the switch's CLI port pattern. |
class | string | The department in the sidebar's class filter: video, audio, lighting, network, control or power. Without it the class comes from the category, then from the ports. |
rev | integer | Bumped by the app on every change to the symbol. |
slots, cards | arrays | A modular chassis. See below. |
phys | object | Physical size and power, for the Racks tab. See below. |
slots: [{id, label, accepts, card}].
accepts is "in", "out", "link", "aux" or "any", or an array of those.card is the card fitted by default, by card id, or null for an empty slot.cards: [{id, name, kind, ports}].
kind is one of the accepts values.ports is a list like a symbol's.<slot id>.<card port id>,
then the chassis's own ports.mount: "rack", "shelf" or "none".ru is 1–60, and width is "full", "half", "third"
or "quarter".mm is {w, h, d} in millimetres; kg is a number; watts and
btu are whole numbers.at is {<port id>: ["f"|"r", x, y]}, with x and y in
percent of that face as seen looking at it. A card's bay goes in bays: {<slot id>: ["f"|"r", x, y, width]}.| Key | Type | Meaning |
|---|---|---|
id | string | Unique on the symbol. On a library symbol it may be left out: the app numbers ports p0, p1 … in list order. On a device's override give every port its id; since 2.0.12 one without is numbered the same way. |
label | string, ≤24 | Required. Drawn as written; the app's editors write capitals. |
side | "left", "right" | Required. Which side of the symbol. Each side lists its ports top to bottom in array order. Before 2.0.12 any other value stopped the drawing; it now reads as left. |
dir | "in", "out", "bi" | Signal direction; default bi. Sets the arrowheads and what may be cabled to what. |
signal | signal kind | "video", "fiber", "network", "audio", "control" or "power". Note the spelling fiber. |
conn | string | The connector, from the list below, or "". |
gap | true | Leaves a gap above this port, to group ports. |
vlan, tagged, trunk, lag | string, string[], true, string ≤8 | Network and fibre ports only. vlan is the untagged VLAN (a trunk's native) by its number. tagged lists VLAN numbers carried tagged. trunk marks a trunk. Ports sharing a lag label are one aggregated link. |
ip | string | An address on this port, for a device with more than one network port. |
universe, protocol | digit string, "SACN" / "ART-NET" | A DMX output's universe (no leading zeros): 1–63999, or 0–32767 for Art-Net. |
| signal | conn |
|---|---|
video | HDMI, DP, 12G SDI, 6G SDI, 3G SDI, HD SDI, DVI, VGA, BNC, HD-BNC, RJ45, SFP+, SFP28, USB-C |
fiber | OPTICALCON DUO, OPTICALCON QUAD, LC, SC, SFP, SFP+, SFP28, QSFP+, QSFP28, SM FIBER, MM FIBER |
network | RJ45, ETHERCON, SFP, SFP+, SFP28, QSFP+, QSFP28, RJ45 10G |
audio | XLR, TRS, AES3, MADI, ANALOG, SPDIF, DIN 1.0/2.3, RJ45, ETHERCON, USB-A, USB-B, USB-C, NL4, NL8, CA-COM, PA-COM, SC32, SPEAKER TERMINAL, TERMINAL, AES50, ULTRANET, RJ45 AUDIO, TOSLINK, ANTENNA, BNC, DB25, RCA, 3.5MM |
control | DMX 5PIN, DMX 3PIN, DMX RJ45, DMX TERMINAL, RS-232, GPIO, MIDI, LTC, XLR, BNC, D-SUB 9, D-SUB 15, D-SUB 26, TRS, CAN, USB-A, USB-B, USB-C, OCULINK |
power | POWERCON, POWERCON 32A, TRUE1, IEC C13, IEC C14, IEC C19, IEC C20, DC, XLR 4-PIN, USB-C, CEE 16A 1P, CEE 32A 1P, CEE 16A 3P, CEE 32A 3P, CEE 63A 3P, CEE 125A 3P, SOCAPEX, POWERLOCK, CAMLOK, SCHUKO |
Another connector name loads and is drawn, but the editor will refuse to cable it to any different connector. A new release may add connectors to these lists; it will not take one away.
builtins.json lists every built-in symbol of the current release:
{ "version": "2.0.12",
"symbols": [ {
"id": "epson", "name": "EPSON PROJECTOR", "category": "Display", "width": 160, "ports": 3,
"ids": ["p0", "p1", "p2"],
"list": [["HDMI IN", "left", "in", "video", "HDMI", 0, -1], ["LAN", "left", "bi", "network", "RJ45", 0, -1], …],
…
}, … ] }
ids and list: the symbol's ports with its default cards fitted, in the order the app expands them.
ids[i] is the id of the port list[i] describes. Each list entry is
[label, side, dir, signal, conn, gap, group].slots, [[id, label, accepts, default card id], …], and cards,
[{id, name, kind, ports: [[id, label, side, dir, signal, conn], …]}]. They let a script fit other cards and work out
their port ids.Take port ids from builtins.json rather than counting. Most built-ins number their ports p0, p1 …
in order, but card ports are <slot>.<port> and come first, and a few symbols name their own ports (the grandMA3
desks, so that cables on older drawings stay put). A port id on a built-in is not changed in a later release.
| Key | Type | Meaning |
|---|---|---|
id | string | Required. Unique. |
name | string | Required. The sheet's tab. The app's own renaming stops at 18 characters; longer names load. |
title | string, ≤48 | The title block's DRAWING for this sheet (2.0.11). Without it, the sheet's name. |
devices | array | See Devices. Later entries draw on top. |
links | array | See Cables. |
notes | array | Text notes and zones. See Notes. |
images | array | See Pictures. |
page | {x, y, w?} | The page frame: its top-left corner in canvas units and its width (none = the paper at 100%, 3 units a millimetre). Leave it out and the app places it round the drawing the first time the sheet is shown with a paper size set. |
| Key | Type | Meaning |
|---|---|---|
id | string | Required. Unique across the project. |
defId | string | Required. The symbol: a built-in's id, or one in the file's library. |
x, y | number | Required. The symbol's top-left corner. The app's grid is 8; nothing needs to sit on it. |
label | string | This device's name: PJ 1, MAIN SERVER. Without it, the symbol's name is shown. |
ip | string | The device's address, shown under its name when the symbol has one network port. |
host, mac, asset | strings | Hostname (≤253), MAC address as "AA:BB:CC:DD:EE:FF", asset number (≤32) (2.0.11). Listed in Lists > DEVICES. |
slots | object | A modular device's cards: {<slot id>: <card id> | null}. A slot not named keeps its default card. |
override | {width?, ports} | This device's own port list, replacing its symbol's. ports is the complete, expanded list. Keep the symbol's port ids for the ports it shares with it. |
collapsed | true | Draws only the ports something is plugged into. |
ifPattern | string | A Network symbol's port names on its own CLI, with {n} counting its network ports, e.g. "1/0/{n}". |
rack | {id, u, x, rear?} | Its place in a rack. u is the lowest unit it fills, 1 = the bottom. x is millimetres from the left of the 450 mm opening, seen from the front. rear: true faces it to the back. The rack must be in racks. |
Two kinds of device are made by the app and are best left to it:
external: the hidden far end of a cable to a place off the drawing.patchpanel: the symbol of a patch panel in a rack. Write the panel as a rack accessory and the app
makes its symbol.| Key | Type | Meaning |
|---|---|---|
id | string | Required. Unique across the project. |
a, b | {dev, port} | Required. The two ends, by device and port id. The arrow is drawn at b, so write it as source → destination. |
signal | signal kind | Required. What the cable carries, which sets its line style. Usually end a's port signal. |
mode | "auto", "manual", "flag" | Default auto (the app routes it). manual runs through pts. flag draws no line, only a flag at each end naming the other. |
pts | [{x, y}] | The waypoints of a manual route. |
off | number | A nudge, in canvas units, of an auto route's middle run. |
no | whole number ≥1 | The cable number (C001). Leave it out: the app numbers new cables and keeps numbers it is given. |
cable | string, ≤40 | The cable type as ordered: CAT6A, 12G SDI, OM3 LC–LC (2.0.9). |
len | number | Its length in metres, whatever the project shows (2.0.9). |
Store it on the sheet of end a. Give end b the far sheet's id, as in
"b": {"dev": "d-pj", "port": "p0", "sheet": "s2"}, and use "mode": "flag". It is drawn as a flag on each sheet. The
file keeps it only when b.dev really is on that sheet, and it is not this one.
The editor refuses some cables: a second cable on a port (except a breakout DAC's trunk), an output into an output, and connectors that do not mate without a converter. The loader checks none of this, so a file can hold cables the editor would refuse. A cable is dropped on load only when a device it names is not on its sheet. A cable to a port the device does not have is kept, but not drawn.
Both live in a sheet's notes:
{id, type: "text", x, y, text, color?, fs?}. text may hold line breaks (\n).{id, type: "box", x, y, w, h, text, color?, fs?}, with the title as
text.color is #RRGGBB, default #1A1A18. fs is the text size, 8–36.
text is required; since 2.0.12 a note without it is read as empty.images is [{id, img, x, y, w, h, name?, op?, lock?, front?}].
img names a picture in the project's imageData, so one picture can be placed many times.op is the opacity, 0.05 to below 1.lock: true stops it being moved. front: true draws it over the cables instead of under them.imageData is {<img>: {data, w, h}}.
im and then 4–40 lower-case letters or digits.data is a PNG or JPEG data: URL, up to 8 million characters.vlans is [{num, name, color, subnet?, start?}].num: a string, e.g. "10". Ports name a VLAN by it.name is up to 16 characters, and color is #RRGGBB.subnet: the network's first three numbers, e.g. "192.168.10". The app numbers devices in it from
start (1–254, default 10).Since 2.0.12 a subnet written as "192.168.10.0/24" is read as "192.168.10".
| Key | Meaning |
|---|---|
sig | Line styles that differ from the standard ones: {<key>: {c, dash, w, label}}. A key is a signal kind, a video connector (12G SDI, 6G SDI, 3G SDI, HD SDI, HDMI, DP, DVI) or a group (SPEAKER, RF, DMX, TIMECODE). c is #RRGGBB. dash is an SVG dash pattern such as "6 3", or "". w is the line width, 0.5–5. label is the legend's name for it. |
hops | Where cables cross: "none", "arc" or "gap". |
textCase | "typed" keeps names as written; absent = CAPITALS. |
cableLabels | false turns off the small labels at each end of a cable (2.0.9). |
font | The drawing's fonts: {text?, head?}, each {family, src: "free" | "file"}. free names a font on Fontsource. file names one installed on a machine, which other machines will not have. |
racks is [{id, name, u, depth?, row?, col?, acc?}]:
u is its height in units (1–60, default 42) and depth its depth in millimetres (default 800).row and col place it in the Racks tab's grid. Without them, racks stand in one row in list order.rack key (Devices).acc lists the rack's accessories:
{id, kind, u, h, face, label?}.
kind is blank, brush, fan, drawer or patch.u is its lowest unit and h its height in units.face is the rails it is on: "f" or "r".depth (mm), and a fan panel takes fans (1–12).rows (1–6), cols (1–48) and ports.
ports is [{c, l?, m?}] in reading order: c is a connector, l a label, and
m: true makes an XLR male.mode and pts are filled in.override without a port list is dropped;active is kept in range;Everything is written in full: every key above, and the whole library, built-ins included. A file the app has saved is a good example of anything this page leaves unclear.
| File version | App | What came |
|---|---|---|
| 3 | 1.x | The format at the start of the repository (September 2026): meta, library, several sheets, active, view, vlans; later styles, focus, pictures. Older files used customDefs for the library and top-level devices and links for one sheet; both still open. |
| 4 | 2.0.0 | racks and a device's rack place. |
| 4 | 2.0.2–2.0.7 | phys.at / bays, cables to places off the drawing, rack accessories and their grid, patch panels. |
| 4 | 2.0.8 | A1 and A0 paper (written as A2 + paper), a page frame's w. |
| 4 | 2.0.9 | A cable's cable and len, meta.units, styles.cableLabels. |
| 4 | 2.0.11 | A device's host, mac and asset; a sheet's title; meta.rev, status and revDate. |
| 4 | 2.0.12 | No new keys. Missing ids and unworkable values are repaired on load (17). This page and the schema. |