# Plan Maestro del Proyecto ## 1. Objetivo del producto Construir una aplicación web orientada a edición narrativa de video basada primero en transcript, donde el usuario sube un video y un archivo SRT o genera un transcript local desde el audio, recibe sugerencias editoriales de IA, revisa visualmente el transcript, ajusta clips manualmente, realiza trim fino dentro de la propia app y exporta una secuencia XML importable en Premiere. ## 2. Problema que resuelve El producto debe reducir el tiempo de edición de contenido hablado al convertir un transcript en una guía editorial accionable. La aplicación debe ayudar a: - Encontrar hooks. - Eliminar redundancias. - Reducir espacios muertos y palabras innecesarias. - Reordenar la narrativa cuando convenga. - Permitir corrección manual fina sin depender solo de la IA. - Exportar una secuencia utilizable en software de edición profesional. ## 3. Alcance de la primera fase La primera fase sigue siendo transcript-first, pero cuando el SRT externo no sea confiable la app debe poder extraer audio y generar timings precisos palabra por palabra localmente. El backend preferido para este caso pasa a ser `stable-ts`, dejando alternativas más ligeras solo como fallback. ### Incluye - Subida de video con SRT opcional. - Extracción local de audio y transcripción con timings por palabra usando un backend avanzado orientado a mejor calidad en audio real. - Lectura automática de metadata técnica del video fuente. - Parseo y normalización del transcript. - Envío del transcript a una API de IA para obtener sugerencias. - Visualización del transcript completo con estados editoriales. - Creación y edición de clips a partir del transcript. - Reordenamiento de clips. - Preview sincronizado transcript + video. - Ajuste manual de in y out dentro de la app. - Exportación de XML para Premiere. - Exportación directa de una versión recortada del video. ### No incluye inicialmente - Forced alignment externo o diarización avanzada más allá del pipeline local actual. - Edición multicámara. - Efectos, transiciones, música, b-roll o subtítulos estilizados. - Colaboración multiusuario en tiempo real. - Render final del video dentro de la plataforma. ## 4. Principios del sistema 1. El transcript original nunca se destruye. 2. Las sugerencias de IA son asistidas, no definitivas. 3. El usuario puede corregir manualmente cualquier decisión. 4. El clip es una entidad temporal distinta al estado editorial del texto. 5. El orden narrativo editado puede diferir del orden original del material. 6. La exportación debe mantener trazabilidad entre transcript, clip y tiempo fuente. 7. El ajuste fino principal ocurre dentro de la app; Premiere queda como salida de interoperabilidad y respaldo profesional. 8. La app debe poder exportar una versión recortada con calidad fuente o calidad equivalente a la fuente, según permita el método de render. 9. La fuente activa de un proyecto puede representarse como una composición virtual de varias partes persistidas; recomponer un MP4 continuo es opcional y nunca debe ser requisito para transcribir, revisar o editar. 10. Toda operación editorial pagada de IA debe dejar trazabilidad auditable: contexto enviado, respuesta recibida, tokens, costo estimado y justificación suficiente para reconstruir por qué se tomó una decisión. 11. La depuración no se evalúa solo por la salida de IA: debe poder compararse contra el transcript original, contra las secuencias efectivamente aprobadas y contra el resultado final editado manualmente para refinar el criterio editorial y evolucionar el prompt por versiones. ## 4.1 Bucle de aprendizaje editorial Después de estabilizar la depuración y el editor clásico, el producto debe incorporar una superficie de análisis profundo del proyecto donde se comparen tres capas: - Transcript original del material. - Resultado de depuración aprobado por secuencia. - Resultado final después de edición manual. Esa superficie debe permitir: - Excluir secuencias no aprobadas o descartadas del análisis. - Medir diferencias de palabras, segmentos conservados y recortes entre original, depuración y edición final. - Pedir a la IA un análisis comparativo entre criterio propuesto por la máquina y criterio editorial real del usuario. - Identificar qué patrón busca el editor en la práctica. - Contrastar ese patrón contra el prompt de depuración activo. - Proponer modificaciones del prompt como una nueva versión auditable, no como overwrite silencioso. La salida esperada es un ciclo de mejora continua del prompt de depuración: observar, comparar, debatir, ajustar, versionar y activar una versión nueva cuando el usuario la apruebe. En paralelo, el editor clásico debe capturar también decisiones manuales de encuadre: cuando el usuario abra `Crop`, pueda marcar una cara u objeto concreto a seguir y graduar la intensidad del seguimiento. Esa señal debe persistirse por clip/aspecto como criterio editorial observable, para que luego el motor compare `objetivo manual + intensidad` contra el auto-frame propuesto y aprenda mejor qué POI y qué agresividad de seguimiento espera realmente el editor. La persistencia no debe limitarse a un rectángulo utilitario. Cada muestra manual de tracking debe guardar también el contexto mínimo para aprendizaje posterior: intención de captura, instrucción de recreación, crop/base vigente, timestamps, centro y tamaño del objetivo, modo (`face`/`object`) e intensidad. Así, cuando el sistema revise "qué eligió el editor como base", podrá reconstruir tanto la geometría como el criterio editorial esperado. Para que ese aprendizaje parta de una base visual menos ruidosa, el editor clásico debe poder generar también un clip estabilizado por bloque desde el propio toolbar del preview, con progreso visible y cancelación. Cuando esa corrida quede lista, `Crop` y los futuros algoritmos de seguimiento deben consumir ese asset estabilizado como fuente preferente antes de inferir desplazamientos o reaprender criterios de auto-frame. ## 5. Modelo conceptual ### 5.1 Entidades principales - Proyecto - Medio de video - Audio extraído del video - Transcript fuente - Segmentos del transcript - Palabras del transcript con tiempos precisos - Sugerencia de IA - Clip - Secuencia editada - Ajustes manuales de trim - Exportación XML ### 5.2 Separación de conceptos #### A. Rango del clip Define el tramo temporal del video fuente. - Tiempo de inicio - Tiempo de fin - Identidad del clip - Orden dentro de la secuencia #### B. Estado editorial del texto Define qué pasó editorialmente con una parte del transcript. - Sugerido por IA - Agregado manualmente - Removido - Movido - Neutral #### D. Palabra como unidad temporal editable La unidad mínima real de edición debe ser la palabra alineada al audio. - Cada palabra tiene `in` y `out` temporales. - Las palabras se renderizan agrupadas visualmente en oraciones o párrafos. - El usuario no necesita ver timestamps en el texto. - Si una palabra se elimina, el video debe recortarse exactamente en el rango temporal de esa palabra. - Si se eliminan palabras intermedias dentro de una oración, un clip original puede dividirse en dos clips resultantes. - Si el usuario inserta un salto manual de línea o corte editorial, se crea un nuevo límite de clip. #### C. Secuencia editada Define el orden final de reproducción de clips. ### 5.3 Metadata técnica del video fuente La app debe leer automáticamente del video fuente, sin depender de entrada manual salvo fallback, al menos estos datos: - duración, - resolución, - fps, - sample rate de audio, - número de canales, - y ruta o referencia del archivo fuente. Para evitar errores de conversión temporal, el sistema debe: - guardar trims internamente en milisegundos, - conservar también el fps real del archivo, - y convertir a frames en el momento de exportar XML. ## 6. Flujo funcional deseado 1. Usuario entra a un panel de administración de proyectos ya procesados. 2. Usuario puede crear un proyecto nuevo con un botón `Add video`. 3. Al agregar el video, el sistema procesa de forma automática sin pasos manuales intermedios. 4. El sistema extrae WAV, detecta idioma si es viable y transcribe palabra por palabra. 5. Solo cuando termina ese procesamiento se abre el editor principal del proyecto. 6. El usuario ve el transcript como texto corrido, sin timestamps visibles. 7. Cada palabra del texto conserva internamente su `in` y `out` temporales. 8. Al borrar palabras o bloques del texto, el sistema recorta el video de manera equivalente. 9. Al introducir un corte editorial manual, el sistema divide clips según la nueva estructura textual. 10. El preview refleja la secuencia resultante. 11. La línea de tiempo muestra clips y waveform para ajuste fino. 12. Usuario guarda cambios. 13. Usuario exporta XML o video final. ## 6.0 Flujo editorial operativo para sugerir secuencias El agente que propone `Secuencias sugeridas` no debe partir de ventanas temporales fijas ni de cortes arbitrarios por duración. El flujo correcto queda definido así: 1. Detectar primero zonas muertas, relleno, divagación o tramos con baja densidad conversacional. 2. Detectar después rangos conversacionales con continuidad temática suficiente para funcionar como unidad editorial. 3. Revisar dentro de cada rango si existe un solo subtema o si hay transiciones internas que justifican más de una secuencia posible. 4. Generar candidatos de secuencia solo desde esos rangos conversacionales ya filtrados. 5. Ejecutar un segundo pase de juicio con contexto amplio del guion para decidir si cada rango debe expandirse, contraerse o descartarse. ### Implicaciones técnicas - El pipeline editorial debe tener un pase explícito de `conversation-map` antes de `segment-map`. - El descubrimiento de candidatos debe ignorar, salvo evidencia fuerte en contra, los tramos clasificados como relleno o baja conversación. - El pase de juicio no debe evaluar el rango como un fragmento aislado si el alcance total todavía es manejable; debe usar visión global o un resumen global del scope. - `Depurar` y los juicios posteriores no deben adelgazar internamente un rango amplio salvo instrucción explícita: si se conserva el tramo temporal, la cobertura de palabras activas dentro de ese tramo también debe mantenerse alta. - Todo fallback del pipeline debe persistir su procedencia técnica para distinguir problemas editoriales reales de caídas operativas del modelo. - El sistema debe persistir una auditoría por scan con, como mínimo, estos indicadores: `spoken scope`, `conversation detected`, `macrosegments built`, `suggested saved` y ratios de cobertura por palabras o duración. - `target_count` no debe funcionar como tope rígido de sugeridas guardadas si eso reduce cobertura conversacional útil; su rol es estimar densidad editorial inicial, no recortar el inventario de revisión humana. - La orientación principal del pipeline debe ser `detectar de que se habla` y cubrir lo mejor posible todas las conversaciones útiles; el sesgo a `solo short-form explosivo` debe ser secundario y no destruir cobertura temática. - Si aparece una conversación válida con subtemas claros, la salida preferida es separarla en piezas editables relacionadas, no forzar una compresión excesiva dentro de una sola sugerida. - Antes de pedir juicio fino al modelo, el backend puede y debe proponer subdivisiones temáticas locales cuando detecte rupturas claras de vocabulario y continuidad dentro de un bloque largo; la IA valida y corrige esa estructura, no parte desde cero en cada caso. ## 6.1 Definición operativa de exportación XML La exportación XML no busca trasladar una edición incompleta para terminarla en Premiere. Su propósito principal es abrir en Premiere una secuencia ya resuelta editorialmente dentro de la app, permitiendo: - revisión final, - retoques puntuales, - y salida en una herramienta más robusta si el usuario lo desea. En consecuencia, la app debe resolver antes de exportar: - selección de material, - orden narrativo, - trim de in y out, - y estado final de la secuencia. ## 6.2 Definición operativa de exportación de video Además del XML, la app debe ofrecer exportación directa de la versión recortada del video para los casos en que el usuario no quiera pasar por Premiere. La meta funcional de esta exportación es conservar: - resolución fuente, - fps fuente, - sincronía de audio, - y una calidad visual equivalente a la del material original. ### Regla técnica El concepto de "misma calidad" debe manejarse así: - si el corte puede resolverse con copia directa de streams sin perder precisión necesaria, se puede aspirar a una salida prácticamente idéntica, - si se requiere trim preciso a nivel de frame o ajustes más finos, normalmente hará falta render o re-encode, - en ese caso, la app debe ofrecer una salida en calidad equivalente a la fuente usando resolución, fps y parámetros de codificación alineados con el original. ### Política provisional de exportación de video La estrategia de exportación debe asumir dos modos operativos: - exportación rápida: intenta evitar re-encode y preservar codec o bitrate originales cuando la secuencia lo permita, - exportación final: prioriza fidelidad del resultado y precisión de trims, aunque requiera re-encode. Esta política existe porque evitar recodificación es deseable, pero no puede garantizarse para cualquier combinación de: - trims finos, - reordenamiento narrativo, - secuencias concatenadas, - y precisión suficiente para una salida final limpia. ### Preguntas técnicas abiertas no bloqueantes Estas dudas deben permanecer documentadas y validarse con pruebas reales, pero no deben frenar el arranque de arquitectura: - en qué casos concretos el flujo podrá usar stream copy sin degradar precisión útil, - cuándo habrá que hacer re-encode aunque se mantengan settings equivalentes, - qué metadata del original conviene replicar exactamente en exportación final, - y cómo comunicar al usuario si una exportación salió por copia directa o por render. ## 6.3 Flujo operativo de append multipartes Cuando el usuario añade otro video al final de un proyecto ya existente, el sistema no debe destruir lo ya procesado ni obligarse a recomponer un archivo continuo para seguir trabajando. La política operativa correcta queda así: 1. Cada video anexado se persiste como una `part` independiente con su propio media asset y su propio transcript. 2. El transcript activo del proyecto se recompone desde esas partes, manteniendo offsets globales consistentes. 3. Preview, timeline, waveform, thumbnails y editores deben poder operar sobre una fuente virtual continua construida desde partes persistidas. 4. La recomposición física de video queda reservada para casos de exportación, cache o compatibilidad puntual, pero no como dependencia del flujo editorial principal. ### Implicaciones técnicas - El backend debe exponer offsets globales por parte y duración acumulada del proyecto. - El frontend debe resolver `tiempo global -> parte + tiempo local` para scrub, play, trims y navegación. - Los clips pueden seguir referenciando una `source_video` concreta para persistencia/exportación, pero la experiencia de edición debe sentirse como una sola fuente continua. - Los assets de timeline de proyectos multipartes deben generarse virtualmente a partir de las partes, no asumir siempre un archivo `composite` existente. - La reingesta del mismo archivo debe detectarse por contenido (`fingerprint`) para reutilizar partes ya procesadas por defecto, dejando `overwrite_existing` como opt-in explícito tanto al crear proyecto como al anexar otra parte. ### Estrategia inicial recomendada La primera estrategia de exportación debe orientarse a una secuencia lineal estilo `xmeml` o Final Cut Pro 7 XML, porque encaja bien con: - una secuencia simple, - clips recortados desde un video fuente, - reordenamiento narrativo, - y exportación de pistas principales de video y audio. Esta decisión debe validarse pronto con pruebas reales de importación en Premiere. ## 7. UI objetivo Interfaz inspirada en herramientas de producción tipo OBS/Premiere: oscura, compacta, técnica y eficiente en uso de espacio. ## 7.0 Política visual editorial por bloque La decisión entre `fill`, `fit` y `split` no debe salir al azar ni como efecto secundario de una sola llamada general al modelo. Debe resolverse en una fase específica del workflow editorial, después de detectar el fragmento, depurar el texto y dividirlo en bloques narrativos. ### Principio rector - `fit` es el modo base conservador cuando el cuadro original preserva mejor el contexto visual o cuando el material no aguanta bien un recorte agresivo; no debe quedarse como default en `16:9` si hay un talking head claro y lo unico que aporta es espacio sobrante a los lados. - `fill` es un privilegio editorial: debe usarse cuando el sujeto o punto de interés está suficientemente claro y el bloque gana impacto al ocupar la mayor altura útil posible sin tocar bordes con un margen lateral sano. - `split` debe reservarse para bloques con dos participantes visibles o un intercambio claro donde convenga enseñar ambos polos del diálogo; si varios cortes consecutivos pedirían `split`, conviene alternar con `fill` para marcar mejor el turno visual. ### Inputs por bloque Cada bloque visual debe resolverse con estos datos mínimos: - `block_start_ms` - `block_end_ms` - `block_duration_ms` - `block_word_count` - `block_role` (`hook`, `context`, `payoff`, `transition`) - `block_text` - `thumbnails` del rango del bloque - `sequence_position` del bloque dentro del fragmento ### Criterios para `fill` - El bloque abre la secuencia o actúa como hook. - Hay una persona hablando a cámara o un foco humano claro. - El centro del encuadre coincide con el punto de interés del diálogo. - En `16:9`, el sujeto puede llenar más altura útil del canvas sin perder información importante ni tocar bordes. - El texto es corto o de impacto inmediato. - El recorte no destruye información visual relevante. ### Criterios para `fit` - La composición original en `16:9` contiene información útil distribuida en todo el cuadro. - El material no tiene suficiente fuerza visual central para justificar `fill`. - No hay un sujeto humano claro cuyo recorte elimine simplemente espacio lateral muerto. - Mantener el encuadre completo ayuda a continuidad entre cortes. - El bloque depende más del contexto visual que de la inmersión sobre un sujeto central. ### Criterios para `split` - Hay dos participantes visibles con separación suficiente para sostener dos paneles legibles. - El bloque es explicativo y necesita lectura sostenida. - La imagen sola no comunica todo el valor del fragmento. - Conviene mantener simultáneamente texto y contexto visual. - Ni `fill` ni `fit` resuelven bien la claridad del mensaje por sí solos. ### Política de decisión - El backend debe calcular primero una preferencia conservadora basada en reglas explícitas. - La decisión por bloque también debe mirar el corte anterior y siguiente cuando haga falta romper continuidad plana entre varios `split` seguidos. - La IA puede proponer o justificar el modo visual por bloque usando texto + thumbnails del bloque. - La decisión final debe ser validada por reglas del sistema antes de entrar al preview. - La UI debe mostrar no solo el modo elegido, sino también la razón editorial resumida. ### 7.1 Vista 1: Administración de proyectos La primera vista no debe ser el editor. Debe ser un panel de administración de proyectos procesados. - Lista de videos/proyectos ya existentes. - Estado de procesamiento. - Botón principal `Add video`. - Al añadir un video, el resto del pipeline debe ser automático. - No debe exponer formularios técnicos largos ni pasos manuales innecesarios. ### 7.2 Vista 2: Editor principal El editor solo se abre una vez terminado el procesamiento inicial del video. ### Distribución objetivo - Barra superior: acciones globales del proyecto activo. - Columna izquierda: módulo `Transcript`. - Panel central/derecho: preview de video. - Franja inferior: timeline escalable y waveform de audio. ### Módulo Transcript - Debe mostrar el contenido como texto corrido y párrafos, no como una lista dominada por timestamps. - Las palabras son elementos editables con tiempo interno. - Las oraciones agrupan palabras y suelen corresponder a clips mayores. - Borrar una palabra elimina su rango temporal equivalente del video. - Borrar una palabra intermedia puede partir un clip en dos. - Un salto editorial manual debe crear un nuevo límite de clip. - Debe poder alternar entre el transcript y una vista auxiliar de `encuadres`/`auto frame` por clip, de forma opt-in y sin invadir el canvas principal del preview. ### Módulo Video Preview - Debe mostrar la secuencia resultante de la edición textual. - Puede representar visualmente clips derivados de palabras y grupos de palabras. - Cuando se elimina texto intermedio, debe reflejar los nuevos `out` e `in` resultantes de los clips adyacentes. ### Timeline y audio - Debe comportarse como una línea de tiempo clásica de edición de video. - Cada clip debe mostrar `in` y `out`. - Debe ser escalable. - Debe incluir representación visual de la pista de audio. - Debe permitir entender cómo quedan los cortes derivados de la edición textual. ### Reglas de UX críticas - El transcript es la superficie principal de trabajo. - Los clips deben derivarse del transcript editado y verse como capas temporales sobre el texto. ## 8. Estado implementado al 2026-03-22 ### Backend y procesamiento - La app ya permite crear proyectos desde MP4 y procesarlos sin SRT obligatorio. - El backend extrae audio, genera transcript con timings palabra por palabra y persiste `TranscriptWord`. - El bootstrap del editor ya devuelve draft editorial, medios del timeline, clips y transcript operativo. - El draft editorial ya se persiste por proyecto e incluye layout e historial de undo/redo. ### Editor transcript-first - El transcript fuente ya funciona como superficie principal de edición. - El usuario puede crear secuencias desde selecciones, apagar palabras, introducir cortes editoriales y reordenar bloques. - La timeline ya deriva sus clips desde el transcript editado, no solo desde clips estáticos guardados. - Las decisiones de edición ya sobreviven refresh, reapertura del proyecto y restauración del draft. ### Timeline y precisión - La timeline ya muestra thumbnails, playhead y waveform real cargados por ventana visible. - Existe diferencia operativa entre corte normal (`C`) y corte exacto (`Ctrl/Cmd + C`). - El trim normal y el trim exacto ya ocurren dentro de la app. - El modelo editorial ya soporta overrides exactos de tiempo para inicio, fin y cortes intermedios. ### Preview y layout - El preview ya reproduce la secuencia editada sobre el video fuente. - El canvas del preview ya puede alternar entre `16:9`, `9:16` y `1:1`. - El layout del editor ya guarda split vertical, alturas de pistas, colapso de paneles y preset de canvas. - La revision visible de `auto frame` ya vive en el panel de transcript como vista opcional `Encuadres`, dejando el canvas del preview limpio para la evaluacion visual del corte. - En `9:16`, `auto frame` ya debe priorizar `fill` guiado por POI cuando hay un hablante claro; `fit` no debe sobrevivir por defecto en talking heads solo porque el sujeto venga pequeno dentro del source `16:9`. - `Encuadres` no debe renderizar `fit` como un strip bruto del source ni usar la forma del POI como si fuera el formato final: tiene que reflejar el mismo lenguaje del preview real, con backdrop blur, frame interior mas pequeno y un viewport centrado cuantizado a formatos editoriales utiles (`16:9`, `4:3`, `1:1`, `9:16`) segun la geometria del POI. ### Exportación y operación - XML y video final ya existen como salidas funcionales. - La exportación todavía necesita validación real en Premiere. - Ya existen launchers simples para levantar backend y frontend en Windows. ## 9. Pendientes vigentes - Validar importación XML en Premiere con proyectos reales. - Decidir si el preset de canvas afecta solo preview o también la exportación final. - Añadir tests automatizados para timeline, undo/redo, drafts y exportación. - Seguir reduciendo fricción de UX en herramientas exactas de timeline. - Los estados editoriales del texto no deben confundirse con los rangos de clip. - Debe existir navegación bidireccional entre clip, transcript, video y timeline. - El usuario debe poder ajustar in/out manualmente. - Los timestamps no deben dominar la lectura del transcript aunque existan internamente. ## 8. Arquitectura técnica recomendada ### 8.1 Estrategia recomendada para uso de API editorial La estrategia correcta para el agente editorial no es mandar todo el alcance a OpenAI en una sola llamada grande ni tampoco pedir una llamada cara por cada palabra. La política recomendada es híbrida: - Primero se hace un `scan` barato y rápido sobre todo el alcance seleccionado para detectar posibles rangos o ideas completas. - Ese `scan` debe ser principalmente local o heurístico, apoyado en transcript, segmentos, densidad verbal y patrones de hook. - El resultado del `scan` no crea todavía secuencias finales: solo produce una cola ordenada de rangos candidatos con prioridad editorial. - Luego el sistema trabaja un solo fragmento activo a la vez. - Para cada fragmento activo se ejecutan fases editoriales explícitas y visibles: - detección y justificación del rango, - depuración literal del texto, - reordenamiento del hook si aplica, - decisión visual por bloque, - preview, - feedback humano, - aprobación o descarte. ### 8.2 Regla operativa - No conviene pedirle a la API que escanee todo el material y además resuelva todos los fragmentos completos en una sola llamada, porque eso reduce auditabilidad, aumenta costo y hace que la UI se sienta instantánea y opaca. - Tampoco conviene disparar una llamada remota por cada microtramo del transcript desde el inicio, porque eso degradaría costo y latencia. - La mejor relación entre costo, control y legibilidad UX es: - `scan global una vez`, - `trabajo editorial profundo por fragmento`, - `avance secuencial con memoria editorial`. ### 8.3 Memoria editorial requerida El run del agente debe mantener memoria de: - `frontier_position_ms` - `covered_ranges` - `approved_fragments` - `discarded_fragments` - `idea_registry` Esto evita repetir contenido y permite que el agente siga el discurso como una historia que avanza de principio a fin. ### Backend - Django - Django REST Framework - Celery - Redis - OpenAI API - faster-whisper - Parser SRT - Generador de XML ### Frontend - React - Vite - Estado central del editor - DnD para reordenamiento de clips - Visualización de waveform ### Procesamiento multimedia - FFmpeg para lectura de metadatos, extracción de audio y tareas auxiliares - Pipeline ASR local con `word_timestamps` para reconstrucción temporal palabra a palabra ## 9. Fases del proyecto ## Fase 0. Descubrimiento y especificación ### Objetivo Cerrar alcance real del MVP y documentar decisiones estructurales. ### Entregables - Definición de alcance MVP. - Modelo conceptual validado. - Lista de librerías y stack. - Reglas editoriales base. ### Criterio de cierre - Existe documentación suficiente para arrancar implementación sin ambigüedad grave. ## Fase 1. Base del proyecto ### Objetivo Levantar la base técnica de backend y frontend. ### Tareas - Crear proyecto Django. - Crear app principal. - Configurar entorno y settings. - Preparar almacenamiento de archivos. - Preparar API base. - Crear frontend base con layout inicial. ### Criterio de cierre - Proyecto arranca localmente y muestra una shell funcional de la interfaz. ## Fase 2. Ingesta de video y SRT ### Objetivo Permitir subida, validación y parseo de materiales. ### Tareas - Subida de video. - Subida de SRT. - Validación de formatos. - Lectura automática de fps, resolución, duración y metadata de audio. - Parseo de SRT. - Persistencia de transcript y segmentos. - Asociar transcript al proyecto. ### Criterio de cierre - El usuario puede subir archivos y ver el transcript parseado. ## Fase 3. Normalización del transcript ### Objetivo Limpiar el transcript para convertirlo en superficie editorial útil. ### Tareas - Unir líneas rotas. - Limpiar ruido y repeticiones mecánicas. - Reconstruir frases cuando aplique. - Definir unidades editables. ### Criterio de cierre - El transcript se puede renderizar y operar como segmentos consistentes. ## Fase 4. Integración IA ### Objetivo Enviar transcript procesado y obtener sugerencias editoriales estructuradas. ### Tareas - Diseñar prompt. - Definir contrato JSON de respuesta. - Validar respuesta. - Guardar sugerencias. - Manejar errores, reintentos y respuestas incompletas. ### Criterio de cierre - La aplicación genera sugerencias reproducibles y validadas. ## Fase 5. Editor sobre transcript ### Objetivo Permitir visualización y edición editorial directa sobre el transcript. ### Tareas - Pintar texto sugerido, removido, agregado y movido. - Mostrar clips como capas de rango. - Soportar superposición visual. - Click en clip para resaltar rango. - Crear clips manuales. - Ajustar rango de clips. ### Criterio de cierre - El usuario puede construir y corregir la edición directamente sobre el transcript. ## Fase 6. Preview sincronizado ### Objetivo Conectar transcript, clips y video en una revisión sincronizada. ### Tareas - Click en transcript salta al video. - Click en clip resalta transcript y posiciona el video. - Reproducción por secuencia editada. - Lista de clips sugeridos y manuales. ### Criterio de cierre - La revisión editorial es navegable y usable sin exportar todavía. ## Fase 7. Ajuste fino en timeline y waveform ### Objetivo Permitir corrección precisa de in/out dentro de la app como parte central del producto, no como dependencia de Premiere. ### Tareas - Dibujar timeline del edit. - Dibujar pista de audio/waveform. - Selección de clip activo. - Handles de trim. - Nudge fino por teclado. - Guardar trims manuales. ### Criterio de cierre - El usuario puede corregir desajustes del SRT de forma manual. ## Fase 8. Persistencia editorial ### Objetivo Guardar el estado completo del trabajo para retomarlo. ### Tareas - Guardar proyecto. - Guardar clips. - Guardar orden secuencial. - Guardar estados editoriales del transcript. - Guardar trims. - Reconstruir sesión al reabrir. ### Criterio de cierre - El usuario puede cerrar y volver a abrir sin perder estructura editorial. ## Fase 9. Exportación XML ### Objetivo Generar un XML compatible con Premiere basado en una secuencia ya resuelta en la app. ### Tareas - Confirmar estrategia inicial de XML lineal estilo xmeml con prueba real. - Traducir secuencia a XML. - Probar importación real. - Manejar duración, fps y source references. - Confirmar que el XML replica fielmente trims y orden ya definidos en la app. ### Criterio de cierre - Premiere importa una secuencia válida y usable. ## Fase 9.1 Exportación de video final ### Objetivo Generar una versión recortada del video desde la propia app, sin depender de Premiere. ### Tareas - Definir estrategia de exportación directa con FFmpeg. - Detectar cuándo es viable copia directa de streams y cuándo se requiere re-encode. - Mantener resolución y fps del video fuente. - Intentar preservar codec y bitrate fuente cuando sea técnicamente viable. - Mantener audio sincronizado. - Permitir exportar la secuencia ya reordenada y trimada. - Definir presets de salida mínimamente útiles. ### Criterio de cierre - La app genera un archivo de video final que reproduce fielmente la secuencia editada con calidad fuente o equivalente. ## Fase 10. Endurecimiento del MVP ### Objetivo Reducir riesgos funcionales antes de ampliar alcance. ### Tareas - Manejo de errores. - Tests básicos. - Validaciones de archivos. - Logs. - Optimización de UX principal. ### Criterio de cierre - Existe una versión MVP estable para prueba real. ## 10. Riesgos principales ### Riesgo 1. SRT impreciso Impacto: los in/out sugeridos no quedan finos. Mitigación: - Padding automático inicial. - Ajuste manual por waveform. - Posible refinamiento posterior con audio. ### Riesgo 2. Respuesta inconsistente de IA Impacto: sugerencias mal estructuradas o poco útiles. Mitigación: - Contrato JSON estricto. - Validación de salida. - Reintentos controlados. - Prompt más acotado. ### Riesgo 3. UI demasiado compleja demasiado pronto Impacto: lentitud en desarrollo y uso confuso. Mitigación: - Separar modo guion y modo ajuste fino. - Priorizar flujo principal antes de funciones avanzadas. ### Riesgo 4. Exportación XML incompatible Impacto: el valor del producto cae mucho si Premiere no importa bien. Mitigación: - Probar exportación real temprano. - No dejar XML para el final absoluto. - Basarse primero en una variante lineal simple antes de intentar formatos más complejos. ### Riesgo 6. Metadata técnica mal interpretada Impacto: la secuencia exportada puede abrir con cortes desplazados, timebase incorrecto o settings visuales inconsistentes. Mitigación: - Leer fps y resolución directamente del video fuente. - Conservar fps como valor preciso para exportación. - No depender de entrada manual para datos técnicos básicos. ### Riesgo 7. Expectativa incorrecta sobre "misma calidad" Impacto: el usuario puede esperar identidad binaria con el archivo original incluso en cortes que requieren re-encode preciso. Mitigación: - Distinguir entre copia directa y render final. - Mostrar el modo de exportación usado. - Preservar resolución y fps fuente. - Ofrecer calidad equivalente a la fuente cuando no sea viable copia directa. ### Riesgo 8. Suposición errónea sobre evitar re-encode siempre Impacto: se podría diseñar el producto alrededor de una promesa de velocidad o fidelidad que no aplique a todos los casos de uso reales. Mitigación: - tratar la exportación sin recodificación como optimización y no como garantía universal, - validar temprano con secuencias simples y secuencias reordenadas, - y mantener disponible un modo de exportación final robusto. ### Riesgo 5. Trim poco preciso en la app Impacto: el usuario dependería de Premiere para terminar un trabajo que el producto debería resolver internamente. Mitigación: - Timeline y waveform utilizables. - Handles claros de trim. - Nudge fino por teclado. - Persistencia robusta de ajustes manuales. ## 11. Criterios de aceptación del MVP El MVP será aceptable cuando permita: - Crear un proyecto. - Subir video y SRT. - Obtener sugerencia editorial de IA. - Ver transcript con estados visuales. - Crear y editar clips. - Reordenar clips. - Previsualizar la secuencia. - Ajustar in/out manualmente. - Guardar el estado del proyecto. - Exportar XML usable en Premiere que respete el orden y los trims definidos en la app. - Exportar un video final recortado con calidad fuente o equivalente. ## 12. Método de seguimiento Para evitar desorden, cada avance debe registrarse en tres capas: 1. Checklist general de estado. 2. Bitácora de trabajo con fecha y cambios realizados. 3. Actualización del plan cuando cambie alcance o prioridad. ## 13. Reglas para actualizar esta documentación Actualizar este archivo cuando ocurra alguno de estos eventos: - Cambio de alcance del MVP. - Cambio de stack tecnológico. - Cambio de flujo principal del producto. - Descubrimiento de una restricción fuerte. - Nueva decisión importante de UX o exportación. ## 14. Próximo paso recomendado El próximo paso operativo más sensato es definir la estructura inicial del proyecto y arrancar Fase 1 con backend y frontend base. ## Fase futura: Evolución a SaaS / Companion App A partir de abril 2026 el producto evoluciona hacia un modelo cliente-servidor donde la UI se sirve desde altoque.tv/maxeditor y el procesamiento FFmpeg ocurre en una companion app instalada localmente en cada PC del usuario. Los videos nunca salen de la máquina del cliente. ### Documentos de referencia - [SAAS_ARCHITECTURE.md](SAAS_ARCHITECTURE.md): diseño técnico completo de la arquitectura híbrida. - [SAAS_WORKPLAN.md](SAAS_WORKPLAN.md): plan de trabajo detallado en 7 fases (0–6) con tareas verificables. ### Estrategia en dos versiones - **v1 (uso interno oficina):** auth básica con email/password creados manualmente, sin Stripe, suscripciones de tipo lifetime para empleados. - **v2 (SaaS público):** mismo código, agrega Stripe, trials, signup público, marketing site, onboarding automatizado. ### Criterio de cierre Fase SaaS - Empleados de oficina usando el sistema en producción desde altoque.tv. - Cero llamadas a FFmpeg en el server: todo el procesamiento ocurre en el cliente. - Updates de UI llegan automáticamente al subir build al server. - Updates del companion notifican al usuario y permiten descarga manual.