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. Metadata

A design can carry an optional meta block. It describes the design, with its title and description, credits the published post the design is, and names the post it was remixed from. It sits next to v and frames:

{
  "v": 1,
  "meta": {
    "title": "Heart",
    "description": "A heart that beats.",
    "author": "pauwma",
    "postId": 123,
    "url": "https://app.glyphmuseum.com/post/123",
    "remixOf": 98
  },
  "frames": [ /* ... */ ]
}

Every field describes the design in the file. Files that were never published carry no author, postId or url, because there is no post to credit yet. They can still carry a title, a description and remixOf.

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

Metadata 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.
• Every field is optional. Validate field by field, drop what does not fit, keep what does.
• title and description are plain user text. Trim them, and expect them truncated to 18 and 255 characters.
• If url and postId disagree, trust postId and drop the url.
• 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. When remixOf is present, credit that post as well.

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.