ビデオオーバーレイクリーンアップ

リポジトリ: https://github.com/hyuuuliu/video-overlay-cleanup-skill

概要

このスキルは、生の動画や画面録画から、目に見えるオーバーレイを減らしたクリーンなバージョンを作成するために使用します。

このスキルはワークフロースキルであり、魔法のように完全な情報を復元するものではありません。以下の用途に最適です。

固定位置にある固定オーバーレイ
マスクが既知の短命なバナーやフローティングUI
編集や再配布のための画面録画のクリーンアップ
Gemini Nano Banana 2を使用したフレーム単位の復元ジョブの準備

このスキルは、タスクを「動画クリーンアップ」または「オーバーレイ除去」として位置づけ、隠されたコンテンツの事実上の復元を保証するものではありません。

プロバイダサポート

このバージョンは、生成的なフレーム修復のための1つの実際のモデルプロバイダをサポートしています。

Gemini画像生成・編集APIを介した Gemini Nano Banana 2

gemini-nano-banana モードを使用する前に、ユーザーはAPIキーを設定する必要があります。

export GEMINI_API_KEY='your_api_key_here'

オプションのモデルオーバーライド:

export GEMINI_MODEL='gemini-3.1-flash-image-preview'
export GEMINI_IMAGE_SIZE='1K'

実行時要件

スキルをインストールまたはレビューする際には、これらを明示的に宣言してください。

必要なバイナリ:
- bash
- ffmpeg
- ffprobe
- python3
Geminiモードに必要な認証情報:
- GEMINI_API_KEY
オプションのGemini環境変数:
- GEMINI_MODEL
- GEMINI_IMAGE_SIZE
Geminiモードに必要なPythonパッケージ:
- google-genai
- Pillow

ユーザーがGeminiパスを希望する場合は、references/gemini-provider.md を参照してください。

最適なリクエスト

以下のいずれかをユーザーが依頼した場合に、このスキルを使用してください。

動画からステータスバー、トップバー、ボトムバー、字幕ストリップ、ウォーターマーク、またはフローティングコントロールを削除する
再利用やクリッピングの前にスマートフォンの画面録画をクリーンアップする
動画をフレームに分割し、マスクされた領域を修復して再構築する
動画オーバーレイ除去のための反復可能なFFmpegパイプラインを準備する
Gemini Nano Banana 2を使用して、マスクされたオーバーレイ領域をフレームごとに修復する
既知のオーバーレイ領域のマスクまたは領域仕様を生成する

デフォルト戦略

動作可能な最も軽量なパスを選択してください。

固定オーバーレイ、安定領域: 生成されたマスクと removelogo を使用して ffmpeg を使用する
固定領域だが removelogo の品質が不十分な場合: フレームを抽出し、マスクされた領域でGemini Nano Banana 2を実行する
動的オーバーレイ: フレームを抽出し、マスクを作成または伝播させ、Gemini Nano Banana 2を実行し、動画を再構築する

固定領域や決定論的な方法で十分な場合に、デフォルトで全フレーム生成編集を行わないでください。

ワークフロー

1. オーバーレイを分類する

以下のケースのどれに該当するかを判断します。

fixed-edge-overlay: 上部ステータスバー、下部ナビゲーションバー、字幕ストリップ、コーナーロゴ
fixed-box-overlay: 固定ウォーターマークまたは1つの領域にあるフローティングウィジェット
dynamic-overlay: 通知バナー、移動するステッカー、一時的なフローティングコントロール
unknown: ユーザーがマスクを定義するのに十分な詳細をまだ提供していない

オーバーレイの位置が不明な場合は、不足している最小の詳細を尋ねるか、妥当な最初のマスクを提案し、それをドラフトとしてラベル付けします。

2. パスを選択する

fixed-edge-overlay または fixed-box-overlay の場合、組み込みスクリプトを優先します。

scripts/make_mask.py
scripts/clean_video.sh --mode removelogo

Geminiベースのワークフローの場合、以下を使用します。

scripts/clean_video.sh --mode gemini-nano-banana
scripts/gemini_nano_banana_edit.py

低レベルまたはカスタムプロバイダのワークフローの場合、以下を使用します。

scripts/extract_frames.sh
scripts/restore_frames.py
scripts/rebuild_video.sh

エンドツーエンドのフローについては references/pipeline.md を、マスク設計のガイダンスについては references/mask-strategies.md を、Gemini固有の動作については references/gemini-provider.md を参照してください。

3. マスクを慎重に作成する

マスクが成功を左右します。以下のルールを守ってください。

フレーム全体ではなく、オーバーレイのみをマスクする
大きすぎるマスクよりも、わずかにタイトなマスクを優先する
固定バーの場合は、プリセットまたはパーセンテージベースの領域を使用する
動的オーバーレイの場合は、フレーム編集範囲をローカルかつ明示的に保つ

このスキルで使用される領域フォーマットは x:y:w:h です。各値は 120 のようなピクセルまたは 8% のようなパーセンテージにすることができます。

例:

上部7パーセント: 0:0:100%:7%
下部ストリップ: 0:92%:100%:8%
コーナーウォーターマーク: 78%:3%:18%:12%

4. クリーンアップパスを実行する

高速固定オーバーレイパス

オーバーレイが1か所に留まる場合に使用します。

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode removelogo \
  --region '0:0:100%:7%'

プリセットを追加することもできます。

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode removelogo \
  --preset iphone-status-bar

Gemini Nano Banana 2 パス

ユーザーがマスクされたフレーム単位の復元を希望する場合に使用します。

export GEMINI_API_KEY='your_api_key_here'

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode gemini-nano-banana \
  --region '0:0:100%:12%' \
  --image-size 1K

オプションのモデルオーバーライド:

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode gemini-nano-banana \
  --region '0:0:100%:12%' \
  --model gemini-3.1-flash-image-preview \
  --image-size 2K

カスタムフレーム編集パス

ユーザーがGeminiの代わりにカスタムエディターコマンドを明示的に希望する場合にのみ使用します。

bash scripts/clean_video.sh \
  --input /abs/path/input.mp4 \
  --output /abs/path/output.mp4 \
  --mode frame-edit \
  --region '0:0:100%:12%' \
  --editor-cmd 'my-editor --input {input} --mask {mask} --output {output}'

エディターコマンドは以下を受け取ります。

{input}: ソースフレームパス
{mask}: マスクパス
{output}: 出力先フレームパス
{index}: ゼロベースのフレーム番号

5. 制限について明示する

以下のいずれかが当てはまる場合は、常に注意してください。

隠されたコンテンツがどのフレームにも表示されたことがない
結果が事実上の復元ではなく、視覚的な再構成である
オーバーレイが動的であり、マスクが近似である
フレームごとの編集には、この最初のパスを超える時間的安定化が必要になる可能性がある
特に大きなマスク領域の場合、Geminiの出力はフレームごとにわずかに異なる可能性がある
Geminiモードは実行中にフレーム数、基本コスト見積もり、累積トークン/支出の進行状況を報告するようになりました
Geminiモードは保存時に元のフレームのマスクされていないすべてのピクセルを保持するようになりました。そのため、マスクされた領域のみがモデル出力から採用されます

既知の制限事項

リスク説明はシンプルに保ちます。

マスクされた領域や覆われた領域は毎回確実に復元されるわけではありません
結果は妥当な視覚的クリーンアップであり、真の復元が保証されているわけではありません
Gemini処理は、特に長い動画やフレーム数が多い場合、高コストになる可能性があります

現在の信頼性に関する注意事項

現在のGemini実装は、いくつかのセーフガードを使用しています。

処理開始前の予算見積もり
処理中の累積トークンと支出の報告
フレームごとの検証と再試行
一時的なプロバイダエラーに対するリクエストレベルの再試行
元のフレームのマスクされていないすべてのピクセルを保持するマスクコンポジット

最後のセーフガードは重要です。モデルが白いマスクの外側のハムスター、ケージ、またはその他の表示されているシーンコンテンツを編集した場合でも、保存された出力は元のマスクされていないピクセルを保持します。これにより視覚的な安定性が向上しますが、すべての有用な編集は提供されたマスク内で行われる必要があることも意味します。

出力の期待値

良い結果には以下が含まれます。

クリーンアップされた動画パス
選択された方法: removelogo、gemini-nano-banana、または frame-edit
使用された正確なマスクまたはプリセット
GEMINI_API_KEY が必要であったかどうか
Geminiモードが処理を計画したフレーム数
Gemini呼び出し開始前の基本推定支出
処理中に報告された累積トークンと支出のサマリー
リアリズム、一貫性、または残存アーティファクトに関する重要な注意点

有用な場合は、ユーザーが検査できるように作業ディレクトリも保持します。

抽出されたフレーム
生成されたマスクファイル
再構築された中間動画
ジョブマニフェスト

品質基準

野心的だがノイズの多い編集よりも、安定した再現可能なクリーンアップを優先する
フレームの未編集部分を編集しない
まず決定論的なFFmpegパスを使用する
生成編集を的を絞ったフォールバックとして扱い、デフォルトにしない
「よりクリーンに見える」と「事実上復元された」を区別する
プロバイダのAPIキーが必要な場合にユーザーに注意を促す

プロンプトパターン

適切な呼び出し例:

「$video-overlay-cleanup を使用して、この画面録画から上部ステータスバーを削除してください。」
「$video-overlay-cleanup を Gemini Nano Banana 2 と共に使用して、この動画の上部バナーをクリーンアップしてください。」
「$video-overlay-cleanup を使用して、この動画をフレームに分割し、フローティングオーバーレイをクリーンアップして、再構築してください。」

実装の詳細については、以下をロードしてください。

hyuuuliu/video-overlay-cleanup-skill

video-overlay-cleanup-skill とは？

お気に入りのAIに質問する

ドキュメント