/video-translate — 動画翻訳と文字起こし
機能と意図の識別(厳守すること)
- 文字起こし&ドキュメント出力:字幕または音声を書き起こし → Markdown文書を出力(字幕があれば優先。高速で無料)。
- 翻訳&動画出力:書き起こし → 翻訳・ブラッシュアップ → 中国語字幕を焼き付け → 字幕付き動画ファイル + Markdown文書を出力。
判定ルール:
- ユーザーが「書き起こして」「文字起こし」「ドキュメント出力」「Markdownで」と言った場合 → Markdown文書のみ生成(「ドキュメントのみ」フローへ)。
- ユーザーが「翻訳」「動画を翻訳」「字幕をつけて」「字幕を追加」と言った場合 → 完全翻訳パイプラインを必ず実行(音声抽出 → WhisperでSRT書き起こし → 翻訳・ブラッシュアップ → 字幕を動画に焼き付け → Markdownも同時生成)。ドキュメントだけ出力して終了してはいけない。
- 入力がURLの場合 → ダウンロードしてから処理。ローカルファイルパスの場合 → そのまま処理。
Pythonインタプリタ: このスキルのすべてのコマンドは Windows の記法で python と記述する。macOS/Linuxでは python3 に読み替えること。
SKILL_DIR の解決(コマンド実行前に必ず行う)
SKILL_DIR を、今読み込んだこのSKILL.mdが存在するディレクトリの絶対パスに設定する。スクリプトは常に SKILL_DIR/scripts/ 以下に配置する。まずチェック:
SKILL_DIR="<今ReadしたSKILL.mdのディレクトリの絶対パス>"
if [ ! -f "$SKILL_DIR/scripts/transcribe_srt.py" ]; then
echo "ERROR: scripts not found under SKILL_DIR=$SKILL_DIR" >&2
exit 1
fi
ステップ -1:出力ルートの解決(⛔ 必須、すべてに優先)
コマンド実行・ファイル書き込みの前に、必ず設定を読んで output_dir を取得し <出力ルート> とする:
python -c "import sys; sys.path.insert(0, r'${SKILL_DIR}/scripts'); import config; c = config.load_translate_config(); config.ensure_output_root(c['output_dir']); print(c['output_dir'])"
- 設定ファイルは
~/.config/video-skills/translate.json(初回はpython "${SKILL_DIR}/scripts/setup.py"でテンプレート生成可能)。 output_dirは絶対パス、または~で始まるパスであること。欠落・無効な場合は上記コマンドがエラーになる——すぐに停止し、ユーザーにそのファイルを編集して絶対パスを入力するよう促す。デフォルト値を自動入力して続行してはならない。- 中間生成物はすべて
<出力ルート>/tmp/に書き込む。最終成果物(動画、Markdown)は<出力ルート>/data/に書き込む。 - ⛔ 文中の
<出力ルート>/...はすべて実行前に実際の絶対パスに置き換えること。プレースホルダーをそのままコマンドに含めてはならない(カレントディレクトリに書き込まれ、「保存場所がおかしい」という不具合になる)。 - ユーザーが明示的に「絶対パスの出力先」を指定し確認した場合のみ、ユーザー指定のパスに書き込むことを許可する。
同時に環境事前チェックを一度実行する(/watch と共通。静かに成功すればOK):
python "${SKILL_DIR}/scripts/setup.py" --check
失敗した場合は python "${SKILL_DIR}/scripts/setup.py" を実行し依存関係をインストールする(ffmpeg/yt-dlpは自動インストール。書き起こしエンジンは pip install faster-whisper)。その他のインストール詳細は、エラーが発生したら references/インストールガイド.md を参照すること。
パイプライン概要
入力(URL / ローカルファイル)
│
▼
ステップ 0 字幕タイプのゲート(翻訳パイプラインでは必ず確認:中国語 / バイリンガル)
ステップ 1 ダウンロード + 音声抽出 → <出力ルート>/tmp/
ステップ 2 Whisper 単語レベル書き起こしから原文SRT → <出力ルート>/tmp/<ファイル名>.srt
ステップ 3 翻訳・ブラッシュアップ(あなた自身が実行。8ルール)→ <ファイル名>-zh.srt(バイリンガル時は1エントリ2行)
ステップ 4 字幕焼き付け(+オプションで透かし) → <出力ルート>/data/<タイトル>-中国語字幕.mp4
ステップ 4.5 フレームキャプチャ確認(≥2フレーム)
ステップ 5 Markdown文書生成 → <出力ルート>/data/
ドキュメントのみのシナリオではステップ0/3/4をスキップし、「ドキュメントのみ」セクションへ進む。
ステップ 0:字幕タイプの確認(⛔ ゲート。翻訳パイプラインでは必ず最初に実行)
- 中国語字幕:中国語翻訳のみ表示(画面がすっきり)。
- 中日バイリンガル字幕:中国語を上(大文字サイズ)、英語を下(小文字サイズ)。
ユーザーが会話内で字幕タイプを明確に指定した場合(「中国語」「バイリンガル」「中英」「bilingual」などと言った場合) → ユーザー指定に従う。 それ以外のすべての場合 → 必ず AskUserQuestion で選択肢を提示する:
AskUserQuestion(
question="字幕タイプを選択してください",
options=["中国語字幕(中国語のみ表示)", "中日バイリンガル字幕(中国語を上、英語を下)"]
)
⛔ 回避禁止:ARGUMENTS に含まれる字幕タイプはユーザー指定とみなさない——ユーザーが会話内で直接口頭で言った場合のみ有効。選択肢を表示せずにステップ1を開始するのはフローエラー。translate.json の subtitle_type はあくまでデフォルト値であり、ユーザーの確認に代わるものではない。
ステップ 1:ダウンロード + 音声抽出
URL の場合(スクリプトを統一使用——内蔵のブラウザcookiesが自動的にフォールバックされ、YouTubeの403/SABR/PO-tokenやBilibiliのログイン壁に対応):
# 完全な動画(翻訳パイプラインでは字幕焼き付け用に動画本体が必要)
python "${SKILL_DIR}/scripts/download.py" "<動画URL>" "<出力ルート>/tmp/dl"
# ドキュメントのみで焼き付け不要 → 音声のみで高速
python "${SKILL_DIR}/scripts/download.py" "<動画URL>" "<出力ルート>/tmp/dl" --audio
- スクリプトはJSONを出力(video_path / subtitle_path / info.title)。
- 初回はcookiesなしで試行。成果物が生成されなかった場合は自動で
--cookies-from-browser chromeを追加してリトライ。よく使うブラウザがChrome以外の場合:--browser firefox/--browser edgeを追加。 - それでも失敗する場合(より強いリスク対策)→ ユーザーにプロキシ(
--proxy http://127.0.0.1:7890)の切り替えを促してリトライ。無限リトライはしない。 - 長い動画(>10分)の場合 yt-dlp の
--download-sectionsを使用しない(最初に完全な動画をダウンロードしてからカットするため非常に遅い)。そのまま完全な動画をダウンロードし、部分が必要な場合はffmpegの-ssでカットする。
音声抽出(ローカルファイルまたはダウンロード済み動画 → mp3):
ffmpeg -y -i "<動画ファイル>" -vn -acodec libmp3lame -q:a 2 "<出力ルート>/tmp/<ファイル名>.mp3"
ステップ 2:Whisper 単語レベル書き起こしから原文SRT
⛔ 鉄則:字幕焼き付け用の原文SRTは、必ずWhisperの単語レベル書き起こしで生成すること。プラットフォームの自動字幕(yt-dlp --write-auto-subs)を時間ソースとして使用してはならない。 理由:YouTubeの自動字幕はスクロール重ね合わせ形式(各エントリに前のエントリのテキストが含まれる)であり、クリーンな文単位のテキストと正確なタイムスタンプを抽出できず、焼き付けると必ず同期がずれる。単語レベルのタイムスタンプだけが信頼できる時間ソースである。
python "${SKILL_DIR}/scripts/transcribe_srt.py" "<出力ルート>/tmp/<ファイル名>.mp3" \
--output "<出力ルート>/tmp/<ファイル名>.srt"
# 言語認識ミス / 複数言語混在トラックの場合、強制指定:--language en(または zh/ja/…)
- デフォルトエンジン = ローカル faster-whisper(単語レベルのタイムスタンプ、API費用ゼロ。初回実行時に自動でHuggingFaceからモデルをダウンロード)。
- faster-whisper がインストールできない場合 →
GROQ_API_KEY/OPENAI_API_KEYを設定して--engine apiを追加(APIによる単語レベルフォールバック。ローカルルートと同じ文分割ロジックを共有)。APIが単語レベルのタイムスタンプを返さない場合、スクリプトはセグメントレベルにダウングレードし、stderrに「字幕精度が低下しました」と明示する——この点をユーザーに伝えること。 - ⛔ 会話内で書き起こしPythonコードをその場で書かないこと——スクリプトは「文+ポーズ」で分割する(セグメントを基本単位とし、6秒を超える場合のみ単語で分割、400ms未満の場合のみマージ)。スクリプトを回避して独自にgreedy分割を書くと、A文の末尾とB文の先頭が同じフレームに押し込まれる(実戦で踏んだ罠を根本解決)。
--max-line-msで1エントリの最大時間を制御(デフォルト6000ms)、--pause-msで文区切りのポーズ閾値を制御(デフォルト500ms)。
ステップ 3:翻訳・ブラッシュアップ(あなた自身が実行——これはLLMの仕事であり、スクリプトはない)
ステップ2の原文SRTを読み込み、1エントリずつ翻訳・ブラッシュアップし、ブラッシュアップ後のSRTを <出力ルート>/tmp/<ファイル名>-zh.srt に出力する。あなたの役割:プロの字幕テキスト編集者。中国語の文章作成、口語の復元、字幕フォーマット規範に精通していること。
ブラッシュアップ8ルール(中核)
- ASR認識誤りの修正:同音・類似音の文字、固有名詞のスペルミス(例:Claude が cloud と認識される、MCP が NCP と認識される)、数字・略語・単位。動画の画面を参考に判断してもよい。
- 句読点と文語化:まず句読点を補い口語を文語に変換する(話し手のトーンは保持)。ただし最終出力の字幕テキストからはすべての句読点を削除する(カンマ、ピリオド、疑問符、感嘆符すべて削除)。中国語と英語の間には半角スペースを1つ入れる(例:
これは Google の製品)。 - 冗長性の除去:情報量のない口癖、繰り返し、フィラー(「あの」「ええと」「つまり」)を削除し、意味の連続性を保ちキー情報を失わない。少し冗長でも、意味を失わない方を優先。
- タイムスタンプの厳密な整合:元のタイムスタンプは厳密に保持し、勝手にずらしてはならない。決して手動で開始時間を早めてはならない(字幕が発話より前に表示されるようになる)。長時間表示のトリミング:1エントリの時間幅が >6秒でテキストが短い場合 = Whisperが発話後の無音/BGMを同じセグメントに含めた可能性。ffmpegの無音検出で発話終了位置を正確に特定すること。数式による推定はしない:
最初のffmpeg -i <音声> -ss <start> -to <end> -af silencedetect=n=-30dB:d=0.5 -f null - 2>&1 | grep silence_startsilence_start(startオフセットを加算)をトリミング後のendとして使用。セグメント全体が発話の場合はトリミングしない。1エントリが >8秒でテキストが長い場合、複数エントリに分割可能。タイムスタンプは元の範囲内で適切に配分する。隣接エントリの結合は禁止。分割のみ許可。分割後は番号を振り直す。タイムスタンプの重複は禁止。 - 文節と段落分け:中核原則は分割は許可、結合は禁止。1つの原文エントリに対して1つの翻訳エントリ。12文字を超える場合は意味の切れ目で2つに分割(タイムスタンプは比例配分)。基本的に1行。各行 ≤12中国語文字(スペースと英語を含む)、トーンの区切りで分割し、完全なフレーズを2つのエントリに分割しない。短く分割する方を優先し、画面上に複数行を積まない。
- 固有名詞:人名・地名・会社・製品名は原文を保持(先頭大文字)。技術用語は英語を保持(API、GPU、AI、ASR)。広く知られたブランドは翻訳しない(Google、iPhone、YouTube)。あまり知られていない用語は最初の出現時に簡単な中国語の説明を付けてもよい。
- 言語スタイル:現代の若者の言語習慣に合わせる。ネット用語・スラングは自然で親しみやすく翻訳する。翻訳調を避ける(「これはとてもワクワクすることです」→「これマジやばい」)。ナレーションは簡潔な文語、会話・歌詞は口語感を保持。
- 歌詞:♪ で囲む(
♪ 歌詞 ♪)。意味と韻を重視し、逐語訳はしない。ナレーションと交互に表示される場合、視聴者が区別できるようにする。
出力フォーマット(厳密なSRT)
1
00:00:00,000 --> 00:00:03,500
これは1つ目の字幕テキストです
2
00:00:03,500 --> 00:00:07,200
これは2つ目の字幕テキストです
番号は1から連続。タイムスタンプは HH:MM:SS,mmm(カンマでミリ秒)。テキストに句読点なし。中国語と英語の間にスペース。エントリ間に空行。ファイル末尾に空行。
バイリンガルモード(ユーザーがステップ0でバイリンガルを選択した場合)
「バイリンガルSRT」を生成:各エントリは2行——中国語を上、英語(原文)を下。タイムスタンプは原文SRTと1文1文完全に一致(再文節分割や結合はしない。原文の分割に中国語も従う)。中国語行は通常通り句読点を削除、用語を規範化。英語行は原文を保持(ASR認識誤りのみ修正):
1
00:00:19,239 --> 00:00:21,239
みなさんお元気ですか
Hello everyone, how are you?
長い動画(>10分)のセグメント並列処理
字幕エントリ数が多い場合、セグメントに分割して並列翻訳:1セグメント約500エントリ。developerの並列サブタスクで翻訳し、翻訳完了後にマージして番号を振り直す。マージ後、グローバル検証:タイムスタンプに重複・ジャンプがないこと、番号が連続していること、意味が一貫していること、フォーマットが準拠していること。
⛔ パイプラインは停止しない:ブラッシュアップ完了後すぐにステップ4(焼き付け)を実行する。中間レポートを出力したり、ユーザーの確認を待ったりしない。パイプライン全体は、最終成果物(動画 + Markdown)がすべて完了した時点で一度だけ報告する。
ステップ 4:字幕焼き付け(+オプションで透かし)
統一して burn.py を使用する——ffmpegコマンドを手組みしない。スクリプトが集中処理する内容:Windowsのパスにおけるfilter内のエスケープ(C:\a.srt → 'C\:/a.srt'。手組みでは十中八九間違う)、音声の強制AAC変換(yt-dlpのOpusトラックはX/WeChat/Weiboアップロードで失敗する。⛔ -c:a copy は禁止)、透かしのfontfile解析と時間配置、字幕+透かしを同一の -vf で一度にエンコード(2回目の画質劣化を避ける)。
中国語単独(SRT直接焼き付け):
python "${SKILL_DIR}/scripts/burn.py" "<動画ファイル>" \
--subs "<出力ルート>/tmp/<ファイル名>-zh.srt" \
--output "<出力ルート>/data/<動画タイトル>-中国語字幕.mp4"
中日バイリンガル(まずASSに変換してから焼き付け——⛔ 必ずASS経由):
python "${SKILL_DIR}/scripts/bilingual_ass.py" "<出力ルート>/tmp/<ファイル名>-zh.srt" \
--output "<出力ルート>/tmp/<ファイル名>-zh.ass" [--cn-size N] [--height 動画の高さ]
python "${SKILL_DIR}/scripts/burn.py" "<動画ファイル>" \
--subs "<出力ルート>/tmp/<ファイル名>-zh.ass" \
--output "<出力ルート>/data/<動画タイトル>-中国語字幕.mp4"
- ⛔ なぜバイリンガルはASS必須なのか:
subtitlesフィルタのforce_style FontSizeはエントリ全体に一律適用されるため、1エントリ内で中国語を大きく、英語を小さくすることができない。SRT内のインライン{\fsN}はffmpegのsrtデコーダで除去される(実際に3段階のフォントサイズでテストした結果、md5がすべて同一になった)。真のASSをlibassに渡して初めて、1エントリ内で\Nによる改行とインラインでのフォントサイズ変更が可能になる。bilingual_ass.pyはそのためのものであり、ASSを手書きしてはならない。 - フォントサイズ:ユーザーが会話内で中国語のフォントサイズを明確に指定した場合(例:「フォントサイズ24」)→
--cn-size 24を渡す。英語は自動的に 中国語 / 1.7 で計算。指定がない場合 → スクリプトが解像度に応じてデフォルトを選択。中国語︰英語 ≈ 1.7 は実測でクリーンなコントラスト比。 - ⛔ ASSのFontSize/MarginVは PlayResY=288 に対する相対値であり、ピクセルではない。libassは動画解像度に応じて自動的にスケーリングするため、解像度に比例してフォントサイズを線形に拡大してはならない(1080pの17を2倍にして4Kにすると画面の半分を占める)。1080pで MarginV=N の場合、実際は N×3.75px 程度の底面からの距離(MarginV=110 ≈ 画面中央。110pxではない)。ピクセル感覚で調整してはならない。
透かし(デフォルトではオフ。translate.json の settings.watermark_enabled: true またはユーザーが要求した場合にオン):
python "${SKILL_DIR}/scripts/burn.py" "<動画ファイル>" --subs <字幕> \
--watermark-text "<透かしテキスト>" --output <出力>
時間位置は長さに応じて自動配置(<30分:3回4秒 / 30-60分:5回5秒 / >60分:15分ごとに1回10秒。最初と最後は固定)。透明度0.28、0.5秒でフェードイン・フェードアウト、左上隅。パラメータは --watermark-opacity/--watermark-fontsize などで上書き可能。会話内で指定されたパラメータは設定ファイルより優先される。
元の動画下部にハード字幕がある場合の回避:新しい字幕は上に移動し、元の字幕を隠してはいけない:
# 1行ハード字幕
python "${SKILL_DIR}/scripts/burn.py" <動画> --subs <字幕> --avoid-hardsub single ...
# 2行、または行数が変動する場合(1文は1行、別の文は2行)→ 2行回避として扱う。1行部分の中国語が少し高くなるのは許容範囲
python "${SKILL_DIR}/scripts/burn.py" <動画> --subs <字幕> --avoid-hardsub double ...
回避段階(single=MarginV 42/FontSize 19、double=MarginV 60/FontSize 19)は経験値。フレームキャプチャ確認で合格しない場合、--margin-v で ±3-5 微調整して再焼き付けする。
最終的なコマンドが確信できない場合は、まず --dry-run でコマンドを表示して確認してから実際に実行する。
ステップ 4.5:フレームキャプチャ確認(⛔ 必須、≥2フレーム)
焼き付け後、必ずフレームキャプチャを取得しReadで確認する:字幕が完全に表示されているか、元のハード字幕を隠していないか、バイリンガルのフォントサイズ差が明確か、中国語が豆腐(フォント欠落)になっていないか:
ffmpeg -y -i "<出力動画>" -ss <時間点1> -vframes 1 "<出力ルート>/tmp/check1.jpg"
ffmpeg -y -i "<出力動画>" -ss <時間点2> -vframes 1 "<出力ルート>/tmp/check2.jpg"
回避が必要な場合、2フレームはそれぞれ元字幕が1行の時点と2行の時点を選択すること。両方のフレームで遮蔽がない場合のみ合格。1フレームだけ見て納品するのは、かつて踏んだ罠。 問題がある場合は --margin-v/--font-size を調整して再焼き付けし、再度確認する。
ステップ 5:Markdown文書生成
共通ルール(すべてのシナリオ):
- 書き起こしテキストを読み込む(SRTから番号とタイムスタンプ行を除去、または
vtt_to_text.pyでクリーニングしたテキスト)。原文の増補・削除・変更は厳禁。句読点の追加、文の結合、段落分けのみ行う。すべての内容をカバーし、漏れがあってはならない。 - 中国語コンテンツ:短い文を結合、句読点を規範化、意味に応じて段落分け → 1ファイル
<出力ルート>/data/<動画タイトル>-中国語.mdを出力。⛔ 中国語コンテンツには翻訳ルールを決して使用してはならない。 - 非中国語コンテンツ:まず原文言語で
<出力ルート>/data/<動画タイトル>-原文.mdを生成(同様に増補改変禁止)。その後、references/深度文稿规则.mdを読み、そのルールに従って<出力ルート>/data/<動画タイトル>-中国語.mdを作成する(深い記事形式。逐文直訳ではない)。 - Front matter は
title、source_urlのみを含む。
ドキュメントのみのシナリオ(ユーザーが書き起こし・テキストのみを希望し、字幕焼き付けは不要)
- 字幕付き動画は優先的に字幕を取得(無料で最速。⛔ ドキュメント出力時のみ——字幕焼き付け時はこのルートを禁止。ステップ2の鉄則を参照):
クリーニング後のプレーンテキストはトークンを約半分に削減。python "${SKILL_DIR}/scripts/download.py" "<動画URL>" "<出力ルート>/tmp/dl" --captions-only python "${SKILL_DIR}/scripts/vtt_to_text.py" "<出力ルート>/tmp/dl/<字幕>.vtt" --output "<出力ルート>/tmp/cleaned.txt"cleaned.txtを読み込み、ステップ5に従って文書を出力する。 - 字幕なし → 音声をダウンロード(
--audio)→transcribe_srt.pyで書き起こし → SRTから番号とタイムスタンプを除去してプレーンテキストを取得 → ステップ5に従って文書を出力。
一時ファイルとクリーンアップ
- 中間生成物(音声、SRT、ASS、フレームキャプチャ)はすべて
<出力ルート>/tmp/に配置。処理完了後にクリーンアップ可能。最終成果物は<出力ルート>/data/にあり影響を受けない。 - 書き起こしSRTはデバッグ用に保持してもよい。ユーザーはいつでも手動でtmp/を空にできる。
エラー処理
| 症状 | 処理 |
|---|---|
| ダウンロード失敗(403/リスク対策/ログイン壁) | スクリプトが自動でcookiesリトライ。それでも失敗した場合は --browser firefox/edge に変更、またはプロキシ設定をユーザーに提案。地域ロック・有料コンテンツであることが確認できればその旨を伝える |
| faster-whisper 未インストール | pip install faster-whisper。インストールできない場合は --engine api(APIキー必要) |
| 書き起こし言語誤認識 | --language en(または該当言語)を追加して強制的に再書き起こし |
| 焼き付け後に中国語が豆腐になる | フォント欠落——burn.py はデフォルトでプラットフォームに応じて選択(Windows: 雅黑、macOS: 苹方、Linux: Noto CJK)。Linuxでは sudo apt install fonts-noto-cjk が必要。--font-name で指定も可能 |
| 字幕が元のハード字幕を隠す | `--avoid-hardsub single |
| ディスク容量不足 | <出力ルート>/tmp/ をクリーンアップ |
| 依存関係関連のエラー | references/インストールガイド.md を読み、指示に従ってインストールした後メインフローに戻る |
依存関係チェックの原則:メインフローを直接実行し、エラーが発生したらその都度確認する——事前に1つ1つ依存関係をチェックして時間を無駄にしない。デフォルトで環境は整っている前提(ステップ-1の --check で基本項目はカバー済み)。