# FlipLetters

> FlipLetters (https://flipletters.com) makes split-flap / flip-dot board videos
> with synthesized mechanical click sound. Boards are defined in "flipcode" —
> a small open text format (like Markdown for flap displays). Editor:
> https://app.flipletters.com · Spec: https://flipletters.com/docs

## For AI agents (read this first)

You can draft and share boards with **no account, no payment, and no API key**.
There is no API-key request page for agents today. Your job is to produce valid
flipcode and a Studio URL; the human previews and exports under their plan.

### npm packages

| Package | Install | Role |
|---|---|---|
| @flipletters/flipcode | `npm i @flipletters/flipcode` | MIT parser/serializer (zero deps) |
| flipletters-mcp-server | `npx -y flipletters-mcp-server` | Local MCP tools (stdio) |

- npm: https://www.npmjs.com/package/@flipletters/flipcode
- npm: https://www.npmjs.com/package/flipletters-mcp-server
- GitHub (flipcode): https://github.com/tera-sarah/flipcode
- Contact on packages: FlipLetters <dev@flipletters.com>

### MCP config (Claude Desktop / Claude Code / Cursor, etc.)

```json
{
  "mcpServers": {
    "flipletters": {
      "command": "npx",
      "args": ["-y", "flipletters-mcp-server"]
    }
  }
}
```

### MCP tools

Local (no key):
1. `flipletters_flipcode_reference` — cheat sheet; call before writing
2. `flipletters_example_board` — known-good starting board by type
3. `flipletters_validate_board` — normalize + warnings + **share URL**
4. `flipletters_template_url` — readable `?board=…&slide=…` URLs

Cloud (set FLIPLETTERS_API_KEY=flk_… from Studio Account → API keys & agents):
5. `flipletters_render_board` — cloud MP4 under key owner's plan
6. `flipletters_render_status` — poll job
7. `flipletters_list_teams` — teams the owner belongs to
8. `flipletters_share_to_team` — push board into Team Library

Loop: reference → write flipcode → validate → deliver share link.
Optional: render or share_to_team with API key.

### Without MCP

Write flipcode (below) and return one of:

- Readable params (each mirrors a flipcode line; `|` separates rows):
  https://app.flipletters.com/?board=station&grid=8x34&title=DEPARTURES&slide=ROW ONE|ROW TWO&flip=cascade,11&hold=6
- Full fidelity (base64url flipcode in the fragment):
  https://app.flipletters.com/#code=<base64url>

### flipcode in 12 lines

```
flipletters v1
board: trainboard 8x34      # minimal|trainboard|artboard|flipdot|marquee|announcement + ROWSxCOLS
output: 1920x1080 30fps     # or vertical / square / 4k, or 1200x630@25
title: DEPARTURES           # station & announcement boards
accent: #ffb63d
sound: solari volume 0.8    # solari|thock|deep|clickity|fizz|none

--- slide 1
hold: 5s
flip: cascadeRows 11/s jitter 0.2 stagger 0.4
| ONE ROW OF UPPERCASE BOARD TEXT
| ANOTHER ROW
```

Transitions: allAtOnce, cascadeRows, sweepColumns, randomDissolve, wave,
diagonal, radial, spinStop. No fades or zooms — flip-native equivalents only.
Parsers are forgiving: out-of-range values clamp with warnings; unknown lines
are ignored. Only empty documents error.

### Free vs paid (agents)

| Action | Cost |
|---|---|
| Draft / validate flipcode (MCP or library) | Free forever (no key) |
| Share / open-with-code Studio URL | Free |
| Human preview with sound | Free |
| Create API key (Studio Account → API keys & agents) | Free (signed-in human) |
| Human / agent cloud MP4 export | Free quota then paid plans (same entitlements) |
| Create a Team workspace | Premium human |
| Join a team by invite | Free |
| Agent cloud render / team share with key | Uses human’s plan; key from Account |

Local MCP needs no key. Cloud keys: human creates `flk_…` in
app.flipletters.com → Account → API keys & agents (shown once). Full plans:
https://flipletters.com/pricing

## Billing (humans)

Creating and drafting are free. Exporting MP4s: 5 free watermarked exports,
then $1.99/single export, Premium $8.99/mo (no watermark, Pro templates, 4K,
teams), Studio $29.99/mo (long ambience renders, own audio, TikTok posting).

## How-to (quick)

1. Studio: open https://app.flipletters.com → </> Code → paste flipcode → Apply → Export
2. Library: `npm i @flipletters/flipcode` → parseFlipcode → encodeFlipcodeForUrl → share URL
3. Agent: MCP `npx -y flipletters-mcp-server` → reference → write → validate → share URL
4. No tools: write flipcode from this file / /docs and return a ?board=…&slide=… URL

Full how-to: https://flipletters.com/docs#how-to
GitHub (source + HOWTO.md + examples): https://github.com/tera-sarah/flipcode

## Key pages

- https://flipletters.com — home
- https://flipletters.com/docs — flipcode spec + how-to + npm + agent guide
- https://flipletters.com/docs#how-to — step-by-step how-to
- https://flipletters.com/docs#for-agents — agent section
- https://flipletters.com/docs#npm-packages — package section
- https://github.com/tera-sarah/flipcode — public repo (spec + parser)
- https://github.com/tera-sarah/flipcode/blob/main/HOWTO.md — how-to on GitHub
- https://flipletters.com/templates — template gallery (free ones show full code)
- https://flipletters.com/pricing — plans
- https://app.flipletters.com — the Studio (editor)