Signalflow

project file format · version 4

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.

Contents

  1. What stays compatible
  2. A first file
  3. The top level
  4. Ids
  5. meta
  6. library: symbols
  7. Ports
  8. Built-in symbols and their port ids
  9. Sheets
  10. Devices
  11. Cables
  12. Text notes and zones
  13. Pictures
  14. VLANs
  15. Drawing conventions
  16. Racks and accessories
  17. What the app does with a file
  18. Version history

1. What stays compatible

2. A first file

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.

3. The top level

KeyTypeWhen it is missing
versionnumberNot read. Write 4.
metaobjectThe drawing keeps the title block it had before the file was opened. Write it. See meta.
libraryarray of symbolsThe built-ins only. Write your own symbols here; [] is fine.
sheetsarray of sheetsOne empty sheet called SHEET 1.
activenumberThe 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.
vlansarrayThis machine's saved VLAN scheme, if there is one. See VLANs.
stylesobjectThe standard drawing conventions. See Drawing conventions.
focusarray of signal kindsNo ghosting. With kinds listed, the drawing opens showing only those, the rest faded.
racksarrayNo racks. See Racks.
imageDataobjectNo 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.

4. Ids

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.

The app does not repair duplicate ids. Two devices with one id make it pick one of them for every cable.

5. meta: the project and its title block

KeyTypeMeaning
projectstringRequired when meta is written. The project name in the title block and in every file name.
drawnBystringThe title block's DRAWN BY.
revstring, ≤8The revision (2.0.11).
statusstring, ≤32The 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.
pageobject or absentThe paper. Absent or null = no page frame. See below.
units"ft" or absentShows cable lengths in feet. Lengths are always stored in metres.
logodata URLA 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.
logoSizenumber, 24–180The 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.

The paper: meta.page

Each sheet then has its own frame on that paper. See Sheets.

6. library: symbols

A symbol is a kind of device: its name, size and ports. A device on a sheet names its symbol by defId.

KeyTypeMeaning
idstringRequired. Unique in the library. Avoid the built-ins' ids unless you mean to replace one.
namestring, ≤36Required. Drawn in capitals in the symbol header. A make and model, e.g. "BARCO E2 GEN 2".
portsarray of portsRequired (it may be empty). See Ports.
widthnumberThe symbol's width in canvas units. The editors keep it between 130 and 280. Default 160.
categorystringThe 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.
classstringThe 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.
revintegerBumped by the app on every change to the symbol.
slots, cardsarraysA modular chassis. See below.
physobjectPhysical size and power, for the Racks tab. See below.

Modular symbols: slots and cards

Physical data: phys

7. Ports

KeyTypeMeaning
idstringUnique 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.
labelstring, ≤24Required. 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.
signalsignal kind"video", "fiber", "network", "audio", "control" or "power". Note the spelling fiber.
connstringThe connector, from the list below, or "".
gaptrueLeaves a gap above this port, to group ports.
vlan, tagged, trunk, lagstring, string[], true, string ≤8Network 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.
ipstringAn address on this port, for a device with more than one network port.
universe, protocoldigit string, "SACN" / "ART-NET"A DMX output's universe (no leading zeros): 1–63999, or 0–32767 for Art-Net.

Connectors, by signal kind

signalconn
videoHDMI, DP, 12G SDI, 6G SDI, 3G SDI, HD SDI, DVI, VGA, BNC, HD-BNC, RJ45, SFP+, SFP28, USB-C
fiberOPTICALCON DUO, OPTICALCON QUAD, LC, SC, SFP, SFP+, SFP28, QSFP+, QSFP28, SM FIBER, MM FIBER
networkRJ45, ETHERCON, SFP, SFP+, SFP28, QSFP+, QSFP28, RJ45 10G
audioXLR, 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
controlDMX 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
powerPOWERCON, 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.

8. Built-in symbols and their port ids

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], …],
    …
  }, … ] }

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.

9. Sheets

KeyTypeMeaning
idstringRequired. Unique.
namestringRequired. The sheet's tab. The app's own renaming stops at 18 characters; longer names load.
titlestring, ≤48The title block's DRAWING for this sheet (2.0.11). Without it, the sheet's name.
devicesarraySee Devices. Later entries draw on top.
linksarraySee Cables.
notesarrayText notes and zones. See Notes.
imagesarraySee 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.

10. Devices

KeyTypeMeaning
idstringRequired. Unique across the project.
defIdstringRequired. The symbol: a built-in's id, or one in the file's library.
x, ynumberRequired. The symbol's top-left corner. The app's grid is 8; nothing needs to sit on it.
labelstringThis device's name: PJ 1, MAIN SERVER. Without it, the symbol's name is shown.
ipstringThe device's address, shown under its name when the symbol has one network port.
host, mac, assetstringsHostname (≤253), MAC address as "AA:BB:CC:DD:EE:FF", asset number (≤32) (2.0.11). Listed in Lists > DEVICES.
slotsobjectA 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.
collapsedtrueDraws only the ports something is plugged into.
ifPatternstringA 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:

12. Text notes and zones

Both live in a sheet's notes:

13. Pictures

14. VLANs

Since 2.0.12 a subnet written as "192.168.10.0/24" is read as "192.168.10".

15. Drawing conventions: styles

KeyMeaning
sigLine 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.
hopsWhere cables cross: "none", "arc" or "gap".
textCase"typed" keeps names as written; absent = CAPITALS.
cableLabelsfalse turns off the small labels at each end of a cable (2.0.9).
fontThe 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.

16. Racks and accessories

racks is [{id, name, u, depth?, row?, col?, acc?}]:

acc lists the rack's accessories:

17. What the app does with a file

When it opens one

Soon after

When it saves

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.

18. Version history

File versionAppWhat came
31.xThe 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.
42.0.0racks and a device's rack place.
42.0.2–2.0.7phys.at / bays, cables to places off the drawing, rack accessories and their grid, patch panels.
42.0.8A1 and A0 paper (written as A2 + paper), a page frame's w.
42.0.9A cable's cable and len, meta.units, styles.cableLabels.
42.0.11A device's host, mac and asset; a sheet's title; meta.rev, status and revDate.
42.0.12No new keys. Missing ids and unworkable values are repaired on load (17). This page and the schema.