Teach an English word as a video supercut

Turn one English word into a self-contained HLS lesson:

intro.ts  (word /IPA/ · 中文 gloss · usage + Volcano TTS)
   ⋯ EXT-X-DISCONTINUITY
[supercut] every season2 clip where the word is spoken  (search-app /api/playlist, COS URLs)
   ⋯ EXT-X-DISCONTINUITY
cta.ts    (关注王建硕 + Volcano TTS)
= search-app/out/<word>.m3u8

No MP4 is burned — only the two cards are rendered as tiny .ts, re-encoded to
match the supercut's codec so they play in any HLS player.

Prerequisites (check once)

• ffmpeg / ffprobe on PATH (Homebrew).
• Python volcengine SDK (declared in mira requirements.txt, used for TTS):
  python3 -c "import volcengine". If missing, ask the user to allow
  pip3 install volcengine==1.0.58 (it's a pinned repo dependency).
• The deployed search-app at https://search-app-three-kappa.vercel.app
  (default). Override with SEARCH_APP_BASE=http://localhost:3000 if running
  locally (needs Node ≥ 23.6 + npm start).

Steps

1. Get the word. A single English word (or short phrase). If the user gave
   a sentence, pick the target word.

2. Write the mini-lesson JSON. YOU (Claude) author it — no dictionary API.
   Keep it accurate and concise. Save to a temp file, e.g. /tmp/lesson.json:

json { "word": "love", "ipa": "/lʌv/", "pos": "v. / n.", "gloss": "爱，热爱", "usage": "下面是它在真实电影里的说法", "tts_text": "love. 爱。" }

• tts_text is read aloud over the intro card — keep it to the word + a
  short 中文 gloss (Volcano reads mixed English/中文 fine).
• usage is one short line shown on the card (≤ ~20 chars renders best at
  low resolutions).

3. Build it:

bash cd /Users/jianshuo/code/mira/search-app python3 scripts/build_lesson.py --word love --lesson /tmp/lesson.json

Useful flags: --speaker zh_female_qingxin (default), --limit 300 (max
clips), --no-tts (silent cards), --base <url>, --out <dir>.

4. Report the printed output path (search-app/out/<word>.m3u8) and the
   clip count. The .m3u8 plus its sibling <word>.intro.ts / <word>.cta.ts
   are the deliverable; out/ is git-ignored.

Notes

• If the word has no clips, the script exits with "no clips match" and writes
  nothing — tell the user and suggest a more common word.
• Intro/CTA are encoded to the FIRST supercut segment's resolution/codec/fps so
  the first discontinuity needs no decoder re-init (avoids bufferAppendError).
• To play locally: ffplay search-app/out/<word>.m3u8, or serve the out/
  folder over HTTP and open in any HLS player (Safari plays .m3u8 natively).