FlipLetters flipcode

Boards as text

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). Draft / validate / share need no key. Details: For AI agents.

{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/api/mcp"
    }
  }
}

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)

Draft/validate need no key. Optional FLIPLETTERS_API_KEY enables cloud render and team share. Full agent section: For AI agents.

{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/api/mcp"
    }
  }
}

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, validate, and share FlipLetters boards without an account, without payment, and without an API key. 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. Draft / validate / share: no key. Cloud render / team: Authorization: Bearer flk_… from Studio → Account → API keys & agents.

{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/api/mcp"
    }
  }
}

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. Draft / validate / share need no key. Cloud render / team tools need Authorization: Bearer flk_….

{
  "mcpServers": {
    "flipletters": {
      "url": "https://app.flipletters.com/api/mcp"
    }
  }
}

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

Draft / validate / share need no key — hosted or stdio. Do not invent credentials for that. When an agent should spend a human's cloud export quota or push into a Team Library, the human creates a key 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.

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.