Escaleta

Del guion a la lista de planos, midiendo contra la grabación real.

Una escaleta es el documento de producción que parte un programa en bloques, cada uno con su contenido y su duración. Esto es eso, pero para vídeos de YouTube y sin salir de tu máquina: pegás el guion, se parte en bloques, les asignás plano, y si el audio ya está grabado la app lo alinea contra el texto para darte los tiempos de verdad.

Está en el menú de KDE como Escaleta, con su icono. Se abre en ventana propia, sin barra de direcciones ni terminal.

Desde consola, si hace falta:

~/Documentos/escaleta/encuadre [guion.md]      # ventana propia
python3 ~/Documentos/escaleta/servidor.py      # solo el servidor

Levanta en http://127.0.0.1:8148. Si el puerto está ocupado por otro Encuadre, se limita a abrirte la pestaña; si lo ocupa otra cosa, te lo dice y podés pasarle --puerto=8149. El PID queda en $XDG_RUNTIME_DIR/escaleta.pid.

Cómo funciona

Tu .md es la fuente de verdad y no se toca nunca. Al lado se crea un guion.planos.json con las asignaciones. Si borrás la app, el guion sigue siendo tuyo y editable en Obsidian o donde quieras.

El parser entiende tu formato tal como sale de la IA que te acomoda el texto:

en el guion	se convierte en
# TÍTULO	sección
---	corte de bloque
*[Plano del piano]*	indicación visual (ya es B-roll)
**VOZ EN OFF**	etiqueta de quién habla
**frase**	acento, el golpe de la escena
línea suelta	una línea de voz en off

Si le pegás un ladrillo de texto sin formato, lo parte por frases.

Medir contra el audio

Si el vídeo ya está grabado, no hace falta estimar nada: Medir audio en la cabecera abre el selector de archivos, transcribe la grabación con faster-whisper y alinea la transcripción contra el guion que ya tenés.

Cada bloque recibe su tiempo real de inicio, fin y duración. Y salen dos cosas que a mano no se ven:

• los bloques donde el audio no coincide con lo escrito (marcados ≠ audio), o sea lo que improvisaste o dijiste distinto
• los tramos de audio que no están en el guion

Va a unos 4× tiempo real en CPU: 7 minutos de audio en menos de 2 minutos. El motor vive en .venv-audio y no se toca desde el Python principal.

Con el audio medido aparece la barra de ritmo: el vídeo entero coloreado por tipo de material, con los tramos de más de 25 segundos sin cambio de imagen subrayados en rojo. Ahí es donde se te va la gente.

Modelos

Al medir se elige el detalle: Rápido (small, ~0,5× la duración del audio), Fino (medium, ~1,5×, el recomendado) o Máximo (large-v3, ~4× y 3 GB de descarga). Cuanto más fino, menos falsas discrepancias marca.

Un bloque se marca ≠ audio cuando 3 o más palabras no casan, o cuando falla más de la mitad y tiene al menos 5 palabras. No por porcentaje a secas: un bloque de dos palabras solo puede dar 0%, 50% o 100% y llenaría la pantalla de avisos falsos.

Las líneas que no casan pero caen entre dos que sí, reciben el hueco repartido y se marcan como deducidas (en cursiva y más tenues).

Parte de cámara

T, o el botón Apuntar toma, guarda la hora exacta del reloj. Como los archivos de cámara llevan la hora en sus metadatos, después sabés qué clip es cuál sin abrirlos todos. Varias tomas del mismo bloque se apilan; la estrella marca cuál fue la buena (por defecto, la última). Un bloque con tomas cuenta como grabado.

La hora sale en el CSV completo y en la lista de planos.

Si editás el guion por fuera

El .md es un archivo de verdad y se edita donde quieras. La app lo vigila: si cambia en el disco te sale un aviso para recargar.

Cuando una línea con plano asignado cambia, ese plano no se pierde: queda apartado y aparece la barra "1 bloque perdió su plano". El panel de recuperación te enseña la línea vieja tachada, el plano que tenía y la línea actual que más se le parece, con el porcentaje. Un clic y vuelve a su sitio con sus notas intactas.

Solo se proponen bloques que aún no tienen plano, para no pisar trabajo hecho.

Unir y separar bloques

ctrl+clic marca varios bloques, U los funde en uno. Útil cuando la IA que te acomoda el guion partió una idea en cuatro frases y vos querés grabarla de una. Para deshacerlo, el bloque unido tiene su botón Separar.

Las uniones viven en el JSON, nunca en tu .md.

Exportar

• Lista de planos (markdown): para llevar al móvil el día de rodaje
• Hoja completa (CSV): todo el desglose
• Marcadores de Resolve (CSV): con timecode real, se importan en la timeline
• Capítulos de YouTube: los # títulos de tu guion con su minuto exacto

Los tres últimos necesitan el audio medido.

Anotaciones de utilería

De las indicaciones visuales (y solo de esas, nunca de la voz en off) se sacan las cosas que tienen que estar delante de la cámara. Aparecen en un renglón tenue bajo las notas del inspector (clic en una la añade a las notas) y al pie de cada grupo de rodaje. No hay vista propia ni ficha que rellenar: a propósito.

Las tres vistas

• Guion: tablero de tres columnas (sin imagen / con plano / grabado). Clic en una tarjeta abre el panel de la derecha; se arrastra entre columnas.
• Rodaje: las mismas tomas reagrupadas por cómo se graban, no por orden de guion. El A-roll se junta por localización, el B-roll por localización y encuadre. Esta es la vista que se lleva al rodaje.
• Planos: el catálogo entero, con qué es cada plano, cuándo usarlo y en qué se suele meter la pata.

Atajos (en la vista Guion, con una tarjeta seleccionada)

• 1–0 encuadre
• q–y ángulo
• a–v movimiento
• ⇧A A-roll · ⇧B B-roll · ⇧P pantalla · ⇧F archivo
• espacio marcar grabado
• ↑ ↓ moverse entre tarjetas
• esc cerrar el panel
• ctrl+clic marcar varios · U unirlos

Pulsar dos veces la misma opción la quita. Todo se guarda solo.

Archivos

Pruebas

cd ~/Documentos/escaleta && python3 -m unittest discover -s tests

40 pruebas sobre el parser, el catálogo, el almacén (incluido qué pasa si editás el guion por fuera o si el JSON se corrompe), la alineación con audio, la recuperación de planos huérfanos y la utilería.

encuadre          lanzador: levanta el servidor y abre la ventana
servidor.py       HTTP + API (stdlib, sin dependencias)
parser.py         guion -> bloques, con ids estables por contenido
catalogo.py       los 4 ejes de plano: 34 opciones con su explicación
almacen.py        .planos.json: asignaciones, uniones, tiempos de audio
audio.py          transcripción + alineación contra el guion
utileria.py       qué cosas nombra cada indicación visual
_transcribir.py   corre DENTRO de .venv-audio, escupe JSON por línea
static/           interfaz (sin frameworks)
.venv-audio/      faster-whisper, aislado del resto

El único módulo que necesita dependencias es el de audio, y vive en su propio venv: si el venv no está, la app funciona igual sin medir.