FlipLetters flipcode

Boards as text

Short answer: flipcode is how you write a split-flap video as plain text. List the board, the slides and how each one flips, and FlipLetters Studio renders it as an MP4 with mechanical click sound. (Looking for OpenCV’s flipCode? That’s an unrelated image-mirroring argument; see the FAQ below.)

flipcode is a file format — a small language like Markdown or LaTeX, not a general programming language. The language is called flipcode, a document is a board file (.flip if you want an extension), and this page is the written rules: the flipcode spec, v1. Its vocabulary is exactly what a physical split-flap or flip-dot board can do — boards, slides, flip choreography, holds, click sounds — and nothing more. That constraint is the point: everything expressible in flipcode renders as a believable mechanical board, deterministically — same code, same video.

Agents start here: hosted MCP https://app.flipletters.com/api/mcp (alias /mcp/v1, discovery /.well-known/mcp/server.json). Hosted tools/call needs Authorization: Bearer flk_…. Local stdio draft tools need no key. Details: For AI agents.

{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/api/mcp",
      "headers": {
        "Authorization": "Bearer flk_…"
      }
    }
  }
}

Flipcode for each template

Pick a board, watch the animation, then open the Flipcode tab to see the text that produces it — including a cheatsheet of keywords, sizes, and what each field means. Comments starting with # or // are for humans; the parser ignores them.

Board sizes (what looks good)

Oversized grids are clamped to the max. Bigger flip-dot boards look sharper but take longer to render. Cream Editorial and Confetti are not separate engines — they're minimal / announcement plus backdrop: cream or backdrop: confetti. New templates later would add new board: names or backdrop values; old files still parse (unknown keys warn).

Field cheat sheet

A complete board file

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
| 10:41 TOKYO HANEDA    BOARDING C2

| lines are the board's text rows, spaces preserved — the code looks like the video it produces. Comments start with // or #. Open any board in the Studio and press </> FLIPCODE to see and edit it live.

Global directives

Slides

Recipes — flip-native effects

There is deliberately no fade, zoom, or slide-in — a flap board can't do those. Every effect people reach for has a flip-native equivalent:

Boards in URLs

A template can live in a legible address — every query parameter mirrors one flipcode line, and the Studio loads it on visit. slide repeats; | separates rows:

app.flipletters.com/?board=station&grid=8x34&title=BRUNCH
  &accent=e23a55&slide=EGGS BENEDICT|FLAT WHITE&flip=cascade,9&hold=6

For full fidelity (paint grids, per-slide detail) the Studio's Copy link packs the entire board file into a #code= fragment — no account, no server storage.

Versioning & forward compatibility

Every document declares its version in the header (flipletters v1). New vocabulary arrives only under a bumped version, and parsers must ignore unknown directives with warnings rather than errors — so a v1 renderer degrades gracefully when it meets v2 vocabulary, and a messy hand-written file still parses. Only an empty document is an error.

How to use flipcode

Four common paths. Same language everywhere — Studio, npm, MCP, and plain URLs. Open source lives at github.com/tera-sarah/flipcode; packages on npm: @flipletters/flipcode · flipletters-mcp-server. Site home: flipletters.com.

A. In the Studio (no install)

1. Open app.flipletters.com.
2. Press </> Code.
3. Paste a flipcode document (example at the top of this page) → Apply.
4. Preview with sound, then Export MP4 under your plan.

B. From a share link (no account)

Anyone with a link can open the board. Readable params for short text boards:

https://app.flipletters.com/?board=station&grid=8x34&title=DEPARTURES
  &slide=ROW ONE|ROW TWO&flip=cascade,11&hold=6

Full fidelity packs the entire board into #code= (built by the library or MCP validate tool — see below).

C. In JavaScript / TypeScript

npm install @flipletters/flipcode

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

const source = `flipletters v1
board: minimal 3x14
output: 1920x1080 30fps
sound: thock volume 0.85

--- slide 1
hold: 4s
flip: cascadeRows 11/s jitter 0.2 stagger 0.4
|
|   HELLO WORLD
|
`;

const { project, warnings } = parseFlipcode(source);
const code = serializeProject(project);
const shareUrl =
  "https://app.flipletters.com/#code=" + encodeFlipcodeForUrl(code);
// open shareUrl in the Studio — free to preview; export uses the human's plan

More examples and the in-repo how-to: GitHub README · HOWTO.md · examples/*.flip.

D. As an AI agent (MCP)

Hosted HTTP MCP requires a Studio API key for every tools/call. Local stdio draft/validate need no key. Optional FLIPLETTERS_API_KEY on stdio enables cloud render and team share. Full agent section: For AI agents.

{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/api/mcp",
      "headers": {
        "Authorization": "Bearer flk_…"
      }
    }
  }
}

Billing & plans

Creating and exporting are free; the watermark is where plans apply. Free: every board type, full editor, previews with sound, share links, and unlimited watermarked MP4 exports at any size. Premium ($8.99/mo): no watermark, 300 exports or 100 render-hours per month, and team creation. Studio ($29.99/mo): everything in Premium plus 1000 exports or 300 render-hours, hours-long ambience loops, your own audio track, and direct TikTok posting. Free templates in the gallery are open code; marketplace templates from creators may be free or paid — a paid template's editable source is delivered after purchase, into your library. Joining a team is always free; drafting boards as text (flipcode) never costs anything for anyone — humans or AI agents. Full plan list: /pricing.

npm packages

Two public packages implement this page. Both are MIT, published under the @flipletters / FlipLetters npm account ([email protected]). Neither requires an API key for draft, parse, or validate.

# hosted MCP (Cursor / remote — no install)
# https://app.flipletters.com/api/mcp

# library
npm install @flipletters/flipcode

# local stdio (still valid)
npx -y flipletters-mcp-server

Package pages: @flipletters/flipcode · flipletters-mcp-server. Standalone flipcode source: github.com/tera-sarah/flipcode.

For AI agents

If you are an AI agent: you can draft flipcode with the library or local stdio MCP without an account, without payment, and without an API key. The hosted Streamable HTTP MCP at app.flipletters.com requires Authorization: Bearer flk_… for every tools/call (a signed-in human mints a key, free, in Studio → Account → API keys & agents). A board is a flipcode text document (this page is the format reference). Your deliverable is a URL that opens the exact board in the Studio, where your human previews it with sound, tweaks it, and exports under their plan.

Hosted MCP first (Cursor / remote — no install): https://app.flipletters.com/api/mcp. Alias https://app.flipletters.com/mcp/v1. Discovery https://app.flipletters.com/.well-known/mcp/server.json. GET discovery: no key. Every hosted tools/call (draft and cloud): Authorization: Bearer flk_… from Studio → Account → API keys & agents.

{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/api/mcp",
      "headers": {
        "Authorization": "Bearer flk_…"
      }
    }
  }
}

Local stdio (still valid): npx -y flipletters-mcp-server.

Recommended workflow

1. Read this page (or call flipletters_flipcode_reference), or start from flipletters_example_board.
2. Write a complete flipcode document (header + one or more slides).
3. Validate with flipletters_validate_board (or parseFlipcode from the library). Fix warnings and re-validate until clean.
4. Hand the human the share URL from validation (full fidelity #code=) or a short readable URL for simple text boards.
5. Do not claim you rendered an MP4 unless a metered render tool is available and configured. Export happens in the Studio under the human's quota.

Path 1 — no tools

Write flipcode following this page, then return a readable URL. Every query parameter mirrors one flipcode line; | separates rows within a slide:

https://app.flipletters.com/?board=station&grid=8x34&title=DEPARTURES
  &slide=ROW ONE|ROW TWO&flip=cascade,11&hold=6

Path 2 — MCP server

Hosted URL first, then local stdio. Hosted tools/call needs Authorization: Bearer flk_…. Local stdio draft / validate / share need no key.

{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/api/mcp",
      "headers": {
        "Authorization": "Bearer flk_…"
      }
    }
  }
}

Stdio fallback: npx -y flipletters-mcp-server. With a key, render and team tools spend the key owner's export quota and membership — never invent keys.

API keys — Account panel in the Studio

Hosted HTTP MCP requires a key for every tools/call (draft included). Local stdio draft / validate / share still need no key — do not invent credentials for that path. A signed-in human mints a key (free) in the Studio: open app.flipletters.com → Account → API keys & agents. The full secret is shown once (flk_…); revoke anytime. Keys use the same plan limits as that account (free watermarked quota, Premium/Studio caps, team membership).

Free for agents / free users: unlimited flipcode drafting, validation, share links, Studio preview, and creating API keys. Paid for the human (same as product pricing): watermark-free exports, higher quotas, 4K, long ambience, TikTok post, creating a team workspace. Joining a team by invite stays free. The agent drafts; the human (or their Premium team) owns export and collaboration. Agent MCP tools that call cloud render / team share with the key are rolling out on top of the existing Cloud Run render pipeline and Team library.

Machine-readable summary: /llms.txt. HTTP API: /docs/api. OpenAPI: /openapi.json. Hosted MCP: app.flipletters.com/api/mcp. MCP page: /mcp.

flipcode FAQ

Start from a ready board: Station Board, Flip-Dot, Minimal, or a departure board video. Curious about the clack? Read why split-flap boards sound the way they do.

An open format

The spec is open: anyone may write or parse flipcode. The reference implementation is @flipletters/flipcode (MIT) so scripts, bots, and AI tools can read and write board files. Rendering them as videos — flap physics, materials, synthesized click sounds — is the FlipLetters Studio. Free templates in the gallery publish their full code on listing pages, ready to copy and remix.