VideoUtils

Aplicacion de escritorio para Windows construida con Electron, React y TypeScript para:

• dividir videos por duracion, tamaño aproximado o numero de partes;
• comprimir videos a un tamaño objetivo o con un preset de calidad;
• previsualizar una estimacion antes de ejecutar FFmpeg;
• procesar archivos localmente con binarios empaquetados de FFmpeg y FFprobe.

Que hace la aplicacion

La app tiene un flujo simple:

1. Seleccionar un video de entrada.
2. Seleccionar una carpeta de salida.
3. Analizar el archivo con FFprobe para extraer metadatos.
4. Elegir una operacion:
   • Split: divide el video.
   • Compress: comprime el video.
5. Revisar la estimacion calculada.
6. Ejecutar el proceso y seguir el progreso en tiempo real.

Modos de division

• By duration: divide por duracion maxima por segmento.
• By size (approx.): estima la duracion de cada parte a partir del bitrate del archivo.
• Number of parts: reparte el video en un numero fijo de partes.

Modos de compresion

• Target size: intenta generar un MP4 con un peso aproximado. Generalmente ocupa menos de lo solicitado ( p.ej videos de ~3GB, se solicita 400Mb, resultado ~280Mb)
• Quality preset: comprime usando presets de calidad (high, medium, low).

La compresion genera salida MP4 con video H.264 y audio AAC.

Stack tecnico

• Electron para el proceso principal y la ventana de escritorio.
• React 19 para la interfaz.
• Vite para desarrollo y build del renderer.
• TypeScript para main, preload y renderer.
• ffmpeg-static y ffprobe-static para empaquetar los binarios.
• Vitest para tests unitarios.

Estructura del proyecto

src/
  main/
    main.ts                # proceso principal de Electron
    preload.ts             # API expuesta al renderer
    services/              # FFmpeg, FFprobe y ejecucion de jobs
  renderer/
    App.tsx                # interfaz principal
    main.tsx               # bootstrap de React
    styles.css             # estilos
  shared/
    estimation.ts          # reglas de estimacion
    format.ts              # formateadores
    types.ts               # tipos compartidos
tests/
  estimation.test.ts       # tests de la logica de estimacion

Requisitos

• Node.js 20 o superior recomendado.
• npm 10 o superior recomendado.
• Windows para generar y ejecutar el paquete .exe.

Instalacion

npm install

Desarrollo local

Arrancar en modo desarrollo

npm run dev

Esto levanta:

• Vite en http://localhost:5173
• compilacion en watch del proceso principal de Electron
• Electron apuntando al servidor de desarrollo

Ejecutar tests

npm test

Generar build local

npm run build

Este comando genera:

• dist-renderer/ para la interfaz compilada;
• dist-electron/ para el proceso principal y preload.

Empaquetado para Windows

Generar el ejecutable portable

npm run dist

Salida esperada:

• release/VideoUtils 1.0.0.exe
• release/win-unpacked/

win-unpacked contiene la aplicacion descomprimida, util para pruebas manuales. El .exe portable es el artefacto para distribuir.

Nota importante sobre el renderer empaquetado

La app cargada desde archivo local necesita rutas relativas a los assets del renderer. Por eso vite.config.ts usa:

base: "./"

Sin eso, la build puede abrir una ventana en blanco porque index.html intentaria cargar /assets/... en vez de ./assets/....

Como usar la app

Dividir un video

1. Pulsa Choose video.
2. Pulsa Choose folder.
3. Pulsa Analyze video.
4. En Configuration, selecciona Split.
5. Elige el modo y los parametros.
6. Revisa Estimate.
7. Pulsa Process video.

Comprimir un video

1. Selecciona archivo y carpeta.
2. Analiza el archivo.
3. En Configuration, selecciona Compress.
4. Elige Target size o Quality preset.
5. Ajusta el bitrate de audio si hace falta.
6. Revisa Estimate.
7. Ejecuta Process video.

Como colaborar en GitHub

Flujo recomendado

1. Crea una rama desde main.
2. Haz cambios pequenos y coherentes.
3. Ejecuta npm test.
4. Si tocas UI o empaquetado, ejecuta tambien npm run build.
5. Abre un Pull Request con descripcion clara, impacto y pasos de prueba.

Convenciones utiles

• Mantener src/shared como fuente comun de tipos y reglas.
• No llamar a Node directamente desde React; usar preload.ts e IPC.
• Si cambias empaquetado o rutas, probar tanto npm run dev como npm run dist.
• Si introduces una nueva regla de estimacion, anade tests en tests/estimation.test.ts.

Checklist para un PR

• El cambio funciona en npm run dev.
• npm test pasa.
• npm run build pasa.
• Si afecta al empaquetado, npm run dist genera el .exe correctamente.
• La documentacion se ha actualizado si el comportamiento cambia.

Troubleshooting

La app empaquetada abre una ventana en blanco

Revisar:

• que vite.config.ts mantenga base: "./";
• que exista dist-renderer/index.html dentro del paquete;
• que main.ts cargue dist-renderer/index.html cuando no hay VITE_DEV_SERVER_URL.

FFmpeg o FFprobe no arrancan

Revisar:

• que ffmpeg-static y ffprobe-static esten en dependencies, no en devDependencies;
• que el empaquetado incluya node_modules;
• que el antivirus no este bloqueando la ejecucion de binarios empaquetados.

El resultado final no coincide exactamente con la estimacion

Es esperable en parte:

• la division por tamano es aproximada;
• la compresion a tamano objetivo depende del contenido real del video;
• audio, GOP, escenas y complejidad visual afectan al tamano final.

Scripts disponibles

{
  "dev": "Desarrollo completo con renderer + main + Electron",
  "build": "Build del renderer y del proceso principal",
  "dist": "Build completo y empaquetado portable para Windows",
  "test": "Tests unitarios con cobertura"
}

Mejoras futuras recomendadas

• configurar icono de aplicacion para evitar el icono por defecto de Electron;
• considerar asar: true con asarUnpack para binarios externos;
• anadir tests de integracion para el flujo IPC;