@flipletters/flipcode

Parser and serializer for flipcode — the FlipLetters split-flap board language. Zero dependencies, runs in Node and the browser.

flipcode is a small file format (think Markdown or LaTeX, not a general programming language): a split-flap / flip-dot video template as a short text document. Its vocabulary is exactly what a physical flap board can do — boards, slides, flip choreography, holds, click sounds — nothing more. A document is a board file (.flip); the written rules are the flipcode spec, v1.

flipletters v1
board: trainboard 8x34
output: 1920x1080 30fps
title: DEPARTURES
accent: #ffb63d
sound: solari volume 0.8

--- slide 1
hold: 12s
flip: cascadeRows 11/s jitter 0.2 stagger 0.4
| TIME  DESTINATION     STATUS  TRK
| 10:25 LOS ANGELES     ON TIME  B4

Usage

import {
  parseFlipcode,
  serializeProject,
  encodeFlipcodeForUrl,
  projectFromUrlParams,
} from "@flipletters/flipcode";

// text → project (forgiving: aliases, percents, clamping with warnings)
const { project, warnings } = parseFlipcode(code);

// project → canonical text
const code2 = serializeProject(project);

// build a share link that opens the board in the FlipLetters Studio
const url = `https://app.flipletters.com/#code=${encodeFlipcodeForUrl(code2)}`;

// resolve a readable template URL (?board=station&title=BRUNCH&slide=A|B)
const loaded = projectFromUrlParams(new URLSearchParams(location.search), project);

The parser never hard-errors on messy input — unknown directives and out-of-range values are normalized and reported in warnings; only empty input throws. That is a spec rule: v1 parsers must ignore unknown vocabulary so documents written for newer versions degrade gracefully.

Rendering a parsed project as an MP4 (flap physics, materials, synthesized click sounds) is the FlipLetters Studio; this package is the open text layer so scripts, bots, and LLM pipelines can read and write boards.

Repository layout

• SPEC.md — the flipcode spec, v1
• src/index.ts — the reference parser + serializer
• examples/ — real board files (.flip) that open in the Studio via its </> Code panel
• npm test — spec conformance tests (Node 22+)

Publishing (maintainers)

This directory is the complete public repo. From a fresh clone of the monorepo:

cd packages/flipcode
git init -b main && git add -A && git commit -m "flipcode spec + reference parser"
git remote add origin https://github.com/<owner>/flipcode.git
git push -u origin main
npm publish --access public   # claims the @flipletters npm scope on first publish

The FlipLetters app keeps an engine-integrated copy of this parser; its test suite (npm run test:flipcode) includes a parity check against this package, so the two cannot drift silently.

License

MIT