Video Decode — Fase 1

App web modular para subir videos de clases o videollamadas y obtener transcripción segmentada. Esta es la base arquitectónica y la Fase 1; fases posteriores añadirán enriquecimiento con Gemini, análisis visual y guías paso a paso.

Dónde se guarda el video y qué hay en la BD

• En disco: los archivos de video se guardan en la carpeta /uploads/videos (ruta relativa al proyecto). No se guardan en la base de datos.
• En la base de datos (SQLite): solo se guardan metadata y rutas: tabla Video (id, nombre original, nombre guardado, ruta en disco, MIME, tamaño, estado) y tabla ProcessingJob (id, videoId, stage, status, mensaje, fechas). El contenido binario del video solo existe en disco.

Detalle en docs/UPLOAD-PERSISTENCE.md.

Arquitectura

• Presentación: src/app (páginas) y src/components (UI).
• Orquestación: src/services (casos de uso y pipeline).
• Dominio: src/domain (tipos y entidades).
• Módulos: src/modules — media (FFmpeg), transcription (Whisper), persistence (archivos + Prisma/SQLite).

Detalle en docs/ARCHITECTURE.md.

Requisitos previos

• Node.js 20+
• FFmpeg instalado y en PATH (para extracción de audio).
• Whisper (Python) instalado y en PATH:

  pip install openai-whisper

  En Windows, si el comando no es whisper, configura:

  set WHISPER_COMMAND=python -m whisper

Instrucciones para correr en local

1. Clonar / abrir el proyecto y instalar dependencias:

   cd video-decode
   npm install

2. Variables de entorno (opcional; hay valores por defecto):

   cp .env.example .env

   Edita .env si quieres cambiar rutas o el modelo Whisper:

   • DATABASE_URL="file:./dev.db" — SQLite.
   • UPLOADS_VIDEOS_DIR — carpeta de videos subidos (por defecto ./uploads/videos).
   • UPLOAD_DIR, AUDIO_DIR — carpetas para pipeline de audio (por defecto ./data/uploads y ./data/audio).
   • WHISPER_COMMAND — comando para ejecutar Whisper (por defecto whisper).
   • WHISPER_MODEL — modelo: tiny, base, small, medium, large (por defecto base).

3. Base de datos (crea prisma/dev.db y genera el cliente):

   npx prisma db push
   npx prisma generate

4. Arrancar la app:

   npm run dev

   Abre http://localhost:3000.

5. Uso (flujo de upload):

   • En la página principal, elige un video (mp4, webm, mov, avi, mkv, m4v, ogv) y pulsa Subir y transcribir.
   • El sistema valida tipo/extension, guarda el archivo en uploads/videos y registra Video + ProcessingJob en la BD.
   • La respuesta se muestra en la misma página: ID del video, nombre original, ruta guardada, tamaño, estado y job creado. Desde ahí puedes ir a Ver job para el detalle del job (y en el futuro, el transcript cuando el pipeline esté en marcha).

Cómo probar el upload

1. Arranca la app (npm run dev) y abre http://localhost:3000.
2. Elige un archivo de video (por ejemplo un .mp4 pequeño).
3. Pulsa Subir y transcribir.
4. Comprueba que aparece el panel con: ID del video, nombre original, ruta guardada (algo como …/uploads/videos/…), tamaño, estado del video (uploaded), job creado (ID, stage upload, status pending) y el enlace Ver job.
5. Opcional: revisa que el archivo existe en ./uploads/videos/ y que en la BD hay un registro en Video y otro en ProcessingJob (por ejemplo con npx prisma studio).

Endpoints (Fase 1)

Método	Ruta	Descripción
POST	/api/upload	Sube video (form field video). Valida, guarda en uploads/videos, crea Video y ProcessingJob. Devuelve { video, job }.
GET	/api/jobs	Lista últimos videos con sus jobs.
GET	/api/jobs/[id]	Detalle de un job y su video ({ job, video }).
GET	/api/jobs/[id]/transcript	Segmentos del transcript del job.

Fases futuras (no implementadas)

• Fase 2: Enriquecimiento semántico con Gemini (resúmenes, anotaciones).
• Fase 3: Análisis visual del video (frames, detección de pizarra/demos).
• Fase 4: Generación de guía paso a paso con capturas relevantes.

Los hooks para estas fases están descritos en docs/ARCHITECTURE.md.