AI専用動画編集ツールに『色』と『手ブレ補正』を足したら、効いていたはずのパスのエスケープが片方だけ通用しなかった — clipwright

• URL: https://zenn.dev/satoh_y_0323/articles/1fa6ddadb3d874
• 日付: 2026-06-19
• Tier: Tier 3
• 要旨: MCP 動画編集サーバー clipwright に色補正と手ブレ補正を実装した際の設計判断と落とし穴。FFmpeg フィルターごとにパース挙動が異なる問題、セキュリティレビューで発見された 3 つの脆弱性、binaries の構造解析に関する選択。

詳細

clipwright v0.7.0（色補正）と v0.8.0（手ブレ補正）の実装記。設計思想は「検出と適用の分離」で、各ツールは OTIO に注記を書くだけ、実際の映像処理は clipwright-render が一度だけ行う。

色補正（clipwright-color）では、FFmpeg の signalstats で各フレームの平均輝度を測定して brightness 値を自動算出。contrast・saturation・gamma は意図的に自動化せず、AI の判断に委ねる仕様に。

手ブレ補正で遭遇した主要な問題：

• Windows 絶対パスのエスケープが drawtext では成功しても vidstabtransform では失敗。同じ「ファイルパス系オプション」でもフィルターの内部パーサが異なるため、エスケープ方式に統一性がない。解決策として cwd をファイル格納フォルダに変更し、相対ファイル名のみをフィルターグラフに渡す実装に転換。

セキュリティレビューで検出された脆弱性 3 種：

• パストラバーサル（CWE-22）：OTIO 由来の信用できない .trf_path が OTIO 外のファイルにアクセス可能に。境界チェック強化で対応。
• フィルターグラフ注入（CWE-78）：ファイル名に : や ; が含まれると FFmpeg オプション注入が可能。ファイル名の sanitize と受け側での特殊文字チェック。
• メモリ枯渇（DoS）：.trf ファイルサイズ上限を設置。

severity（手ブレの強さ）は spec では注記対象だが、.trf バイナリフォーマットの正確な構造が不明確なため、推測値を出すより null で返す判断。計測したフリの不確かな値より、正直に「測定不能」を返す方が AI に対して誠実。

通底する教訓：パスのエスケープで安全性を得るより、危険な形をそもそもフィルターグラフに出さない設計が強いこと。