Developers

Start here

Glyph Museum stores every design as a small JSON file. The format is open, documented on this page, and free to build on. If your app can render a Nothing Phone matrix, it can read our designs in an afternoon.

The designs themselves are a different matter. They are made by people who share them with the community for free, so the one thing we ask is that the credit stays attached to the work.

1. The design format

A design is a JSON object with a format version and an ordered list of frames. One frame is a static design, more than one is an animation.

{
  "v": 1,
  "frames": [
    { "p": [0, 0, 80, 120, 255, ...] }
  ]
}

An animation is the same object with more frames, each carrying its own duration:

{
  "v": 1,
  "frames": [
    { "d": 200, "p": [ /* 489 values */ ] },
    { "d": 100, "p": [ /* 489 values */ ] },
    { "d": 300, "p": [ /* 489 values */ ] }
  ]
}

Resolutions

The Glyph Matrix is a circle cut out of a square grid, so p holds only the LEDs that physically exist, not the full square. Each row is centered inside the grid and holds a fixed number of LEDs.

The row patterns, and the loop that walks a flat p array back onto the grid:

// LEDs per row, top to bottom
const ROWS_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];
const ROWS_13 = [5, 9, 11, 11, 13, 13, 13, 13, 13, 11, 11, 9, 5];

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

If all you have is the array, its length tells you the resolution: 489 is Phone (3), 137 is Phone (4a) Pro.

2. Attribution metadata

Designs downloaded from a published post carry an optional meta block that names the creator and links back to the original. It sits next to v and frames:

{
  "v": 1,
  "meta": {
    "author": "pauwma",
    "postId": 123,
    "url": "https://app.glyphmuseum.com/post/123"
  },
  "frames": [ /* ... */ ]
}

Files a user created and never published carry no meta at all, because there is nothing to credit yet.

Please keep it

If your app re-saves a design, carry the meta block through untouched. Once a file leaves our apps this block is the only thing holding the credit to the work, and preserving it costs you one line.

Read it defensively

Attribution should never get between a user and their file. These are the rules our own importers follow, and we suggest the same:

• If meta is missing, malformed, or not an object, treat it as absent. Never fail an import over it.
• Validate field by field. Drop what does not fit, keep what does.
• If url and postId disagree, trust postId.
• Ignore keys you do not recognise.

Less information beats wrong information. A design with no author shown is fine, a design credited to the wrong person is not.

3. Rules for third-party apps

Reading a file a user exported themselves needs no permission and works today. If you want to go further and let people bring in designs published by the community, these are the conditions.

1. 01

   Credit the author

   Show the creator's handle wherever the design appears, and link back to its post. The meta block hands you both.

2. 02

   Keep community designs free

   Access to designs made by the community cannot sit behind a paywall. Charging for your own tools and features is entirely your call. Charging for other people's work is not.

3. 03

   No bulk collection

   Do not scrape, mirror, or bundle the catalog. One design at a time, because a user asked for it, is what this is for. Hidden or removed posts must stay gone.

4. 04

   Publishing stays with us

   Designs are published to Glyph Museum only through official Glyph Museum apps. Accounts, moderation and community safety live there, so there is no third-party publish path. Users can always export a file and bring it over themselves.

These conditions are also written into our Terms of Service, section 5.4.

4. The format will grow

We add things over time, including new keys inside meta. Two habits keep your importer working through that:

• Ignore keys you do not recognise instead of rejecting the file.
• Never assume meta is there.

On our side, we will not remove or repurpose the fields documented here. When a new resolution ships it arrives as a new v value with its own row pattern, and this page gets updated the same day.

5. Building something?

Tell us. We are happy to answer format questions, look at what you are making, and point people your way when it is out. Reaching out first also means you hear about format changes before they land.