| name | make-lyric-video |
| description | トラックディレクトリから字幕付き動画を生成する。歌詞のタイミングをWhisperで取得し、背景画像＋音声＋字幕を合成してMP4を出力する。 |
| argument-hint | ["トラックディレクトリのパス"] |
| allowed-tools | Bash(bash *, python *, ffmpeg *) |
字幕付き歌詞動画の生成
トラックディレクトリ $ARGUMENTS から字幕付き動画を生成する。
前提
トラックディレクトリは以下の構造であること:
source/lyrics.txt — 正しい歌詞テキスト
source/track.wav — 音声ファイル
artwork/cover.png — 背景画像（.jpeg も可）
subtitle/ — 字幕関連（whisper.json, track.srt を格納）
video/ — 最終成果物を格納
手順
1. Whisperでword-level timestampsを取得
bash ${CLAUDE_SKILL_DIR}/scripts/whisper.sh "<トラックディレクトリ>/source/track.wav" "<トラックディレクトリ>/subtitle"
mv "<トラックディレクトリ>/subtitle/track.json" "<トラックディレクトリ>/subtitle/whisper.json"
取得したJSONからタイミングを確認:
python3 ${CLAUDE_SKILL_DIR}/scripts/extract_timestamps.py "<トラックディレクトリ>/subtitle/whisper.json"
2. SRTファイルの作成
word-level timestampsを元に、lyrics.txt の正しい歌詞テキストで SRT を作成する。
タイミング
- 各エントリの開始時間は、実際の歌い出しより約0.4秒前倒しにする（字幕を先に表示して読む時間を確保するため）
- 終了時間は実際の歌い終わりに合わせる — 早く切れると歌詞が読み切れない。Whisperのword timestampsで最後の単語の終了時間を確認すること
- 歌い出し前（イントロ等）には字幕を出さない
テキスト
- 1エントリにつき1〜2行（韻の対や意味の区切りでまとめる）
- セクションタグ（[Verse 1] 等）は字幕に含めない
- Whisperの認識テキストは誤字が多いので必ず
lyrics.txt の正しい歌詞に置き換える
- 固有名詞はアルファベット表記にする — 「Claude Code」「Codex」など。カタカナ（コーデックス、クロードコード等）にしない
- コマンド・関数名は小文字で表記する —
diff, approve, sleep(), exit など。略語（PR等）は大文字のまま
- 長い行は意味の区切りで改行する — 1行が長すぎると自動折り返しで単語の途中（例: "Anthropi" / "c"）で切れて読みにくくなる。全角約15文字・半角約30文字を目安に、句の区切り（全角スペース
の位置）で改行を入れる
字幕にしないもの
- カッコ書き
() のパート — コーラスの掛け声・合いの手（(hey!) (yeah) (come on) (お前ら人間) 等）
- 同じフレーズの連続繰り返し — バックコーラス（「ただの機械 ただの機械」→「ただの機械」のみ、「お前の未来 お前の未来」→1回のみ）
- Outroやブリッジでのフック繰り返し — 同じフレーズが何度もリピートされる部分は字幕を出さず、次のメインリリックで字幕を復活させる方がインパクトが出る
3. タイミング検証
動画を生成する前に、SRTをWhisperのJSONと突き合わせて検証する:
python3 ${CLAUDE_SKILL_DIR}/scripts/validate_srt.py "<トラックディレクトリ>/subtitle/track.srt" "<トラックディレクトリ>/subtitle/whisper.json"
出力:
- 全エントリのタイミング突き合わせ一覧（✓=理想、△=許容、⚠️=要修正）
- 問題リスト（要修正のもののみ）
チェック内容:
- 開始時間が歌い出しの0.2〜0.6秒前か（0.15秒以内の遅れは許容）
- 終了時間が歌い終わりより前に切れていないか
- エントリ間のタイミング逆転がないか
- 表示時間が1.5秒未満のエントリがないか
- 行の表示幅（全角15文字・半角30文字超え）
問題が0件になるまでSRTを修正すること。
よくある問題と対処:
- Whisperが複数行を1セグメントにまとめる — word timestampsで行の境界を特定し、SRTを分割する
- エントリの表示時間が短すぎる — 最低1.5秒は表示する
- Chorus/Bridgeの繰り返し部分でタイミングがズレる — 各Chorusのタイミングは独立して確認する
4. 動画生成
重要: 複数曲を処理する場合も1曲ずつ順番に生成→確認する。並列実行しない。
X用（スクエア 1:1）
bash ${CLAUDE_SKILL_DIR}/scripts/generate_video.sh "<トラックディレクトリ>" square
YouTube用（16:9、字幕なし）
bash ${CLAUDE_SKILL_DIR}/scripts/generate_video.sh "<トラックディレクトリ>" youtube
YouTube用は字幕を動画に焼き込まない。SRTファイルはYouTube側で字幕として別アップする運用。
スクリプトが自動的に処理すること:
- source/track.wav, subtitle/track.srt, artwork/cover.* を検出
- 日本語ファイル名のシンボリックリンク作成→ffmpeg実行→リンク削除
- 画像を出力解像度にリサイズ（大きい画像でも動画サイズが肥大化しない）
- 画像が正方形でない場合、squareモードではcenter cropで1:1に
- youtubeモードではcover_wide.*を優先、字幕なしで生成
- ディレクトリ名からトラック名を抽出してファイル名に使用
5. 確認と修正
- まずX用（スクエア）のみ生成してユーザーに確認してもらう
- タイミングや字幕内容に問題があればSRTを修正→validate→再生成
- OKが出たらYouTube用（16:9）も生成
- 複数曲の場合は1曲ずつこのサイクルを回す
トラブルシューティング: Whisperの幻覚（2026-07-29 サイファー/マイクチェックで確認）
スクラッチ音・強いビートの曲で、whisper.sh（medium モデル）が全編「me」「Hah」等の幻覚を出すことがある。その場合は large-v3-turbo ＋ --condition-on-previous-text False で直接実行する:
uvx --from mlx-whisper mlx_whisper "<トラック>/source/track.wav" \
--language ja -f json -o "<トラック>/subtitle" \
--model mlx-community/whisper-large-v3-turbo \
--word-timestamps True --condition-on-previous-text False
- large-v3-turbo 単体でもヴァース間の幻覚が残ることがある。
--condition-on-previous-text False の併用が効く
- Suno がフレーズをまたいで歌う場合、セグメント境界が歌詞の行境界とズレる。SRT化の前に該当区間の word timestamps で行境界を確定させる
再生確認の注意
同名ファイルを再生成した時は、開きっぱなしのプレイヤーで再生すると途中から無音になる等の壊れた再生になる（上書きのため）。プレイヤーを閉じて開き直してもらう。
