cut-silences

無音のカット（パイプラインエージェント 1）

自動編集の最初のステップです。未編集の録音と単語レベルの文字起こしを受け取り、無音のみを削除します。最初の単語の前と最後の単語の後の無音に加え、しきい値を超える単語間のポーズを、自然な呼吸分の間隔まで短縮します。完全に無音にはしません。話者の発話には手を加えません。言い間違い、撮り直し、どもりは「ミスカット」エージェント（エージェント 2）の担当です。

このエージェントは決定論的で、文字起こしに基づいて処理します。そのため、出力（*.silence-transcript.json）は次のエージェントやビート同期バリデーターにそのまま渡せます。

使用する場面

• 「無音をカット」「ポーズをトリミング」「無音部分を削除」「テンポを良くする」
• 文字起こしの直後に行う、マスター編集ワークフローの最初の段階として。

前提条件

単語レベルの文字起こし JSON が必要です。ElevenLabs Scribe 形式（ { words: [{ text, start, end, type }], audio_duration_secs }）または一般的な { words: [{ text, start, end }] } のいずれかを使用できます。ワークスペースの文字起こしツールで生成してください。

node scripts/transcribe-elevenlabs.mjs path/to/raw.mp4    # -> path/to/raw.json

使い方

# 1) Plan only — compute the cut, write EDL + re-timed transcript (no video touched)
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcript.json> \
  --out-dir video-projects/<slug>/assets

# 2) With a video — also write the ffmpeg command (still does not render yet)
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcript.json> \
  --video video-projects/<slug>/assets/raw.mp4 --out-dir video-projects/<slug>/assets

# 3) Render the cut video (local ffmpeg, re-encode, A/V kept in sync)
#    add --apply to actually run ffmpeg
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcript.json> \
  --video video-projects/<slug>/assets/raw.mp4 --apply \
  --output video-projects/<slug>/assets/edited-silenced.mp4

オプション

フラグ	デフォルト	説明
--video <path>	—	ソース動画。ffmpeg コマンドとレンダリングを有効にします
--out-dir <dir>	文字起こしファイルと同じ場所	出力先
--output <path>	<video-stem>.silenced.mp4	カット後の動画ファイルのパス
--gap <s>	0.55	トリミング対象の無音とみなす最小ポーズ
--head-pad <s>	0.22	最初の単語の前に残す無音
--tail-pad <s>	0.34	最後の単語の後に残す無音
--apply	オフ	ffmpeg を実行してカットをレンダリングします

判定方法（無音のルール）

• --gap（0.55s）未満のポーズはそのまま残します。自然な話し方のリズムを保つためです。
• トリミングするポーズには、自然な呼吸分の間隔を残します。長いポーズ（≥2s）では 0.24s、文末記号（. ! ?）の後では 0.20s、それ以外では 0.14s と、文脈に応じて調整されます。残す間隔は、直前のフレーズの終わり寄りになります。
• 冒頭と末尾の無音は、--head-pad／--tail-pad で指定した長さまでトリミングします。
• 削除範囲は統合し、残す範囲はその補集合として扱います。カットは ffmpeg の trim／atrim と concat フィルターグラフでレンダリングします（*.silence-filter.txt スクリプトに書き込み、-/filter_complex 経由で渡します）。これにより、映像と音声の同期が保たれます。

出力（--out-dir に書き込み）

ファイル	用途
<stem>.silence-edl.json	残す範囲と削除範囲、長さ、パラメーター（編集リスト）
<stem>.silence-transcript.json	編集後のタイムラインに合わせて再設定した単語の時刻（エージェント 2 とビート処理に渡します）
<stem>.silence-decisions.md	人が読める概要と、トリミングされた最長のポーズ
<stem>.silence-filter.txt	ffmpeg フィルターグラフ（--video を指定した場合のみ）
<video-stem>.silenced.mp4	カット後の動画（--apply を指定した場合のみ）

標準出力に表示される JSON の概要には、removed、removedPct、範囲の件数、出力パスが含まれます。マスターワークフローでの記録や、後続処理への受け渡しに便利です。

調整のヒント

• トーキングヘッド形式の YouTube 動画では、デフォルトの --gap 0.55 により、一般的な未編集のテイクから純粋な無音が約 15～20% 削除されます。より歯切れよくテンポの速いカットにするには --gap を下げ、自然な呼吸の間を多く残すには上げてください。
• 文の切れ目でのカットが強すぎると感じる場合は、文の切れ目に残す呼吸分の間隔を長くするか、--gap を上げてください。

次のエージェントへの引き継ぎ

<stem>.silence-transcript.json（レンダリングした場合は silenced.mp4 も）をミスカットエージェントに渡してください。タイムスタンプはすでに編集後のタイムラインに合わせてあるため、後続のビートのタイミング調整や scripts/validate-beat-sync.mjs では追加の調整は不要です。