ffmpeg-skill
Skripte befinden sich in scripts/ neben dieser Datei; führen Sie sie mit python3 <skill-dir>/scripts/<name>.py aus, und Bereitstellungsvorlagen in templates/. Diese Datei reicht aus, um eine Aufgabe zu erledigen: Die folgende Tabelle leitet die Anfrage weiter, und --help für das auszuführende Skript ist die günstigste vollständige Flag-Liste. Eine Referenzdatei kostet genauso viel wie diese; öffnen Sie eine nur für eine Frage, die Sie haben: references/scripts.md (jede Flag aller 42 Skripte), references/devices.md (iPhone HDR, GoPro, DJI, Bildschirmaufnahmen, Zoom), references/gotchas.md (die ausführliche Form der Einzeiler-Regeln am Ende). MCP: tools/list zeigt standardmäßig nur die 12 Kernwerkzeuge; die anderen 30 (gemäß dieser Tabelle) bleiben über tools/call aufrufbar, beschrieben durch contract --json; setzen Sie FFMPEG_SKILL_MCP_FULL=1 für alle 42.
Gemeinsame Flags, bei jedem Skript: --dry-run; --json (Ausgabepfad, eine Prüfung der Ausgabe, die ausgeführten Befehle); --json-brief (Status/Ausgabe/verifiziert plus eine summary; bevorzugen bei Schreibschritten); --fast (Vorschauqualität); --progress; --timeout SEKUNDEN (kind: timeout, Standard 1800); --overwrite (Schritt 7); --plan DATEI (der Trockenlauf als ein Plan, den render.py DATEI später ausführt; lehnt ab, wenn sich eine Eingabe geändert hat). Neu-codierende Werkzeuge akzeptieren auch --codec h264|hevc|av1|prores und --quality N: nicht gesetzt, SDR ist x264, HDR ist x265 Main10; prores benötigt -o NAME.mov, h264 lehnt HDR ab (color.py --to-sdr zuerst).
Schreibwerkzeuge führen unter --dry-run nichts aus; die Messwerkzeuge (probe, check, sync, multicam, scenes, cropdetect, report, silence, loudness, stabilize) können trotzdem ffmpeg/ffprobe ausführen, überspringen dabei Artefakte/Seitendateien (--edl, --sheet, ein generiertes .ass); verify ignoriert das Flag. Pro Werkzeug: contract --json dry_run.
Arbeitsablauf (in dieser Reihenfolge)
- Umgebung, nur bei Fehlschlag. Starten Sie niemals eine Aufgabe mit
doctor: Eine defekte Maschine schlägt mitkind: missing_tooloder einem ffmpeg-Fehler fehl, der den Filter/Encoder benennt. Führen Siepython3 <skill-dir>/scripts/_contract.py doctor(odernpx ffmpeg-skill doctor) nach einem solchen Fehler aus, oder wenn gefragt wird, was die Maschine kann: Lesen Sieok/usable, melden Sie die fehlende Fähigkeit. Das Tool-Schema voncontract --jsonist für einen Planungs-Agenten gedacht, nicht für diesen Arbeitsablauf. - Prüfen, was Sie planen müssen. Führen Sie
probe.pyfür jede Eingabe aus, von der Sie planen – Dauer, fps, Auflösung, Codecs, Kanäle,variable_frame_rate_suspected– und immer dann, wenn der Benutzer nach einer Datei fragt. Keine separate Prüfung vor jeder Bearbeitung: Jedes Schreibwerkzeug trägt in--jsonbereits seine Eingabe und eine Prüfung der Ausgabe. Planen Sie mit echten Zahlen, niemals mit Annahmen. - Verlustfrei bevorzugen. Wenn die Anfrage ohne Neucodierung erfüllt werden kann (einfache Schnitte an Keyframes, Remuxen, reine Audio-Änderungen), dann codieren Sie nicht neu.
cut.pyundloudness.pykopieren standardmäßig das Video im Stream-Copy;--accuratebeicut.pynur für frame-genaue Schnitte. - Planen Sie mit
--dry-run --json, dann führen Sie aus. Vertrauen Sie--json, nicht der Zusammenfassungszeile eines Trockenlaufs, für jede Zahl im Plan (eine Dimension dort kann ein Platzhalter sein). Vor langen Codierungen verwenden, um Fakten zu melden.--fastist Vorschauqualität,--progressgibt Prozent/ETA auf stderr aus. Zeigen Sie-oniemals auf eine Datei, die Sie nicht in dieser Aufgabe erstellt haben, es sei denn, der Benutzer hat darum gebeten, dass sie ersetzt wird; übergeben Sie--overwritenur dann. - Verketten Sie in einer sinnvollen Reihenfolge. Eine Bereitstellungsanfrage ohne weitere Bearbeitung ist ein einzelner Vorlagenlauf (
render.py --template NAME INPUT), keine handgebaute Kette. Andernfalls: Farbe (HDR→SDR / LUT) → Schnitt → Zusammenfügen → Stille → Anpassen → Untertitel/Overlay → Synchronisation → Audio → Lautheit → Export. Rahmenänderungen vor Untertiteln, damit der Text für den endgültigen Rahmen dimensioniert ist. So wenig wie möglich neu codieren: Zwischenergebnisse bei CRF 18,export.pyzuletzt. Drei oder mehr Schritte:render.pymit einer project.json. - Prüfen Sie das Ergebnis. Melden Sie vor der Meldung
check.py AUSGABE --platform Xfür das genannte Ziel (ein Vorlagenlauf macht das bereits). Format-Zeilen (Codec, Pixelformat, Größe, True Peak, Farb-Tags, VFR) sind sicher zu korrigieren. Beurteilungs-Zeilen ändern den Inhalt: Dauer (Schnitt verliert Material), Seitenverhältnis (Zuschnitt verliert Kanten), fps (verringert Bewegung), Lautheit (Atmosphäre darf nicht verstärkt werden) – korrigieren Sie nur, wenn die Anfrage die Antwort impliziert, sonst nennen Sie die Wahl und ihre Kosten. Erwähnen Sie WARNungen; jagen Sie ihnen nicht hinterher. - Überprüfen Sie die Ausgabe. Bestätigen Sie Dauer, Auflösung, fps und Audio passen zur Anfrage, aus der
--json/--json-brief-Prüfung des Schreibwerkzeugs oderprobe.py, und melden Sie diese Zahlen („final.mp4: 59,98 s, 1080x1920, 30 fps, AAC Stereo“). Ein Schritt ist erst dann erledigt, wenn das Skript mit Exit-Code 0 beendet wurde und die Ausgabe wie erwartet geprüft wird: Ein Exit-Code ungleich Null, eine fehlende oder leere Datei oder eine Prüfung, die der Anfrage widerspricht, ist ein Fehler, der mit der Fehlermeldung des Skripts gemeldet wird. - Behalten Sie die Originale des Benutzers. Überschreiben Sie niemals die Quelle; schreiben Sie neue Dateien neben die Eingabe oder dorthin, wo es gefragt wird. Ein vorhandener Ausgabepfad wird abgelehnt (
kind: input);--overwriteist die einzige Möglichkeit, „ja, ersetze es“ zu sagen. - Schauen Sie sich das Bild an. Immer wenn sich das Bild geändert hat (Untertitel, Overlays, Grafiken, Zuschnitt/Pad, Größenänderung, Farbe, Übergänge, ein
join.py, das einen Clip auf den Rahmen des ersten Clips skaliert,color.py --to-sdr) führen Sielook.py AUSGABE --tiles 3x2(oder--at Tfür einen einzelnen Frame) aus und betrachten Sie das PNG (4x3 für das gesamte Clip-Layout). Nicht fertig, bisLook:dieses PNG nennt – eine Prüfung kann keinen Untertitel auf einem Gesicht sehen. Nur Audio:Look: not needed. Worauf zu achten ist, teilt sich ähnlich wie die Zeilen voncheck.pyin Schritt 5 auf:- Mechanisch (Aufgabe dieses Skills, zu überprüfen und zu melden): Der angegebene Text/das Logo befindet sich an der angegebenen Position, Untertitel erscheinen zu den angegebenen Zeitstempeln, Abmessungen sind gerade. Letterboxing von
fit.py --fit padist das korrekte Ergebnis dieses Modus, niemals ein zu kennzeichnender Mangel. - Beurteilung (melden Sie es, bestehen oder fallen Sie nicht stillschweigend): Ob ein Motiv oder ein Gesicht abgeschnitten ist, Text über einem Gesicht sitzt, Farben verwaschen aussehen, ein Übergang landet. Diese müssen entscheiden, was das Motiv ist, der Aufruf des aufrufenden Agenten – sagen Sie, was Sie in einer Zeile sehen; sie beurteilen.
Ohne Bildfähigkeit: Schreiben Sie
Look: PFAD (Pixel nicht inspiziert; Agent hat keine Bildansicht)– behaupten Sie niemals, dass ein Bild inspiziert wurde, wenn es nicht der Fall war, ohne auf eine Fähigkeit zu warten, die nicht vorhanden ist.
- Mechanisch (Aufgabe dieses Skills, zu überprüfen und zu melden): Der angegebene Text/das Logo befindet sich an der angegebenen Position, Untertitel erscheinen zu den angegebenen Zeitstempeln, Abmessungen sind gerade. Letterboxing von
Bevor Sie etwas ausführen: Was zu fragen, was anzunehmen
Stellen Sie eine kurze Frage nur dann, wenn die Antwort die Ausgabe wesentlich ändert und die Anfrage sie nicht impliziert. Wenn mehrere Dinge gleichzeitig offen sind (ein vages „Mach es für soziale Medien“ lässt Ziel, Seitenverhältnis, Länge und Untertitel offen), fragen Sie nicht einzeln pro Runde: Schlagen Sie ein Bündel mit Ihren Standardeinstellungen vor und lassen Sie den Benutzer jeden Teil ändern („Reels: 9:16 gepaddet, 60 s, -14 LUFS, keine Untertitel – OK?“). Eine Frage, eine Antwort, dann die Ausführung. Fragen Sie niemals nach etwas, das Ihnen probe.py sagen kann.
- Ziel bestimmt Seitenverhältnis, Längenbegrenzung, Lautheit und Codec; „für Reels“ beantwortet alle vier und nennt eine Vorlage. Kein Ziel und ein einfacher Schnitt/Untertitel: Behalten Sie das Quellformat und sagen Sie es. Wenn der Benutzer „exportieren“, „posten“ oder „liefern“ sagt, fragen Sie wohin.
- Dauer („mach es 60 s“) ohne eine Methode: Für Änderungen ≤1,5× beschleunigen, sonst trimmen, sagen Sie welches. Fragen Sie, wenn der Inhalt ein Vortrag ist (Trimmen verliert Wörter) und die Änderung groß ist.
- Untertitel ohne eine Textquelle:
--transcribe, wenn ein lokaler Whisper existiert, sonst nach dem Text oder einer zeitgesteuerten Datei fragen; niemals Dialoge erfinden. - Schriftarten und Marke: Wenn der Benutzer eine Marke, Farben oder „unsere Schriftart“ erwähnt, fragen Sie nach oder erstellen Sie einmal
brand.json, verwenden Sie es wieder. - CJK / nicht-lateinischer Text: Lassen Sie das Werkzeug die Schriftart pro Schrift (
--fontschaltet es aus);--lang ja|kofür Han-Text.doctor --json.fonts.scriptssagt, was hier rendert. Tofu ist ein gescheiterter Job. - Zuschnittposition für
--fit crop: Standardmäßig zentrieren, aber wenn die Anfrage oder die Quelle ein außermittiges Motiv nennt („das Produkt rechts halten“, jemand im Blatt sichtbar außermittig), verwenden Sie--crop-x/--crop-y(0=links/oben, 1=rechts/unten) anstatt die Mitte zu raten, oder fragen Sie, welche Kante behalten werden soll. - Alles andere (Übergangstyp, Untertitelstil): Wählen Sie die konventionelle Standardeinstellung, sagen Sie, was Sie gewählt haben, bieten Sie die Alternative in einer Zeile an.
Was dieses Skill entscheidet und was nicht
Dieses Skill schneidet, fügt zusammen, misst, synchronisiert, exportiert und prüft Dateien – es führt eine Bearbeitung aus, es entscheidet nicht darüber. Was dem Menschen, dem aufrufenden Agenten oder einem anderen Skill gehört:
- Welcher Schnitt richtig ist oder ob ein Ergebnis genehmigungsfähig ist – dieses Skill misst und meldet (PASS/WARN/FAIL von
check.py, Dauerfehler voncut.py); der Benutzer oder der Produktionsagent entscheidet, ob das ausgeliefert wird. - Was ein Highlight interessant macht –
scenes.py --highlightsbewertet nach einem gemessenen Stellvertreter (Audio-Energie, Dauer): Kandidaten, kein Urteil. - Thumbnail- oder Cover-Komposition – eine Designentscheidung, keine Messung.
- Zu verstehen, worum es in einem Video geht – hier gibt es keine Bildanalyse jenseits der Kontaktabzüge von
look.py, für die Augen des aufrufenden Agenten, nicht für dieses Skill, um es zu interpretieren. - Zu beurteilen, was gut aussieht – „dieses LUT anwenden“, „Belichtung um +0,3 Blenden korrigieren“ (
color.py) ist mechanisch; „diese Szene filmisch abstimmen“ gehört zu einem Farbabstimmungs-Skill (color-grading-skill), das die Parameter entscheidet und danncolor.pyaufruft. - Die Wörter in einem Untertitel – Cue-Text wird so eingebrannt, wie geschrieben. Zu lang für den Rahmen bedeutet eine kleinere Größe,
--max-linesoder die eigene Bearbeitung des Benutzers; nie umschreiben, kürzen oder paraphrasieren, selbst wenn darum gebeten wird, „es passend zu machen“ – sagen Sie es, bieten Sie--max-lines 1in einer kleineren Größe an. - Ein Motiv oder eine Region auswählen, die Ihnen nicht gegeben wurde – „auf x=200, y=0 zuschneiden“ ist mechanisch, sobald die Box bekannt ist; „zuschneiden, um den Sprecher im Bild zu behalten“ erfordert zu entscheiden, was der Sprecher ist, ein Urteil des aufrufenden Agenten (aus einem
look.py-Blatt).
Die Grenze: Gleiche Eingabe + gleiche explizite Parameter, die immer die gleiche überprüfbare Ausgabe erzeugen, gehört hierher; alles, was von Geschmack, Verständnis oder dem abhängt, was gut aussieht oder klingt, gehört zu demjenigen, der dieses Urteil fällt.
Wenn eine Anfrage eine FFmpeg-Funktion benötigt, die keines der 42 Skripte bereitstellt, sagen Sie es und nennen Sie die nächstgelegene integrierte Option – raten Sie niemals einen rohen ffmpeg/ffprobe-Aufruf außerhalb von scripts/*.py. Es umgeht jede Garantie, die dieses Skill macht, also niemals als Fallback, wenn ein Flag eines Skripts etwas nicht abdeckt.
Anfrage → Skript
Diese Tabelle und die tools-Liste von doctor --json sind die Quelle der Wahrheit für das, was existiert: Nennen Sie nur ein Skript, das Sie in einem von ihnen gesehen haben (es gibt kein doctor.py, kein trim.py, kein subtitle.py).
Zeitstempel-Flags (--start, --end, --at, --from, --duration, --offset sowie die Zeiten in Cue- und Kapiteldateien) akzeptieren Sekunden, mm:ss(.fff), hh:mm:ss(.fff) oder SMPTE hh:mm:ss:ff mit @fps (00:01:02:[email protected]) – fügen Sie einen NLE-Cue-Plan ein, wie er ist; Längenflags (--min-silence, --margin, --fade) sind einfache Sekunden.
| Benutzer sagt | Tun |
|---|---|
| „schneide von 1:20 bis 2:05“, „trimme die ersten 10 s“ | cut.py input.mp4 --start 1:20 --end 2:05 |
| „behalte nur diese Teile“, „entferne die Mitte“ | cut.py input.mp4 --segments 0-1:00,1:30-2:00 |
| „mach es genau 60 Sekunden“ | fit.py input.mp4 --duration 60 (Geschwindigkeit) oder --method trim |
| „schneide dies und mach es HEVC / AV1 / ProRes“ (Ausgabe-Codec genannt) | cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc (--codec/--quality bei jedem Neucodierungs-Werkzeug; ProRes benötigt -o NAME.mov) |
| „schneide die Pausen raus“, „Jump Cuts“ | silence.py input.mp4 [--threshold -40 --min-silence 0.8] |
| „schneide die Ähs und Ähms raus“, „entferne die Füllwörter“ | silence.py input.mp4 --filler --words words.json (gemessene Wort-Zeitsteuerungen; --transcribe erstellt sie) |
| „schneide nicht mitten im Satz, nur die echten Pausen“ | silence.py input.mp4 --speech-aware – ein Atemzug unter --min-silence innerhalb eines Satzes bleibt erhalten, nur Satzgrenzen-Pausen werden geschnitten; kombiniert mit --filler zu einer Liste |
| „ein 60 s Highlight aus dieser Stunde“ | scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt → cut.py --segments |
| „auf den Beat schneiden“, „es zur Musik schneiden“ | scenes.py track.mp4 --beats --json > beats.json, dann cut.py input.mp4 --segments ... --snap beats --snap-source beats.json (--snap-source trägt das gemessene Raster) |
| „hier beschleunigen, dort Zeitlupe“ (bekannte Segmente) | speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0 |
| „dieses Bild halten“, „das letzte Bild einfrieren“ | freeze.py clip.mp4 --hold 2 |
| „sanfte Zeitlupe“, „halbe Geschwindigkeit aber flüssig“ | fit.py input.mp4 --duration 2x --smooth interpolate (langsam) oder --smooth blend |
| „diesen Clip umkehren“ | reverse.py input.mp4 |
| „diesen Clip loopen, um 30 Sekunden zu füllen“ | loop.py bg_loop.mp4 --duration 30 |
| „mach es vertikal / 9:16 / quadratisch“ | fit.py input.mp4 --aspect 9:16 --fit pad (oder --fit crop; --pad-fill blur für verschwommene Balken) |
| „ändere die Größe auf eine Höhe/Breite“ | fit.py input.mp4 --height 1080 (oder --width, oder beides für einen exakten Rahmen) |
| „auf diese exakte Box zuschneiden“ (bekannte x/y/w/h) | crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920 |
| „verschwommener Hintergrund statt schwarzer Balken“ | fit.py input.mp4 --aspect 9:16 --fit blur (gesamtes Bild erhalten, Ränder eine verschwommene, abgedunkelte Kopie) |
| „um 90 Grad drehen“, „spiegeln“ | fit.py input.mp4 --rotate 90 / fit.py input.mp4 --flip h |
| „der Horizont ist geneigt“ (bekannte Grad) | straighten.py tilted.mp4 --degrees -2.5 |
| „flache Ansicht aus diesem 360°-Video“ (bekannte yaw/pitch/fov) | sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70 |
| „dieses alte Filmmaterial ist Zeilensprung“ | deinterlace.py input.mp4 |
| „es ist körnig/verrauscht, bereinigen“ | denoise.py input.mp4 --strength medium |
| „dieses Gesicht/dieses Kennzeichen unscharf/pixelig machen“ (bekannte Box) | redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate |
| „dieses verwackelte Filmmaterial stabilisieren“ | stabilize.py input.mp4 |
| „sind darauf schwarze Balken?“ | cropdetect.py input.mp4 |
| „iPhone Dolby Vision Clip sieht falsch aus“ | color.py clip.mov --to-sdr oder --strip-dovi (HDR behalten, DV-Ebene entfernen) |
| „die Farben sehen verwaschen aus / iPhone HDR“ | color.py input.mp4 --to-sdr |
| „wende diesen LUT an“ (bekannte .cube-Datei) | color.py input.mp4 --lut path/to/lut.cube |
| „Farben korrigieren, sodass sie auf einen Rec.709-Monitor passen“ | color.py input.mp4 --to-sdr (die Quelle ist HDR, es sei denn, das Gegenteil ist bekannt) |
| „HDR-Video für SDR-Ausgabe korrigieren, ohne die HDR-Daten zu entfernen“ | color.py input.mp4 --to-sdr --retain-hdr |
| „ändere die Lautstärke um +3 dB“ | audio.py input.mp4 --gain 3 |
| „normalisiere die Audio-Lautheit auf -14 LUFS“ | loudness.py input.mp4 [--loudness -14] |
| „mach die Lautstärke gleichmäßig, damit leise Stellen nicht zu leise sind“ | loudness.py input.mp4 --compress |
| „entferne den Sound aus dieser Datei“ | audio.py input.mp4 --no-audio |
| „ersetze den Ton durch diese andere Datei“ | audio.py video.mp4 --replace soundtrack.wav |
| „mischt diesen Track mit einem anderen, das eine ist lauter“ | audio.py video.mp4 --mix intro_bgm.wav --mix-gain -10 --mix-video-volume 0 |
| „füge Hintergrundmusik hinzu, die die Stimme nicht übertönt“ | audio.py input.mp4 --mix music.mp3 --mix-gain -20 --duck |
| „entferne einen bestimmten Frequenzbereich“ (bekanntes Hz) | audio.py buzzy.mp4 --filter equalizer=f=60:t=q:w=1:g=-20 (roh; die unteren Regeln gelten) |
| „zwei Audiospuren zusammenführen (Mehrspur-Audio)“ | audio.py video.mp4 --mix second_track.wav --mix-gain 0 --mix-video-volume -99 |
| „mach ein Stereo-Audio aus dieser Monospur“ | audio.py input.mp4 --mix input.wav (Monospur verdoppelt reichen, --mix macht bequem Stereo) |
| „audio mit diesem externen Mikrofon synchronisieren“ | sync.py internal.wav external.wav (gibt den Offset und eine Wellenform; erneuter Aufruf: audio.py video.mp4 --sync-offset 0.25) |
| „synchronisiere diese Kamera-Aufnahmen“ (2+ Videospuren) | multicam.py main.mp4 cam2.mp4 (kein Zusammenfügen: erzeugt eine Multicam-EDL; multicam.py main.mp4 cam2.mp4 --output sync_demo.mp4 verbindet, synchronisiert das Layout) |
| „erstelle Untertitel“ (bekannte SRT/ASS-Datei) | caption.py input.mp4 --subs captions.srt / caption.py input.mp4 --subs captions.ass |
| „Untertitel für Gehörlose erstellen“ | caption.py input.mp4 --subs captions.srt --burn |
| „sprechende Untertitel“ (animiert, Karaoke-Stil) | caption.py input.mp4 --subs captions.ass --burn --animate karaoke (--animate wirkt nur mit ASS) |
| „einen unteren Drittel-Titel hinzufügen“ (Text unten einblenden) | `caption.py input.mp4 --lower-third |