Cena Raiz
Principio
- 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).
- 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. - El audio es lo principal, lo visual va después. Los candidatos a corte provienen de los límites del habla y los silencios.
- Preguntar → confirmar → ejecutar → iterar → persistir. Nunca toques el corte hasta que el usuario confirme la estrategia en lenguaje natural.
- Generalizar. Observa el material, pregunta al usuario, luego edita — nunca asumas qué tipo de video es.
- 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.
- 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)
- La puerta de fase es real. Sin trabajo de Fase 2 antes de que el corte sea aprobado.
- 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). - Fundidos de audio de 30 ms en cada límite de segmento (codificado en render.py).
- Nunca cortes dentro de una palabra — ajusta a los límites de palabra de la transcripción.
- 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.
- Almacena en caché las transcripciones por fuente. Nunca vuelvas a transcribir a menos que la fuente haya cambiado.
- Corrección de color por segmento durante la extracción, nunca después de la concatenación.
- Confirmación de la estrategia antes de la ejecución.
- Todas las salidas de la sesión en
<videos_dir>/edit/— nunca dentro del repositorio cena-raiz. - FASE 2 es solo Remotion — sin texto quemado ni superposiciones con ffmpeg/PIL.
- 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.tsxetc.) — el único archivo de código editable essrc/CustomGraphics.tsx, solo para gráficos personalizados. - Verifica numéricamente primero. Ejecuta
verify_cut.pyen cada corte renderizado; abre imágenes solo para uniones marcadas. Agrupa cualquier revisión de múltiples fotogramas en un montajecontact_sheet.py/grade.py --candidates. - Nunca leas datos de máquina en el contexto:
transcripts/*.json(sin procesar),captions.json,track.json,segments.json, binarios de máscara/pista. Leetakes_packed.mdy 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 synces 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 contraspeech_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
/UNALIGNEDen_transcription_backendsignifica 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+ffprobeen PATH; dependencias de Python (uv sync); Node 18+ para Fase 2.yt-dlpviene con las dependencias de Python, por lo que las fuentes URL no necesitan instalación adicional.- El skill
remotion-best-practicespara 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.--sectiondescarga 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.--simulateimprime 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--languagecuando 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 ungain_db. Detecta lo que nada más detecta: un susurro aparte donde la transcripción es perfecta,speech_regionsdice "habla" yverify_cutno 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 elgradea aplicar. Soloconfidence: lowdebería enviarte de vuelta al usuario; el detalle de identificación está enreferences/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. Escribejcut_timelineen 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). Estableceedit-data.jsonfpspara que coincida con elcut.mp4resultante.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-LEVELpor 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 degain_db.grade.py <in> -o <out>— preajustes de corrección/filtros sin procesar.--candidates "a=<filtro>;b=<preajuste>;original=" --frame <t> -o cmp.pngrenderiza 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 enedit/verify/watch_<stem>/, una Lectura por hoja. Para inventario visual de material desconocido, y para inspeccionarcut.mp4más allá de los números de verify_cut.--timesfija fotogramas de referencia de transcripción: momentos deícticos detakes_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á enassets/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):
-
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/finalVideosolo cuando existen; la pestaña Fase-2 reproducefinalVideo— el render CON subtítulos/inserciones — mientras que Fase 1 reproduce el corte limpio;sourceDurationspermite a la IU limitar las extensiones de tomas;awaitingStyle/stylecontrolan la pestaña Estilo a continuación.) -
Selecciona el adaptador de tiempo de ejecución; nunca invoques las herramientas de otro host.
- Claude Code: asegúrate de que
.claude/launch.jsontenga la configuración (ajusta--rootpor sesión). El servidor toma el puerto solo por bandera, así que pasa el$PORTasignado por el arnés y estableceautoPort:{"name": "cena-raiz-preview", "runtimeExecutable": "sh", "runtimeArgs": ["-c", "exec python3 <skill>/helpers/preview_server.py --root '<edit>' --port \"$PORT\""], "autoPort": true, "port": 4820}. Ejecutapreview_startcon el nombrecena-raiz-preview, luego armaMonitor(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 4820como un proceso local en segundo plano cuando el entorno pueda mantenerlo vivo. Una vez que responda, usa el skillcontrol-in-app-browserpara abrirhttp://127.0.0.1:4820en el Navegador de la aplicación automáticamente y deja esa pestaña en la vista previa. No asumas que existenpreview_start,Monitoro.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...
- Claude Code: asegúrate de que
[truncado para traducción]