Nextcloud: reproductor de vídeo que no funciona, cómo arreglarlo con Galería de vídeo

Si el reproductor de vídeo de Nextcloud se entrecorta, se niega a arrancar o muestra un muro de recuadros grises en lugar de miniaturas, la causa suele ser la misma: se le está entregando al navegador un archivo que no puede decodificar. El visor integrado de Nextcloud va bien para un clip de móvil en H.264, pero dale un MKV, un HEVC o un archivo de 10 bits, un rip en VC-1 o MPEG-2, o un archivo con audio DTS o TrueHD, y el reproductor se queda parado o en negro. Galería de vídeo es un plugin de Nextcloud que resuelve esto en el origen. Indexa todos los vídeos de la cuenta, reproduce los formatos que un navegador no puede abrir por sí solo y elige por archivo cómo enviarlo, para que no pagues una recodificación completa cuando bastaría con un simple reempaquetado. Este tutorial es para quienes gestionan su propia instancia y quieren que el reproductor se comporte.

Qué obtienes

Galería de vídeo (videogallery) encuentra todos los archivos de vídeo de una cuenta —carpeta personal, carpetas compartidas, almacenamiento externo—, los ordena por la fecha real de grabación y reproduce cada uno en el navegador. Admite HEVC, 10 bits, VC-1, MPEG-2, DTS, TrueHD, AVI y MKV. Para cada archivo y cada navegador decide si enviarlo intacto, reempaquetarlo (cambia el contenedor, copia los flujos), convertir solo el sonido o recodificarlo en la tarjeta gráfica. Esa decisión por archivo es el corazón de la solución: un archivo que ya se reproduce no se toca, y uno que no puede reproducirse se convierte solo hasta donde hace falta.

Requisitos previos

• Nextcloud 34 y PHP 8.4 o superior. La app se niega a activarse por debajo de 8.4.
• ffmpeg en el servidor: sudo apt install ffmpeg (Debian, Ubuntu), sudo dnf install ffmpeg (Fedora, RHEL) o sudo apk add ffmpeg (Alpine).
• Tareas en segundo plano (Cron) de Nextcloud en funcionamiento para la indexación y la generación de vistas previas.
• Opcional pero recomendable: una tarjeta gráfica para la conversión (NVIDIA NVENC, Intel Quick Sync, VA-API para Intel/AMD). Sin ella, la conversión se ejecuta en la CPU.
• Recomendable: un disco rápido, idealmente NVMe y separado del disco del sistema, para los archivos temporales.

Paso 1 — Instalar y activar la app

Descarga el archivo videogallery-x.y.z.tar.gz desde tu cuenta de MediaLab Works en Licenses y extráelo en la carpeta apps/ (o custom_apps/) de Nextcloud, de modo que tengas apps/videogallery/, con el usuario del servidor web como propietario:

cd /var/www/nextcloud/apps
sudo tar -xzf ~/videogallery-x.y.z.tar.gz
sudo chown -R www-data:www-data videogallery

Actívala:

sudo -u www-data php occ app:enable videogallery

Después abre Administration settings → Video Gallery → License, pega tu clave de licencia y guarda. La app contacta con el servidor de licencias, vincula la clave a esta instancia y muestra la licencia como Active.

Paso 2 — Crear la biblioteca ahora en lugar de esperar

Cron indexará tus archivos con el tiempo, pero puedes empezar de inmediato:

sudo -u www-data php occ videogallery:scan

Puedes pasar un nombre de usuario para analizar una sola cuenta. Si más adelante no aparecen vídeos nuevos, la causa habitual es que las tareas en segundo plano no se están ejecutando; pulsa Look for new files en The library dentro de los ajustes, o vuelve a ejecutar el comando de análisis.

Paso 3 — Dirigir los archivos temporales a un disco rápido

Abre Administration settings → Video Gallery. La app encuentra ffmpeg, comprueba lo que la máquina puede hacer realmente y elige por sí sola un directorio de trabajo; la página te dice en una frase qué falta y el comando que lo soluciona. En Working files, apunta el directorio de trabajo a un disco rápido que no sea el del sistema. La app solo borra dentro de su propio directorio marcado, así que tus medios nunca corren riesgo.

Paso 4 — Medir la máquina y configurar la GPU

En This server ves los codificadores que funcionan de verdad aquí: NVENC, Quick Sync, VA-API, VideoToolbox o software. Ejecuta Measure this machine: prueba la tarjeta gráfica con una muestra exigente y conserva la mejor combinación funcional de preajustes y ruta de decodificación. Cualquier cifra se puede sobrescribir. Si tienes varias tarjetas, activa o desactiva cada una en Graphics cards, o dale a cada una su propio límite.

Muchas distribuciones arrancan PHP-FPM con PrivateDevices=true, lo que oculta la tarjeta: obtienes «no CUDA-capable device is detected» aunque funcione desde una shell. Para NVIDIA, añade un drop-in con sudo systemctl edit php8.4-fpm (usa tu versión de PHP):

[Service]
PrivateDevices=no
DevicePolicy=closed
DeviceAllow=/dev/nvidia0 rw
DeviceAllow=/dev/nvidiactl rw
DeviceAllow=/dev/nvidia-uvm rw
DeviceAllow=/dev/nvidia-uvm-tools rw
DeviceAllow=/dev/nvidia-modeset rw

Para Intel y AMD: sudo usermod -aG render www-data. Después sudo systemctl daemon-reload && sudo systemctl restart php8.4-fpm. Tras cambiar controladores, pulsa Test the hardware again.

Paso 5 — Deja que mida la conexión

En Quality and the connection, activa la medición de la conexión antes de reproducir y que siga ajustando durante la reproducción. La app mide el enlace antes y durante la reproducción, de modo que un archivo de alto bitrate solo se envía intacto cuando la conexión puede con él, y la calidad sigue a la conexión. En el reproductor, el menú de calidad muestra lo elegido, por ejemplo Automatic (4.0 Mbit/s); elige ahí una calidad fija si lo prefieres.

Paso 6 — Dejar bien la línea de tiempo y las miniaturas

La línea de tiempo se construye a partir de las fechas reales de grabación leídas del interior del archivo, luego del nombre del archivo y, por último, de su marca de tiempo. Por eso una biblioteca copiada ya no parece filmada toda el día de la migración. También puedes ordenar por más reciente añadido, más reciente filmado, nombre, duración o tamaño; la elección se guarda en la cuenta, en todos los dispositivos. En Previews, ajusta la duración y la altura del clip al pasar el cursor y el espacio reservado para las vistas previas en caché: esto es lo que llena las tarjetas de portada con vistas previas silenciosas al pasar el cursor en lugar de recuadros grises. Si faltan vistas previas, ejecuta sudo -u www-data php occ videogallery:preview (opcionalmente para un solo usuario) y asegúrate de que Cron funciona.

Paso 7 — Subtítulos, pistas de audio y capítulos

En los menús del reproductor tienes todos los subtítulos incrustados y en archivos aparte, todas las pistas de audio y los capítulos. También se encuentran los archivos aparte con nombres como Film.en.srt o Film_en.srt junto al vídeo. El reproductor ofrece además pantalla completa, vista previa de fotograma al arrastrar, gestos táctiles para brillo, volumen y búsqueda, imagen en imagen y reanudación entre dispositivos. Cuando quieras una copia bit a bit o verlo en una TV, Open in another player entrega el original intacto a VLC, Infuse u otro reproductor del dispositivo.

Paso 8 — Series y cursos en orden

Una carpeta de archivos numerados se reproduce en orden, con la siguiente parte ofrecida al final. En Kinds of folder, el administrador escribe las reglas que clasifican las carpetas en cursos, cámara, series y películas. Si tu carpeta de curso salta de un lado a otro, revisa primero esas reglas.

Consejos y solución de problemas

• Algo no se reproduce: ejecuta sudo -u www-data php occ videogallery:selftest. Convierte parte de un archivo real en ambos sentidos, busca en el centro, comprueba que el resultado se reproduce y que no queda nada atrás.
• No se usa la tarjeta gráfica: revisa occ videogallery:status. Normalmente PHP-FPM no puede ver la tarjeta (PrivateDevices) o www-data no está en el grupo render.
• ffmpeg no encontrado: instálalo, o indica su ruta en The library → Paths, if ffmpeg is somewhere unusual.
• Comprobar el estado general: occ videogallery:status --probe te da una imagen rápida; occ videogallery:cleanup (o --all) limpia los archivos temporales.
• Compartir: comparte un vídeo o una carpeta con una persona, un grupo o un enlace, con o sin descarga, mediante el propio uso compartido de Nextcloud. Los enlaces para reproductores externos llevan un token firmado y con caducidad, y no se guarda nada para ellos.

Conclusión

La mayoría de los avisos de «el reproductor de vídeo de Nextcloud no funciona» se reducen a que se le pide al navegador decodificar algo que no puede. Galería de vídeo lo arregla por archivo —intacto, reempaquetado, solo audio o recodificado—, mide la conexión para intentar la reproducción intacta solo cuando el enlace puede con ella y construye una línea de tiempo a partir de las fechas reales de grabación con vistas previas al pasar el cursor. Instálala, ejecuta Measure this machine, apunta el directorio de trabajo a un disco rápido y deja que Cron haga el resto. El recorrido completo está en la guía de usuario; el changelog registra lo que cambia y, si algo sigue fallando, la base de conocimiento y las preguntas frecuentes son el siguiente paso.