video-compressor

video-compressor — 動画圧縮ツール

FFmpeg を使用して動画ファイルを低ビットレートの MP4 に圧縮し、音声の明瞭さを保ちながらファイルサイズを縮小します。ハードウェアを自動検出して最適なエンコード方式を選択します（Apple Silicon ではデフォルトで VideoToolbox のハードウェアアクセラレーションを使用します）。

使用シーン

• 動画ファイルが大きすぎる場合に、音声情報だけを残し、動画は補助的な参考情報として利用する
• ディレクトリ内の複数の動画ファイルを一括で圧縮する
• 動画のビットレートを下げてストレージ容量を節約する
• 動画中の無音・静止区間（休憩時間、黒画面、無音の空白など）を削除しつつ、切り取った区間を確認用に保持する

機能モード

このスキルは、次の2つの動作モードに対応しています。

モード1：圧縮（デフォルト）

動画を低ビットレートの MP4 に圧縮し、ファイルサイズを縮小します。

モード2：無音・静止区間の切り取り

動画内で以下の条件を両方満たす区間を検出して削除します。

1. 音声が無音（音がない）
2. 映像が静止（連続するフレームにほとんど変化がない。休憩中に操作がない場合や黒画面など）

用途：講義の録画中の休憩、会議室が無人のときの静かな待機時間など、不要な内容の削除。

デフォルトのワークフロー（圧縮モード）

1. 入力の確認

ユーザーが指定したファイルパスまたはディレクトリパスを確認します。次の動画形式に対応しています。

.mp4 .mov .avi .mkv .webm .flv .wmv .ts

2. パラメーターの確認

デフォルト設定（ほとんどの場合、変更は不要です）。

パラメーター	デフォルト値	説明
CRF 品質値	23	適応型の品質設定です。値が小さいほど高画質です（ソフトウェアエンコードのみ）
最大ビットレート	2500k	VBV ビットレートの上限
音声ビットレート	96k	AAC 音声の音質
エンコードプリセット	veryfast	速度と圧縮率のバランスを調整します（ソフトウェアエンコードのみ）
エンコーダー	自動検出	Apple Silicon ではデフォルトで HEVC VT、それ以外では x264
同時実行スレッド数	自動	VideoToolbox ではデフォルトで 1（ハードウェアエンコーダーを共有するため、同時実行数を増やすとかえって遅くなります）。ソフトウェアエンコードではデフォルトで ≤8
出力ファイル名のサフィックス	_compressed	出力ファイル名に付けるサフィックス

設定の詳細については、references/config.md を参照してください。

3. 圧縮の実行

# 单个文件
python3 scripts/compress.py -i <文件路径>

# 多个文件（并发压缩）
python3 scripts/compress.py -i <文件1> <文件2> <文件3>

# 整个目录
python3 scripts/compress.py -i <目录路径>

# 混合：文件 + 目录
python3 scripts/compress.py -i <文件1> <目录路径> <文件2>

カスタムパラメーターを指定する場合：

python3 scripts/compress.py -i <文件1> <文件2> --crf 28 -a 64k --preset medium -j 2

4. 結果レポートの出力

圧縮完了後、ファイルごとの結果を出力します。

文件名                    原始大小    压缩后大小   压缩比
video1.mp4                120.5 MB    28.3 MB     76.5%
─────────────────────────────────────────────────
合计                       205.7 MB    47.4 MB     77.0%

無音・静止区間の切り取りワークフロー

使用するタイミング

ユーザーが以下のような状況に言及した場合は、このモードを使用します。

• 動画の途中に休憩時間があり、削除したい
• 動画に長時間の静止・無音区間がある
• 録画中の空白時間、無音、黒画面を削除したい

1. 切り取りの実行

python3 scripts/trim_silences.py -i <视频文件路径>

デフォルトのパラメーターを使用します（無音と静止を同時に検出し、最短3秒から対象にします）。

カスタムパラメーターを指定する場合：

# 仅检测静音片段（不考虑画面是否静止）
python3 scripts/trim_silences.py -i <路径> --mode silence

# 仅检测画面静止片段（不考虑是否有声音）
python3 scripts/trim_silences.py -i <路径> --mode static

# 自定义阈值：更严格的静默检测
python3 scripts/trim_silences.py -i <路径> --noise-db -40 --min-duration 5

モード選択の推奨

動画の種類	推奨モード	説明
講義の録画中の休憩	both	無音と静止の両方を条件とし、誤って切り取らないようにします
会議室が無人の時間帯	both または static	空調のホワイトノイズが常にある場合は both を使用します
試合・映画の解説（全編に音声がある場合）	static	映像が静止している部分のみを切り取ります
監視カメラの録画（映像が固定されている場合）	static	音声はほとんど必要ありません

2. 出力内容の確認

切り取り完了後、以下が出力されます。

ファイル	説明
原文件名_trimmed.mp4	編集済みバージョン（対象区間を削除済み）
原文件名_cuts/	切り取った区間を保存するディレクトリ
原文件名_cuts/_report.json	切り取った区間のタイムスタンプレポート

切り取った区間のディレクトリには、各区間が個別の MP4 ファイルとして保存されます。ファイル名には開始時刻と終了時刻が含まれるため、簡単に確認できます。

3. パラメーターの説明

パラメーター	デフォルト値	説明
--noise-db	-30	無音検出のデシベル閾値です。値が小さいほど厳しくなります
--scene-threshold	0.05	映像の静止判定閾値（0～1）です。値が小さいほど厳しくなります（わずかな画面変化は許容されます）
--min-duration	120	区間の最短時間（秒）。デフォルトは2分で、長い区間のみを切り取ります
--mode	both	検出モード：both=無音と静止の両方、silence=無音のみ、static=映像の静止のみ
--crf	23	CRF 品質値
--maxrate	2500k	最大ビットレートの上限
--bufsize	2500k	VBV バッファーサイズ
--audio-bitrate	96k	出力音声のビットレート
--preset	veryfast	エンコードプリセット
--codec	自動検出	エンコーダーの選択（hevc_vt / h264_vt / x264 / x265 / x264_fast）

ハードウェアアクセラレーション

このツールはシステムのハードウェアを自動検出し、最適なエンコード方式を選択します。

プラットフォーム	エンコーダー	速度向上（実測）	出力形式	説明
Apple Silicon (M1/M2/M3/M4)	hevc_videotoolbox	機種ごとの冷却性能による差が非常に大きいため、実際の測定結果を優先してください（下記の実測メモを参照）	HEVC/H.265	ハードウェアエンコードを自動的に使用します
Apple Silicon（代替）	h264_videotoolbox	同上	H.264	HEVC が使用できない場合のフォールバック
その他のプラットフォーム	libx264	1x リアルタイム	H.264	標準的なソフトウェアエンコード

実測値の参考（ファンレスの MacBook Air M1、8GB）：

• x264 veryfast CRF28 のソフトウェアエンコード：約 5～7× リアルタイム（単一プロセス）。同時実行4～6個の場合は約 10× リアルタイム（この機種の熱による性能低下の限界に達しています）。さらに同時実行数を増やすとかえって低下します
• HandBrake vt_h264：x264 より約 15% 高速ですが、出力ファイルのサイズは 60% 大きく、メリットは大きくありません
• brew ffmpeg に組み込まれた VideoToolbox のハードウェアデコード経路は使用できません（hwaccel_output_format=videotoolbox で Unrecognised hwaccel output format が発生します。brew のビルドには VT のハードウェアフレーム出力が含まれていません）
• x264 では preset の変更（ultrafast ↔ veryfast）による速度への影響は無視できる程度で、速度向上のために preset を下げる価値はありません

速度に関する注意：上記の値は実測に基づく参考範囲です。実際の速度は解像度、フレームレート、画質パラメーター、システム負荷によって異なります。同時実行時のスループットをテストする際は、各子プロセスの rc（return code）を必ず確認してください。プロセスがすぐに終了すると「高速」という誤った結果になるため、実行中に実際の出力ファイルサイズとエンコード時間を確認する必要があります。画面録画・教材のソースビットレートは ≤3Mbps が目安です。圧縮前に ffprobe -v error -show_entries format=bit_rate -of csv=p=0 <file> で確認してください。

画面録画・教材のソースビットレートに関する注意点（v1.5.0 で自動化済み）：圧縮前に ffprobe でソースファイルの bit_rate を確認します。ハードウェア経路（hevc_vt/h264_vt）は hw_detect.py で目標ビットレートが 2000k に固定されており、--crf/--maxrate パラメーターは無視されます。ソースの総ビットレートが ≤3 Mbps（画面録画・教材の特徴）の場合、スクリプトは x264 CRF 適応型エンコードを自動選択し、メッセージを表示します。高ビットレートのソースは引き続きハードウェア経路を使用します。--codec を明示的に指定すると、自動選択を上書きできます。CRF 適応型エンコードは静止画面ではビットレートをほとんど消費しません。画面録画の実測圧縮率は80～88%、速度は12～20x リアルタイムです。手動で見積もる場合は、60秒間のサンプルを使用できます。ffmpeg -ss <中段> -t 60 -i 输入 -c:v libx264 -crf 23 ... でサンプルサイズを確認し、動画全体のサイズを推定してください。

起動時に検出結果が自動的に表示されます。例：

硬件检测: Apple Silicon (10 核 / 64 GB)
编码器: HEVC VideoToolbox (硬件加速) — 实际 1080p60 约 2-5x 实时
FFmpeg: 9.0 (VideoToolbox 支持: H.264 + HEVC)

エンコーダーを手動で指定する場合：

python3 scripts/compress.py -i <路径> --codec hevc_vt   # 强制 HEVC 硬件编码
python3 scripts/compress.py -i <路径> --codec h264_vt   # 强制 H.264 硬件编码
python3 scripts/compress.py -i <路径> --codec x264      # 强制软件编码
python3 scripts/compress.py -i <路径> --codec x265      # 软件 HEVC 编码（高压缩）

使用可能なエンコーダー：hevc_vt h264_vt x264 x265 x264_fast

長時間の動画と detach モード

30分を超える動画では、--detach を付けて起動することをおすすめします。

python3 scripts/compress.py -i <长视频.mp4> --codec hevc_vt --detach

--detach の動作：

• スクリプトは ffmpeg の起動後、PID を返してすぐに終了し、処理完了を待ちません
• ffmpeg プロセスはスクリプトのセッショングループから分離されます（start_new_session）。スクリプトが強制終了されてもエンコードには影響しません
• ログは /tmp/ffmpeg_<视频名>_<时间戳>.log に書き込まれ、tail -f で追跡できます

トラブルシューティング

ffmpeg バイナリの起動時クラッシュ（dyld Library not loaded）

症状：スクリプトの起動直後に「dyld Symbol not found」または「Library not loaded」と表示されます。

原因：よくあるケースは、brew upgrade で x265 などの依存ライブラリをアップグレードした後、ffmpeg が再リンクされていないことです。ffmpeg バイナリが引き続き旧バージョンのシンボルを参照しています。

修正：

brew upgrade ffmpeg        # 让 ffmpeg 重新链接到新依赖
# 或
brew reinstall ffmpeg      # 完全重装

新しいスクリプトは起動時に ffmpeg の健全性を積極的にチェックします。クラッシュした場合は、診断内容と修正コマンドをすぐに出力し、無言でフォールバックすることはありません。

stderr ログの全文

失敗時の ffmpeg ログ全文は /tmp/ffmpeg_<视频名>_<时间戳>.log に保存され、切り詰められて重要な診断情報が失われることはありません。

厳守事項

• 元ファイルを上書きしない：出力ファイルには常にサフィックスを追加します
• 既存の出力を無言で上書きしない：出力ファイルがすでに存在する場合は、自動的に _compressed_2 などの連番に切り替えます。上書きが許可されるのは --overwrite を指定した場合のみです
• 同じディレクトリに出力する：トリミング版と切り出したクリップのディレクトリは、どちらも元ファイルと同じディレクトリになります
• 音声品質を維持する：音声には AAC エンコードを使用し、デフォルトは 96k です
• MP4 形式で出力する：すべての出力ファイルは MP4 形式です（ハードウェアエンコードは HEVC/H.264 + AAC、ソフトウェアエンコードは x264 + AAC）
• 長い動画には必ず --detach を指定する：数分を超えると予想されるエンコードでは、必ず --detach を指定してください（ffmpeg をプロセスグループから切り離すため、セッションのタイムアウトや終了がエンコードに影響しません）。同期モードやターミナルで管理するバックグラウンド処理は、いずれも実際に強制終了されたことがあり、moov atom のない不完全な出力は再生できません

依存関係

依存関係	バージョン要件	インストール方法
ffmpeg	≥ 5.0（VideoToolbox の -q:v を使う場合は ≥ 7.0 を推奨）	brew install ffmpeg
Python	≥ 3.9（スクリプトはシステム標準の python3 にも対応しています）	システム標準のもの、または brew install python

他のスキルとの連携

• universal-media-downloader と連携できます：動画のダウンロード後に圧縮して、容量を節約します
• local-asr / tingwu-asr と連携できます：圧縮してから文字起こしすることで、ファイル転送時間を短縮します