Was macht kinocut?
Verwende Kinocut, wenn ein Agent eine strukturierte Videobearbeitungsoberfläche benötigt, anstatt FFmpeg-Befehle von Hand zu schreiben. Es stellt MCP-Tools, einen Python-Client und eine CLI für Bearbeitung, Analyse, Untertitel, Audio, Hyperframes, geschichtete Compositing und lokale Wiederverwendungsworkflows bereit.
Standardpfad (zuerst ausführen)
kino doctordannkino --format json info <datei>.- Rufe bei einer unbekannten Aufgabe
search_toolsmit der Benutzeraufgabe auf (z. B. „Füllwörter entfernen“ oder „Gesicht im Bild halten“), inspiziere dann die erforderlichen Eingaben des zurückgegebenen Tools. Plane mitvideo_intentfür unterstützte Absichten (optionalgoal=kompiliert eine Cutdatei; ein 360/Desk/Table/x4-Ziel schlägt auch einen360_assembly_planvor). Überprüfe, ob der Vorschlag die Anfrage tatsächlich erfüllt, bevor du renderst. - Rendern (
video_cutfile_render,video_edit, Workflow oder ein einzelnes Engine-Tool). Für 360:video_review_decidegenehmigen/ablehnen des Plans, dann rendern – rendere niemals einenproposed-Plan..insvwird abgelehnt; benötige eine gestitchte 360-MP4. Anleitung:docs/360_ASSEMBLY.md. video-quality-check/assert_quality. Syncrepurposeundshorts-packageschlagen bei einer Punktzahl von 80 fehl, es sei denn, sie werden übersprungen/allow_fail.- Menschliche visuelle/auditive Überprüfung. Behandle eine Quittung niemals als veröffentlicht.
Tiefgang (Rettung, Bergung, Compositing, Hyperframes, Thin Sound S12): docs/TOOLS.md, docs/RESCUE.md, docs/WORKFLOWS.md. Workflow-Zulassungsliste: probe, trim, resize, convert, crop, add_text, merge, composite_layers, burn_in.
Lade bei Bedarf die entsprechende Anleitung. Verwende Quelle als Beleg für redaktionelle Entscheidungen; bewahre Namen, Zahlen, Verneinungen und Einschränkungen. Melde fehlende Belege oder nicht unterstützte Aktionen, anstatt Quellenbehauptungen, Zeitstempel oder Fähigkeiten zu erfinden. Ein Planungstool schlägt eine Bearbeitung vor; seine Existenz bedeutet nicht, dass der erforderliche Detektor oder das Modell ausgeführt wurde. Code besitzt Timing, Transformationen, Validierung und Ausführung; die menschliche Überprüfung bleibt vom Modellurteil getrennt.
Revideo lokaler Code-Video-Flow (Entwicklungstipp)
Verwende revideo_materialize, revideo_install und revideo_render, wenn der Aufrufer ein inspizierbares, gestaffeltes Projekt benötigt. Verwende revideo_render_job für die gleichen bewachten Schritte in einem einzigen Aufruf. Eine bereitgestellte Szene ist vertrauenswürdiger, ausführbarer TypeScript-Code: inspiziere sie vor der Verwendung und führe niemals nicht vertrauenswürdigen Szenencode aus. Die Abhängigkeitsinstallation kann auf npm zugreifen; das Rendern erfolgt lokal gegen Kinocuts gepinnte Vorlage. Die Renderquittung bindet beobachtete Medien- und Ausgabebytes an den exakten, begrenzten, auf der Festplatte befindlichen Job-Datei-Digest. .mp4, .webm und .mov wählen gepinnte MP4-, WebM- und ProRes-4444-Exportermodi aus und werden vor der Veröffentlichung verifiziert. Verifiziere die Quittung gegen die Ausgabebytes, führe video_quality_check und video_release_checkpoint aus und verlange dann eine menschliche visuelle Überprüfung.
Starte hier
- Lese
../../README.mdfür die Installation und den Sicherheitsvertrag. - Führe
kino doctorvor FFmpeg / Hyperframes / KI-Erweiterungen aus.
Wähle eine Oberfläche
- MCP: am besten für Claude Code, Cursor, Codex-ähnliche Clients und andere Agent-Hosts. Konfiguriere
uvx --from kinocut kino. - CLI: am besten für direkte lokale Bearbeitungen, schnelle Diagnosen,
composite-layers --dry-run, Batch-Jobs und CI-freundliche JSON-Ausgabe. - Python-Client: am besten für wiederholbare Pipelines, die strukturierte Ergebnisse, Ausgabepfade und gespeicherte Layerplan-Quittungen benötigen.
360-Dualkamera-Assemblierung (veröffentlicht 1.14.0)
Verwende, wenn die Quelle eine gestitchte equirectanguläre 360-MP4 von einer beliebigen Kamera (Insta360, Ricoh Theta, GoPro MAX, DJI Osmo 360, …) ist und die Anforderung zwei virtuelle Kameras als Split / Switch / PiP / Einzelbild ist.
video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH)oderClient.propose_360_assembly(...).- Zeige Kameras, Layout und Storyboard-Standbilder. Erfinde kein Yaw/Pitch.
video_review_decide/Client.decide_360_assemblymitapproveoderreject.- Rendere nur einen genehmigten Plan (
Client.render_360_assemblyodervideo_review_decide+output_path).
Es gibt kein video_360_* MCP-Tool und keinen kino 360 Befehl. Die CLI intent und review-decide führen diesen Compiler nicht aus. Director-Hooks akzeptieren einen injizierten JSON-Proposer; ein konfigurierter Modellname allein führt kein Modell aus. Cloud-Vorschläge erfordern allow_cloud; Direktoren schreiben niemals Pixel.
Produkt-/Objekt-Matte (veröffentlicht in 1.15.1; aktuell in 1.15.3)
Das optionale Objekt-Matte-Extra ist in der veröffentlichten Version 1.15.3 verfügbar. Verwende den bestehenden Befehl hyperframes-remove-background / hyperframes_remove_background. Das Standardmodell ist Personen. Für Katalog-SKUs, Schmuck, Flaschen, Schuhe, Verpackungen oder alles, was keine Person ist:
hyperframes_remove_background(info=true)– listet Modelle auf, kein Download.pip install "kinocut[object-matte]"dannmodel="birefnet-general".- Optional
--mask-interval 3bei Produktvideos. Optionales Ausrüstungs-Overlay für übrig gebliebene Drehteller/Ständer/Stative/Schwenks. - Composite auf eine Shop-Platte mit
composite-layers. Behalte jedessrcinnerhalb des Spezifikationsverzeichnisses.
Erfinde nicht video_product_matte; dies ist kein neues MCP-Tool. Falle nicht auf das Personenmodell zurück, wenn das Objekt-Extra fehlt. Anleitung: docs/PRODUCT_MATTE.md. Beispiel: examples/product-matte/.
Dedizierte Videorettung
Verwende video_rescue_*, rescue-* oder Client.rescue_*, wenn die Anforderung darin besteht, einen lokalen Clip zu reparieren, während seine Quelle, Geschichte und Timeline erhalten bleiben.
Erforderliche Reihenfolge:
- Rufe den Plan auf und speichere das Planartefakt.
- Präsentiere
safe_repairs,recommendations,unavailable_repairs,blocked_repairs, Vorschauen, Paketabsichten, Fähigkeiten und eine Schätzung dem Benutzer. - Inspiziere den Plan vor dem Rendern. Erhalte oder leite explizite Genehmigung nur für IDs in
safe_repairsab; das Weglassen der ID-Liste bedeutet alle sicheren IDs im überprüften Plan. - Rufe das Rendern mit genau diesen genehmigten sicheren IDs auf.
- Inspiziere die Renderquittung und melde dann Paketpfade, nicht verfügbare Sidecars, Integrität, Gate-Prüfung, Datenschutz, Fortsetzung und Bereinigungsstatus.
Rendere niemals direkt aus einem nicht überprüften Plan. Füge keine Empfehlungs-IDs, nicht verfügbare IDs oder blockierte IDs zur Genehmigung hinzu. Verwende keine Cloud-Tools, brenne keine Rettungsuntertitel ein, überschreibe die Quelle nicht und behandle unavailable nicht als automatischen Fehler. Ein Abbruch oder ein Verifizierungsfehler muss unbefördert oder unter Quarantäne bleiben.
Deterministische KI-Video-Inspektion
Verwende video_ingest, video_preflight und video_inspect_temporal (oder ihre flachen CLI- und Python-Äquivalente), wenn generiertes Filmmaterial vor einer Bearbeitungsentscheidung Belege benötigt. Importiere zuerst, dann adressiere das Asset mit seinem zurückgegebenen Hash. Ersetze diese Asset-ID niemals durch einen Host-Pfad oder konstruiere einen AssetRecord an der öffentlichen Grenze. Die zeitliche Inspektion gibt das vollständige Paket mit abgetasteten Frames und Bewegungsstreifen, deterministische Ergebnisse und explizite nicht verfügbare Provider-Fähigkeiten zurück. Das Fehlen eines Providers ist zu erwarten und darf keinen Download oder Netzwerk-Fallback auslösen.
Überwachte KI-Video-Überprüfung und Bergung
Verwende video_verdict, video_acceptance_eval, video_body_swap und video_salvage (oder ihre flachen CLI- und Python-Äquivalente) für exakte Asset-Editorialentscheidungen und derivative Wiederherstellung. Ein nicht genehmigtes Urteil kann die Agentenanalyse erfassen, aber eine genehmigte Disposition muss eine aktive, exakte menschliche Entscheidung mit expliziter Anforderung, Rolle und Artefakt-Nachweisen binden. Die Akzeptanzbewertung ist abgeleitet und keine Genehmigungsaktion, und jede Bergungsausgabe beginnt in einem neuen, nicht genehmigten Überprüfungsslots.
Erfinde niemals eine Entscheidungs-ID, gib eine nicht gespeicherte Genehmigung weiter oder suche nach einem Force/Override-Pfad. Body-Swap lehnt eine Dauerabweichung ab, es sei denn, der Aufrufer wählt eine explizite Richtlinie. Bergung erfordert ein bestehendes privates Projekt, ein gespeichertes Quell-Asset, eine begrenzte Rezept-Richtlinie und eine exakte Akzeptanzspezifikations-ID.
Die Akzeptanzbewertung nimmt aktive gespeicherte acceptance_spec_id und verdict_ids, niemals vom Aufrufer erstellte Beweisobjekte. Public Body-Swap nimmt immer zuerst project_dir und beide Quellpfade müssen zu aktiven Assets in genau diesem Projekt auflösbar sein.
Lies docs/AI_VIDEO_REVIEW_AND_SALVAGE.md, bevor du diesen Workflow betreibst. Behandle jedes Derivat als neue, nicht genehmigte Arbeit und behalte das explizite menschliche visuelle/auditive Gate vor der Veröffentlichung bei.
Planung nach der Rettung
Verwende das passende video_* MCP-Tool, den flachen CLI-Befehl oder die Client-Methode, wenn die Anfrage semantisches Abrufen, gewöhnliche Bereinigungs-Bearbeitungen, subjektbewusste Transformationen, Wiederherstellung, Composition, kreative Koordination oder Remote-Egress benötigt. Übergib JSON-kompatible Beweise und Absicht; präsentiere den zurückgegebenen Plan und Diff vor jedem separaten Renderschritt.
Erfinde niemals Quellbeschreibungen, verstecke Unsicherheit, leite Genehmigung aus einem Plan ab oder behandle einen fehlenden lokalen Executor als Erlaubnis, einen Cloud-Provider zu verwenden. Remote-Arbeit erfordert ein separates Egress-Manifest und Genehmigung. Ein Planer, dem Beweise oder Fähigkeiten fehlen, muss sich enthalten.
Geschichtetes Compositing
Verwende composite-layers / video_composite_layers, wenn die Bearbeitung ein geordneter Stapel von Bild-, Video- oder Vollton-Layern ist, insbesondere untere Drittel, Bild-in-Bild-Varianten, Blurback-Platten, Masken/Mattes oder plattformspezifische Layout-Varianten.
Bevorzuge diesen Pfad gegenüber rohen FFmpeg-Filtergraphen, wenn ein Agent Transformationen, Deckkraft, Start-/Dauerfenster, Masken/Matte-Alphaquellen oder eine Quittung benötigt, die vor der Veröffentlichung überprüft werden kann.
Plan-zuerst-Flow:
- Schreibe eine JSON-Spezifikation mit
canvas, geordnetenlayersund expliziteroutput. - Führe
kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.jsonaus. - Inspiziere den Layer-Plan auf Quell-Hashes, Filtergraph-Hash, Transformationen, Rotation/Pivot, Blend-Modi, Timing-Fenster und Masken.
- Rendere erst, nachdem der Plan richtig aussieht.
- Führe
video-quality-check,storyboardoderthumbnailundvideo_release_checkpointaus.
Der Compositor unterstützt zugelassene Vollbild- und positionierte Blend-Modi (multiply, screen, overlay, darken, lighten) mit Deckkraft und Timing-Fenstern; Quittungen bleiben layer_plan v2. Nicht-normal-Blends unterstützen Deckkraft und start/duration-Fenster in zwei Geometrien: Vollbild bei {0,0} ohne explizite Größenangabe oder ein positioniertes Rechteck mit sowohl positiver ganzzahliger width als auch height und einer integralen, nichtnegativen Position innerhalb der Leinwand. Das RGB-Blenen vermeidet die Anwendung von Farbarithmetik auf subabgetastete Chroma-Ebenen. Skalierung, Rotation/Pivot, Masken/Matte, Bruchpositionen und rechteckige Formate außerhalb der Leinwand bleiben zurückgestellt und schlagen mit unsupported_blend_geometry fehl. Video-Layer und Video-Masken beginnen ihre Wiedergabe zu ihrem deklarierten Start. Halte alle Quellen und Masken innerhalb des Spezifikationsverzeichnisses. Die Ausgabe ist nur Video; anchor ist ein Positionsalias, unterschieden von pivot. Rotation + Maske, Audiocompositing und vollständige NLE-Adapter bleiben zurückgestellt. Inspiziere die Quittung vor der menschlichen Überprüfung; behandle dies nicht als vollständigen NLE-Ersatz.
Agent-Workflow-Engine
Wenn die Bearbeitung ein mehrstufiger Job ist (kein einzelner Toolaufruf), verwende die Workflow-Engine, um zu planen, validieren, rendern, wiederherzustellen und nachzuweisen von einer JSON-Job-Spezifikation aus – über video_workflow_* (MCP), workflow-* (CLI) oder Client.workflow_* (Python). Operationen sind eine kleine Zulassungsliste (probe | trim | resize | convert | crop | add_text | merge | composite_layers | burn_in), die an geprüfte Engines gebunden sind; Medienreferenzen sind symbolisch (@sources.*, @work/*, @outputs.*) und arbeitsbereichsbeschränkt; alles schlägt geschlossen fehl. Siehe ../../docs/WORKFLOWS.md.
Plan → validieren → rendern → inspizieren → fortsetzen:
workflow-validate --spec job.json– günstiges strukturelles Gate; rendert nichts.workflow-plan --spec job.json --save-plan plan.json– Trockenlauf-OP-Graph + Quellproben/Hashes; rendert null Medien.workflow-render --spec job.json --save-receipt receipt.json– sequentiell ausführen; eine Herkunftsquittung ausgeben (Pro-Schritt-Hashes, Bereinigungsmanifest, Determinismus-Vorbehalt). Füge--all-variantsfür Batch-Varianten hinzu.workflow-inspect --receipt receipt.json– schreibgeschützte Integritätsprüfung + Hinweise zur menschlichen Überprüfung, bevor du einer Quittung vertraust.workflow-render --spec job.json --resume receipt.json– einen Job fortsetzen, der mit Zwischenergebnissen fehlgeschlagen ist (fehlgeschlossen bei geänderter Spezifikation).
Quittungen speichern nur arbeitsbereichsrelative Pfade – halte Spezifikationen und Beispielquittungen frei von Home-Pfaden, Benutzernamen und Token.
Arbeitsablauf
- Inspiziere zuerst die Eingabe:
kino info <datei>oder das MCP/Python-Äquivalent. - Erstelle einen risikoarmen Plan: Trimmen, Größenänderung, Audi Normalisierung, Untertitel, Overlays, Effekte oder Hyperframes-Render.
- Bevorzuge Vorschauen oder Trockenlauf-Manifeste vor teuren oder destruktiven Exporten:
previewfür schnelle visuelle Überprüfung.repurpose-planvorrepurpose.- Hyperframes
inspect,snapshotoderstillvor vollem Render. - Für gespeicherte Shorts-Pläne:
shorts-plan-show→shorts-review→shorts-render→shorts-package. - Für Thin Sound:
sound-capabilitiesdannsound-plan-validate/sound-voice-batch/sound-mix-render/sound-qa-loudness/sound-qa-asr(oderkino sound <aktion>). - Gib numerische Werte für Sound-Dauern, Verstärkungen, Lautstärke und Profilversionen an; Booleans werden vor der Koerzession abgelehnt. Explizite ungültige Pläne können den Beispielplan nicht auswählen. Typisierte Pläne werden erneut validiert; siehe
docs/SOUND_INPUT_VALIDATION.mdfür feldspezifische Kompatibilitätsregeln. - Echte ASR verwendet eine gehashte Audio/Referenz-Anfrage und explizites Root; behalte sein Transkript-ZIP und melde Unstimmigkeiten ehrlich. Nur zwischengespeichertes lokales Whisper; keine automatischen Downloads. Legacy-Hash-Only-Aufrufe sind Simulationen. Siehe
docs/SOUND_ASR_REQUESTS.md. - Für echte Mono/Stereo-PCM16-Loudness-QA, liefere
SoundLoudnessRequestplus Projekt-Root und inspizierewithin_tolerance; erfolgreiche Messung kann nicht konform sein. FFmpeg ist erforderlich, und die No-Input-Fixierung wird als Demo gekennzeichnet. Siehedocs/SOUND_LOUDNESS_REQUESTS.md. - Für beibehaltenes Mono/Stereo-Mastering, liefere
SoundMasterRequestund explizites Root ansound-master-render; siehedocs/SOUND_MASTER_REQUESTS.md. Inspiziere das verifizierte ZIP, den tatsächlichen Normalisierungsmodus und die gemessene endgültige Richtlinieneinhaltung, dann höre vor der Veröffentlichung zu. Eingangskanäle werden beibehalten; vorhandene Ausgabe wird nie ersetzt. - Für tatsächliche lokale EN/ES ca.
...
[abgeschnitten für Übersetzung]