読み原稿カット v3
火山エンジン文字起こし + AI 言い間違い検出 + ウェブレビュー + カット後再文字起こし + AI 字幕校正
クイックスタート
ユーザー: この読み原稿動画をカットして
ユーザー: この動画を処理して
ユーザー: この画面収録をベース素材パッケージに
字幕生成を個別の Skill に分割しないでください。読み原稿カット は読み原稿ベース素材パッケージの唯一のエントリです。
ユーザーが読み原稿の画面収録を渡した場合、本 Skill はデフォルトで後続の 読み原稿本番 が直接使用できるベース素材パッケージを生成します:
source_cut.mp4 # カット後読み原稿動画
subtitles.srt # カット後動画に基づき再文字起こしされ、AI 校正された字幕
assets/ # オプションのスクリーンショット、コメント画像、結果ページ
レビューページは、ユーザーが「どこを削除するか」を確認し、新しい動画をカットするためだけに使います。字幕は元の動画の字幕を流用してはならず、火山の初回文字起こしを最終字幕として直接使ってはいけません。エージェントはカット後動画に基づいて再文字起こしを行い、AI 校正を経てから subtitles.srt に書き込む必要があります。
出力ディレクトリ構造
output/
└── YYYY-MM-DD_動画名/
├── 読み原稿カット/
│ ├── 1_文字起こし/
│ │ ├── audio.mp3
│ │ ├── volcengine_result.json
│ │ └── subtitles_words.json
│ ├── 2_分析/
│ │ ├── readable.txt
│ │ ├── auto_selected.json
│ │ └── 言い間違い分析.md
│ └── 3_レビュー/
│ ├── review.html
│ └── video.mp4 → 元動画(シンボリックリンク)
└── 字幕/
├── 1_文字起こし/
│ ├── audio.mp3
│ └── volcengine_result.json
├── subtitles_with_time.json
└── 3_出力/
├── video.raw.srt
└── video.srt
ルール: 既存フォルダは再利用し、なければ新規作成。
フロー
0. 出力ディレクトリ作成
↓
1. 音声抽出 (ffmpeg)
↓
2. 火山エンジン録音ファイル認識 2.0 呼び出し (Seed ASR v3)
↓
3. volcengine_result.json 生成
↓
4. 単語レベルの字幕生成 (subtitles_words.json)
↓
5. AI による言い間違い/無音分析、事前選択リスト生成 (auto_selected.json)
↓
6. レビューウェブページ生成 (review.html)
↓
7. レビューサーバー起動、ユーザーがウェブページで確認
↓
【ユーザー確認待ち】→ ウェブページで「カット実行」をクリック
↓
8. サーバーが新しい動画のみをカット
↓
9. エージェントがカット後動画の生成完了を監視
↓
10. カット後動画に基づき音声を再抽出、火山に文字起こし依頼、video.raw.srt 生成
↓
11. エージェントが原稿/本文と照合して AI 校正、video.srt 書き込み
↓
12. ベース素材パッケージ整理: source_cut.mp4 + subtitles.srt + オプション assets/
カット後字幕のハードルール:
- カット後動画に基づいて再文字起こしする必要があり、元の動画の字幕から逆算してはならない。
- 火山の文字起こしは初稿であり、
video.raw.srtに出力する。 video.srt/subtitles.srtはエージェントが AI 校正した最終字幕のみとする。- 校正時はユーザーから提供された読み原稿、本文、固有名詞、文脈を参照して、用語、同音誤認識、文の区切りを修正する。動画内で話されていない内容を追加してはならない。
実行手順
手順 0: 出力ディレクトリ作成
# 変数設定(実際の動画に応じて調整)
VIDEO_PATH="/path/to/動画.mp4"
VIDEO_NAME=$(basename "$VIDEO_PATH" .mp4)
DATE=$(date +%Y-%m-%d)
BASE_DIR="output/${DATE}_${VIDEO_NAME}/読み原稿カット"
# サブディレクトリ作成
mkdir -p "$BASE_DIR/1_文字起こし" "$BASE_DIR/2_分析" "$BASE_DIR/3_レビュー"
cd "$BASE_DIR"
手順 1-3: 文字起こし
cd 1_文字起こし
# 1. 音声抽出(ファイル名にコロンがある場合は file: プレフィックスが必要)
ffmpeg -i "file:$VIDEO_PATH" -vn -acodec libmp3lame -y audio.mp3
# 2. 火山エンジン録音ファイル認識 2.0 呼び出し(デフォルト resource_id=volc.seedasr.auc)
SKILL_DIR="/Volumes/成峰/コード/剪辑Agent/.claude/skills/読み原稿カット"
"$SKILL_DIR/scripts/volcengine_transcribe.sh" audio.mp3
# 出力: volcengine_result.json
文字起こしスクリプトはデフォルトで火山 v3 Seed ASR 2.0 を使用:
POST /api/v3/auc/bigmodel/submit
POST /api/v3/auc/bigmodel/query
X-Api-Resource-Id: volc.seedasr.auc
一時的に他のリソースにフォールバックまたは比較する場合は、環境変数で上書き:
VOLCENGINE_ASR_RESOURCE_ID=volc.bigasr.auc "$SKILL_DIR/scripts/volcengine_transcribe.sh" audio.mp3
手順 4: 単語レベルのタイムライン生成
node "$SKILL_DIR/scripts/generate_subtitles.js" volcengine_result.json
# 出力: subtitles_words.json
cd ..
タイムスタンプルール:
generate_subtitles.jsはresult.utterances(v3)と旧版utterancesの両方に対応する必要がある。- v3 結果内の無効なタイムスタンプトークン(多くはスペース、
start_time/end_time = -1)はフィルタリングする必要がある。そうしないと誤った無音が発生する。 - 2026-06-25 の 180 秒サンプル評価: Seed ASR 2.0 の校正字幕タイムウィンドウに対する単語境界オフセット中央値は約 80ms、P90 は約 240ms、最大約 620ms。デフォルトの読み原稿カットタイムラインとして使用可能だが、長い文は単語レベルのタイムスタンプに基づいて字幕行に再分割する必要がある。
手順 5: 言い間違い分析(スクリプト+AI)
5.1 読みやすい形式を生成
cd 2_分析
node -e "
const data = require('../1_文字起こし/subtitles_words.json');
let output = [];
data.forEach((w, i) => {
if (w.isGap) {
const dur = (w.end - w.start).toFixed(2);
if (dur >= 0.2) output.push(i + '|[無' + dur + 's]|' + w.start.toFixed(2) + '-' + w.end.toFixed(2));
} else {
output.push(i + '|' + w.text + '|' + w.start.toFixed(2) + '-' + w.end.toFixed(2));
}
});
require('fs').writeFileSync('readable.txt', output.join('\\n'));
"
5.2 ユーザー習慣を読み込む
まず ユーザー習慣/ ディレクトリ内のすべてのルールファイルを読む。
5.3 文リストを生成(重要な手順)
まず文に分割し、その後分析する。 無音で区切って文リストを作成:
node -e "
const data = require('../1_文字起こし/subtitles_words.json');
let sentences = [];
let curr = { text: '', startIdx: -1, endIdx: -1 };
data.forEach((w, i) => {
const isLongGap = w.isGap && (w.end - w.start) >= 0.5;
if (isLongGap) {
if (curr.text.length > 0) sentences.push({...curr});
curr = { text: '', startIdx: -1, endIdx: -1 };
} else if (!w.isGap) {
if (curr.startIdx === -1) curr.startIdx = i;
curr.text += w.text;
curr.endIdx = i;
}
});
if (curr.text.length > 0) sentences.push(curr);
sentences.forEach((s, i) => {
console.log(i + '|' + s.startIdx + '-' + s.endIdx + '|' + s.text);
});
" > sentences.txt
5.4 スクリプトで自動的に無音をマーク(必ず先に実行)
node -e "
const words = require('../1_文字起こし/subtitles_words.json');
const selected = [];
words.forEach((w, i) => {
if (w.isGap && (w.end - w.start) >= 0.2) selected.push(i);
});
require('fs').writeFileSync('auto_selected.json', JSON.stringify(selected, null, 2));
console.log('≥0.2sの無音数:', selected.length);
"
→ auto_selected.json を出力(無音 idx のみ)
5.4b 頭尾のトリミング(文字起こしの死角、必須)
🚨 火山は音声のみを文字起こしし、末尾の文字起こしされていない雑音/終了動作は字幕に含まれず、すべての検出器は見えない。 動画の長さを比較して補う必要がある。
ユーザー習慣/3-無音区間処理.mdを参照。
VDUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "file:$VIDEO_PATH")
node -e "
const fs=require('fs');
const w=require('../1_文字起こし/subtitles_words.json');
const auto=require('./auto_selected.json');
const VDUR=$VDUR, last=w[w.length-1];
if(VDUR - last.end > 0.3){ // 末尾未カバー → 末尾要素を追加し事前選択
w.push({text:'',start:last.end,end:VDUR,isGap:true,reason:'末尾未文字起こし(雑音/終了)'});
auto.push(w.length-1);
fs.writeFileSync('../1_文字起こし/subtitles_words.json',JSON.stringify(w));
fs.writeFileSync('./auto_selected.json',JSON.stringify([...new Set(auto)].sort((a,b)=>a-b),null,1));
console.log('末尾要素追加 idx',w.length-1,'['+last.end+'→'+VDUR+']');
} else console.log('末尾は既にカバーされています');
if(w[0].start>0.3) console.log('⚠️ 先頭',w[0].start,'s がカバーされていません。先頭要素の追加を検討してください');
"
5.5 AI による言い間違い分析(auto_selected.json に追記)
🚨 核心原則: 削除は前を優先。すべての重複/言い間違いは、前のものを削除し、後のものを保持する。
検出タイプごとにエージェントを分担し、並列実行:
各エージェントは1つの検出のみを担当し、プロンプトを短く正確にし、ルールの相互干渉を避ける。
| エージェント | 入力 | 検出内容 | 削除範囲 |
|---|---|---|---|
| A-文間重複 | sentences.txt | 隣接/1文飛ばして先頭5文字以上が同一 | 前の文全体を削除 |
| B-文内重複 | sentences.txt | 同一文内で A+中間+A のパターン | 前の断片のみ削除、文全体は削除しない |
| C-不完全文 | sentences.txt | 言いかけて無音+後で言い直し | 不完全文全体を削除 |
スクリプトで直接処理可能(AI 不要):
- 吃音語(あのあの、えーっと)→ 正規表現
- フィラー(うん、あー、えー)→ 手動確認待ちとしてマーク
検証(verify)—— リスクに応じて投入し、全面展開しない(ユーザー習慣/10-削除リスク階層.md を参照):
- 低リスクは検証不要: 無音、一字一句のサブセット重複(削除対象が保持内容の一字一句の先頭、例:「私は同じ文を」を削除し「私は同じ文のことを」を保持)、≤3字の純粋な詰まり/フィラー → 直接 auto_selected に入れ、ウェブページでの手動確認でカバー。
- 高リスクは必ず検証: 文全体の削除、「先頭が一致し末尾が分岐」(例:「予算を超えた」vs「計画能力を超えた」)、長い断片の重複 → 対抗レビュアーを送り、固有の内容を削除していないことを確認。
- 教訓: 以前すべての候補に対して 2× 検証を行ったところ、ヒットは ~4/91 で、すべて高リスククラスに該当(
log/参照)。検証は高コストなので、削除を誤りやすい箇所に限定して投入すべき。
エージェントプロンプトテンプレート:
各エージェントへのプロンプトには以下を含める:
1. そのエージェントに対応する1つの検出ルールのみ(ユーザー習慣/から読み込み)
2. 完全な sentences.txt 内容
3. 明確な要求: 削除する idx 範囲のリストを返すこと
4. 🚨 「前削除、後保持」を強調: 前のバージョンを削除し、後のより完全なバージョンを保持
エージェント戻り値形式:
| 文番号 | idx範囲 | タイプ | 内容概要 | 処理 |
|------|---------|------|----------|------|
削除idxリスト: [すべての削除するidx]
結果のマージ:
すべてのエージェントから返された idx リストを収集 → auto_selected.json にマージ → 重複除去・ソート
範囲全体削除ルール: 言い間違いをマークする際、startIdx から endIdx までのすべての要素(中間の gap を含む)を auto_selected に追加する。個別に文字 idx を選択して gap をスキップしないこと。
🚨 重要警告: 行番号 ≠ idx
readable.txt 形式: idx|内容|時間
↑ この値を使用
行番号1500 → "1568|[無1.02s]|..." ← idxは1568、行番号1500ではありません!
言い間違い分析.md 形式:
## 文間重複 (Agent A)
| 文番号 | idx範囲 | 内容概要 | 処理 |
|------|---------|----------|------|
| 5 | 212-233 | 文6と重複、文6の方が完全 | 前の文を削除 |
## 文内重複 (Agent B)
| 文番号 | idx範囲 | 内容概要 | 処理 |
|------|---------|----------|------|
| 16 | 492-510 | 「多くの人がCLIコマンドと言うと」前半重複 | 断片を削除 |
## 不完全文 (Agent C)
| 文番号 | idx範囲 | 内容概要 | 処理 |
|------|---------|----------|------|
| 7 | 266-275 | 「説明するために、この質問に答えるために」未完了 | 文全体を削除 |
5.6 読み原稿アライメントによる補完(読み原稿がある場合)
ユーザーが読み原稿/原文稿を提供する場合(読み原稿は原稿を読んでいる)、それを文レベルのアライメントによる補完に使用する —— ユーザー習慣/11-読み原稿アライメント.md を参照。
読み原稿 = 意味の ground truth(言い回しは変わる可能性あり、例:「2つのモデル」↔「2つの大規模モデル」、一字一句 diff しない)。各文字起こし文を読み原稿の文にアライメントし、純粋なテキスト検出で見逃された文レベルの言い間違いを捉える: 文全体の言い直し、不完全文、対応する読み原稿なし —— 特に技術用語の詰まり(Mindverse / δ-mem / LoRA を間違えて言い直し、「Delta Mam」、孤立した単字「から」)。このような文全体の削除は高リスク → 検証を経て、保持されたバージョンが読み原稿の本来の意味をカバーしていることを確認。
手順 6-7: レビュー
cd ../3_レビュー
# 6. レビューウェブページ生成(動画ファイルを渡し、自動でシンボリックリンク作成)
node "$SKILL_DIR/scripts/generate_review.js" ../1_文字起こし/subtitles_words.json ../2_分析/auto_selected.json "$VIDEO_PATH"
# 出力: review.html, video.mp4(シンボリックリンク)
# 7. レビューサーバー起動
node "$SKILL_DIR/scripts/review_server.js" 8899 "$VIDEO_PATH"
# 開く http://localhost:8899
⚠️ review_server.js を使用する必要があります。
python3 -m http.serverでは代用できません。 理由: 動画再生は HTTP Range リクエスト(206)に依存しており、python の簡易サーバーは対応していないため、動画が再生できなかったり音声が出なかったりします。 一般ユーザーはこのターミナルウィンドウを開いたままにしておけばOKです。Claude Code / Codex では、エージェントが現在の環境で利用可能なバックグラウンドタスク機能を使用してホストします。ユーザーに tmux のインストールを要求しないでください。
ユーザーはウェブページで:
- 動画を再生して確認
- 削除項目をチェック/チェック解除
- 左クリックで文字をなぞって一括削除/復元(複数行にまたがる操作対応)。ドラッグしすぎた場合、手を離さずに戻すと選択範囲がリアルタイムで狭まります
- 「カット実行」をクリック
手順 8: カット後動画の監視
ユーザーがレビューページのボタンをクリックすると、review_server.js は新しい動画のみをカットし、レビューディレクトリに cut_done.json を書き込みます。エージェントはこのファイルを監視し、カット後動画が実際に生成され、サイズが安定していることを確認する必要があります。
# 別のエージェントタスク/ターミナルで、ユーザー確認後のカット結果を待つ
node "$SKILL_DIR/scripts/watch_cut_done.js" "output/YYYY-MM-DD_動画名/読み原稿カット/3_レビュー"
監視結果はカット後動画のパスを返します:
{
"output": "output/YYYY-MM-DD_動画名/読み原稿カット/3_レビュー/動画名_cut.mp4",
"newDuration": "123.45",
"outputSize": 12345678
}
戻り値の output を CUT_VIDEO として記録し、後続の字幕はこの動画に基づいて再文字起こしする必要があります。
curl /api/cut やスクリプトでクリックをシミュレートしないでください。ユーザーが明示的に許可した場合を除きます。
手順 9: カット後動画に基づいて再文字起こし
"$SKILL_DIR/scripts/generate_srt_for_video.sh" "カット後動画.mp4" "output/YYYY-MM-DD_動画名/字幕"
字幕はカット後動画に基づいて再文字起こしする必要があり、元の動画の字幕から逆算してはなりません。
この手順では、火山の初回文字起こしのみを出力します:
output/YYYY-MM-DD_動画名/字幕/1_文字起こし/volcengine_result.json
output/YYYY-MM-DD_動画名/字幕/subtitles_with_time.json
output/YYYY-MM-DD_動画名/字幕/3_出力/video.raw.srt
手順 10: AI による字幕校正
エージェントは video.raw.srt または subtitles_with_time.json を読み込み、ユーザーから提供された読み原稿/本文/固有名詞/文脈を参照して AI 校正を行う必要があります。
校正ルール:
- 元のタイムラインを保持し、字幕テキストのみを優先的に変更する。
- 技術用語、ツール名、人名、英単語、同音誤認識を修正する。
- 明らかに不適切な文の区切りを調整する。
- 動画内で話されていない内容を追加しない。
- 校正完了後、
字幕/3_出力/video.srtに書き込む。
手順 11: ベース素材パッケージの整理
AI 校正完了後、カット後動画と最終字幕をプロジェクトルートディレクトリに整理します:
OUTPUT_ROOT="output/YYYY-MM-DD_動画名"
ln -sf "$CUT_VIDEO" "$OUTPUT_ROOT/source_cut.mp4"
ln -sf "$OUTPUT_ROOT/字幕/3_出力/video.srt" "$OUTPUT_ROOT/subtitles.srt"
最終成果物には少なくとも以下を含む:
output/YYYY-MM-DD_動画名/字幕/3_出力/video.srt
output/YYYY-MM-DD_動画名/source_cut.mp4
output/YYYY-MM-DD_動画名/subtitles.srt
ユーザーが次のステップで 読み原稿本番 を実行する場合、成果物を以下のように整理します:
source_cut.mp4 = カット後読み原稿動画
subtitles.srt = AI 校正後のカット後字幕 SRT
assets/ = オプション素材
source_cut.mp4 と subtitles.srt はシンボリックリンクでも可。ユーザーに報告する際は、それらがカット後動画とカット後字幕を指していることを明示します。
レビューのハードルール
レビューページの手順で必ず停止し、リンクをユーザーに渡します。
ユーザーが確認するまで、エージェントは次の3つのことのみ行えます:
review.htmlの生成review_server.jsの起動- ユーザーにレビューページの URL を伝える
ユーザーが明示的に「実行をクリックして」または「直接カットして」と言わない限り、エージェントは以下を許可されません:
/api/cutの直接呼び出し- curl/スクリプトによるクリックのシミュレート
- レビューページをスキップしてカット後動画を直接生成
ユーザーがレビューページで「カット実行」をクリックした後、サーバーはカット後動画のみを生成します。エージェントはカット後動画の完了を監視した後、カット後の再文字起こしと AI 字幕校正に進むことができます。
データ形式
subtitles_words.json
[
{"text": "大", "start": 0.12, "end": 0.2, "isGap": false},
{"text": "", "start": 6.78, "end": 7.48, "isGap": true}
]
auto_selected.json
[72, 85, 120] // Claude 分析で生成された事前選択インデックス
カットエンコーディング(ハードルール)
⚠️ 元の動画パラメータに合わせて再エンコードし、フレームレベルで正確にカット。
cut_video.sh の動作方法:
- 元の動画のエンコードパラメータ(codec/profile/pix_fmt/bitrate)を自動検出
filter_complexで trim+concat を使用してフレームレベルで正確にカット- 同じパラメータで再エンコード:
-profile:v high -b:v {元の動画ビットレート} -pix_fmt yuv420p
重要: 再エンコードの画質は元の動画パラメータに一致するかどうかに依存し、CRF 値ではありません。
- ✅
-b:v {元の動画ビットレート} -profile:v high -pix_fmt yuv420p→ 目視で違いなし - ❌
-crf Nのみ指定し、profile/pix_fmt を指定しない → ずれが生じる可能性あり
設定
火山エンジン API Key
ユーザーが火山音声認識 API Key を持っていない場合、まず火山コンソールで「録音ファイル認識 2.0」を有効にし、API Key を作成するよう依頼:
https://console.volcengine.com/speech/new/setting/activate?projectName=default
現在のデフォルトモデルリソース:
録音ファイル認識 2.0 / Seed ASR
resource_id = volc.seedasr.auc
Key を取得したら、Skills ルートディレクトリの .env に書き込む:
cd /Volumes/成峰/コード/剪辑Agent/.claude/skills
cp .env.example .env
# .env を編集し、VOLCENGINE_API_KEY=xxx を記入
npm でインストールした場合、Skills ルートディレクトリは通常:
~/.claude/skills/chengfeng-videocut-skills
~/.codex/skills/chengfeng-videocut-skills