# telop-lib

> 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 (PIVOT/NewsPicks style), variety TV subtitles, karaoke lyrics, and overseas edit/kinetic-typography videos.

## 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` (pop|zoom|slide|fade|type|none), `sample`, `use` (when to use), `tags`, `accent` ({fill} for `|...|` accent spans), `sub` (secondary text spec for `rank`), `karaoke` (sung-color for `karaoke` layout).

## 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]
```

- `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`: CSS entrance animation (preview only; for video burn-in use ffmpeg fades)
- 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-vspo-double","text":"絶対楽しい","start":0,"end":2.4,"pos":"bottom"}]`

It screenshots each caption as a transparent PNG via Playwright, scales to the input resolution, and overlays with 0.2s alpha fades. Audio is copied.

## 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-vspo-*`
- 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.

## BGM library (bonus)

`/bgm/` is a sister catalog of code-generated (procedural, copyright-clean) loop BGM. `GET /bgm/bgms.json` lists 100 tracks {id, mood, bpm, key, dur, file}. Moods: chill, corporate, suspense, pop, emotional, game, horror, ambient, funky, epic. Preview/download: `/bgm/audio/<id>.mp3`. To synthesize a custom length/BPM, run `bgm/gen-bgm.mjs --id <id> --bars N -o out.wav` (Node.js, no deps). Mix into video:
```
ffmpeg -i input.mp4 -i bgm.mp3 -filter_complex "[1:a]volume=0.25,aloop=loop=-1:size=2e+09[b]" -map 0:v -map 0:a? -map "[b]" -shortest out.mp4
```

## License

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