mk-video-editing

Was macht mk-video-editing?

Wandeln Sie mitgeliefertes Filmmaterial in einen ansehnlichen, konsistenten Schnitt um: die richtigen Worte in der richtigen Reihenfolge, eine Kamera, die das Motiv gut einrahmt, ein konsistentes Bild, sauberer und gleichmäßiger Ton sowie geschmackvolle Titel. Die Struktur ergibt sich aus dem Filmmaterial und dem, was darin gesagt wird.

Was die Fähigkeit kann

Bedarf	Werkzeuge	Kosten	Referenz
Worttranskripte, Erkennung von Füllwörtern/Fehlstarts/Pausen	edit:transcribe (mlx-whisper), speech:flow	kostenlos, lokal	footage-editing.md
Stabilisieren, Sprecher verfolgen, 4K-Totalen neu einrahmen (Schübe, Punch-Ins, Schwenks), HDR→SDR, Deflicker, Farbangleichung, Überblendungen, Jump Cuts	edit:analyze, edit:track, EDL + medit (edit:render)	kostenlos, lokal	footage-editing.md
Dialogbereinigung, Mischung, Ducking, Lautstärke	speech:clean (ISOLATE=1 Demucs), speech:mix, speech:measure	kostenlos, lokal	footage-editing.md
Voice-Over	voice:tts (ElevenLabs via Fal)	kostenpflichtig, genehmigt	credentials.md
Titel, Einblendungen, Abspannkarten (ProRes 4444 Alpha)	mgraphics JSON-Szenen, graphics:render, Vorlagen in scripts/tools/graphics/examples/	kostenlos, lokal	Graphics-README
Musikbett unter dem Schnitt	EDL music (geduckt), music:score (ElevenLabs Music via Fal), audio:analyze für Beattiming	kostenpflichtig nur bei Generierung	finishing.md
Soundeffekte für Titel/Übergänge	SoundSynth (synth: whoosh, riser, impact, tick…), sfx:gen/sfx:mix oder EDL sounds	kostenlos (Stable Audio prompt: kostenpflichtig)	finishing.md
Bildeffekte (Blitz, Dip, Punch, Glühen, Linsen, Streifen…)	mvfx Cue-Sheets, vfx:stills/vfx:render	kostenlos, lokal	finishing.md
Ausgabe-Codierungen	media:twitter, media:youtube, media:faststart	kostenlos, lokal	tasks.md
Parallele Sub-Agents für unabhängige Jobs	work:next/work:accept/work:log/work:watch	kostenlos	tasks.md

Jede Aufgabe mit ihren Argumenten und Optionen befindet sich in tasks.md. Testprofile sind in testing.md.

Ausführungsvertrag

Entwickelt für Claude Code auf macOS 14+ auf Apple Silicon (Swift 5.9+, Ruby 3.2+, Bundler, FFmpeg, ImageMagick, uv für lokales Whisper). Führen Sie zuerst doctor aus, wenn eine Aufgabe aufgrund eines fehlenden Werkzeugs fehlschlägt; setup baut die Swift-Werkzeuge. Ruby ist die einzige Ausführungseinstiegsschicht: führen Sie ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project 'task[args]' aus. Aufgaben delegieren an Ruby-Dienste (lib/media/edit.rb, speech.rb, guard.rb, …), die die nativen Swift-Werkzeuge medit (scripts/tools/edit), mgraphics (scripts/tools/graphics) und mvfx (scripts/tools/vfx) steuern. Fügen Sie eine Ruby-Methode und eine dünne Aufgabe hinzu, wenn eine Fähigkeit fehlt. Ein Projekt führt seine eigene Kopie von lib/ und tools/ aus: Nach Änderungen an der Fähigkeit synchronisieren Sie die geänderten Dateien mit rsync in das Projekt.

Speichersicherheit (obligatorisch)

4K/HDR-Hardwaredekodierung hält Frames in VTDecoderXPCService, außerhalb des eigenen Speicher-Fußabdrucks des Jobs. Auf einem 16-GB-Rechner ohne Auslagerungsdatei führt Speichererschöpfung zum Einfrieren des Computers anstatt zu einer Verlangsamung. Daher:

• Führen Sie jeweils einen schweren Job aus (medit analyze/render/stills, mgraphics-Codierungen, Demucs, große ffmpeg-Codierungen). Starten Sie niemals mehrere parallel oder im Hintergrund gleichzeitig; verketten Sie sie sequentiell in einem Hintergrundbefehl, falls nötig. JOBS bleibt 1, es sei denn, der RAM beträgt ≥ 32 GB.
• Jeder medit/mgraphics/mvfx-Renderaufruf erfolgt über Media::Guard (automatisch in den Ruby-Diensten): es tastet den Job- + Decoder-Fußabdruck und den freien Kernel-Prozentsatz alle 0,3 s ab und beendet mit SIGKILL vor MEDIT_MAX_FOOTPRINT_MB (Standard 3500) oder unter MEDIT_MIN_FREE_PCT (Standard 30). Es verweigert den Start, wenn der freie Speicher bereits niedrig ist. Alle drei Renderer verwenden standardmäßig JOBS=1; parallele Blöcke erfordern eine explizite JOBS-Einstellung.
• Validieren Sie jeden neuen Decode/Render-Codepfad zuerst auf einer kurzen Reichweite mit engen Grenzen (TO=15 MEDIT_MAX_FOOTPRINT_MB=1500 MEDIT_GUARD_LOG=/path/log), überprüfen Sie, ob das Log flach ist, und führen Sie dann die volle Länge aus.
• Umwickeln Sie in Swift-Mediaschleifen jeden copyNextSampleBuffer- und Core-Image-Render in autoreleasepool (asynchroner Code leert niemals den Standard-Pool: Frames lecken mit ~1,5 GB/s).

Gemessener stationärer Zustand: Analyse ≈ 1,0 GB (Job + Decoder) pro 4K-HLG-Quelle; ein Render mit einer Überblendung öffnet zwei Quellen.

1. Aufnahme

Fragen Sie nur nach dem, was fehlt: Filmdateipfade, um was für einen Schnitt es sich handelt (Vortragsauszug, Zusammenfassung…), Titel/Abspann-Text, Ziellänge, Voice-Over-Wünsche. Initialisieren Sie mit den Medien (symgelinkt, niemals kopiert oder verändert):

ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" init --project /abs/project --media /abs/clip1.MOV --media /abs/clip2.MOV --prompt-file /abs/brief.md
ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project setup

Prüfen Sie jede Quelle (ffprobe: Größe, fps, Dauer, HDR-Transfer). Extrahieren Sie Audio (audio/raw/*.wav, 48 kHz) und transkribieren Sie lokal: edit:transcribe[analysis/transcripts,source/...] (mlx-whisper large-v3-turbo, Wortzeiten; kostenlos). Lesen Sie jedes Transkript und schreiben Sie, was jeder Clip sagt, mit Zeitstempeln, in docs/BRIEF.md. Recherchieren Sie im Web nach Ereignisfakten, die in Titeln verwendet werden, und dokumentieren Sie die Quellen.

2. Analysieren (sequentiell)

REGION=0,0,1,0.62 DETECT_REGION=0.15,0.3,0.85,0.8 mv 'edit:analyze[source/A.MOV,analysis/A.json]'   # eins nach dem anderen
mv 'edit:track[analysis/A.json,analysis/A.track.json]'      # SEED=x,y wenn der Sprecher nicht früh gefunden wird; SPACE=frame für Stabilisierung: 0
mv 'edit:stats[analysis/A.json,from,to]'

• REGION begrenzt die Stabilisierung (Phasenkorrelation) auf statische Szenenbereiche (Bühne, Bildschirme) und schließt das Publikum aus.
• DETECT_REGION beschneidet die Bühne für die Vision-Erkennung von Personen bei etwa 2-facher Auflösung – wesentlich für einen weit entfernten Sprecher (Erkennung stieg von 2 % auf 40–90 % der Samples).
• Tracks sind weltverankert (Stabilisierung entfernt), kontinuitätsausgewählt und lassen weite Vordergrundboxen (Köpfe) via max_aspect fallen.
• Handyaufnahmen (iPhone usw.) sind bereits in der Kamera stabilisiert: rendern Sie sie mit stabilize: 0 und SPACE=frame-Tracks. Unser Stabilisator kann bewegte Folieninhalte fälschlicherweise für Kamerabewegungen halten und plötzliche horizontale Sprünge hinzufügen. Überprüfen: zählen Sie Frames mit |Δshift| > 8 px in der Analyse; Restverwacklung bei iPhone 4K gemessen ≈ 0,9 px RMS, nicht korrekturbedürftig.

Sprachfluss (Füllwörter, Fehlstarts, Wiederholungen, unnatürliche Pausen)

VERBATIM=1 mv 'edit:transcribe[analysis/transcripts_verbatim,source/A.MOV]'   # macht Whisper bereit, ähm/äh zu schreiben
mv 'speech:flow[analysis/transcripts_verbatim/A.json,audio/clean/A.wav,analysis/flow/A.json]'   # lesen Sie analysis/flow/A.txt

Der Detektor misst Pausen akustisch (Energie + Stimmhaftigkeit, nicht Whisper-Wortzeiten), klassifiziert sie (Satz/Komma/Phrase) und markiert Füllwörter, nicht transkribierte Brummtöne, Wiederholungen und mögliche Fehlstarts, jeweils mit einem vorgeschlagenen cut. Entscheiden Sie über jede basierend auf der Bedeutung und wenden Sie dann Schnitte mit Media::Cuts im Generator (Schritt 4) an. Achten Sie auf Selbstkorrekturen und abgebrochene Sätze („um … zu sein—", ein unvollendeter letzter Satz vor Applaus), indem Sie die .txt-Datei lesen; der Detektor schlägt nur Kandidaten vor.

• Farbstatistiken auf gesamter Framebreite werden von Projektionsflächen dominiert; gleichen Sie die Belichtung auf dem Sprecherbereich (Kacheln um den Track) an und beurteilen Sie den Weißabgleich anhand von Standbildern.

3. Planen und genehmigen

Schreiben Sie docs/PLAN.md: Auswahltabelle (Quelle, Ein/Aus an Satzgrenzen, Inhalt, Verbindung: Überblendung/Sprungschnitt), Titel, Voice-Over-Text, Kamerasprache, Bild- und Audiobehandlung. Fassen Sie im Chat zusammen; zeichnen Sie die Genehmigung mit NOTE='...' plan:approve auf (auch erforderlich vor kostenpflichtigen Aufrufen, z. B. ElevenLabs Voice-Over via voice:tts; siehe credentials.md – in Plugin-Sitzungen laufen kostenpflichtige Aufgaben über den mk-video-editing MCP-Server).

4. Erstellen Sie die EDL mit einem Generator-Skript

Schreiben Sie edit/build_edl.rb (siehe footage-editing.md für das vollständige EDL-Schema und ein ausgearbeitetes Beispiel). Definieren Sie ein Einstellungsvokabular (TOTAL zoom≈1.2–1.4, MITTELWEIT fit≈0.4, MITTEL fit≈0.56, PUNCH fit≈0.72 begrenzt durch max_zoom 3.6) und schreiben Sie Kamerabeats in Quellsekunden aus dem Transkript: langsame Heranzooms über 6–12 s, geschnittene Punch-Ins auf Betonungszeilen, Schnitt auf Totale bei Themen-/Folienwechseln, Neueinrahmung bei jedem Sprungschnitt. Pro Clip: safe-Bereich (störenden Vordergrund fernhalten), deflicker, grade-Angleichung; ein gemeinsamer look. Überlagerungen sind ProRes-4444-Alpha-Titel (siehe Titel unten).

Entfernen Sie Wörter und Pausen innerhalb einer Auswahl mit lib/media/cuts.rb: Media::Cuts.pause_cuts (automatische Kürzung unnatürlicher Pausen), Media::Cuts.segments (teilen Sie die Auswahl in Sprungschnitt-Segmente, rastern Sie die Grenzen auf den leisesten Punkt zwischen Wörtern, öffnen Sie jedes Segment mit einer kontrastierenden Einrahmung, halten Sie jeden Zoom ≥ 4,5 s), Media::Cuts.text (protokollieren Sie, was jeder Schnitt entfernt, in edit/cuts.txt). Beginnen und enden Sie jede Auswahl in Stille und fern von Kamerahandling (überprüfen Sie die Verschiebungsgeschwindigkeit nahe der Ränder). Ausgearbeitetes Beispiel in footage-editing.md.

5. Audio

speech:clean[audio/raw/A.wav,audio/clean/A.wav] (PRESET=room: Brummschnitt, FFT-Entrauschung, Mudschnitt, Präsenz, De-Esser, sanfter Expander, Leveler; ISOLATE=1 für lokale Demucs-Gesangsspur). Fügen Sie Voice-Over mit voice:tts hinzu, wenn gewünscht (MODEL=v4 für Eleven v4). Fügen Sie ein Musikbett nur hinzu, wenn das Briefing danach verlangt: einen bereitgestellten Track oder music:score, platziert als EDL music (finishing.md). Führen Sie dann speech:mix[edit/edl.json,audio/mix.wav] aus. Es mischt das Clip-Audio mit Überblendungen bei Dissolves (audio_xfade: 0.15 bewahrt das letzte Wort vor einer 0,6 s Überblendung), audio_duck unter Voice-Over, sounds und music mit Seitenketten-Ducking und wendet dann einen zweistufigen Loudnorm auf -16 LUFS / -1,5 dBTP an.

6. Überprüfen, rendern, ausliefern

• DEBUG=1 edit:stills[edit/edl.json,edit/review/vN,t1,t2,...] — jedes Standbild plus der vollständige Quellframe mit Ausschnitt (rot), Motiv (grün) und Sicherheitsbereich (gelb). Überprüfen Sie Einrahmung, Kopfraum, Vordergrundeindringlinge, Belichtung/WB-Kontinuität über Schnitte hinweg.
• edit:sheet Kontaktbögen; edit:preview[edl,out.mp4,from,to] Halbauflösungs-Entwürfe geänderter Bereiche.
• edit:render[edit/edl.json,output/final.mp4] (JOBS=1). Überschreiben Sie niemals eine ausgelieferte Master-Datei.
• Qualitätssicherung vor dem Rendern des Videos: speech:mix, dann edit:transcribe der Mischung und lesen Sie die Wörter um jedes Clips at herum (günstig; fängt abgeschnittene Wörter und Ein-Wort-Blitze). Überprüfen Sie nach dem Rendern erneut das Transkript des Finales; protokollieren Sie Versionen und Probleme in docs/REVIEW.md.

Liefern Sie das Video, die Plan-/Briefing-/Überprüfungsdokumente und eine kurze Zusammenfassung der Entscheidungen und bekannten Probleme. Führen Sie RSpec-Profile aus testing.md aus, nachdem Sie das Toolkit geändert haben, und swift test in tools/graphics nach Renderer-Änderungen.

Titel

Beginnen Sie mit den Vorlagen in scripts/tools/graphics/examples/: opening_title.json, lower_third.json und end_card.json (1920×1080, AvenirNext, eine Akzentfarbe). Kopieren Sie sie nach edit/titles/, ändern Sie Text und Timing, oder generieren Sie sie aus edit/make_titles.rb, wenn es mehrere gibt. Überprüfen Sie im Web Namen, Rollen und Ereignisfakten.

1. Rendern Sie Standbilder mit ONLY= über einem Frame der Einstellung (PLATE=) und überprüfen Sie Lesbarkeit, den Sicherheitsrand und Akzente.
2. Rendern Sie CODEC=prores4444 SUPERSAMPLE=2 graphics:render[edit/titles/x.json,edit/titles/x.mov,frames,1920,1080,fps] mit der Bildrate des Schnitts.
3. Platzieren Sie es als EDL-overlays-Eintrag, abdunkelnd oder unscharf machend der Platte unter einer Eröffnungskarte mit Kamera-dim/blur.

Das Szenenformat (Knoten, Tracks, Easing, Glühen, Schriften) befindet sich im Graphics-README. Führen Sie nach Renderer-Änderungen swift test in scripts/tools/graphics aus und vergleichen Sie alte und neue Titel-Renderings Byte für Byte.

Nachbearbeitung (optional)

Ein Musikbett, Soundeffekte und Bildeffekte sind optionale Durchgänge, beschrieben in finishing.md:

• das Bett geht in speech:mix vor dem Rendern;
• SFX (sfx.yml) und VFX (cues.yml) laufen auf dem gerenderten Master und schreiben immer eine neue Datei.

Verwenden Sie sie, wenn das Briefing ein Promo- oder Zusammenfassungsgefühl verlangt. Saubere Gesprächsschnitte benötigen sie selten.

Parallele Arbeit

Teilen Sie für lange Schnitte unabhängige Jobs (Titel, Voice-Over-Zeilen, Überprüfungsstandbilder pro Abschnitt, QA-Transkripte) in config/production.json mit ihren depends auf. Übergeben Sie sie Sub-Agents über work:next, lassen Sie sie mit work:log berichten und akzeptieren Sie jeden nach der Überprüfung (work:accept). Sub-Agents können Szenen, Skripte und Dokumente parallel schreiben. Schwere Medienjobs (medit, mgraphics/mvfx-Codierungen, Demucs) laufen weiterhin nacheinander (Speichersicherheit siehe oben).