Communitygithub.com

KyaniteLabs/kinocut

Nutze Kinocut für bewachte Videobearbeitung, quellbasierte Planung, FFmpeg-Operationen, Medienanalyse, Untertitel, Audio-Workflows, Hyperframes- oder Revideo-Rendering, Wiederverwendungspakete und Release-Checkpoints über einen MCP-Server, Python-Client oder CLI. Wird ausgelöst, wenn ein Agent lokale Medien sicher inspizieren, planen, bearbeiten, rendern, validieren oder paketieren muss.

Was ist kinocut?

Kinocut ist ein strukturiertes Videobearbeitungssystem, das speziell für KI-Agenten entwickelt wurde, die lokale Medien bearbeiten müssen, ohne dabei auf die manuelle Erstellung von FFmpeg-Befehlen angewiesen zu sein. Es bietet eine umfassende Suite von Werkzeugen, die über drei Oberflächen zugänglich sind: einen MCP-Server (ideal für Claude Code, Cursor und Codex), einen Python-Client (für wiederholbare Pipelines) und eine CLI (für direkte lokale Edits und JSON-Ausgabe). Zu den Kernfunktionen gehören die 360-Grad-Dual-Kamera-Assemblierung (für eine einzelne gestitchte equirectanguläre 360-Grad-MP4), ein optionales Objekt-Matte-Modul mit einem BIREFNet-General-Modell für Produkt-Hintergrundentfernungen, eine dedizierte Videorettung mit einem genehmigungsbasierten Ablauf sowie eine deterministische KI-Video-Inspektion mit den Tools 'video_ingest', 'video_preflight' und 'video_inspect_temporal'. Kinocut erzwingt eine klare Trennung zwischen Planung und Ausführung: Ein Agent muss immer einen Bearbeitungsplan erstellen und vor dem Rendern genehmigen lassen, wodurch nicht genehmigte Operationen verhindert werden. Für komplexe, mehrstufige Jobs kann die agentive Workflow-Engine genutzt werden, die über einen Job-Spec definiert wird und eine schrittweise Ausführung mit Plänen, Validierung, Zwischenspeicherung und Fortsetzung ermöglicht. Alle Ausgaben werden durch eine Videoqualitätsprüfung und einen Checkpoint-Prozess validiert, bevor sie als verifiziert gelten, und eine menschliche visuelle/auditive Überprüfung ist vor der Veröffentlichung obligatorisch. Kinocut ist auf Privatsphäre und Lokalität ausgelegt: Cloud-Nutzung erfordert eine explizite Genehmigung, und alle Operationen bleiben auf dem lokalen Rechner, ohne automatische Downloads oder Netzwerk-Fallback.

Funktioniert mit✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/KyaniteLabs/kinocut/tree/HEAD/skills/kinocut

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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)

  1. kino doctor dann kino --format json info <datei>.
  2. Rufe bei einer unbekannten Aufgabe search_tools mit der Benutzeraufgabe auf (z. B. „Füllwörter entfernen“ oder „Gesicht im Bild halten“), inspiziere dann die erforderlichen Eingaben des zurückgegebenen Tools. Plane mit video_intent für unterstützte Absichten (optional goal= kompiliert eine Cutdatei; ein 360/Desk/Table/x4-Ziel schlägt auch einen 360_assembly_plan vor). Überprüfe, ob der Vorschlag die Anfrage tatsächlich erfüllt, bevor du renderst.
  3. Rendern (video_cutfile_render, video_edit, Workflow oder ein einzelnes Engine-Tool). Für 360: video_review_decide genehmigen/ablehnen des Plans, dann rendern – rendere niemals einen proposed-Plan. .insv wird abgelehnt; benötige eine gestitchte 360-MP4. Anleitung: docs/360_ASSEMBLY.md.
  4. video-quality-check / assert_quality. Sync repurpose und shorts-package schlagen bei einer Punktzahl von 80 fehl, es sei denn, sie werden übersprungen/allow_fail.
  5. 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.md für die Installation und den Sicherheitsvertrag.
  • Führe kino doctor vor 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.

  1. video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH) oder Client.propose_360_assembly(...).
  2. Zeige Kameras, Layout und Storyboard-Standbilder. Erfinde kein Yaw/Pitch.
  3. video_review_decide / Client.decide_360_assembly mit approve oder reject.
  4. Rendere nur einen genehmigten Plan (Client.render_360_assembly oder video_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:

  1. hyperframes_remove_background(info=true) – listet Modelle auf, kein Download.
  2. pip install "kinocut[object-matte]" dann model="birefnet-general".
  3. Optional --mask-interval 3 bei Produktvideos. Optionales Ausrüstungs-Overlay für übrig gebliebene Drehteller/Ständer/Stative/Schwenks.
  4. Composite auf eine Shop-Platte mit composite-layers. Behalte jedes src innerhalb 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:

  1. Rufe den Plan auf und speichere das Planartefakt.
  2. Präsentiere safe_repairs, recommendations, unavailable_repairs, blocked_repairs, Vorschauen, Paketabsichten, Fähigkeiten und eine Schätzung dem Benutzer.
  3. Inspiziere den Plan vor dem Rendern. Erhalte oder leite explizite Genehmigung nur für IDs in safe_repairs ab; das Weglassen der ID-Liste bedeutet alle sicheren IDs im überprüften Plan.
  4. Rufe das Rendern mit genau diesen genehmigten sicheren IDs auf.
  5. 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:

  1. Schreibe eine JSON-Spezifikation mit canvas, geordneten layers und expliziter output.
  2. Führe kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json aus.
  3. Inspiziere den Layer-Plan auf Quell-Hashes, Filtergraph-Hash, Transformationen, Rotation/Pivot, Blend-Modi, Timing-Fenster und Masken.
  4. Rendere erst, nachdem der Plan richtig aussieht.
  5. Führe video-quality-check, storyboard oder thumbnail und video_release_checkpoint aus.

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:

  1. workflow-validate --spec job.json – günstiges strukturelles Gate; rendert nichts.
  2. workflow-plan --spec job.json --save-plan plan.json – Trockenlauf-OP-Graph + Quellproben/Hashes; rendert null Medien.
  3. workflow-render --spec job.json --save-receipt receipt.json – sequentiell ausführen; eine Herkunftsquittung ausgeben (Pro-Schritt-Hashes, Bereinigungsmanifest, Determinismus-Vorbehalt). Füge --all-variants für Batch-Varianten hinzu.
  4. workflow-inspect --receipt receipt.json – schreibgeschützte Integritätsprüfung + Hinweise zur menschlichen Überprüfung, bevor du einer Quittung vertraust.
  5. 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

  1. Inspiziere zuerst die Eingabe: kino info <datei> oder das MCP/Python-Äquivalent.
  2. Erstelle einen risikoarmen Plan: Trimmen, Größenänderung, Audi Normalisierung, Untertitel, Overlays, Effekte oder Hyperframes-Render.
  3. Bevorzuge Vorschauen oder Trockenlauf-Manifeste vor teuren oder destruktiven Exporten:
    • preview für schnelle visuelle Überprüfung.
    • repurpose-plan vor repurpose.
    • Hyperframes inspect, snapshot oder still vor vollem Render.
    • Für gespeicherte Shorts-Pläne: shorts-plan-show → shorts-review → shorts-render → shorts-package.
    • Für Thin Sound: sound-capabilities dann sound-plan-validate / sound-voice-batch / sound-mix-render / sound-qa-loudness / sound-qa-asr (oder kino 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.md fü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 SoundLoudnessRequest plus Projekt-Root und inspiziere within_tolerance; erfolgreiche Messung kann nicht konform sein. FFmpeg ist erforderlich, und die No-Input-Fixierung wird als Demo gekennzeichnet. Siehe docs/SOUND_LOUDNESS_REQUESTS.md.
    • Für beibehaltenes Mono/Stereo-Mastering, liefere SoundMasterRequest und explizites Root an sound-master-render; siehe docs/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]

Verwandte Skills