Encoop

Sistema de codificación de vídeo distribuido escrito en Go. Un ejecutable actúa como servidor central o worker, con CLI, demonio e interfaz web embebida en español.

El servidor conserva fuentes, prepara fragmentos, asigna trabajo por capacidad del worker, valida resultados y ensambla un MKV con el audio original. Los workers reciben los parámetros del servidor y descargan/codifican/devuelven cada fragmento.

Arranque rápido

Requisitos de compilación: Go 1.23 o posterior. En ejecución: FFmpeg y FFprobe; el servidor necesita FFV1 y los workers los encoders elegidos. Para SVT-AV1 mediante FFmpeg se requiere un wrapper con -crf y -svtav1-params.

go build -trimpath -o bin/encoop.exe ./cmd/encoop
./bin/encoop.exe server --gui

El panel se abre en http://127.0.0.1:8080. Introduce el contenido de data/server/admin.token en «Acceso al nodo». Las credenciales se generan con aleatoriedad criptográfica y se conservan entre reinicios.

En otra terminal:

$env:ENCOOP_TOKEN = (Get-Content data/server/worker.token).Trim()
./bin/encoop.exe worker --server http://127.0.0.1:8080 --max-threads 8 --gui

El worker abre su panel en http://127.0.0.1:8081, con la credencial de data/worker/ui.token. Desde el panel del servidor puedes subir una fuente, elegir encoder, VBR/CRF, bitrate/calidad, preset, parámetros avanzados y duración de fragmento, añadir el trabajo, seguirlo y descargar el resultado.

Linux/macOS usan el mismo comando con go build -o bin/encoop ./cmd/encoop. La GUI es una interfaz en el navegador; no necesita Node, un servidor de desarrollo ni conexión a un CDN.

CLI

Las operaciones administrativas usan el token admin, distinto del token para unir workers:

$env:ENCOOP_TOKEN = (Get-Content data/server/admin.token).Trim()
./bin/encoop.exe status
./bin/encoop.exe submit --source 'D:/videos/source.mkv' --encoder x264 --bitrate 2500 --preset medium --segment 30
./bin/encoop.exe submit --source 'D:/videos/source.mkv' --encoder svt-av1 --bitrate 2000 --preset 6
./bin/encoop.exe submit --source 'D:/videos/source.mkv' --encoder x265 --rate-control crf --quality 28 --preset slow
./bin/encoop.exe submit --source 'D:/videos/source.mkv' --settings ./encoding.json
./bin/encoop.exe upload --source ./source.mkv
./bin/encoop.exe download --job JOB_ID --output ./result.mkv
./bin/encoop.exe cancel --job JOB_ID
./bin/encoop.exe retry --job JOB_ID

submit --source referencia una ruta en el servidor. upload lee un archivo local y devuelve una ruta almacenada que puedes usar después en submit. status devuelve el estado completo en JSON. Cada comando dispone de --help.

Encoders y rutas

Encoder	Backend FFmpeg	Backend nativo	Preset	Calidad
x264	libx264	x264	ultrafast…veryslow	CRF 0–51
x265	libx265	x265	ultrafast…veryslow	CRF 0–51
aomenc	libaom-av1	aomenc	0–8	CQ 0–63
svt-av1	libsvtav1	SvtAv1EncApp	0–13, según versión	CRF 0–63

La detección usa PATH, inspecciona la lista de encoders de FFmpeg y muestra rutas/versiones/capacidades. El servidor asigna únicamente a workers que anuncian el backend requerido. Las opciones incompatibles con una versión concreta aparecen como error del fragmento; las versiones de los binarios están visibles en el panel.

./bin/encoop.exe worker --server https://encode.example.org --token WORKER_TOKEN --ffmpeg 'C:/tools/ffmpeg.exe' --ffprobe 'C:/tools/ffprobe.exe' --encoder-path aomenc='C:/tools/aomenc.exe' --encoder-path svt-av1='C:/tools/SvtAv1EncApp.exe'

Para usar un binario nativo, crea el trabajo con --backend native. FFmpeg sigue siendo necesario para decodificar a Y4M y remultiplexar el resultado a MKV. Los encoders son dependencias externas: el binario Go incluye el programa y la web, pero no redistribuye FFmpeg ni los codecs.

Ajustes centrales, VBR y máximo de hilos local

El servidor fija una configuración inmutable por trabajo y la transmite a todos sus fragmentos: encoder, backend, rate control, bitrate/calidad, preset y opciones específicas. La CLI y la web usan VBR por defecto; la CLI requiere --bitrate explícito, en kbps. --rate-control crf selecciona calidad constante; --rate-control custom permite definir el rate control completo mediante opciones del encoder sin que Encoop inyecte bitrate, calidad o preset.

Con VBR se aplica el mismo objetivo a cada fragmento, pero la complejidad afecta a la calidad visual y al bitrate conseguido. La división no constituye un rate control global o un análisis de dos pasadas de toda la fuente. Para x264/x265, --max-bitrate (kbps) y --buffer-size (kbits), indicados juntos, permiten VBV; para AOM/SVT los modos y límites específicos se configuran mediante opciones avanzadas, sin reinterpretar un límite VBV como otro control.

Cada worker define --max-threads N, por defecto el número de CPU lógicas. Los trabajos nuevos usan threads: 0: cada asignación utiliza ese máximo local. Un techo opcional submit --threads N reduce el presupuesto a min(N, máximo local). El mismo trabajo automático usa 4 hilos en un worker limitado a 4 y 16 en otro limitado a 16. effective_threads informa del presupuesto sin alterar settings.threads ni la calidad central. El worker vuelve a aplicar su límite al recibir el trabajo.

Los límites controlan los parámetros de paralelismo del encoder y decoder; algunos codecs crean hilos auxiliares. No constituyen una cuota de CPU o un límite total de hilos del proceso a nivel del sistema operativo.

Las opciones avanzadas no dependen de una lista cerrada de parámetros de una versión concreta:

./bin/encoop.exe submit --source 'D:/videos/source.mkv' --encoder x265 --bitrate 2500 --encoder-param aq-mode=2 --encoder-param psy-rd=2.0 --encoder-arg=-tune --encoder-arg=grain

--encoder-param nombre=valor añade parámetros privados. Mediante FFmpeg se usa x264-params, x265-params, aom-params o svtav1-params; en modo nativo se traducen a opciones del ejecutable. --encoder-arg añade argumentos literales, uno por bandera o valor, usando la sintaxis del backend elegido. No se interpreta un comando de shell. Los nombres nuevos se pasan al encoder y éste valida qué acepta su versión. Un parámetro nativo puede no tener equivalente en FFmpeg: para todas las opciones de la CLI original utiliza el backend nativo.

Se reservan las opciones que gestionan la entrada/salida del fragmento, su formato y el presupuesto de hilos, incluidos alias y configuraciones opacas que podrían reemplazarlos. Los diccionarios privados se introducen mediante parameters, permitiendo aplicar después los controles locales de hilos. Los encoders se ejecutan dentro del directorio temporal de su fragmento, aislando archivos relativos de estadísticas/análisis entre intentos; esos temporales se eliminan al terminar. Los archivos auxiliares de entrada (qpfile, zonas, estadísticas o análisis preexistentes) deben estar provisionados en los workers y referenciarse mediante rutas absolutas; Encoop no los distribuye automáticamente.

En FFmpeg la precedencia es: campos básicos, argumentos adicionales, parámetros privados y controles de Encoop. En nativo los argumentos adicionales van después de los parámetros privados, antes de los controles finales de Encoop. Si configuras controles de bitrate/calidad alternativos, usa custom para evitar valores generados que compitan con ellos. Consulta los ejemplos completos de configuración.

Red, NAT y CGNAT

Todo el tráfico lo inicia el worker: registro, petición de trabajo, heartbeat, descarga y subida. El servidor nunca abre conexiones hacia él, de modo que no requiere puertos entrantes en el worker, UPnP ni hole punching. Cada worker procesa un fragmento simultáneamente; escala lanzando más procesos con --data, --listen y --name distintos.

El servidor debe ser accesible: IP pública, proxy HTTPS o red privada/VPN compartida. Si también el servidor está detrás de CGNAT, esta versión requiere ese proxy/túnel/VPN; no incluye un servicio externo de relay, STUN o TURN.

HTTPS directo:

./bin/encoop.exe server --listen 0.0.0.0:8443 --tls-cert server.crt --tls-key server.key
./bin/encoop.exe worker --server https://encode.example.org:8443 --token WORKER_TOKEN

Se validan los certificados del servidor. Para un proxy local, conserva el bind del demonio en loopback y publica su HTTP mediante el proxy HTTPS. Las conexiones HTTP fuera de loopback requieren --allow-insecure-http explícito en ambos extremos. No se siguen redirecciones autenticadas. Los workers que poseen el token compartido forman un grupo de confianza; esta versión no implementa cuentas o aislamiento entre organizaciones.

Demonio y persistencia

server y worker ejecutan procesos persistentes en primer plano y finalizan con Ctrl+C. Puedes gestionarlos con systemd, launchd o un supervisor Windows. --daemon los separa de la terminal y escribe daemon.log y daemon.pid en su directorio de datos; consulta el log para verificar el arranque. El PID es informativo y no impide lanzar otro proceso. Cada proceso debe usar su propio directorio de datos.

La cola se conserva en state.json, con escritura temporal, sync y reemplazo. Las asignaciones tienen tokens únicos, heartbeat y caducidad configurable (--lease, predeterminado 2 minutos); se rechazan resultados tardíos de asignaciones anteriores. Si un worker se desconecta, sólo su fragmento pendiente vuelve a la cola al caducar: se codifica desde el principio y se conservan los fragmentos ya completados. Tras agotar --attempts (3 por defecto), el trabajo queda en error y puede reintentarse. Un reinicio recupera la cola y reasigna el trabajo interrumpido; una preparación interrumpida requiere reintento.

La versión 0.2 usa el protocolo 2: actualiza servidor y workers juntos. El servidor migra automáticamente el estado del protocolo 1 conservando CRF y el número de hilos de los trabajos antiguos.

El servidor mantiene originales, copias subidas, segmentos FFV1, resultados y salida final. Los temporales del worker se eliminan después de cada intento. La retención/limpieza de fuentes y trabajos del servidor es manual en esta versión. El panel distingue el tamaño del directorio de datos del espacio libre de su volumen.

Alcance del procesamiento

• Primer stream de vídeo, normalizado a CFR, YUV 4:2:0 de 8 bits y dimensiones pares. FFV1 es sin pérdida después de esa normalización; HDR/10 bits/VFR necesitan un pipeline adicional y no se preservan fielmente.
• Fragmentos con fotogramas intra y timestamps reiniciados. El servidor comprueba codec, dimensiones, número de fotogramas, FPS y duración antes de aceptar cada resultado y la salida ensamblada.
• Salida MKV con vídeo codificado y pistas de audio copiadas del original, limitadas a la duración del vídeo. No se conservan subtítulos, adjuntos ni capítulos de forma completa.
• Parámetros: encoder/backend, VBR/CRF/custom, bitrate/calidad, preset, VBV cuando corresponde, diccionarios privados y argumentos literales. Los perfiles se pueden guardar en JSON. No implementa aún scene detection, multipass global o métricas VMAF.
• Telemetría FFmpeg: progreso, FPS, velocidad, tiempo transcurrido y ETA. En binarios nativos se muestra fase y tiempo; no se calcula un porcentaje/ETA de codificación nativa fiable.
• CPU total del host disponible en Windows/Linux; en otras plataformas figura N/D. El presupuesto de hilos se transmite al encoder; algunos codecs crean además hilos auxiliares. No es una cuota de CPU del sistema operativo.
• Subidas de fuentes hasta 64 GiB y de resultados hasta 8 GiB. No hay transferencias reanudables ni cuotas globales; los fragmentos FFV1 pueden consumir bastante disco y ancho de banda.

Verificación

go test ./...
go vet ./...
$env:ENCOOP_INTEGRATION = '1'
go test -v ./internal/integration

La integración genera un vídeo sintético con audio, lo sube, crea tres fragmentos, ejecuta dos workers con máximos de hilos distintos, descarga el resultado y verifica codec, 30 fotogramas, audio PCM y decodificación sin errores. Comprueba CRF y VBR con parámetros avanzados para x264, x265, AOM y SVT mediante FFmpeg; aomenc nativo cuando está instalado. Comprueba también que los ajustes centrales son idénticos y los hilos efectivos coinciden con cada límite local. Para todos los casos instala FFmpeg moderno con las cuatro librerías. La suite habitual no requiere codecs externos.

Consulta la arquitectura y el protocolo. Documentación de referencia: segmentación y concat de FFmpeg, parámetros de SVT-AV1.