Make your Reeltone look like your Reeltone.

What a skin is

A skin is a .reeltone file — a zip archive holding a skin.json manifest and, optionally, font and image files. Import it (Settings ▸ Appearance ▸ Import Skin…) and Reeltone re-renders using the colors, fonts, and sprites it declares.

What a skin can change:

• Five colors: screen, ink, dimmed ink, panel, and panel text.
• Four typefaces: the segment display face, the digits face, body text, and bold body text — either one of Reeltone's own four built-in faces, or a font file the skin bundles.
• Five bitmap art slots: the tape reel's rim and spoke assembly, the Now Playing background, and the transport keys' normal/pressed fill — see Sprites below. Every slot is optional and falls back to Reeltone's own vector art on its own, so a skin with no sprites at all looks exactly like it did before this section existed.

What a skin cannot change:

• Layout — screen structure, button placement, navigation, spacing. All fixed by the app.
• Behavior — a skin is declarative data (colors, fonts, images). It contains no code and cannot run anything.

Full field-by-field reference: docs/skins/format.md. This page is the illustrated walkthrough; that one is the precise spec.

The anatomy of skin.json

Only three fields are required — formatVersion, id, name. Everything else falls back to Reeltone's built-in LCD theme when omitted, so a recolor can be as short as this:

{
  "formatVersion": 1,
  "id": "com.example.midnight",
  "name": "Midnight",
  "colors": { "screen": "#0A1E33", "ink": "#5FD4FF" }
}

That alone is a complete, valid, importable skin — a cyan-on-navy recolor of the built-in theme, untouched fonts and panel colors included.

Colors

* inkDim's fallback is special: if you omit it, it's derived from your own resolved ink at 35% opacity — not from the built-in theme's dim value. Override ink without touching inkDim and you still get a sensibly dimmed version of your color, not a mismatched one from a different palette.

Accepted formats: #RRGGBB or #RRGGBBAA (with alpha). Three-digit shorthand like #FFF is not accepted — write the full six or eight digits.

Fonts

Four slots, each independently optional: display, digits, body, bodyBold. Each is either a name of a face Reeltone already ships:

"digits": { "builtin": "DSEG7Classic-Regular" }

— one of exactly these four PostScript names —

— or a font file your package ships:

"body": { "file": "MyFont.ttf", "postScriptName": "MyFont-Regular" }

postScriptName must be the font's real internal name, verified against the actual file on import. Get this wrong and you'll hit fontNameMismatch — see Finding a font's PostScript name below, the single most common authoring mistake.

Everything else

Sprites

Five slots, each independently optional: reelRim, reelSpokes, background, keyNormal, keyPressed. Each falls back to Reeltone's own vector drawing on its own — supply just reelRim and you get a bitmap rim with the vector spoke assembly still spinning inside it. There's no way to omit a sprite into a blank screen.

"sprites": {
  "reelRim":    { "file": "rim.png" },
  "reelSpokes": { "file": "spokes.png" },
  "background": { "file": "bg.png", "mode": "tile" },
  "keyNormal":  { "file": "key.png",  "capInsets": [6, 6, 6, 6] },
  "keyPressed": { "file": "keyd.png", "capInsets": [6, 6, 6, 6] }
}

No @2x/@3x. Ship one PNG at whatever resolution looks sharp and Reeltone scales it to the slot's point size — you don't provide multiple resolutions. Import rejects anything over 2048px on a side, and caps the total decoded size across every sprite at 64MB (decoded RGBA memory — width × height × 4 bytes per image, summed — not file size on disk). Both are checked at import, so you find out before it's on a device; scripts/makeskin.swift checks them too, and prints the decoded total.

capInsets — [top, left, bottom, right] in pixels — marks the border of a keyNormal/keyPressed image that must stay crisp while the rest stretches to fit whichever transport key it's drawn for (a full-width play button and a narrow shuffle toggle need the same art at different widths). Without it, a bordered key smears at the edges when stretched. Omit it and the whole image stretches uniformly instead.

mode — only read for background. "stretch" (the default) scales to exactly fill the screen, distorting aspect ratio if needed. "tile" repeats the image at its native size instead, for a seamless pattern that would go soft if stretched full-screen.

A sprites key that isn't one of the five names above is silently ignored, the same as any other field this version of the app doesn't recognize — it just does nothing, which reads as "my sprite isn't showing up" if you've mistyped a slot name. scripts/makeskin.swift warns about this specifically; double-check spelling if your sprite doesn't appear.

Finding a font's PostScript name

A font file's PostScript name is not its filename, and often isn't its "family name" either. Reeltone verifies your declared name against the font's real one at import — a mismatch fails cleanly with fontNameMismatch rather than silently substituting the system font, which is what would otherwise happen on every single screen the font is used.

macOS — Font Book

1. Double-click the .ttf/.otf to open it in Font Book, or select it in Font Book's library.
2. Open the info panel (⌘I, or File ▸ Get Info).
3. Look for PostScript name — copy it exactly, including hyphens and capitalization.

Command line — fontconfig

If you have fc-scan (Linux, or macOS via brew install fontconfig):

fc-scan --format "%{postscriptname}\n" MyFont.ttf

Command line — Python / fontTools

pip install fonttools
python3 -c "
from fontTools.ttLib import TTFont
f = TTFont('MyFont.ttf')
name = f['name']
print(name.getDebugName(6))  # 6 = PostScript name
"

Whichever method you use, paste the exact output into postScriptName — don't retype it by hand. A single mismatched character produces fontNameMismatch.

Zip it, get it onto a device

Recommended: scripts/makeskin.swift

From a checkout of the Reeltone repo, this validates your skin directory the same way the app does — manifest decoding, color parsing, the size ceiling, real font registration and PostScript-name verification, and the contrast ratio — and then zips it:

swift scripts/makeskin.swift path/to/your-skin-dir  MySkin.reeltone

Fix whatever it flags before you try importing on-device — it catches everything the app's import gauntlet would reject, before you leave your desk.

Manual zip

A skin directory holds skin.json at its top level, plus any font files it references, flat alongside it. From inside that directory:

cd your-skin-dir
zip -X -r ../MySkin.reeltone .

-X strips extended attributes macOS otherwise adds (resource forks, Finder metadata) that have no place in the archive. Rename the result to end in .reeltone if it doesn't already.

Getting it onto a device

Reeltone has no in-app gallery or hosting — distribution is Files / share-sheet only, the same way most VirtualDJ-style skin ecosystems work. AirDrop the .reeltone to the device, or save it into Files (iCloud Drive, a shared folder, email attachment — anywhere Files can reach), then in Reeltone go to Settings ▸ Appearance ▸ Import Skin… and pick it. Reeltone previews the skin before it's applied, so an unreadable result never becomes your active theme by accident.

Troubleshooting

Every rejection the importer can produce, and what it means.

One more thing you might see that isn't a rejection: a low-contrast warning on import, when your ink/screen pair scores below a 4.5:1 WCAG ratio. The skin still imports — a legitimately dim LCD is a valid look — you just get a heads-up before committing to it. The gallery's "Dim" skin below exists to demonstrate exactly this.

Gallery

Seven complete, working skins — fork any of them as a starting point. Each links to its skin.json source in docs/skins/examples/. An eighth pack, Dim, ships as a deliberately unusable test fixture rather than a theme.

Testing your skin

Reeltone warns on import when ink and screen fall below a 4.5:1 contrast ratio, but it doesn't block you — an authentically murky LCD is a legitimate look, and the app would be a worse tool if it policed taste. It does guarantee a way back: Appearance's reset control is drawn in fixed colors that no skin can touch, and shaking the device restores the built-in theme from anywhere.

Dim exists to prove that. It measures 1.13:1 — far past unusable — so importing it exercises the whole hostile path end to end: the warning fires, you can apply it anyway, and you can still get back out.