hyuuuliu/video-overlay-cleanup-skill

Video-Overlay-Bereinigung

Repository: https://github.com/hyuuuliu/video-overlay-cleanup-skill

Übersicht

Verwenden Sie diese Fähigkeit, um ein Rohvideo oder eine Bildschirmaufnahme in eine sauberere Version mit weniger sichtbaren Overlays umzuwandeln.

Diese Fähigkeit ist eine Workflow-Fähigkeit, kein Anspruch auf magische Wiederherstellung des ursprünglichen Inhalts. Sie eignet sich am besten für:

• feste Overlays an stabilen Positionen
• kurzlebige Banner oder schwebende UI-Elemente mit bekannter Maske
• Aufbereitung von Bildschirmaufnahmen für Schnitt oder Weiterverbreitung
• Vorbereitung einer bildweisen Wiederherstellungsaufgabe für Gemini Nano Banana 2

Diese Fähigkeit sollte die Aufgabe als Video-Bereinigung oder Overlay-Entfernung beschreiben, nicht als garantierte faktische Wiederherstellung versteckter Inhalte.

Provider-Unterstützung

Diese Version unterstützt einen echten Modellprovider für generative Bildwiederherstellung:

• Gemini Nano Banana 2 über die Gemini-Bildgenerierungs- und -Bearbeitungs-API

Vor der Verwendung des Modus gemini-nano-banana muss der Benutzer einen API-Schlüssel konfigurieren:

export GEMINI_API_KEY='your_api_key_here'

Optionaler Modell-Override:

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

Laufzeitanforderungen

Deklarieren Sie diese explizit bei der Installation oder Überprüfung der Fähigkeit:

• erforderliche Binärprogramme:
  • bash
  • ffmpeg
  • ffprobe
  • python3
• erforderliche Anmeldeinformationen für den Gemini-Modus:
  • GEMINI_API_KEY
• optionale Gemini-Umgebungsvariablen:
  • GEMINI_MODEL
  • GEMINI_IMAGE_SIZE
• erforderliche Python-Pakete für den Gemini-Modus:
  • google-genai
  • Pillow

Lesen Sie references/gemini-provider.md, wenn der Benutzer den Gemini-Pfad wünscht.

Anfragen, die am besten passen

Verwenden Sie diese Fähigkeit, wenn der Benutzer eine der folgenden Aktionen anfordert:

• Entfernen einer Statusleiste, oberen Leiste, unteren Leiste, eines Untertitelstreifens, Wasserzeichens oder schwebenden Steuerelements aus einem Video
• Bereinigen einer Telefon-Bildschirmaufnahme vor der Wiederverwendung oder dem Zuschneiden
• Aufteilen eines Videos in Einzelbilder, Reparieren maskierter Bereiche und Wiederzusammensetzen
• Vorbereiten einer wiederholbaren FFmpeg-Pipeline zur Video-Overlay-Entfernung
• Verwenden von Gemini Nano Banana 2 zur bildweisen Reparatur eines maskierten Overlay-Bereichs
• Generieren von Masken oder Regionsspezifikationen für bekannte Overlay-Bereiche

Standardstrategie

Wählen Sie den leichtesten gangbaren Pfad:

1. Festes Overlay, stabile Region: ffmpeg mit einer generierten Maske und removelogo verwenden
2. Feste Region, aber removelogo-Qualität nicht ausreichend: Einzelbilder extrahieren und Gemini Nano Banana 2 auf den maskierten Bereich anwenden
3. Dynamisches Overlay: Einzelbilder extrahieren, Masken erstellen oder propagieren, Gemini Nano Banana 2 ausführen, dann Video wieder zusammensetzen

Standardmäßig keine generative Vollbildbearbeitung verwenden, wenn eine festgelegte Region oder eine deterministische Methode ausreicht.

Arbeitsablauf

1. Overlay klassifizieren

Entscheiden, welcher dieser Fälle zutrifft:

• fixed-edge-overlay: obere Statusleiste, untere Navigationsleiste, Untertitelstreifen, Ecklogo
• fixed-box-overlay: stabiles Wasserzeichen oder schwebendes Widget in einem Bereich
• dynamic-overlay: Benachrichtigungsbanner, bewegender Sticker, vorübergehendes schwebendes Steuerelement
• unknown: der Benutzer hat noch nicht genügend Details angegeben, um eine Maske zu definieren

Wenn die Position des Overlays unklar ist, nach der kleinsten fehlenden Information fragen oder eine plausible erste Maske vorschlagen und als Entwurf kennzeichnen.

2. Pfad auswählen

Für fixed-edge-overlay oder fixed-box-overlay die integrierten Skripte bevorzugen:

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

Für Gemini-basierte Workflows verwenden:

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

Für Low-Level- oder benutzerdefinierte Provider-Workflows verwenden:

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

Lesen Sie references/pipeline.md für den End-to-End-Ablauf, references/mask-strategies.md für die Maskengestaltung und references/gemini-provider.md für Gemini-spezifisches Verhalten.

3. Maske sorgfältig erstellen

Masken entscheiden über den Erfolg. Diese Regeln beachten:

• Nur das Overlay maskieren, nicht das gesamte Bild
• Eine etwas zu enge Maske einer zu großen vorziehen
• Bei festen Balken Voreinstellungen oder prozentbasierte Regionen verwenden
• Bei dynamischen Overlays den Bildbearbeitungsumfang lokal und explizit halten

Das von dieser Fähigkeit verwendete Regionsformat ist x:y:w:h. Jeder Wert kann Pixel sein wie 120 oder ein Prozentsatz wie 8%.

Beispiele:

• Obere 7 Prozent: 0:0:100%:7%
• Unterer Streifen: 0:92%:100%:8%
• Eckwasserzeichen: 78%:3%:18%:12%

4. Bereinigungspfad ausführen

Schneller Pfad für feste Overlays

Verwenden, wenn das Overlay an einer Stelle bleibt.

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

Sie können auch Voreinstellungen hinzufügen:

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-Pfad

Verwenden, wenn der Benutzer eine maskierte bildweise Wiederherstellung wünscht.

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

Optionaler Modell-Override:

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

Benutzerdefinierter Bildbearbeitungspfad

Nur verwenden, wenn der Benutzer explizit einen benutzerdefinierten Editierbefehl anstelle von Gemini wünscht.

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}'

Der Editorbefehl empfängt:

• {input}: Quellbildpfad
• {mask}: Maskenpfad
• {output}: Zielbildpfad
• {index}: nullbasierte Bildnummer

5. Grenzen explizit benennen

Immer darauf hinweisen, wenn eine dieser Bedingungen zutrifft:

• der versteckte Inhalt war in keinem Bild sichtbar
• das Ergebnis ist eine visuelle Rekonstruktion, keine faktische Wiederherstellung
• das Overlay ist dynamisch und die Maske ist annähernd
• bildweise Bearbeitungen benötigen möglicherweise eine zeitliche Stabilisierung über diesen ersten Durchlauf hinaus
• Gemini kann von Bild zu Bild leicht variieren, insbesondere bei großen maskierten Bereichen
• Der Gemini-Modus meldet jetzt während der Ausführung die Bildanzahl, die geschätzten Basiskosten und den kumulierten Token-/Ausgabenfortschritt
• Der Gemini-Modus bewahrt jetzt beim Speichern alle unmaskierten Pixel des Originalbilds, sodass nur maskierte Bereiche aus der Modellausgabe übernommen werden

Bekannte Einschränkungen

Die Risikoerklärung einfach halten:

• maskierte oder abgedeckte Bereiche werden nicht zuverlässig wiederhergestellt
• das Ergebnis ist eine plausible visuelle Bereinigung, keine garantierte echte Wiederherstellung
• die Gemini-Verarbeitung kann teuer sein, insbesondere bei längeren Videos oder höheren Bildzahlen

Aktuelle Zuverlässigkeitshinweise

Die aktuelle Gemini-Implementierung verwendet mehrere Schutzmaßnahmen:

• Budgetschätzung vor Beginn der Verarbeitung
• kumulierte Token- und Ausgabenberichterstattung während der Verarbeitung
• Validierung und Wiederholung pro Bild
• Wiederholung auf Anforderungsebene bei vorübergehenden Provider-Fehlern
• maskierter Compositing, der alle unmaskierten Pixel des Originalbilds beibehält

Diese letzte Schutzmaßnahme ist wichtig: Wenn das Modell den Hamster, Käfig oder andere sichtbare Szeneninhalte außerhalb der weißen Maske bearbeitet, behält die gespeicherte Ausgabe dennoch die originalen unmaskierten Pixel. Dies verbessert die visuelle Stabilität, bedeutet aber auch, dass alle nützlichen Bearbeitungen innerhalb der bereitgestellten Maske stattfinden müssen.

Erwartungen an das Ergebnis

Ein gutes Ergebnis umfasst:

• den Pfad zum bereinigten Video
• die gewählte Methode: removelogo, gemini-nano-banana oder frame-edit
• die genaue Maske oder verwendeten Voreinstellungen
• ob GEMINI_API_KEY erforderlich war
• die Bildanzahl, die der Gemini-Modus zu verarbeiten plante
• die geschätzten Basiskosten vor Beginn der Gemini-Aufrufe
• die kumulierte Token- und Ausgabenzusammenfassung, die während der Verarbeitung gemeldet wurde
• alle wichtigen Einschränkungen bezüglich Realismus, Konsistenz oder Restartefakten

Wenn sinnvoll, auch das Arbeitsverzeichnis aufbewahren, damit der Benutzer Folgendes überprüfen kann:

• extrahierte Einzelbilder
• generierte Maskendateien
• wiederaufgebautes Zwischenvideo
• Auftragsmanifest

Qualitätsanspruch

• Stabile, wiederholbare Bereinigung gegenüber ambitionierten, aber verrauschten Bearbeitungen bevorzugen
• Vermeiden, unberührte Teile des Bildes zu bearbeiten
• Zuerst deterministische FFmpeg-Pfade verwenden
• Generative Bearbeitung als gezielte Ausweichlösung behandeln, nicht als Standard
• sauberer aussehend von faktisch wiederhergestellt trennen
• Den Benutzer daran erinnern, wann ein Provider-API-Schlüssel erforderlich ist

Aufforderungsmuster

Gute Aufrufe:

• "Verwenden Sie $video-overlay-cleanup, um die obere Statusleiste aus dieser Bildschirmaufnahme zu entfernen."
• "Verwenden Sie $video-overlay-cleanup mit Gemini Nano Banana 2, um das obere Banner aus diesem Video zu entfernen."
• "Verwenden Sie $video-overlay-cleanup, um dieses Video in Einzelbilder aufzuteilen, das schwebende Overlay zu bereinigen und es wieder zusammenzusetzen."

Für Implementierungsdetails laden:

• references/pipeline.md
• references/mask-strategies.md
• references/gemini-provider.md
• references/provider-integration.md