Communitygithub.com

daniela-socoloski/raiz-engine

Gesprächsgesteuerte Videobearbeitung für vertikale Kurzformate (Reels, TikTok, Shorts) und horizontale Langformate. Verwenden, wenn geschnitten, farbkorrigiert, untertitelt, Grafiken hinzugefügt, ein Soundtrack erstellt, transkribiert oder Videobearbeitungen vorbereitet werden sollen. Führen Sie Phase 1 (audiogeführter Rohschnitt und Farbkorrektur) durch, holen Sie die Genehmigung ein und erstellen Sie dann Phase 2/3 mit Remotion-Visuals und Audio.

Was ist raiz-engine?

Der Cena Raiz Skill ist ein KI-gestütztes Videobearbeitungssystem, das für KI-Agenten wie Claude Code, Cursor und Codex entwickelt wurde. Es ermöglicht gesprächsgesteuerte Bearbeitungsabläufe für Kurzformate (Reels, TikTok, Shorts) und Langformate. Der Skill folgt einem strengen Zwei-Phasen-Modell: Phase 1 führt einen sauberen, audiogeführten Rohschnitt mit Farbkorrektur durch, wobei FFmpeg für die segmentweise Extraktion und verlustfreie Konkatenation verwendet wird. Phase 2 fügt mit Remotion Untertitel, Grafiken und Soundeffekte hinzu, wobei ein datengesteuerter Ansatz verwendet wird, der die manuelle Bearbeitung von Vorlagen-Code vermeidet. Das System priorisiert Audio als primären Treiber für Schnittentscheidungen: Schnittkandidaten werden anhand von Sprachgrenzen und Stillelücken identifiziert und Wortgrenzen aus Transkriptionen beachtet. Die lokale Pipeline verwendet WhisperX für wortgenaue Transkription mit forcierter Ausrichtung auf dem Gerät (kein API-Key erforderlich) und bietet umfangreiche Hilfsprogramme für Transkription, Transkript-Paketierung, Sprachpegelmessung, Bauchredner-Erkennung und visuelle Inspektion. Eine standardisierte Vorschau-Oberfläche mit Zeitleiste, Playhead und Einstellungspanels wird für jede Sitzung gestartet und ermöglicht interaktive Überprüfung und Zusammenarbeit. Der Skill erzwingt eine Produktionsdisziplin durch 13 unverhandelbare Regeln, darunter eine Phasentrennung (keine Phase-2-Arbeit vor Genehmigung des Rohschnitts), segmentweise Farbkorrektur, numerische Prüfung vor visueller Inspektion und die strikte Vermeidung von eingebrannten Texten oder Overlays in Phase 1. Der Arbeitsablauf betont menschliche Bestätigung in jeder Phase: Zuschneidestrategie, Rohschnitt-Genehmigung und schließlich die endgültige Freigabe. Optional kann das System über Adobe MCPs für die Arbeit in Premiere Pro und After Effects angebunden werden, wobei die gleiche phasenbasierte, audiogeführte Methodik beibehalten wird.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/daniela-socoloski/raiz-engine/tree/HEAD/skills/cena-raiz

In Ihrer bevorzugten KI fragen

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

Dokumentation

Cena Raiz

Prinzip

  1. Zwei Phasen, ein Tor dazwischen. PHASE 1 ist der saubere Schnitt + die Farbkorrektur; PHASE 2 sind Untertitel, Grafiken und Bilder. (Harte Regel 1 erzwingt das Tor.)
  2. Das LLM denkt anhand des rohen Transkripts und bei Bedarf visueller Hilfsmittel. Das einzige abgeleitete Artefakt, das seinen Wert verdient, ist das gepackte Transkript auf Satzebene (takes_packed.md). Alles andere wird erst zum Entscheidungszeitpunkt abgeleitet.
  3. Audio ist primär, Bilder folgen. Schnittkandidaten stammen aus Sprachgrenzen und Stillelücken.
  4. Fragen → Bestätigen → Ausführen → Iterieren → Speichern. Berühren Sie den Schnitt erst, wenn der Benutzer die Strategie in einfachem Deutsch bestätigt hat.
  5. Verallgemeinern. Sehen Sie sich das Material an, fragen Sie den Benutzer und bearbeiten Sie dann – gehen Sie nie davon aus, um welche Art von Video es sich handelt.
  6. Künstlerische Freiheit ist der Standard. Bestimmte Werte hier sind Beispiele, keine Vorgaben. Nur die Harten Regeln sind verbindlich.
  7. Geben Sie Tokens dort aus, wo der Geschmack sitzt. Maschinendaten sind für Programme, nicht zum Lesen; die Verifizierung ist numerisch, bevor sie visuell ist. Ihre Aufmerksamkeit ist die knappe Ressource – verwenden Sie sie für den Schnitt, nicht zum Parsen von JSON. (Die Harten Regeln 12 und 13 legen fest, was dies verbietet.)

Harte Regeln (Produktionskorrektheit – nicht verhandelbar)

  1. Das Phasentor ist echt. Keine Phase-2-Arbeit, bevor der Schnitt genehmigt wurde.
  2. Segmentweise Extraktion → verlustfreie -c copy-Konkatenation, niemals ein einziges Filtergraph. (Beim standardmäßigen J-Schnitt werden Bild und Ton eines Takes als separate Bereiche extrahiert und die Audiospuren aufsummiert – das ist der einzig zulässige Mix, und der Videopfad erfolgt weiterhin segmentweise + verlustfreie Konkatenation.)
  3. 30ms Audio-Überblendungen an jedem Segmentübergang (kodiert in render.py).
  4. Niemals innerhalb eines Wortes schneiden – an Wortgrenzen aus dem Transkript ausrichten.
  5. Schnittkanten polstern (30–200ms Fenster; Nachlauf etwas länger als Vorlauf). Nach Möglichkeit auf Stille schneiden.
  6. Transkripte pro Quelle zwischenspeichern. Nie neu transkribieren, es sei denn, die Quelle hat sich geändert.
  7. Farbkorrektur pro Segment während der Extraktion, niemals nach der Konkatenation.
  8. Strategiebestätigung vor der Ausführung.
  9. Alle Sitzungsausgaben in <videos_dir>/edit/ – niemals innerhalb des cena-raiz-Repositoriums.
  10. PHASE 2 ist nur Remotion – kein mit ffmpeg/PIL eingebrannter Text oder Overlays.
  11. PHASE 2 ist datengesteuert. Gerüst aufbauen, indem die Track-Vorlage kopiert wird; das Video in public/edit-data.json beschreiben. Niemals den Vorlagen-TSX lesen oder bearbeiten (src/Main.tsx usw.) – die einzige bearbeitbare Codedatei ist src/CustomGraphics.tsx, nur für maßgeschneiderte Grafiken.
  12. Zuerst numerisch verifizieren. verify_cut.py auf jedem gerenderten Schnitt ausführen; Bilder nur für markierte Übergänge öffnen. Jede Multi-Frame-Ansicht in einer contact_sheet.py / grade.py --candidates-Montage zusammenfassen.
  13. Niemals Maschinendaten in den Kontext lesen: transcripts/*.json (roh), captions.json, track.json, segments.json, Matten/Track-Binärdateien. Stattdessen takes_packed.md und Hilfsprogramm-Stdout lesen.

Ausführungsumgebung – lokale Pipeline vs. Adobe MCP

Die Standard-Engine ist die unten beschriebene ffmpeg/Remotion-Pipeline. Für die Verbindung, Diagnose, Fähigkeitserkennung oder kontrollierte Arbeit über die lokalen Adobe MCPs lesen Sie zuerst references/adobe-mcp.md. Es ist clientneutral: Das gleiche Verfahren gilt für Codex und Claude Code.

Wenn der Benutzer die Bearbeitung in Adobe Premiere Pro über das premiere-pro MCP wünscht ("edite a sequência no Premiere", "corte via MCP"), lesen Sie ebenfalls references/premiere-mcp.md. Die METHODE bleibt unverändert – Audio primär, Schnitt auf Stille, Phasentor, geschmackvolle Farbkorrektur – aber die Werkzeuge ändern sich. Transkription und edl.json sind identisch und zwischengespeichert, daher ein genehmigtes EDL wiederverwenden und cut.mp4/Vorschau überspringen. After Effects-Schreibvorgänge unterliegen weiterhin der kontrollierten Adobe-Phase des Repositoriums; die bloße Verfügbarkeit von MCP autorisiert keine Mutation.

Verzeichnisstruktur

<videos_dir>/
├── <Quelldateien, unberührt>
└── edit/
    ├── project.md               ← Gedächtnis; wird bei jeder Sitzung ergänzt
    ├── takes_packed.md          ← Transkripte auf Satzebene, die primäre Leseansicht
    ├── edl.json                 ← Schnittentscheidungen (Phase 1)
    ├── transcripts/<name>.json  ← zwischengespeicherte Transkripte auf Wortebene (WhisperX, lokal)
    ├── clips_graded/            ← Segmentweise Extrakte mit Farbkorrektur und Überblendungen
    ├── cut.mp4                  ← PHASE 1 Ausgabe: sauberer bearbeiteter Schnitt (Genehmigungsartefakt)
    ├── verify/                  ← Montagen / markierte Grenzansichten
    ├── captions.srt + chapters.txt   ← Langformat-Liefergegenstände
    ├── final.mp4                ← Gelieferter Render (Phase 2 + 3, loudnorm'd)
    └── remotion/                ← Remotion-Projekt (Phase 2 + 3)
        ├── public/              ← cut.mp4, edit-data.json (DER Schnitt), captions.json,
        │                          track.json, segments.json, pexels/ web/ brand/, sfx/, trilha.mp3
        └── src/                 ← unveränderlicher Vorlagencode + CustomGraphics.tsx

Einrichtung

Die Ersteinrichtung befindet sich in install.md. Bei einem Kaltstart einfach überprüfen:

  • Transkription benötigt KEINEN API-Schlüssel. WhisperX wird als Abhängigkeit mitgeliefert: uv sync ist die gesamte Installation. Es transkribiert mit Whisper und führt dann eine ERZWUNGENE AUSRICHTUNG (wav2vec2) gegen die Wellenform durch, sodass Wortzeiten gemessen und nicht abgeleitet werden – 93 % der Wörter landen in einer echten Sprachregion und das Ende der Sprache wird innerhalb von 10 ms platziert (gemessen gegen speech_regions.py). Modelle werden beim ersten Ausführen einmal heruntergeladen und zwischengespeichert. Die Geschwindigkeit liegt etwa in Echtzeit und verbessert sich mit der Länge (das Laden des Modells dauert fest ~18 s: ein 16 s Clip benötigte 23 s, eine 166 s Quelle 109 s).
  • Ein /UNALIGNED-Suffix in _transcription_backend bedeutet, dass kein wav2vec2-Modell für die erkannte Sprache existierte, sodass die Wortzeiten die des Decoders selbst sind – grob und für Phase-2-Karaoke-Untertitel nicht sicher. Sagen Sie es, falls es vorkommt.
  • ffmpeg + ffprobe im PATH; Python-Abhängigkeiten (uv sync); Node 18+ für Phase 2. yt-dlp wird mit den Python-Abhängigkeiten ausgeliefert, sodass URL-Quellen keine zusätzliche Installation benötigen.
  • Der remotion-best-practices-Skill für Phase-2-Domänenwissen (bei Bedarf von https://github.com/remotion-dev/skills installieren).
  • Phase 2/3 können optionale API-Schlüssel verwenden (illustrative Bilder, KI-Soundtrack). Diese sind in der Track-Referenz aufgeführt, werden verzögert abgefragt, wenn die Funktion zum ersten Mal verwendet wird, und niemals zur Installationszeit. Nichts in Phase 1 benötigt einen Schlüssel.

Helfer befinden sich in helpers/, aufgelöst relativ zu dieser SKILL.md (normalerweise ~/.claude/skills/cena-raiz/ oder ~/.codex/skills/cena-raiz/ oder ein Symlink/Junction dorthin). Führen Sie sie aus als uv run python helpers/<name>.py – ein bloßes python verpasst das .venv, das uv sync erstellt.

Helfer

Phase 1:

  • ingest_url.py <url> --dest <videos_dir> [--section 12:00-25:30] [--max-height 1080] — Bearbeitung von einem Link: yt-dlp → MP4 (≤1080p) direkt in das Videos-Verzeichnis; von dort ist es eine Quelle wie jede andere. --section lädt NUR einen Zeitbereich einer Langformat-Quelle herunter (keyframe-genau) – die günstige Art, Minuten 12–25 eines 1-stündigen Videos auszuschneiden. --simulate gibt Titel/Dauer/Auflösung aus, ohne herunterzuladen (vor großen Abrufen bestätigen; diese im Hintergrund ausführen).
  • transcribe.py <video> --edit-dir <edit> [--language pt] [--model large-v3-turbo] — wortgenau, zwischengespeichert, lokal (WhisperX + erzwungene Ausrichtung). Keine Obergrenze, kein Aufteilen in Blöcke. --language übergeben, wenn Sie es wissen – die automatische Erkennung kostet einen Durchlauf und kann bei einem kurzen Clip falsch liegen.
  • transcribe_batch.py <videos_dir> — Jede Quelle in einem Verzeichnis, eine nach der anderen (lokale Inferenz verwendet bereits alle Kerne). Pro Datei zwischengespeichert, und ein Fehler bei einer Quelle führt nicht zum Verlust der bereits erledigten.
  • pack_transcripts.py --edit-dir <dir> — Transkripte → takes_packed.md (Satzebene, bricht bei ≥0.5s Stille ab). Die Leseansicht: 1/10 der Tokens des rohen JSONs.
  • speech_regions.py <video> — Akustische Sprachintervalle mittels Silencedetect. Die Quelle der Wahrheit für SchnittKANTEN (Whisper-Zeiten driften/dehnen sich). Antwortet wo Sprache ist – niemals wie laut sie ist.
  • voice_levels.py <video> [--edit-dir <dir>] [--edl edl.json] [--drop-db 5] — die Quelle der Wahrheit für den SprachPEGEL. Markiert jeden Satz, EDL-Bereich ≥5 dB unter dem eigenen Median des Sprechers und dimensioniert ein gain_db. Es fängt ein, was sonst nichts tut: ein geflüstertes Nebenbemerkung, bei dem das Transkript perfekt ist, speech_regions „Sprache" sagt und verify_cut keinen Fehler findet – und der Zuschauer es trotzdem nicht hören kann. Vor dem Schreiben des EDL ausführen.
  • detect_color.py <video> [--json] — löst NORMAL vs. LOG aus der Datei auf, anstatt zu fragen – zuerst Metadaten, Bildstatistiken, wenn die Metadaten schweigen (häufig: eine Transkodierung entfernt die Tags). Gibt Profil, Konfidenz, Beweise und die anzuwendende grade zurück. Nur confidence: low sollte Sie zurück zum Benutzer schicken; die Identifikationsdetails befinden sich in references/log-grade.md.
  • render.py <edl.json> -o cut.mp4 --no-subtitles [--voice-master] [--keep-resolution] [--jobs N] [--no-jcut] [--jcut-lead N] [--jcut-tail-trim N] — Segmentweise Extraktion (Farbkorrektur + Überblendungen, parallel) → J-Schnitt-Überlappungs-Assemblierung (Standard) oder verlustfreie Konkatenation → optionaler Voice-Master → Loudnorm. Schreibt jcut_timeline in das EDL: die tatsächlichen Ausgabepositionen, auf die alles nachgelagerte indexieren muss. Die Bildrate für Kurzformate ist automatisch: 30fps für 30fps+-Quellen, sonst 24 (Langformate behalten die Quellbildrate über --keep-resolution). Setzen Sie edit-data.json fps entsprechend dem resultierenden cut.mp4.
  • verify_cut.py <edl.json> <cut.mp4> [--min-silence 1.2] — Numerische Selbstbewertung: Dauer, pro Übergang Pop-/Wort-Clipping-Prüfungen, tote Luft, schwarze Bilder, Clipping und Pegelbalance über Bereiche hinweg (jeder Bereichs-RMS im Vergleich zum Medianbereich; LOW-LEVEL unter −4 dB). ~350 Tokens Text anstelle von N Bildern. Die Bereichsbalance-Zeile ist der Konvergenztest für eine gain_db-Korrektur.
  • grade.py <in> -o <out> — Grade-Voreinstellungen/rohe Filter. --candidates "a=<filter>;b=<preset>;original=" --frame <t> -o cmp.png rendert N Looks auf dem GLEICHEN Bild in einer beschrifteten Montage.
  • timeline_view.py <video> <start> <end> — Filmstreifen+Wellenform-PNG für EINE markierte Stelle, kein Scan-Werkzeug.
  • contact_sheet.py <video> --times t1 t2 … -o sheet.png — N Bilder in einem beschrifteten Raster; die Methode, um mehrere Momente zu überblicken, die Sie bereits kennen.
  • watch_video.py <video> [--mode scene|keyframe|uniform] [--times t1 t2 …] [--start/--end] [--max-frames 24] — „Was ist IN diesem Filmmaterial?", wenn Sie nicht wissen, wo Sie suchen sollen: Szenenerkennung + Wahrnehmungs-Dedup → beschriftete Kontaktblätter in edit/verify/watch_<stem>/, ein Read pro Blatt. Für die visuelle Bestandsaufnahme unbekannten Materials und zur Untersuchung von cut.mp4 über die Zahlen von verify_cut hinaus. --times fixiert Transkript-Hinweis-Bilder: deiktische Momente aus takes_packed.md („olha isso", „como você pode ver") sind visuell ARM und für die Szenenerkennung unsichtbar – fixieren Sie sie, um in Phase 2 über B-Roll/Callout/Zoom-Platzierung zu entscheiden.

Phase 2/3 Helfer (Untertitel, Gesichtsverfolgung, Bildersuche, Musik) sind in der Track-Referenz aufgeführt, die Sie nach dem Tor laden.

Schnittstelle:

  • preview_server.py --root <edit> [--port 4820] — Bedient die Standard-Vorschauoberfläche (siehe Abschnitt Vorschauoberfläche). Der App-Code befindet sich unter assets/preview/ und ist UNVERÄNDERLICH.

Vorschauoberfläche (Standard – starten Sie sie zu Beginn jeder Bearbeitung)

Jede Bearbeitungssitzung erhält dieselbe interaktive Oberfläche im Vorschaufenster des Benutzers: eine Video-Editor-Zeitleiste (Videospur mit Filmstreifen + Audiospur mit Wellenform), einen Live-Abspielkopf, der den Render in Echtzeit durchläuft, Trim-Griffe pro Take und Take-Entfernung und – ab Phase 2 – Untertitel- und Einfügungsspuren. Das Layout folgt dem Seitenverhältnis der Quelle von selbst: vertikale Quellen platzieren einen hohen Player rechts mit Transport- + Zeitleiste links; horizontale Quellen behalten den Player über der Zeitleiste gestapelt. Dunkles Glas, Marke Cena Raiz. Nie eine UI pro Sitzung bauen – die Standardoberfläche mit state.json füttern. Die Bearbeitung von assets/preview/ ist nur erlaubt, wenn der Benutzer eine UI-Änderung wünscht; es wird geteilt, sodass die Verbesserung für jedes Projekt greift.

Starten (dies zu Beginn einer Sitzung tun, sogar vor dem ersten Render – die UI zeigt einen Wartezustand an):

  1. <edit>/state.json schreiben:

    {"project": "Nome — C0000", "phase": 1, "video": "cut.mp4", "edl": "edl.json",
     "captions": "remotion/public/captions.json", "editData": "remotion/public/edit-data.json",
     "finalVideo": "final.mp4", "fps": 24, "message": "Fase 1 — cortando",
     "sourceDurations": {"C0000": 1038.5},
     "awaitingStyle": false,
     "style": {"edit": "split", "captions": "karaoke",
               "elements": {"tracking": false, "zoomAuto": true, "zoomCuts": true, "musicAI": false}}}
    

    (captions/editData/finalVideo nur, wenn sie existieren; der Fase-2-Tab spielt finalVideo ab – den Render MIT Untertiteln/Einfügungen – während Fase 1 den sauberen Schnitt abspielt; sourceDurations erlaubt der UI, Take-Verlängerungen zu begrenzen; awaitingStyle/style steuern den Estilo-Tab unten.)

  2. Wählen Sie den Laufzeit-Adapter; rufen Sie niemals Werkzeuge eines anderen Hosts auf.

    • Claude Code: Stellen Sie sicher, dass .claude/launch.json die Konfiguration hat (passen Sie --root pro Sitzung an). Der Server nimmt den Port nur per Flag entgegen, also übergeben Sie den harness-zugewiesenen $PORT und setzen Sie autoPort: {"name": "cena-raiz-preview", "runtimeExecutable": "sh", "runtimeArgs": ["-c", "exec python3 <skill>/helpers/preview_server.py --root '<edit>' --port \"$PORT\""], "autoPort": true, "port": 4820}. Führen Sie preview_start mit dem Namen cena-raiz-preview aus, und bewaffnen Sie dann Monitor(command="python3 <skill>/helpers/watch_edits.py '<edit>'", description="escolhas e marcações salvas no preview", persistent=true) im selben Zug.
    • Codex Desktop / CLI: starten Sie uv run python helpers/preview_server.py --root '<edit>' --port 4820 als lokalen Hintergrundprozess, wenn die Umgebung ihn am Leben erhalten kann. Sobald er antwortet, verwenden Sie den control-in-app-browser-Skill, um http://127.0.0.1:4820 automatisch im integrierten Browser zu öffnen und diesen Tab auf der Vorschau zu lassen. Gehen Sie nicht davon aus, dass preview_start, Monitor oder .claude/launch.json existieren. Wenn die Browser-Fähigkeit oder ein persistenter lokaler Prozess nicht verfügbar ist, geben Sie dem Benutzer stattdessen den Befehl und die lokale URL. Nachdem Sie die Vorschau gezeigt haben, sagen Sie dem Benutzer, er solle speichern und erneut ...

Verwandte Skills