wjs-teaching-english

英単語を動画のスーパーカットで教える

1つの英単語から、単体で完結するHLSレッスンを作成します：

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

MP4への焼き込みは行いません。2枚のカードだけを小さな.tsとしてレンダリングし、どのHLSプレーヤーでも再生できるよう、スーパーカットのコーデックに合わせて再エンコードします。

前提条件（最初に一度確認）

• PATH上にffmpeg／ffprobeがあること（Homebrew）。
• Python volcengine SDK（miraのrequirements.txtに記載されており、TTSに使用）： python3 -c "import volcengine"。見つからない場合は、pip3 install volcengine==1.0.58の実行をユーザーに許可してもらいます（リポジトリでバージョンが固定されている依存関係です）。
• デプロイ済みの検索アプリ（デフォルト）：https://search-app-three-kappa.vercel.app。ローカルで実行する場合は、SEARCH_APP_BASE=http://localhost:3000で上書きします（Node ≥ 23.6とnpm startが必要です）。

手順

1. 単語を決めます。 英単語1つ（または短いフレーズ）です。ユーザーが文を入力した場合は、対象となる単語を選びます。

2. ミニレッスンのJSONを作成します。 辞書APIは使用せず、あなた（Claude）が作成します。正確かつ簡潔にまとめます。一時ファイルに保存します。例：/tmp/lesson.json：

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

   • tts_textはイントロカード上で読み上げられます。単語と短い中国語の意味にとどめてください（Volcanoは英語と中国語が混在したテキストも問題なく読み上げます）。
   • usageはカードに表示する短い1行です（低解像度では約20文字以下が最適です）。

3. ビルドします：

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

   便利なフラグ：--speaker zh_female_qingxin（デフォルト）、--limit 300（クリップの最大数）、--no-tts（無音のカード）、--base <url>、--out <dir>。

4. 出力パス（表示されるsearch-app/out/<word>.m3u8）とクリップ数を報告します。納品物は.m3u8と、同じディレクトリにある<word>.intro.ts／<word>.cta.tsです。out/はGitの管理対象外です。

補足

• 単語に該当するクリップがない場合、スクリプトは「no clips match」で終了し、何も書き込みません。その旨をユーザーに伝え、より一般的な単語を提案してください。
• イントロ／CTAは、最初のスーパーカットセグメントの解像度／コーデック／フレームレートに合わせてエンコードされるため、最初の不連続点でデコーダーを再初期化する必要がなく（bufferAppendErrorを回避できます）、再生がスムーズです。
• ローカルで再生するには、ffplay search-app/out/<word>.m3u8を実行するか、out/フォルダーをHTTP経由で配信して、任意のHLSプレーヤーで開きます（Safariは.m3u8をネイティブ再生できます）。