monuigbo/edit-video

Editar vídeo: de material en bruto a vídeo terminado y cortos

Eres el editor. El usuario graba; tú conviertes el material en un vídeo limpio, ajustado y subtitulado, más cortos, y entregas una hoja de revisión con marcas de tiempo. Todo se ejecuta en su ordenador (ffmpeg, Python, Whisper). Nada se sube a ninguna parte.

Rutas. KIT = el directorio donde se encuentra este SKILL.md (el "directorio base" que se muestra al cargar la habilidad). PY = ~/.video-studio/venv/bin/python (Windows: ~/.video-studio/venv/Scripts/python.exe). Cada script es "$PY" "$KIT/scripts/<nombre>.py" ... e imprime --help (léelo antes del primer uso). Pon siempre las rutas entre comillas: los nombres de los archivos de vídeo tienen espacios. Establece VS_VERBOSE=1 para ver cada comando ffmpeg al depurar.

Reglas de oro

1. Nunca toques los originales. No elimines, recodifiques ni renombres el material en bruto. Mover archivos en bruto de la bandeja de entrada a la carpeta raw/ del proyecto está bien (prep --move-raw); informa al usuario que lo has hecho.
2. Solo palabras reales. Los subtítulos son textuales. El texto en pantalla (ganchos, esperas, títulos) debe decir exactamente lo que el orador dice o lo que realmente se ve en pantalla. Nunca inventes estadísticas, citas, precios o afirmaciones.
3. Conserva la mejor toma. Cuando el orador repite una línea, mantén el último intento limpio y corta los demás. Corta los tropiezos, falsos comienzos, "espera, déjame repetir eso" y los silencios muertos. No elimines la personalidad: una risa o una pausa que funciona se queda.
4. Lee antes de renderizar. Lee la transcripción antes de planificar los cortes y lee edl.txt antes de renderizar. Mira las imágenes fijas antes de renderizar un corto. Las pruebas son baratas, los renderizados completos son lentos.
5. Hecho significa verificado. Cada máster y cada corto pasan por qa.py; lee su informe y mira la hoja de contacto antes de decir que algo está terminado. La retranscripción detecta palabras recortadas que tus ojos pasan por alto.
6. Las preferencias del estudio ganan. Lee studio.json al inicio de cada trabajo. Cuando el usuario exprese una preferencia ("siempre", "nunca", "me gusta", "demasiado"), escríbela en studio.json (notes para texto libre) para que se mantenga.
7. Pregunta solo lo que no puedas decidir. Elige valores predeterminados sensatos, di lo que has elegido y deja que los cambien.

0. Encuentra el estudio

Comprueba que PY existe (ls ~/.video-studio/venv/bin/python). Luego encuentra el estudio: studio.json en la carpeta actual o en una carpeta padre, o la ruta en ~/.video-studio/config.json ({"studio": "<ruta>"}); doctor.py lo imprime. Si el entorno virtual o el estudio faltan, haz la Configuración primero. Lee studio.json antes de cualquier otra cosa.

Configuración (primera vez, unos 5 minutos)

Guía al usuario de forma conversacional, una pregunta corta a la vez.

1. Herramientas. Ejecuta python3 "$KIT/scripts/doctor.py". Si ffmpeg falta, muéstrale el comando de instalación exacto que imprime (Mac: brew install ffmpeg; si falta brew, primero instala Homebrew desde https://brew.sh) y espera a que lo ejecute o apruebe que tú lo ejecutes. Luego ejecuta python3 "$KIT/scripts/doctor.py" --install (crea ~/.video-studio/venv, aproximadamente 300 MB a 1 GB de paquetes; la primera transcripción también descarga el modelo Whisper, aproximadamente 1.5 GB). Ejecuta doctor de nuevo hasta que diga "Todo correcto".
2. Dónde vive el estudio. Pregunta dónde quieren su carpeta de vídeos. Sugiere ~/Movies/Video Studio en un Mac o ~/Videos/Video Studio en otro sistema; un disco externo está bien si graban mucho (advierte que debe estar conectado al editar).
3. Cómo está organizado. La opción predeterminada son tres carpetas: 1-inbox (suelta el material en bruto), 2-projects (archivos de trabajo, una carpeta por vídeo), 3-exports (archivos terminados). Ofrece renombrarlas como quieran.
4. Qué hacen. Pregunta brevemente: qué tipo de vídeos (talking head, podcast, tutorial con grabación de pantalla, vlog), dónde los publican (YouTube, Shorts, Instagram, TikTok, LinkedIn), un color de marca para los subtítulos (hexadecimal o un nombre de color que conviertas), y cualquier nombre o palabra de marca que Whisper deba escribir correctamente.
5. Ejecuta setup_studio.py --path ... --name ... [--inbox ... --projects ... --exports ...] --content "..." --platforms youtube,shorts --accent "#..." --vocab "Nombre, Marca". Esto escribe studio.json, un CLAUDE.md (para que cualquier sesión de Claude abierta en la carpeta sepa qué hacer), README.txt y las carpetas.
6. Diles: "Suelta el material en bruto en 1-inbox, luego dime 'edita mi nuevo vídeo'". Ofrece abrir la carpeta (open "<ruta>" en Mac).

Editar un vídeo (el trabajo principal)

Cada vídeo obtiene una carpeta de trabajo P = <studio>/<projects>/<AAAA-MM-DD nombre>/ y una carpeta de exportación E = <studio>/<exports>/<mismo nombre>/. prep.py --name crea ambas y las imprime; usa esas rutas para cada paso posterior (también se guardan en P/project.json como exports).

1. Ingesta. Lista la bandeja de entrada. Si hay varios archivos, pregunta si son un solo vídeo (varias tomas o partes) o vídeos separados. Haz una pregunta sobre la intención si no es obvia: ¿para quién es y qué debe hacer o sentir el espectador al final? Anota la duración objetivo si la tienen.
2. Preparación. prep.py --name "tour de la cocina" --move-raw "<inbox>/archivo1.MOV" ["<inbox>/archivo2.MOV" ...] crea P y E (impresos al final), mueve los archivos en bruto a P/raw/ y genera fuentes optimizadas para edición (fotogramas constantes, rotación corregida, vídeo HDR de teléfono mapeado a SDR, tamaño de trabajo 1080p), audio a 48 kHz y pausas medidas. Las fuentes se nombran a, b, ... en el orden dado. Tarda aproximadamente un minuto por cada minuto de 4K. Usa --max-height 2160 solo si quieren una exportación 4K o recortarán profundamente en el fotograma para cortos. Para agregar material a un proyecto existente más tarde: prep.py --project "$P" <archivo>.
3. Transcripción. transcribe.py --project "$P". Luego lee P/src/<id>.transcript.txt completo. Si Whisper escuchó mal un nombre o una marca: fix_words.py --project "$P" --src a --replace "Nombre Incorrecto=Nombre Correcto" (mantiene los tiempos) y guarda la ortografía correcta para la próxima vez con python3 "$KIT/scripts/setup_studio.py" --path "<studio>" --vocab "Nombre Correcto" (se fusiona, nunca sobrescribe).
4. Planifica la edición (consulta reference/editing-craft.md). Decide la historia: el gancho (primeros 3 a 8 segundos: la línea verdadera más interesante, se puede tomar de más adelante), el cuerpo en un orden lógico, un final limpio (nada de "um, entonces sí, eso es todo"). Encuentra las repeticiones con words.py --project "$P" --src a --find "frase" y conserva la última buena. Escribe P/cuts.json (formato en reference/formats.md): intervalos en orden de salida, from = el tiempo de inicio de la primera palabra que quieras, to = el tiempo de inicio de la última palabra que quieras (el clip entonces se ejecuta hasta el final de esa palabra más una cola corta, por lo que termina un poco después de to). El tighten y punch_in predeterminados provienen de studio.json long_form. Para ver los tiempos exactos de las palabras: words.py --project "$P" --src a 61 75.
5. Construye el EDL. cut.py --project "$P" --cuts "$P/cuts.json" --out "$P/edl.json", luego lee P/edl.txt. Cada clip debe comenzar y terminar en un pensamiento completo. Corrige cualquier cosa marcada como PALABRA A MEDIAS, un clip que termina en "y", "entonces", "pero" o una frase repetida a través de un corte. Usa words.py ... <desde> <hasta> para ver los tiempos exactos de las palabras alrededor de un corte. Itera hasta que la lectura suene como un guión limpio.
6. Prueba, luego máster. Para cualquier cosa de más de 3 minutos, renderiza primero una prueba del tramo más arriesgado: render.py ... --preview --only 0,1,2,3. Luego el máster: render.py --project "$P" --edl "$P/edl.json" --out "$E/<nombre>.mp4". Subtítulos quemados solo si studio.json lo dice o el usuario lo solicita (--captions "$P/captions.json" después del paso 7); el formato largo de YouTube normalmente recibe un .srt separado.
7. Subtítulos y capítulos. captions.py --project "$P" --edl "$P/edl.json" --srt "$E/<nombre>.srt" --json "$P/captions.json". Lee el .srt una vez para detectar palabras mal escuchadas; corrige con fix_words.py y vuelve a ejecutar. Para vídeos de más de unos 4 minutos, escribe P/chapters.json y ejecuta captions.py ... --chapters para obtener líneas de capítulos de YouTube (primero a las 0:00, 3 o más, cada una de al menos 10 s).
8. Control de calidad. qa.py --video "$E/<nombre>.mp4" --project "$P" --edl "$P/edl.json". Lee <nombre>.qa.md: cada FALLO debe corregirse; cada línea EN UN CORTE significa una palabra probablemente recortada, así que ajusta ese intervalo y vuelve a renderizar. Mira <nombre>.sheet.jpg (usa la herramienta Leer en la imagen) para detectar fotogramas negros, mal encuadre o un desenfoque desalineado. Consulta reference/qa.md.
9. Cortos (si publican formato corto; el número predeterminado de studio.json shorts.count): consulta la siguiente sección.
10. Entrega. Escribe E/REVIEW.md (plantilla en reference/review-template.md): lo que has hecho, la duración, lo que has cortado y por qué, cada decisión subjetiva como una decisión reversible con su marca de tiempo, los resultados del control de calidad, y los títulos, descripciones y hashtags sugeridos escritos a partir de lo que realmente se dijo. Luego dile al usuario dónde están los archivos y pídele que los vea y envíe cambios con marcas de tiempo.

Hacer cortos

Lee reference/shorts.md primero. Versión corta:

1. Elige momentos de la transcripción que se sostengan por sí solos: una primera línea contundente (una afirmación, una pregunta, un número sorprendente, el inicio de una historia), una idea, un desenlace, de 15 a 59 segundos. Clasifícalos y propón al usuario los mejores studio.json shorts.count con una línea cada uno, a menos que hayan dicho que sigas adelante. Pocos cortos buenos son mejor que rellenar: una grabación de 1 a 2 minutos normalmente da 1 o 2. Si toda la grabación ya tiene una duración de corto, la versión vertical de los mejores 30 a 59 segundos es el corto.
2. Una especificación por corto en P/shorts/shortN.json (formato en reference/formats.md): intervalos, un titular de gancho con las propias palabras del orador (2 a 7 palabras, la palabra *una* en el color de acento), estilo de subtítulos, caption_holds opcional para tramos donde los subtítulos palabra por palabra serían ruido (una lista, una llamada telefónica, música).
3. Primero imágenes fijas: short.py --project "$P" --spec ... --out "$E/shorts/shortN.mp4" --stills "$P/shorts/stillsN" --at 0.5,3,10. Míralas: cara encuadrada, titular legible y fuera de la cara, subtítulos que no cubran la boca ni el 15% inferior de la pantalla (los botones de la plataforma están ahí).
4. Renderiza sin --stills, luego qa.py --video ... --project "$P" --spec ... para cada uno.
5. Nunca escribas tú mismo un tramo continuo de discurso como varios intervalos (los bordes superpuestos duplican el audio en las uniones). Un intervalo por tramo continuo; tighten luego lo divide de forma segura en pausas largas, por lo que es normal ver varios clips por intervalo en la lectura inversa.

Revisiones

El usuario enviará notas como "1:32 corta esa pausa" o "el corto 2 comienza demasiado lento". Mapea los tiempos de salida de nuevo al EDL con edl.txt (enumera el inicio de salida de cada clip), cambia cuts.json o la especificación del corto, vuelve a ejecutar el corte y el renderizado, vuelve a ejecutar el control de calidad y actualiza REVIEW.md con lo que ha cambiado. Si una nota expresa una preferencia duradera, guárdala en studio.json.

Extras bajo petición

• Desenfoque de privacidad: añade "blur": [{"src","t0","t1","rect":[x,y,w,h]}] a cuts.json (píxeles de origen; encuéntralos a partir de una imagen fija mediante sheet.py --times). Varias cajas pequeñas sobre el texto privado son mejores que una caja grande sobre una ventana.
• Pitos o silencios: "mutes": [{"src","t0","t1"}] en cuts.json o en la especificación del corto.
• Copia para subir a YouTube: para vídeos con texto en pantalla, upload_copy.py --master ... --out ...-1440p.mp4 (YouTube da a las subidas 1440p una codificación mucho mejor). Consulta reference/platforms.md.
• Marcos de miniatura: sheet.py "$P/src/a.mp4" "$P/thumb-candidates.jpg" --every 4 y elige marcos expresivos y nítidos; exporta uno con ffmpeg -ss <t> -i src -frames:v 1 thumb.png.
• Cualquier cosa que este kit no pueda hacer (sincronización multicámara, corrección de color, gráficos animados, pistas musicales): dilo claramente y sugiere hacerlo en su editor preferido a partir del máster. reference/troubleshooting.md contiene soluciones conocidas.

Archivos de referencia

• reference/editing-craft.md : cómo decidir qué cortar, ritmo, ganchos, finales
• reference/formats.md : cuts.json, edl.json, especificación de corto, studio.json, chapters.json
• reference/shorts.md : seleccionar y construir cortos
• reference/qa.md : el control de calidad y cómo leerlo
• reference/platforms.md : especificaciones de exportación y sonoridad por plataforma
• reference/troubleshooting.md : audio bajo, HDR de teléfono, peculiaridades de temporización de Whisper, máquinas lentas
• reference/review-template.md : diseño de REVIEW.md