Communitygithub.com

daniela-socoloski/raiz-engine

Edición de video conversacional para video vertical de formato corto (Reels, TikTok, Shorts) y horizontal de formato largo.

¿Qué es raiz-engine?

Este skill permite realizar ediciones de video completas mediante conversación, centradas en el audio como elemento principal. Está diseñado para plataformas como Claude Code, Codex y Cursor, utilizando un pipeline local con ffmpeg y Remotion, o a través de los MCP de Adobe Premiere Pro. El proceso sigue un flujo de dos fases: en la Fase 1 se realiza el corte limpio y la corrección de color, y en la Fase 2 se añaden subtítulos, gráficos y otros elementos visuales usando Remotion, todo ello validado numéricamente antes de la inspección visual. El skill gestiona transcripciones locales con WhisperX, genera EDLs, y proporciona un panel de vista previa interactivo para que el usuario revise y apruebe cada etapa.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Cena Raiz

Principio

  1. Dos fases, una puerta entre ellas. FASE 1 es el corte limpio + la corrección de color; FASE 2 son subtítulos, gráficos e imágenes. (La Regla Estricta 1 impone la puerta).
  2. El LLM razona a partir de la transcripción sin procesar + elementos visuales bajo demanda. El único artefacto derivado que vale la pena es la transcripción empaquetada a nivel de frase (takes_packed.md). Todo lo demás se deriva en el momento de la decisión.
  3. El audio es lo principal, lo visual va después. Los candidatos a corte provienen de los límites del habla y los silencios.
  4. Preguntar → confirmar → ejecutar → iterar → persistir. Nunca toques el corte hasta que el usuario confirme la estrategia en lenguaje natural.
  5. Generalizar. Observa el material, pregunta al usuario, luego edita — nunca asumas qué tipo de video es.
  6. La libertad artística es la opción por defecto. Los valores específicos aquí son ejemplos prácticos, no mandatos. Solo las Reglas Estrictas son obligatorias.
  7. Gasta fichas donde habita el gusto. Los datos de máquina son para programas, no para leer; la verificación es numérica antes de ser visual. Tu atención es el recurso escaso — ponla en la edición, no en analizar JSON. (Las Reglas Estrictas 12 y 13 dicen qué prohíbe esto).

Reglas Estrictas (corrección de producción — no negociables)

  1. La puerta de fase es real. Sin trabajo de Fase 2 antes de que el corte sea aprobado.
  2. Extracción por segmento → concatenación sin pérdidas -c copy, nunca un filtro de un solo paso. (Bajo el J-cut por defecto, la imagen y el sonido de una toma se extraen como rangos separados y las pistas de audio se suman — esa es la única mezcla autorizada, y la ruta de video sigue siendo por segmento + concatenación sin pérdidas).
  3. Fundidos de audio de 30 ms en cada límite de segmento (codificado en render.py).
  4. Nunca cortes dentro de una palabra — ajusta a los límites de palabra de la transcripción.
  5. Rellena cada borde de corte (ventana de 30-200 ms; el final ligeramente más largo que el inicio). Corta en silencio siempre que sea posible.
  6. Almacena en caché las transcripciones por fuente. Nunca vuelvas a transcribir a menos que la fuente haya cambiado.
  7. Corrección de color por segmento durante la extracción, nunca después de la concatenación.
  8. Confirmación de la estrategia antes de la ejecución.
  9. Todas las salidas de la sesión en <videos_dir>/edit/ — nunca dentro del repositorio cena-raiz.
  10. FASE 2 es solo Remotion — sin texto quemado ni superposiciones con ffmpeg/PIL.
  11. FASE 2 está basada en datos. Anda copiando la plantilla de pista; describe el video en public/edit-data.json. Nunca leas ni edites el TSX de la plantilla (src/Main.tsx etc.) — el único archivo de código editable es src/CustomGraphics.tsx, solo para gráficos personalizados.
  12. Verifica numéricamente primero. Ejecuta verify_cut.py en cada corte renderizado; abre imágenes solo para uniones marcadas. Agrupa cualquier revisión de múltiples fotogramas en un montaje contact_sheet.py / grade.py --candidates.
  13. Nunca leas datos de máquina en el contexto: transcripts/*.json (sin procesar), captions.json, track.json, segments.json, binarios de máscara/pista. Lee takes_packed.md y la salida estándar de los ayudantes en su lugar.

Medio de ejecución — pipeline local vs MCP de Adobe

El motor por defecto es el pipeline ffmpeg/Remotion descrito a continuación. Para conexión, diagnóstico, descubrimiento de capacidades o trabajo controlado a través de los MCP de Adobe locales, lee primero references/adobe-mcp.md. Es neutral en cuanto al cliente: el mismo procedimiento se aplica desde Codex y Claude Code.

Si el usuario pide la edición dentro de Adobe Premiere Pro a través del MCP de premiere-pro ("edite a sequência no Premiere", "corte via MCP"), también lee references/premiere-mcp.md. El MÉTODO no cambia — audio como principal, cortar en silencio, puerta de fase, graduar con gusto — pero cambian las herramientas. La transcripción y edl.json son idénticos y están en caché, por lo que se reutiliza un EDL aprobado y se omite cut.mp4/vista previa. Las escrituras de After Effects siguen sujetas a la fase de Adobe controlada del repositorio; la disponibilidad del MCP por sí sola no autoriza la mutación.

Estructura de directorios

<videos_dir>/
├── <archivos fuente, sin modificar>
└── edit/
    ├── project.md               ← memoria; se añade en cada sesión
    ├── takes_packed.md          ← transcripciones a nivel de frase, la vista de lectura principal
    ├── edl.json                 ← decisiones de corte (Fase 1)
    ├── transcripts/<nombre>.json  ← transcripciones a nivel de palabra en caché (WhisperX, local)
    ├── clips_graded/            ← extracciones por segmento con corrección de color + fundidos
    ├── cut.mp4                  ← salida FASE 1: corte graduado limpio (artefacto de aprobación)
    ├── verify/                  ← montajes / vistas de límites marcados
    ├── captions.srt + chapters.txt   ← entregables de formato largo
    ├── final.mp4                ← render entregado (Fase 2 + 3, con loudnorm)
    └── remotion/                ← proyecto Remotion (Fase 2 + 3)
        ├── public/              ← cut.mp4, edit-data.json (LA edición), captions.json,
        │                          track.json, segments.json, pexels/ web/ brand/, sfx/, trilha.mp3
        └── src/                 ← código de plantilla inmutable + CustomGraphics.tsx

Configuración

La instalación inicial está en install.md. En un inicio en frío solo verifica:

  • La transcripción NO necesita clave API. WhisperX viene como dependencia: uv sync es toda la instalación. Transcribe con Whisper y luego ejecuta ALINEACIÓN FORZADA (wav2vec2) contra la forma de onda, por lo que los tiempos de palabra se miden, no se infieren — el 93% de las palabras aterrizan dentro de una región de habla real y el final del habla se sitúa dentro de 10 ms (medido contra speech_regions.py). Los modelos se descargan una vez en la primera ejecución y se almacenan en caché. La velocidad es aproximadamente en tiempo real y mejora con la longitud (cargar el modelo es un costo fijo de ~18 s: un clip de 16 s tomó 23 s, una fuente de 166 s tomó 109 s).
  • Un sufijo /UNALIGNED en _transcription_backend significa que no existía un modelo wav2vec2 para el idioma detectado, por lo que los tiempos de palabra son los del decodificador — aproximados y no seguros para subtítulos karaoke de Fase 2. Dilo si ocurre.
  • ffmpeg + ffprobe en PATH; dependencias de Python (uv sync); Node 18+ para Fase 2. yt-dlp viene con las dependencias de Python, por lo que las fuentes URL no necesitan instalación adicional.
  • El skill remotion-best-practices para el conocimiento del dominio de Fase 2 (instálalo desde https://github.com/remotion-dev/skills si falta).
  • Las Fases 2/3 pueden usar claves API opcionales (imágenes ilustrativas, banda sonora AI). Se listan en la referencia de pista, se piden perezosamente cuando la característica se usa por primera vez y nunca en el momento de la instalación. Nada en la Fase 1 necesita una clave.

Los ayudantes viven en helpers/, resueltos relativamente a este SKILL.md (normalmente ~/.claude/skills/cena-raiz/ o ~/.codex/skills/cena-raiz/, o un enlace simbólico/punto de unión que apunte allí). Ejecútalos como uv run python helpers/<nombre>.py — un python simple se pierde el .venv que uv sync construye.

Ayudantes

Fase 1:

  • ingest_url.py <url> --dest <videos_dir> [--section 12:00-25:30] [--max-height 1080] — editar desde un enlace: yt-dlp → MP4 (≤1080p) directamente en el directorio de videos; desde allí es una fuente como cualquier otra. --section descarga SOLO un rango de tiempo de una fuente de formato largo (preciso a fotogramas clave) — la forma económica de recortar los minutos 12–25 de un video de 1h. --simulate imprime título/duración/resolución sin descargar (confirma antes de grandes descargas; ejecútalas en segundo plano).
  • transcribe.py <video> --edit-dir <edit> [--language pt] [--model large-v3-turbo] — a nivel de palabra, en caché, local (WhisperX + alineación forzada). Sin límite, sin fragmentación. Pasa --language cuando lo sepas — la detección automática cuesta una pasada y puede elegir mal en un clip corto.
  • transcribe_batch.py <videos_dir> — cada fuente en un directorio, una a la vez (la inferencia local ya usa todos los núcleos). En caché por archivo, y un fallo en una fuente no pierde las ya procesadas.
  • pack_transcripts.py --edit-dir <dir> — transcripciones → takes_packed.md (a nivel de frase, se rompe con silencios de ≥0.5 s). La vista de lectura: 1/10 de los tokens del JSON sin procesar.
  • speech_regions.py <video> — intervalos de habla acústica mediante silencio detectado. La fuente de verdad para los BORDES de corte (los tiempos de Whisper se desvían/estiran). Responde dónde está el habla — nunca qué tan fuerte está.
  • voice_levels.py <video> [--edit-dir <dir>] [--edl edl.json] [--drop-db 5] — la fuente de verdad para el NIVEL del habla. Marca cada frase, ejecuta y rango EDL ≥5 dB por debajo de la mediana del propio hablante y ajusta un gain_db. Detecta lo que nada más detecta: un susurro aparte donde la transcripción es perfecta, speech_regions dice "habla" y verify_cut no encuentra fallos — y el espectador aún no puede oírlo. Ejecútalo antes de escribir el EDL.
  • detect_color.py <video> [--json] — resuelve NORMAL vs LOG desde el archivo en lugar de preguntar: primero metadatos, estadísticas de imagen cuando los metadatos están en silencio (común: una transcodificación elimina las etiquetas). Devuelve perfil, confianza, evidencia y el grade a aplicar. Solo confidence: low debería enviarte de vuelta al usuario; el detalle de identificación está en 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] — extracción por segmento (corrección de color + fundidos, en paralelo) → ensamblaje por superposición J-cut (por defecto) o concatenación sin pérdidas → master de voz opcional → loudnorm. Escribe jcut_timeline en el EDL: las posiciones de salida reales, que es a lo que todo lo posterior debe indexar. Las fps de formato corto son automáticas: 30 fps para fuentes de 30 fps+, sino 24 (formato largo mantiene las fps de la fuente mediante --keep-resolution). Establece edit-data.json fps para que coincida con el cut.mp4 resultante.
  • verify_cut.py <edl.json> <cut.mp4> [--min-silence 1.2] — autoevaluación numérica: duración, sondas de pop/palabra recortada por unión, silencio muerto, fotogramas negros, recorte, y equilibrio de nivel por rango (el RMS de cada rango vs la mediana de los rangos; LOW-LEVEL por debajo de −4 dB). ~350 fichas de texto en lugar de N imágenes. La línea de equilibrio de rango es la prueba de convergencia para una corrección de gain_db.
  • grade.py <in> -o <out> — preajustes de corrección/filtros sin procesar. --candidates "a=<filtro>;b=<preajuste>;original=" --frame <t> -o cmp.png renderiza N looks en el MISMO fotograma en un único montaje etiquetado.
  • timeline_view.py <video> <inicio> <fin> — imagen PNG de tira de película+forma de onda para UN punto marcado, no una herramienta de escaneo.
  • contact_sheet.py <video> --times t1 t2 … -o sheet.png — N fotogramas en una cuadrícula etiquetada; la forma de examinar varios momentos que ya conoces.
  • watch_video.py <video> [--mode scene|keyframe|uniform] [--times t1 t2 …] [--start/--end] [--max-frames 24] — "¿qué hay EN este metraje?" cuando no sabes dónde mirar: detección de escenas + deduplicación perceptual → hojas de contacto etiquetadas en edit/verify/watch_<stem>/, una Lectura por hoja. Para inventario visual de material desconocido, y para inspeccionar cut.mp4 más allá de los números de verify_cut. --times fija fotogramas de referencia de transcripción: momentos deícticos de takes_packed.md ("mira esto", "como puedes ver") son cambios visuales BAJOS e invisibles para la detección de escenas — fíjalos para decidir la colocación de B-roll/llamada/zoom en la Fase 2.

Los ayudantes de Fase 2/3 (subtítulos, seguimiento facial, búsqueda de imágenes, música) están listados en la referencia de pista que cargas después de la puerta.

Interfaz:

  • preview_server.py --root <edit> [--port 4820] — sirve la interfaz de vista previa estándar (ver la sección de Interfaz de vista previa). El código de la aplicación está en assets/preview/ y es INMUTABLE.

Interfaz de vista previa (estándar — ejecútala al inicio de cada edición)

Cada sesión de edición obtiene la misma interfaz interactiva en el panel de vista previa del usuario: una línea de tiempo de editor de video (pista de video con tira de película + pista de audio con forma de onda), un cabezal de reproducción en vivo que se desplaza por el render en tiempo real, asas de recorte por toma y eliminación de tomas, y — desde la Fase 2 — pistas de subtítulos e inserciones. El diseño sigue la relación de aspecto de la fuente por sí mismo: las fuentes verticales colocan un reproductor alto a la derecha con el transporte + la línea de tiempo a la izquierda; las fuentes horizontales mantienen el reproductor apilado sobre la línea de tiempo. Vidrio oscuro, marca Cena Raiz. Nunca construyas una IU por sesión — alimenta la interfaz estándar con state.json. Editar assets/preview/ está permitido solo cuando el usuario solicita un cambio en la IU; es compartido, por lo que la mejora llega a todos los proyectos.

Inicio (hazlo cuando comience una sesión, incluso antes del primer render — la IU muestra un estado de espera):

  1. Escribe <edit>/state.json:

    {"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 solo cuando existen; la pestaña Fase-2 reproduce finalVideo — el render CON subtítulos/inserciones — mientras que Fase 1 reproduce el corte limpio; sourceDurations permite a la IU limitar las extensiones de tomas; awaitingStyle/style controlan la pestaña Estilo a continuación.)

  2. Selecciona el adaptador de tiempo de ejecución; nunca invoques las herramientas de otro host.

    • Claude Code: asegúrate de que .claude/launch.json tenga la configuración (ajusta --root por sesión). El servidor toma el puerto solo por bandera, así que pasa el $PORT asignado por el arnés y establece autoPort: {"name": "cena-raiz-preview", "runtimeExecutable": "sh", "runtimeArgs": ["-c", "exec python3 <skill>/helpers/preview_server.py --root '<edit>' --port \"$PORT\""], "autoPort": true, "port": 4820}. Ejecuta preview_start con el nombre cena-raiz-preview, luego arma Monitor(command="python3 <skill>/helpers/watch_edits.py '<edit>'", description="escolhas e marcações salvas no preview", persistent=true) en el mismo turno.
    • Codex desktop / CLI: inicia uv run python helpers/preview_server.py --root '<edit>' --port 4820 como un proceso local en segundo plano cuando el entorno pueda mantenerlo vivo. Una vez que responda, usa el skill control-in-app-browser para abrir http://127.0.0.1:4820 en el Navegador de la aplicación automáticamente y deja esa pestaña en la vista previa. No asumas que existen preview_start, Monitor o .claude/launch.json. Si la capacidad del Navegador o un proceso local persistente no están disponibles, proporciona al usuario el comando y la URL local en su lugar. Después de mostrar la vista previa, dile al usuario que guarde y re...

[truncado para traducción]

Skills relacionados