# テロップラボ (telop-lab)

> 200 ready-to-use Japanese video caption (telop / テロップ) styles for AI-driven video editing. Styles are collected from real YouTube shorts, VTuber clips (kiri-nuki), business media explainers, variety TV subtitles, karaoke lyrics, and overseas edit/kinetic-typography videos. Canonical host: https://telop-lab.com/

## MCP server (easiest entry)

Connect any MCP client to **`https://telop-lab.com/mcp`** (streamable HTTP, stateless — no auth). Tools:

- `search_telops({query?, cat?, limit?})` — find style ids by keyword/category
- `get_telop({id})` — full style definition + overlay URL + caps.json snippet
- `list_categories()` — category names + counts
- `build_overlay_url({id, text, pos?, progress?})` — URL that renders the telop as transparent 1080x1920 (screenshot it → PNG → ffmpeg overlay)

Typical agent flow: `search_telops` → `get_telop` → `build_overlay_url` → screenshot → composite.

## Machine-readable catalog

- `telops.json` — the full catalog. `styles[]` entries: `id` (stable), `name`, `cat` (variety|kiri-nuki|business|documentary|lyrics|sns|overseas|info), `font` (key into `fonts` map), `weight`, `size` (px on a 1080x1920 canvas), `fill` (color or CSS `linear-gradient(...)`), `stroke` (array of `{c,w}` outer→inner), `glow`/`shadow`, `marker`/`underline`/`frame` (decoration), `layout` (subtitle|bar|banner|card|bubble|chip|vertical|karaoke|rank|letterbox), `pos` (top|center|bottom|right), `anim`, `sample`, `use` (when to use), `tags`, `accent` ({fill} for `|...|` accent spans), `sub` (secondary text spec for `rank`), `karaoke` (sung-color for `karaoke` layout).
- `anim` values: `none` | `fade` | `pop` | `zoom` | `stamp`(衝撃ドンッ) | `slide` | `shake`(連続震えループ) | `blur` | `wipe` | `chars`(1文字ずつポップ) | `chars-up`(1文字ずつ下から) | `scatter`(パラパラ) | `drop`(落下) | `type`(タイプライター) | `karaoke`(塗りつぶし進行). Entrance animations are modeled on real YouTube/editing conventions (char stagger ~42-90ms, stamp 260%→100%/~390ms, letterbox band stagger 240ms).

## Rendering API

`overlay.html` renders any style to a transparent 1080x1920 stage:

```
overlay.html?id=<styleId>&text=<text>[&pos=top|center|bottom][&tag=<t>][&kp=0..1][&subText=<t>][&animate=1][&anim=<override>][&frozen=1]
```

- `text`: use `|...|` to mark accent-colored spans (e.g. `これが|最強|なんだよ`)
- `tag`: bottom band label for `letterbox` layout
- `kp`: karaoke progress 0..1 (fraction of characters recolored)
- `animate=1`: play entrance animation (WAAPI, live preview)
- `anim=<name>`: override the style's `anim` for this render
- `frozen=1`: deterministic capture mode — animations built as paused CSS; seek with `window.__seek(tMs, totalWindowMs)` then screenshot. `window.__animDur` = entrance ms, `window.__animLoop` = continuous anim (shake/karaoke).
- sets `window.__ready = true` when fonts are loaded (wait for this before screenshotting)

## Burning into video

`apply.mjs` (Node + playwright-core + ffmpeg):

```
node apply.mjs input.mp4 --style <id> --text "<text>" --start <sec> --end <sec> -o out.mp4
node apply.mjs input.mp4 --captions caps.json -o out.mp4
```

caps.json: `[{"style":"kr-clip-double","text":"絶対楽しい","start":0,"end":2.4,"pos":"bottom"}]`

It screenshots each caption via Playwright. Static styles → transparent PNG + alpha fades. Animated styles (`anim` ≠ none) → PNG sequence captured via `frozen=1` + `__seek` frame stepping → ffmpeg overlay; entrance animations are burned in, exits use a 0.15s fade. `--no-anim` forces everything static. Per-caption `anim` field overrides the catalog. Audio is copied.

## Caveats (重要)

- **テロップは焼き込み済みピクセル**。編集ソフトのテキストレイヤーのように後から文字だけ差し替えることはできない。文字を変える = PNGを再生成して動画を再合成する（つまりパイプラインを再実行する）。
- **`caps.json` がプロジェクトファイル**。元動画と caps.json を残しておけば、文字修正は「caps.json を書き換えて apply.mjs を再実行」だけで済む。エージェントに直してもらう場合も caps.json を渡すのが最短。
- 合成前にテキストを確定させること（誤字・表記ゆれは再レンダリングコストになる）。プレビューだけしたい場合は `overlay.html` のURLをブラウザで開くだけで確認できる。
- overlay URL は状態を持たない（`?id=&text=` がすべて）。同じURLは常に同じ見た目を返す。

## Picking a style

- Variety talk / general shorts → `cat:variety` (va-white-black is the safest default)
- VTuber/streamer clips → `cat:kiri-nuki`, member color via `kr-member-*` or `kr-clip-*`
- Business/explainer/interviews → `cat:business`
- Dramatic/documentary → `cat:documentary`
- Song lyrics → `cat:lyrics` (`ly-karaoke-*` for sung-progress)
- SNS/chat simulation → `cat:sns`
- English/meme/kinetic edits → `cat:overseas`
- Numbers/labels/rankings/warnings → `cat:info`

Match the video's mood: loud entertainment → thick strokes + accent; quiet/serious → mincho or thin styles. Safe area: keep text out of the top/bottom 15% of 9:16 (covered by app UI) — `pos:bottom` already accounts for this.

## License

MIT. Fonts are all SIL Open Font License (Google Fonts), loaded at runtime.