Dot Hub JSON format

Summary

A Dot Hub file is a Glyph Museum file with two extra root blocks. Anything that reads one reads the other. If you implement nothing else, implement these five things:

1. Frames are the only required part. frames[].p holds LED brightness 0–255 in reading order; array length alone tells you the resolution.
2. Never fail an import over metadata. Parse frames first, metadata second. A broken block is an absent block.
3. Carry blocks you do not own through untouched. meta belongs to Glyph Museum and dotHubMeta to Dot Hub. Read them, write them back, never author them.
4. tools is the block that is yours. Append one entry for your own app; that is where you record what you did.
5. A stamp is not a credit. Only claim a user name on work your app actually created or edited.

Object model

One JSON object at the root. Five possible keys, of which one is required.

Structure at a glance

{
  "v":          number             // target matrix
  "frames":     [ { "p", "d" } ]   // required, ordered
  "meta":       { … }              // Glyph Museum's — carry it
  "dotHubMeta": { … }              // Dot Hub's — carry it
  "tools":      [ { … } ]          // yours — append yourself
}

A complete file, all blocks present

{
  "v": 4,
  "meta": { "author": "pauwma", "postId": 123 },
  "dotHubMeta": { "version": "1.1", "user": "paulg", "edited": true },
  "tools": [
    { "id": "app.glyphmuseum.com", "name": "Glyph Museum", "user": "pauwma", "created": true },
    { "id": "com.gesekus.dothub",  "name": "Dot Hub",      "user": "paulg",  "edited": true }
  ],
  "frames": [
    { "d": 100, "p": [0, 0, 80, 120, 255, …137 or 489 values] }
  ]
}

Field reference

Every element of the format. The your app column is the short answer to what to do with each block when you save a file.

Root object

frames[ ]

meta { }

Defined and written by Glyph Museum. Read these fields to display credit; never author the block yourself.

dotHubMeta { }

Written only by Dot Hub. Read it to know a file passed through Dot Hub and who worked on it there; carry it through unchanged when you re-save. Record your own involvement in tools instead.

tools[ ] { }

The block your app writes into. One entry per application, oldest first.

Limits

The p array

The Glyph Matrix is a circle cut out of a square grid, so p holds only the LEDs that physically exist. Each row is centred inside the grid. Index 0 is the start of the top row; values continue left to right, then down.

The form to write

13×13 rows, top to bottom: [5, 9, 11, 11, 13, 13, 13, 13, 13, 11, 11, 9, 5]. 25×25: [7, 11, 15, 17, 19, 21, 21, 23, 23, 25, 25, 25, 25, 25, 25, 25, 23, 23, 21, 21, 19, 17, 15, 11, 7].

Walking a flat p array back onto the grid

let i = 0;
for (let row = 0; row < gridSize; row++) {
  const leds = rowPattern[row];
  const colStart = (gridSize - leds) / 2;   // rows are centred
  for (let col = 0; col < leds; col++) {
    draw(colStart + col, row, p[i++]);
  }
}

Writing p

Always write the compact form. Dot Hub accepts the full square grid on read as a convenience, but a Glyph Museum reader does not — 169 or 625 values will not open there.

What your app needs to implement

Work down these until one stops describing your app. Each level assumes the ones above it.

// Read it, keep the original object, write it straight back.
// Including keys you do not recognise. Never build one yourself.
"meta": { "author": "pauwma", "postId": 123, "url": "…", …unknown keys… }

"tools": [
  // …every entry that was already there, unknown keys intact…
  {
    "id":      "com.yourcompany.yourapp",   // package name, or your site's host
    "name":    "Your App",
    "user":    "their handle",              // only with created or edited
    "created": true                         // or "edited": true, or neither
  }
]

The tools chain

meta and dotHubMeta answer who made this. tools answers what it was made with, and is explicitly allowed to grow as a design travels between apps.

The merge rule

When you write a file, append an entry for yourself. If the newest entry is already your id with a compatible user — equal, or one of the two absent, in which case the absent one is filled in — merge your flags into it instead of appending.

Rules

• Order is oldest first. Append at the end.
• Neither flag set means the file only passed through — opened, re-saved, exported, not changed. Still worth recording.
• Cap at 16 entries. Drop from the middle: index 0 is always kept, and so are the newest.
• Omit the key entirely when the chain is empty. Never write "tools": [].
• Preserve unknown keys inside every entry you did not write. This is where other apps record things, so a re-save must not trim them.
• Never back-fill. A file with a meta block but no tools does not get a synthesised Glyph Museum entry, obvious though the origin is. The chain holds only what apps wrote about themselves.

Reading a file

Metadata must never get between a user and their file. These are the rules Dot Hub's own importer follows, taken from Glyph Museum's guidance.

1. Parse frames first, metadata second. A broken metadata block can then never turn a good file into an error.
2. Treat a block that is missing, malformed, or the wrong shape as absent.
3. Validate field by field. Drop what does not fit, keep what does.
4. Validate tools entry by entry. One bad entry is skipped; the rest of the chain survives.
5. Treat an empty or whitespace-only string as absent.
6. Ignore keys you do not recognise — and preserve them when writing.
7. Infer resolution from p.length, not from v.

Rejection reasons

Writing a file

A checklist for anything that produces one of these files.

1. Write v from the matrix size — 25 → 1, 13 → 4 — even though Dot Hub ignores it. Other readers use it.
2. Write p in the compact form, values clamped to 0–255.
3. Write d per frame, or omit it to accept the 100 ms default.
4. Copy meta and dotHubMeta through byte for byte, including keys you do not recognise. Do not create either.
5. Append your own tools entry per chapter 5, carrying every existing entry through with its unknown keys intact.
6. Only write a user where your app genuinely created or edited the frames.
7. Omit optional keys rather than writing null or "".

Brightness scale

On disk brightness is always 0–255. Dot Hub scales to 0–4095 in memory by 16.0588; that factor is an implementation detail and never appears in a file.

Differences from Glyph Museum

Everything that is not identical between the two formats, in one table. The base format is documented at glyphmuseum.com/developers.

Forward compatibility

Both formats grow by adding keys, never by removing or repurposing them. Ignore what you do not recognise instead of rejecting the file, never assume a metadata block is there, and carry through whatever you were handed. New keys in dotHubMeta raise its version; a new resolution arrives as a new v with its own row pattern.