The .reeltone skin format

A .reeltone file is a plain ZIP archive containing a skin.json manifest and the local fonts or images it references. Version 1 themes the fixed Reeltone deck. Version 2 can also define a shaped macOS window, positioned player regions, animation frames, and attached panels.

Skins are declarative data. They cannot contain executable code or change what an app action does.

Package rules

my-player.reeltone
├── skin.json       required at archive root
├── chassis.png     optional artwork
├── play-down.png   optional state artwork
└── Display.ttf     optional font

The uncompressed archive must be 64 MiB or smaller.
Paths must stay inside the archive. Symlinks, absolute paths, and ../ traversal are rejected.
Image dimensions are capped at 2048 × 2048, with a 64 MiB total decoded-image budget.
IDs must be stable and filesystem-safe. Reverse-DNS form such as com.example.my-player is recommended.

Minimum manifest

{
  "formatVersion": 1,
  "id": "com.example.my-player",
  "name": "My Player"
}

Only formatVersion, id, and name are required. Missing visual fields fall back to Reeltone's built-in LCD theme.

Colors and fonts

Field	Purpose
`colors.screen`	Main LCD background.
`colors.ink`	Primary foreground and text.
`colors.inkDim`	De-emphasized foreground; defaults to the skin's ink at 35% opacity.
`colors.panel`	Chrome outside the main screen.
`colors.panelText`	Foreground shown on panel chrome.

Colors use #RRGGBB or #RRGGBBAA. Aim for at least 4.5:1 contrast between ink/screen and panelText/panel.

Each of fonts.display, fonts.digits, fonts.body, and fonts.bodyBold may reference a Reeltone built-in PostScript name or a bundled font file and its exact PostScript name.

Classic sprites

Version 1 can replace artwork while preserving the standard deck geometry.

Slot	Rendered as
`reelRim`	Resizable reel perimeter.
`reelSpokes`	Resizable rotating reel interior.
`background`	Screen fill; aspect-fill is usually best.
`keyNormal`	Resizable transport key at rest.
`keyPressed`	Resizable transport key while pressed.

"sprites": {
  "background": { "file": "background.png", "mode": "fill" },
  "keyNormal": {
    "file": "key.png",
    "capInsets": [6, 6, 6, 6],
    "mode": "stretch"
  }
}

Version 2: shaped macOS skins

A shaped skin adds window, regions, and optionally panels. The chassis image's natural pixel dimensions define the fixed window coordinate space. Region rectangles use [x, y, width, height] from the image's top-left origin.

{
  "formatVersion": 2,
  "id": "com.example.shaped-player",
  "name": "My Shaped Player",
  "window": {
    "size": [640, 240],
    "art": { "normal": "chassis.png" }
  },
  "regions": [
    { "component": "artwork", "rect": [34, 30, 128, 128] },
    { "component": "title", "rect": [180, 30, 330, 28], "marquee": true },
    { "component": "playPause", "rect": [78, 176, 54, 34] },
    { "component": "seek", "rect": [205, 182, 278, 18] }
  ]
}

Regions are drawn and hit-tested in array order; later regions sit above earlier ones. Available components include playback transport, seek and volume controls, text readouts, artwork, visualiser, equaliser, track list, library, window controls, decorations, and panel toggles.

Interactive regions can provide normal, hover, pressed, playing, playing-hover, and playing-pressed artwork. Frame sequences may animate continuously or only during playback. Keep every state aligned to the exact same rectangle and preserve transparent pixels around the control to avoid visible chassis seams.

Use the local v2 JSON schema as the machine-readable contract for component names, properties, and allowed values.

Artwork and font licensing

The manifest's optional license field describes your package metadata and artwork; it does not automatically license a font you bundle. Include the font's own license file when its terms require it. Use original artwork or assets you have permission to redistribute—evoking a classic media-player era is different from copying a proprietary skin.

Test and install

Export from the Classic Theme Builder or Shaped Skin Studio.
In Reeltone, open Settings → Appearance → Import Skin.
Resolve every validation warning, preview the skin, and install it.