mk-video-editing

¿Qué hace mk-video-editing?

Convierte el metraje proporcionado en un montaje consistente y visible: las palabras correctas en el orden correcto, una cámara que encuadra bien al sujeto, una imagen uniforme, sonido limpio y nivelado, y títulos de buen gusto. La estructura proviene del metraje y de lo que se dice en él.

Qué puede hacer la skill

Necesidad	Herramientas	Coste	Referencia
Transcripciones de palabras, detección de muletillas/falsos inicios/pausas	edit:transcribe (mlx-whisper), speech:flow	gratuito, local	footage-editing.md
Estabilizar, seguir al orador, reencuadrar planos generales 4K (acercamientos, paneos), HDR→SDR, deflicker, igualar color, fundidos, cortes seguidos	edit:analyze, edit:track, EDL + medit (edit:render)	gratuito, local	footage-editing.md
Limpieza de diálogo, mezcla, enmascaramiento, sonoridad	speech:clean (ISOLATE=1 Demucs), speech:mix, speech:measure	gratuito, local	footage-editing.md
Narración	voice:tts (ElevenLabs vía Fal)	de pago, aprobado	credentials.md
Títulos, tercios inferiores, cartas finales (ProRes 4444 alpha)	Escenas mgraphics JSON, graphics:render, plantillas en scripts/tools/graphics/examples/	gratuito, local	README de gráficos
Música de fondo bajo el montaje	EDL music (enmascarado), music:score (ElevenLabs Music vía Fal), audio:analyze para el ritmo	de pago solo si se genera	finishing.md
Efectos de sonido en títulos/transiciones	SoundSynth (synth: whoosh, riser, impact, tick…), sfx:gen/sfx:mix o EDL sounds	gratuito (Stable Audio prompt: de pago)	finishing.md
Efectos de imagen (flash, fundido, subrayado, brillo, lente, estelas…)	Hojas de pauta mvfx, vfx:stills/vfx:render	gratuito, local	finishing.md
Codificaciones de entrega	media:twitter, media:youtube, media:faststart	gratuito, local	tasks.md
Subagentes paralelos en trabajos independientes	work:next/work:accept/work:log/work:watch	gratuito	tasks.md

Cada tarea con sus argumentos y opciones está en tasks.md. Los perfiles de prueba están en testing.md.

Contrato de ejecución

Diseñado para Claude Code en macOS 14+ en Apple Silicon (Swift 5.9+, Ruby 3.2+, Bundler, FFmpeg, ImageMagick, uv para Whisper local). Ejecute doctor primero cuando una tarea falle por una herramienta faltante; setup construye las herramientas Swift. Ruby es la única capa de entrada de ejecución: ejecute ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project 'tarea[args]'. Las tareas delegan en servicios Ruby (lib/media/edit.rb, speech.rb, guard.rb, …) que controlan las herramientas nativas Swift medit (scripts/tools/edit), mgraphics (scripts/tools/graphics) y mvfx (scripts/tools/vfx). Agregue un método Ruby y una tarea ligera cuando falte una capacidad. Un proyecto ejecuta su propia copia de lib/ y tools/: después de cambiar la skill, sincronice (rsync) los archivos cambiados al proyecto.

Seguridad de memoria (obligatorio)

La decodificación de hardware 4K/HDR mantiene los fotogramas en VTDecoderXPCService, fuera del espacio de memoria del trabajo. En una máquina de 16 GB sin intercambio, agotar la memoria congela el ordenador en lugar de ralentizarlo. Por lo tanto:

• Ejecute un trabajo pesado a la vez (medit analyze/render/stills, mgraphics encodes, Demucs, grandes codificaciones ffmpeg). Nunca lance varios en paralelo o en segundo plano junto con otros; encadénelos secuencialmente en un solo comando de fondo si es necesario. JOBS permanece en 1 a menos que la RAM ≥ 32 GB.
• Cada llamada de renderizado medit/mgraphics/mvfx pasa por Media::Guard (automático en los servicios Ruby): muestrea la huella del trabajo + decodificador y el porcentaje de memoria libre del núcleo cada 0.3 s y termina con SIGKILL antes de MEDIT_MAX_FOOTPRINT_MB (predeterminado 3500) o por debajo de MEDIT_MIN_FREE_PCT (predeterminado 30). Se niega a iniciar cuando la memoria libre ya es baja. Los tres renderizadores usan JOBS=1 por defecto; los fragmentos paralelos requieren una configuración explícita de JOBS.
• Valide cualquier nueva ruta de código de decodificación/renderizado en un rango corto con límites ajustados primero (TO=15 MEDIT_MAX_FOOTPRINT_MB=1500 MEDIT_GUARD_LOG=/ruta/log), verifique que el registro sea plano, luego ejecute la duración completa.
• En los bucles de medios Swift, envuelva cada copyNextSampleBuffer y renderizado de Core Image en autoreleasepool (el código asíncrono nunca drena el pool predeterminado: los fotogramas se filtran a ~1.5 GB/s).

Estado estable medido: análisis ≈ 1.0 GB (trabajo + decodificador) por fuente 4K HLG; un renderizado con fundido abre dos fuentes.

1. Ingesta

Pregunte solo por lo que falta: rutas del metraje, qué es el montaje (extracto de charla, resumen…), texto de títulos/créditos, duración objetivo, deseos de narración. Inicialice con el material (enlazado simbólicamente, nunca copiado ni modificado):

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

Examine cada fuente (ffprobe: tamaño, fps, duración, transferencia HDR). Extraiga audio (audio/raw/*.wav, 48 kHz) y transcriba localmente: edit:transcribe[analysis/transcripts,source/...] (mlx-whisper large-v3-turbo, tiempos de palabras; gratuito). Lea cada transcripción y escriba lo que dice cada clip, con marcas de tiempo, en docs/BRIEF.md. Busque en la web hechos del evento utilizados en los títulos y registre las fuentes.

2. Analizar (secuencialmente)

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]'   # uno a la vez
mv 'edit:track[analysis/A.json,analysis/A.track.json]'      # SEED=x,y cuando el orador no se encuentra al principio; SPACE=fotograma para estabilizar: 0
mv 'edit:stats[analysis/A.json,from,to]'

• REGION limita la estabilización (correlación de fase) al paisaje estático (escenario, pantallas), excluyendo al público.
• DETECT_REGION recorta el escenario para la detección de personas Vision a ~2× resolución — esencial para un orador lejano (la detección pasó del 2 % al 40–90 % de las muestras).
• Las trayectorias están bloqueadas al mundo (estabilización eliminada), seleccionadas por continuidad, y descartan cuadros de primer plano anchos (cabezas) mediante max_aspect.
• El metraje de teléfono (iPhone, etc.) ya está estabilizado en la cámara: renderícelo con stabilize: 0 y trayectorias SPACE=fotograma. Nuestro estabilizador puede confundir el contenido móvil de la diapositiva con movimiento de cámara y agregar saltos horizontales repentinos. Verifique: cuente los fotogramas con |Δshift| > 8 px en el análisis; la vibración residual en iPhone 4K medida es de ≈ 0.9 px RMS, que no merece corrección.

Flujo del habla (muletillas, falsos inicios, repeticiones, pausas antinaturales)

VERBATIM=1 mv 'edit:transcribe[analysis/transcripts_verbatim,source/A.MOV]'   # prepara Whisper para escribir um/uh
mv 'speech:flow[analysis/transcripts_verbatim/A.json,audio/clean/A.wav,analysis/flow/A.json]'   # lea analysis/flow/A.txt

El detector mide las pausas acústicamente (energía + sonoridad, no los tiempos de palabras de Whisper), las clasifica (oración/comma/frase) y marca muletillas, zumbidos no transcritos, repeticiones y posibles falsos inicios, cada uno con un cut propuesto. Decida cada uno según el significado, luego aplique los cortes con Media::Cuts en el generador (paso 4). Busque autocorrecciones y oraciones abandonadas ("para poder ser—", una última oración sin terminar antes del aplauso) leyendo el .txt; el detector solo propone candidatos.

• Las estadísticas de color de fotogramas completos están dominadas por las pantallas de proyección; iguale la exposición en el área del orador (teselas alrededor de la trayectoria) y juzgue el balance de blancos en fotogramas fijos.

3. Planificar y aprobar

Escriba docs/PLAN.md: tabla de selecciones (fuente, entrada/salida en límites de oración, contenido, unión: fundido/corte seguido), títulos, texto de narración, lenguaje de cámara, tratamiento de imagen y audio. Resuma en el chat; registre la aprobación con NOTE='...' plan:approve (también requerido antes de llamadas de pago, p. ej. narración ElevenLabs vía voice:tts; consulte credentials.md — en sesiones de plugin, las tareas de pago se ejecutan a través del servidor MCP mk-video-editing).

4. Construir la EDL con un script generador

Escriba edit/build_edl.rb (consulte footage-editing.md para el esquema completo de EDL y un ejemplo práctico). Defina un vocabulario de tomas (WIDE zoom≈1.2–1.4, MWIDE ajuste≈0.4, MED ajuste≈0.56, PUNCH ajuste≈0.72 limitado por max_zoom 3.6) y escriba tiempos de cámara en segundos de fuente tomados de la transcripción: acercamientos lentos durante 6–12 s, punch-ins de corte en líneas de énfasis, corte a plano general en cambios de tema/diapositiva, reencuadre en cada corte seguido. Por clip: área safe (mantenga fuera el primer plano que distraiga), deflicker, grade de coincidencia; un look compartido. Las superposiciones son títulos ProRes 4444 alfa (consulte Títulos más abajo).

Elimine palabras y pausas dentro de una selección con lib/media/cuts.rb: Media::Cuts.pause_cuts (acortar automáticamente pausas antinaturales), Media::Cuts.segments (dividir la selección en segmentos de corte seguido, ajustar los límites al punto más silencioso entre palabras, abrir cada segmento en un encuadre contrastante, mantener cada zoom ≥ 4.5 s), Media::Cuts.text (registrar lo que cada corte elimina en edit/cuts.txt). Inicie y finalice cada selección en silencio y lejos del manejo de la cámara (verifique la velocidad de desplazamiento cerca de los bordes). Ejemplo práctico en footage-editing.md.

5. Audio

speech:clean[audio/raw/A.wav,audio/clean/A.wav] (PRESET=room: corte de retumbo, denoising FFT, corte de barro, presencia, de-esser, expansor suave, nivelador; ISOLATE=1 para voces Demucs locales). Agregue narración con voice:tts cuando se solicite (MODEL=v4 para Eleven v4). Agregue una música de fondo solo cuando el resumen lo pida: una pista suministrada o music:score, colocada como EDL music (finishing.md). Luego ejecute speech:mix[edit/edl.json,audio/mix.wav]. Mezcla el audio del clip con fundidos cruzados en las transiciones (audio_xfade: 0.15 mantiene la última palabra antes de un fundido de 0.6 s), audio_duck bajo la narración, sounds y music con enmascaramiento por cadena lateral, luego aplica loudnorm de dos pasos a −16 LUFS / −1.5 dBTP.

6. Revisar, renderizar, entregar

• DEBUG=1 edit:stills[edit/edl.json,edit/review/vN,t1,t2,...] — cada fotograma fijo más el fotograma fuente completo con recorte (rojo), sujeto (verde) y área segura (amarillo). Verifique encuadre, espacio sobre la cabeza, intrusiones de primer plano, continuidad de exposición/balance de blancos entre cortes.
• edit:sheet hojas de contacto; edit:preview[edl,out.mp4,from,to] borradores a media resolución de rangos modificados.
• edit:render[edit/edl.json,output/final.mp4] (JOBS=1). Nunca sobrescriba un máster entregado.
• QA antes de renderizar video: speech:mix, luego edit:transcribe la mezcla y lea las palabras alrededor del at de cada clip (barato; detecta palabras recortadas y destellos de palabras solitarias). Después del renderizado, vuelva a transcribir el final; registre versiones y problemas en docs/REVIEW.md.

Entregue el video, los documentos de plan/resumen/revisión y un breve resumen de las decisiones y problemas conocidos. Ejecute los perfiles RSpec de testing.md después de cambiar el kit de herramientas y swift test en tools/graphics después de cambios en el renderizador.

Títulos

Comience desde las plantillas en scripts/tools/graphics/examples/: opening_title.json, lower_third.json y end_card.json (1920×1080, AvenirNext, un color de acento). Cópielas a edit/titles/, cambie el texto y el tiempo, o genérelos desde edit/make_titles.rb cuando haya varios. Verifique en la web nombres, roles y hechos del evento.

1. Renderice fotogramas fijos con ONLY= sobre un fotograma de la toma (PLATE=) y verifique legibilidad, margen seguro y acentos.
2. Renderice CODEC=prores4444 SUPERSAMPLE=2 graphics:render[edit/titles/x.json,edit/titles/x.mov,frames,1920,1080,fps] a la velocidad de fotogramas del montaje.
3. Colóquelo como una entrada overlays de la EDL, oscureciendo o desenfocando la placa bajo una tarjeta de apertura con dim/blur de cámara.

El formato de escena (nodos, pistas, easing, brillo, fuentes) está en el README de gráficos. Después de cambios en el renderizador, ejecute swift test en scripts/tools/graphics y compare renders de títulos antiguos y nuevos byte a byte.

Finalización (opcional)

Una música de fondo, efectos de sonido y efectos de imagen son pasos opcionales, descritos en finishing.md:

• la música va en speech:mix antes del renderizado;
• los SFX (sfx.yml) y VFX (cues.yml) se ejecutan sobre el máster renderizado y siempre escriben un archivo nuevo.

Úselos cuando el resumen solicite un estilo promocional o de resumen. Los montajes de charlas limpias rara vez los necesitan.

Trabajo en paralelo

Para montajes largos, divida los trabajos independientes (títulos, líneas de narración, fotogramas fijos de revisión por sección, transcripciones QA) en config/production.json con sus depends. Entréguelos a subagentes a través de work:next, haga que informen con work:log y acepte cada uno después de la revisión (work:accept). Los subagentes pueden escribir escenas, scripts y documentos en paralelo. Los trabajos pesados de medios (medit, mgraphics/mvfx encodes, Demucs) aún se ejecutan uno a la vez (seguridad de memoria, véase arriba).