Miguel
/
Obsidean_VM
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Obsidean_VM/01-Documentation/Synology/DS220+/Jellyfin en Synology DS220+.md

39 KiB
Raw Blame History

Guía Completa para Configurar la Transcodificación por Hardware (QSV) de Jellyfin en Synology DS220+ con Docker

I. Introducción

Propósito: Este informe aborda el objetivo de habilitar la transcodificación por hardware Intel QuickSync Video (QSV) para el servidor multimedia Jellyfin versión 10.10.7, ejecutándose dentro de un contenedor Docker en un NAS Synology DS220+. El propósito es proporcionar una guía exhaustiva de configuración y solución de problemas para superar los desafíos comunes asociados con esta tarea.

Contexto: El Synology DS220+, equipado con un procesador Intel Celeron J4025, posee la capacidad inherente de realizar transcodificación acelerada por hardware mediante QSV. Sin embargo, habilitar esta funcionalidad para una aplicación como Jellyfin dentro del entorno aislado de Docker en Synology DiskStation Manager (DSM) requiere una serie de pasos de configuración específicos. Estos pasos involucran el acceso a dispositivos de hardware, la gestión de permisos y la configuración precisa del software, lo que frecuentemente presenta dificultades para los usuarios.

Estructura del Informe: Este documento se estructura para guiar al usuario a través del proceso completo:

  1. Análisis de las capacidades del hardware (CPU J4025 y QSV).
  2. Prerrequisitos necesarios en Synology DSM para permitir el acceso al hardware desde Docker.
  3. Configuración detallada del contenedor Docker de Jellyfin.
  4. Ajustes específicos dentro de la interfaz de Jellyfin (v10.10.7).
  5. Métodos de verificación y una guía de solución de problemas comunes, incluyendo el análisis de registros.

II. Capacidades del Intel Celeron J4025 y QuickSync (Abordando Punto 1 de la Consulta)

Visión General del Procesador:

El Synology DS220+ integra el procesador Intel Celeron J4025. Este chip pertenece a la familia Gemini Lake Refresh y se caracteriza por su bajo consumo energético (TDP de 10 W), lo que lo hace adecuado para dispositivos NAS. Cuenta con 2 núcleos y 2 hilos de procesamiento, operando a una frecuencia base de 2.00 GHz y alcanzando hasta 2.90 GHz en modo ráfaga. Si bien es eficiente energéticamente, su rendimiento general de CPU es modesto, situándose en la gama de entrada, adecuado para tareas básicas pero limitado para multitarea intensiva o cargas de trabajo pesadas.

Gráficos Integrados (iGPU):

El J4025 incluye una unidad de procesamiento gráfico (GPU) integrada, la Intel UHD Graphics 600. Esta iGPU cuenta con 12 Unidades de Ejecución (EUs) y opera a frecuencias entre 250 MHz y 700 MHz. Es capaz de manejar salida de video 4K a 60Hz a través de DisplayPort.

Confirmación de Soporte QuickSync:

Es fundamental confirmar que el procesador Celeron J4025 y su iGPU UHD Graphics 600 sí soportan la tecnología Intel Quick Sync Video (QSV). QSV es la tecnología clave de Intel que permite la aceleración por hardware para la codificación y decodificación de video, descargando estas tareas de los núcleos principales de la CPU y utilizando los circuitos especializados de la iGPU.

Soporte de Códecs Acelerados por Hardware:

La iGPU UHD Graphics 600 (Gemini Lake Refresh) ofrece aceleración por hardware para varios códecs de video populares. Basándose en las especificaciones y las configuraciones recomendadas para Jellyfin en hardware similar, las capacidades son las siguientes:

  • Decodificación por Hardware:
    • H.264 (AVC): Soportado (Estándar universalmente soportado por QSV).
    • H.265 (HEVC): Soportado, incluyendo perfiles de 8 bits y 10 bits.1
    • VP9: Soportado, incluyendo perfiles de 8 bits y 10 bits.1
    • MPEG2: Soportado (Común en QSV de esta generación, presente en ajustes de Jellyfin).1
    • VC1: Soportado (Común en QSV de esta generación, presente en ajustes de Jellyfin).1
    • AV1: No soportado por hardware. La decodificación de AV1 se realizará por software, utilizando los núcleos de la CPU.
  • Codificación por Hardware:
    • H.264 (AVC): Soportado (Característica estándar de QSV, referenciada como "H.264 Output" en la consulta inicial).
    • H.265 (HEVC): Soportado (Característica estándar de QSV para esta generación, opción configurable en Jellyfin).1

La siguiente tabla resume estas capacidades:

Tabla 1: Capacidades de Códecs QSV del Celeron J4025 / UHD 600
Códec Decodificación HW Codificación HW Notas
H.264 (AVC) Sí Sí Ampliamente compatible.
H.265 (HEVC) Sí (8/10-bit) Sí Esencial para contenido 4K moderno.
VP9 Sí (8/10-bit) No Común Usado por YouTube; decodificación importante.
MPEG2 Sí No Común Para contenido más antiguo (DVDs).
VC1 Sí No Común Para contenido más antiguo (Blu-ray).
AV1 No No Decodificación solo por software; alto uso de CPU esperado.

Consideraciones de Rendimiento:

Aunque QSV descarga significativamente la CPU durante la transcodificación, es crucial entender que el Celeron J4025 sigue siendo un procesador de bajo rendimiento. Además, algunas implementaciones de QSV en SoCs (System-on-a-Chip) como el J4025 pueden tener un rendimiento inferior en comparación con las versiones de escritorio o portátiles. Esto implica que, si bien QSV funcionará, el número de transcodificaciones simultáneas (especialmente de contenido 4K de alta tasa de bits) o el uso de funciones intensivas como el mapeo de tonos (tone mapping) HDR a SDR o la incrustación de subtítulos gráficos, podría estar limitado por la potencia general del hardware. La presencia de QSV es una condición necesaria, pero no suficiente, para un rendimiento ilimitado en hardware de gama baja.

Una limitación importante es la falta de decodificación por hardware para el códec AV1. Cualquier archivo multimedia en formato AV1 requerirá decodificación por software, lo que ejercerá una carga muy pesada sobre los limitados núcleos de la CPU del J4025, anulando los beneficios de QSV para ese contenido específico. Esto es relevante para usuarios con bibliotecas que incluyan material en AV1.

III. Prerrequisitos de Synology DSM para Aceleración por Hardware (Abordando Punto 2 de la Consulta)

Antes de configurar el contenedor Docker, es esencial asegurarse de que el sistema operativo Synology DSM esté preparado para permitir el acceso a los dispositivos de hardware necesarios.

Verificar la Existencia de Dispositivos /dev/dri:

El kernel de Linux expone los dispositivos de hardware gráfico a través del subsistema Direct Rendering Manager (DRM) en el directorio /dev/dri. Para la aceleración por hardware de Intel (QSV/VAAPI), los dispositivos clave son típicamente card0 y renderD128. Es necesario verificar su existencia en el sistema Synology mediante SSH:

Bash

ls -l /dev/dri

Se espera ver listados como card0 y renderD128. Si estos archivos no existen, podría indicar un problema subyacente con los módulos del kernel de DSM o la detección del hardware, aunque esto es poco probable en un DS220+ con DSM estándar. La ausencia de estos archivos impediría cualquier forma de aceleración por hardware.

Comprobar y Establecer Permisos para Dispositivos /dev/dri:

Un punto de fallo extremadamente común al configurar la aceleración por hardware en Docker sobre Synology son los permisos de acceso a los dispositivos en /dev/dri. El proceso de Jellyfin, ejecutándose dentro del contenedor Docker, necesita permisos para leer y escribir en estos dispositivos.

Primero, se deben verificar los permisos actuales:

Bash

ls -l /dev/dri

Se debe anotar el propietario (usualmente root) y, más importante, el grupo propietario. Este grupo puede variar según la versión de DSM; podría ser root, video, render, o un grupo específico de Synology como videodriver.

Existen dos métodos principales para otorgar acceso al contenedor:

  • Método 1 (Solución Alternativa - Menos Segura): Uso de chmod

    Este método implica cambiar directamente los permisos de los archivos del dispositivo para hacerlos accesibles a todos los usuarios o a un grupo más amplio.2 Comandos comunes ejecutados vía SSH como root son:

    Bash

    sudo chmod 666 /dev/dri/renderD128
# O, de forma más amplia pero menos específica:
# sudo chmod 777 /dev/dri/*

    El comando chmod 666 otorga permisos de lectura y escritura a todos (propietario, grupo, otros), mientras que chmod 777 también otorga permisos de ejecución. Aunque es más fácil de implementar, esta aproximación es menos segura ya que concede acceso potencialmente innecesario.2 Además, los permisos del sistema de archivos /dev suelen restablecerse al reiniciar el NAS. Por lo tanto, este comando chmod a menudo necesita ser ejecutado automáticamente en cada arranque mediante una Tarea Programada en el Panel de Control de DSM (ejecutada como root en el evento "Arranque").3

  • Método 2 (Recomendado - Más Seguro): Uso de Pertenencia a Grupo

    Este enfoque consiste en identificar el grupo que ya posee los permisos necesarios sobre los dispositivos /dev/dri (el grupo anotado con ls -l) y añadir el usuario que ejecuta el contenedor Docker a ese grupo específico. Primero, se necesita el ID numérico del grupo (GID). Si el grupo es, por ejemplo, render, se obtiene su GID con:

    Bash

    getent group render | cut -d: -f3

    Reemplace render con el nombre del grupo correcto identificado en su sistema (video, videodriver, etc.). Este GID se utilizará posteriormente en la configuración de Docker Compose (group_add).3 Este método es más seguro porque concede acceso solo a los miembros del grupo apropiado. La dificultad radica en identificar correctamente el grupo relevante en la versión específica de DSM, ya que podría diferir de las configuraciones estándar de Linux.

La recurrencia de problemas de permisos en discusiones y guías 2 y la existencia de estos dos métodos (uno fácil pero inseguro, otro seguro pero que requiere identificar el grupo correcto) subrayan un desafío central en esta configuración. Es preferible utilizar el método de pertenencia a grupo por seguridad.

Identificar IDs de Usuario/Grupo Correctos (PUID/PGID):

Por razones de seguridad, se recomienda encarecidamente no ejecutar contenedores Docker como usuario root. En su lugar, se debe utilizar un usuario sin privilegios o el usuario administrador principal. Es necesario obtener el ID de Usuario (UID) y el ID de Grupo primario (GID) de la cuenta de usuario bajo la cual se ejecutará el proceso de Jellyfin dentro del contenedor. Esto se hace vía SSH con el comando id <nombre_de_usuario> (reemplace <nombre_de_usuario> con el nombre de usuario deseado). Guías como las de MariusHosting o Dr Frankenstein 1 a menudo proporcionan instrucciones detalladas o enlaces para obtener estos valores. Estos PUID y PGID son cruciales para las variables de entorno en la configuración de Docker Compose.1

Estado de Paquetes DSM Relevantes:

Finalmente, asegurarse de que el paquete Docker (o su nombre más reciente, Container Manager) esté instalado y en ejecución desde el Centro de Paquetes de Synology.

IV. Configuración de Jellyfin en Docker para Acceso QSV (Abordando Puntos 3 y 7 de la Consulta)

Enfoque Recomendado: Docker Compose / Pilas de Portainer:

La interfaz gráfica estándar de Docker/Container Manager en Synology DSM a menudo carece de las opciones avanzadas necesarias para pasar dispositivos de hardware (/dev/dri) o añadir grupos suplementarios (group_add) al contenedor. Por ello, el método más fiable y recomendado es definir la configuración del contenedor utilizando Docker Compose. Esto se puede hacer:

  1. Creando un archivo docker-compose.yml directamente en el NAS (por ejemplo, usando el paquete Text Editor o vía SSH) y ejecutándolo con docker-compose desde SSH.
  2. Utilizando la funcionalidad de "Pilas" (Stacks) en Portainer, si Portainer está instalado, que permite pegar directamente el código de Docker Compose.
  3. Utilizando la funcionalidad de "Proyecto" basada en Compose dentro de la aplicación Container Manager más reciente de Synology, que también permite pegar código Compose.

Desglose Detallado de Docker Compose:

A continuación se presenta una estructura recomendada para el archivo docker-compose.yml, integrando las mejores prácticas observadas:

YAML

version: '3.8' # O una versión compatible

services:
  jellyfin:
    image: jellyfin/jellyfin:10.10.7 # Usar la versión específica del usuario o 'latest'
    container_name: jellyfin-qsv # Nombre descriptivo
    network_mode: host # Opción más simple para acceso a dispositivos/descubrimiento, considerar red bridge personalizada para mayor control/seguridad
    volumes:
      - /volume1/docker/jellyfin/config:/config # Ruta al directorio de configuración en el NAS
      - /volume1/docker/jellyfin/cache:/cache   # Ruta al directorio de caché en el NAS
      # - /volume1/docker/jellyfin/logs:/logs    # Opcional: Mapeo explícito de logs (a menudo van a /config/logs por defecto)
      - /volume1/video:/media/videos:rw         # Mapeo de biblioteca de películas (ajustar rutas y permisos :rw o :ro)
      - /volume1/music:/media/musica:rw         # Mapeo de biblioteca de música (ajustar rutas)
    environment:
      - PUID=1026 # REEMPLAZAR con el UID real del usuario
      - PGID=100  # REEMPLAZAR con el GID real del usuario
      - TZ=Europe/Madrid # REEMPLAZAR con la zona horaria correcta
      # - JELLYFIN_PublishedServerUrl=http://su_dominio:8096 # Opcional: Para acceso externo
    devices:
      # Método recomendado: Mapear explícitamente ambos dispositivos
      - /dev/dri/renderD128:/dev/dri/renderD128
      - /dev/dri/card0:/dev/dri/card0
      # Alternativa (más simple, menos específica):
      # - /dev/dri:/dev/dri
    group_add:
      # Añadir SÓLO si se usa el Método 2 de permisos (Pertenencia a Grupo)
      - "105" # REEMPLAZAR con el GID del grupo propietario de /dev/dri (e.g., render, video, videodriver)
    security_opt:
      - no-new-privileges:true # Recomendado para seguridad [1]
    restart: unless-stopped # Política de reinicio

Explicación de Secciones Clave:

  • image: Se recomienda usar la imagen oficial jellyfin/jellyfin, especificando la versión 10.10.7 o usando latest. Aunque linuxserver/jellyfin fue usado en el pasado para workarounds de drivers, ahora se considera obsoleto para este propósito.
  • network_mode: host 4 simplifica el acceso a dispositivos y el descubrimiento automático (DLNA/App), pero vincula directamente los puertos del contenedor a los del host. Una red bridge personalizada (como synobridge) ofrece mejor aislamiento si se configuran los mapeos de puertos necesarios (e.g., ports: - 8096:8096). Para empezar, host puede ser más fácil.
  • volumes: Es crucial mapear directorios persistentes para la configuración (/config), caché (/cache), y las bibliotecas multimedia.1 Las rutas internas del contenedor (e.g., /media/videos) deben coincidir con las configuradas en las bibliotecas de Jellyfin.
  • environment: Establecer PUID, PGID y TZ es fundamental.1 El uso de PUID/PGID 0 (root) se observa como un intento de solucionar problemas de permisos, pero no se recomienda por seguridad. Es preferible configurar correctamente los permisos de grupo o chmod.
  • devices: Esta es la sección crítica para QSV.1 Se comparan los intentos del usuario:
    • /dev/dri/renderD128:/dev/dri/renderD128: Mapea el nodo de renderizado principal. Es esencial, pero podría ser insuficiente si card0 también es necesario para la inicialización.1
    • /dev/dri/:/dev/dri/: Mapea todo el directorio. Debería funcionar 2, pero es menos específico. Si esto falló para el usuario, el problema probablemente radica en los permisos o la configuración de Jellyfin.
    • Recomendación: Mapear explícitamente tanto renderD128 como card0 1 es el enfoque más robusto y recomendado para empezar, asegurando que todos los componentes necesarios estén disponibles.
  • group_add: Usar solo si se aplica el método de permisos por grupo (Método 2, Sección III). Se debe añadir el GID numérico del grupo que posee los dispositivos /dev/dri.3
  • security_opt: no-new-privileges:true es una buena práctica de seguridad.1
  • restart: Define cómo debe reiniciarse el contenedor en caso de fallo o reinicio del NAS.4

La variabilidad en las recomendaciones de mapeo de dispositivos (renderD128 solo, ambos, o /dev/dri:/dev/dri) en diferentes fuentes 1 sugiere que diferentes configuraciones pueden funcionar, posiblemente dependiendo de la versión de DSM/kernel/drivers. Sin embargo, mapear ambos dispositivos específicos (renderD128 y card0) parece ser la opción más completa y menos propensa a fallos por falta de un componente.

Tabla 2: Configuración Docker Compose Recomendada para Jellyfin QSV en DS220+
Parámetro Valor/Sintaxis Recomendada Explicación/Notas
image jellyfin/jellyfin:10.10.7 Usar imagen oficial, versión específica del usuario.
container_name jellyfin-qsv Nombre claro para identificación.
network_mode host (o bridge personalizado) host es más simple para empezar; bridge requiere mapeo de puertos.
volumes - /ruta/host/config:/config
- /ruta/host/cache:/cache
- /ruta/media:/media/ruta_interna		 Mapear configuración, caché y bibliotecas. Ajustar rutas del host.
environment PUID=<UID>
PGID=<GID>
TZ=<ZonaHoraria>		 Esencial: Usar UID/GID no-root correctos y zona horaria. No usar PUID/PGID 0.
devices - /dev/dri/renderD128:/dev/dri/renderD128
- /dev/dri/card0:/dev/dri/card0		 Crítico: Mapear ambos dispositivos explícitamente para QSV.
group_add - "<GID_dri>" (Opcional) Usar solo si se aplica el método de permisos por grupo. Reemplazar <GID_dri> por el GID correcto.
security_opt - no-new-privileges:true Mejora la seguridad del contenedor.
restart unless-stopped Reiniciar el contenedor automáticamente a menos que se detenga manualmente.

Una vez creado el archivo docker-compose.yml (por ejemplo, en /volume1/docker/jellyfin/docker-compose.yml), se puede iniciar el contenedor desde SSH navegando a ese directorio y ejecutando:

Bash

sudo docker-compose up -d

V. Ajustes de Reproducción de Jellyfin para Transcodificación QSV (v10.10.7) (Abordando Punto 4 de la Consulta)

Después de iniciar el contenedor Docker con la configuración correcta, es necesario ajustar las opciones de transcodificación dentro de la interfaz web de Jellyfin.

Navegación: Acceder a la interfaz web de Jellyfin, ir a Administración -> Panel de Control -> Reproducción (en la barra lateral izquierda) -> pestaña Transcodificación.

Selección de Aceleración por Hardware:

  • En el desplegable "Aceleración por hardware", seleccionar Intel QuickSync (QSV).1
  • El campo "Dispositivo QSV" que aparece debe dejarse en blanco en la mayoría de los casos. Jellyfin/FFmpeg generalmente detecta automáticamente el dispositivo correcto (/dev/dri/renderD128) si se ha pasado correctamente al contenedor.
  • Nota sobre VAAPI: Video Acceleration API (VAAPI) es otra API para aceleración por hardware en Linux que también utiliza la iGPU de Intel. Aunque QSV suele ser preferible cuando funciona correctamente (puede ofrecer más funciones o mejor rendimiento), VAAPI puede seleccionarse como alternativa si QSV presenta problemas persistentes.

Opciones de Decodificación por Hardware:

  • Marcar las casillas correspondientes a los códecs que la UHD 600 puede decodificar por hardware (consultar Tabla 1): H.264, HEVC, HEVC 10bit, VP9, VP9 10bit, MPEG2, VC1.1
  • Importante: No marcar la casilla de AV1, ya que no tiene soporte de decodificación por hardware en este procesador.
  • Aunque las guías sugieren marcar muchas casillas 1, hay que tener en cuenta que algunos códecs, incluso si teóricamente soportados, podrían causar inestabilidad en ciertas combinaciones de hardware/driver (por ejemplo, formatos más antiguos como MPEG2/VC1 o los exigentes formatos de 10 bits). Se recomienda empezar con la lista completa (excepto AV1) pero estar preparado para desmarcar códecs específicos (especialmente MPEG2, VC1, HEVC 10bit, VP9 10bit) si se encuentran problemas durante la solución de errores.

Opciones de Codificación por Hardware:

  • Marcar Habilitar codificación por hardware.4
  • Marcar Permitir codificación en formato HEVC si se desea. Esto permite a Jellyfin transcodificar hacia HEVC, lo que puede ahorrar ancho de banda en comparación con H.264, pero podría ser más lento o menos compatible con dispositivos cliente antiguos.1 Se recomienda habilitarlo.

Configuración de Mapeo de Tonos (Tone Mapping HDR->SDR):

Esta función es necesaria para visualizar correctamente contenido HDR en pantallas SDR, pero es intensiva en recursos.

  • Habilitar mapeo de tonos VPP: Recomendado: Marcado. Utiliza las capacidades de Video Post Processing (VPP) de la iGPU para realizar el mapeo de tonos por hardware.1
  • Habilitar mapeo de tonos: Recomendado: Desmarcado. Esta opción a menudo se refiere a métodos alternativos como el mapeo de tonos basado en OpenCL, que requiere configuración adicional (instalar drivers/mods específicos en el contenedor) y puede tener un rendimiento pobre o fallar en la UHD 600.1
  • Existe cierta confusión en las fuentes sobre estas dos opciones. Mientras que S14 y 1 recomiendan VPP=Marcado y Tone Mapping=Desmarcado para Gemini Lake, S15 reportó éxito con ambas marcadas. Dado el limitado rendimiento del J4025, confiar únicamente en VPP (si funciona) es la apuesta más segura. Se recomienda empezar con VPP Marcado y Tone Mapping Desmarcado.

Otros Ajustes:

  • Preferir decodificadores por hardware nativos del SO (DXVA o VA-API): Recomendado: Marcado. Aunque se selecciona QSV, marcar esta opción puede ayudar a FFmpeg a inicializar correctamente el backend VAAPI que QSV utiliza en Linux.4
  • Habilitar codificador por hardware H.264 de bajo consumo Intel / Habilitar codificador por hardware HEVC de bajo consumo Intel: Recomendado: Desmarcado.5 Estos codificadores suelen ser para implementaciones QSV diferentes (e.g., en procesadores Atom) y pueden causar fallos o bajo rendimiento en Gemini Lake. Deshabilitarlos es también un paso de troubleshooting sugerido.
  • Permitir extracción de subtítulos sobre la marcha: Recomendado: Marcado.

Tabla 3: Ajustes de Transcodificación Recomendados en Jellyfin para J4025 QSV (v10.10.7)
Categoría Ajuste Valor Recomendado Razón/Notas
Aceleración Aceleración por hardware Intel QuickSync (QSV) Selecciona la tecnología QSV de Intel.
Dispositivo QSV (Dejar en blanco) Generalmente detectado automáticamente si los dispositivos Docker están bien mapeados.
Decodificación HW H.264, HEVC, HEVC 10bit, VP9, VP9 10bit, MPEG2, VC1 Marcado Habilitar decodificación HW para códecs soportados por UHD 600.
AV1 Desmarcado Crítico: AV1 no tiene soporte HW en J4025.
Codificación HW Habilitar codificación por hardware Marcado Permite usar QSV para la salida de transcodificación.
Permitir codificación en formato HEVC Marcado Permite transcodificar a HEVC (ahorro de ancho de banda).
Mapeo de Tonos Habilitar mapeo de tonos VPP Marcado Usa el post-procesamiento por hardware para mapeo de tonos HDR->SDR.
Habilitar mapeo de tonos Desmarcado Evita métodos alternativos (OpenCL) que pueden fallar o requerir setup extra en Gemini Lake.
Otros Preferir decodificadores por hardware nativos del SO (DXVA/VAAPI) Marcado Ayuda a la inicialización de VAAPI/QSV en Linux.
Codificadores H.264/HEVC de bajo consumo Intel Desmarcado No aplicables o pueden causar problemas en Gemini Lake.
Permitir extracción de subtítulos sobre la marcha Marcado Necesario para algunos tipos de subtítulos.

Tras realizar estos cambios, es fundamental hacer clic en el botón Guardar al final de la página de configuración de transcodificación.

VI. Guía de Verificación y Solución de Problemas (Abordando Puntos 5, 6 y 8 de la Consulta)

Una vez configurados Docker y Jellyfin, es necesario verificar que la transcodificación por hardware está funcionando y saber cómo solucionar problemas si no es así.

Confirmación de QSV Activo:

  1. Panel de Control de Jellyfin: Durante la reproducción de un archivo que requiera transcodificación (por ejemplo, forzando una calidad inferior en el cliente), ir al Panel de Control -> Flujos Activos. Buscar indicadores (HW) junto a los pasos de decodificación y/o codificación del flujo de video. La presencia de (HW) confirma que se está usando aceleración por hardware.
  2. Información de Reproducción del Cliente: La mayoría de los clientes de Jellyfin (web, móvil, TV) tienen una opción durante la reproducción (a menudo un icono de engranaje o similar) para ver "Información de Reproducción" o "Estadísticas para Nerds". Esta pantalla suele indicar si la reproducción es Directa (Direct Play), Remux (Direct Stream) o Transcodificación, y a menudo muestra la razón de la transcodificación.
  3. Monitor de Recursos de Synology: Observar el uso de la CPU en el Monitor de Recursos de DSM mientras se realiza una transcodificación. Con QSV activo, el uso de la CPU debería ser notablemente más bajo que sin aceleración por hardware (transcodificación por software). Un uso de CPU cercano al 100% indica que QSV probablemente no está funcionando correctamente. Sin embargo, cierto uso de CPU es normal, ya que QSV no acelera todas las partes del proceso (e.g., transcodificación de audio, demux/mux).

Análisis de Registros (Logs):

Los registros son herramientas indispensables para diagnosticar problemas.

  • Ubicación de los Registros:

    • Registros del Servidor Jellyfin: Se pueden ver directamente desde la interfaz web: Panel de Control -> Registros. Alternativamente, se puede acceder a los archivos de registro en el volumen mapeado en Docker (e.g., /volume1/docker/jellyfin/config/logs o la ruta mapeada explícitamente) usando File Station o SSH. El archivo principal suele ser log_YYYYMMDD.log.
    • Registros de Transcodificación FFmpeg: Son cruciales para problemas de reproducción. Se encuentran en el mismo directorio de registros de Jellyfin, con nombres como ffmpeg-transcode-<identificador_único>.log. Se genera un archivo por cada intento de transcodificación.
    • Acceso Dentro del Contenedor: Para inspeccionar registros u otros archivos dentro del contenedor en ejecución, se puede usar el comando docker exec desde SSH en el NAS: sudo docker exec -it jellyfin-qsv /bin/bash (reemplace jellyfin-qsv por el nombre real del contenedor). Una vez dentro, navegar a /config/logs.

  • Habilitación de Registro de Depuración (Debug Logging): Para obtener información más detallada, se puede habilitar el modo de depuración. Esto requiere crear (o editar si ya existe) un archivo llamado logging.json en el directorio de configuración de Jellyfin (/config dentro del contenedor). El contenido para habilitar la depuración es:

    JSON

    {
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    }
  }
}

    Advertencia: El modo de depuración genera una cantidad masiva de registros y solo debe usarse temporalmente para solucionar problemas. Recordar eliminar o revertir el archivo logging.json después. Puede ser necesario reiniciar el contenedor Jellyfin para que los cambios surtan efecto.

  • Interpretación de los Registros:

    • Buscar mensajes relacionados con la inicialización del contexto de hardware (VAAPI/QSV). Mensajes como Initializing VAAPI device, Trying to use QSV, Hardware acceleration enabled son indicativos de progreso.
    • Prestar atención a mensajes de error explícitos como Device creation failed, Cannot allocate memory, Failed to query an output frame, Error initializing output stream, No such file or directory.
    • Revisar los argumentos de la línea de comandos de FFmpeg que Jellyfin registra justo antes de iniciar una transcodificación. Esto revela los códecs de entrada/salida, filtros aplicados (escalado, mapeo de tonos, subtítulos) y las flags de aceleración por hardware (-hwaccel qsv, -vf scale_qsv, -c:v h264_qsv).
    • Identificar Códigos de Salida de FFmpeg: Buscar líneas como FFmpeg exited with code X. El code 1 es un error genérico y requiere examinar los mensajes previos. Otros códigos (e.g., 137, 218, 251) pueden ser más específicos pero a menudo están mal documentados. Ver Tabla 4.

Problemas Comunes y Soluciones:

A continuación se resumen los problemas más frecuentes encontrados al configurar QSV en Jellyfin/Docker/Synology y sus posibles soluciones:

  • Problema: La reproducción falla inmediatamente con "Fatal Player Error". El log de FFmpeg muestra Device creation failed, Cannot open /dev/dri/renderD128, o errores de permisos.

    • Causa Probable: Mapeo incorrecto de dispositivos en Docker Compose (devices:) O permisos insuficientes en los archivos /dev/dri/ en el host Synology.
    • Solución:
      1. Verificar la sección devices: en docker-compose.yml (usar el mapeo recomendado de renderD128 y card0).
      2. Verificar y corregir permisos en /dev/dri/ en el host (preferiblemente usando pertenencia a grupo con group_add en Docker Compose; o como alternativa, usar chmod con una tarea programada).
      3. Asegurarse de usar PUID/PGID correctos (no root).
      4. Reiniciar el contenedor Jellyfin (docker-compose down && docker-compose up -d).

  • Problema: La transcodificación comienza pero falla a mitad de la reproducción. El log de FFmpeg muestra Cannot allocate memory, Can't allocate a surface.

    • Causa Probable: Problema con el driver QSV/i915, límite de memoria de la iGPU excedido (especialmente con 4K, 10-bit, o mapeo de tonos), bug en FFmpeg, o a veces relacionado con streams de diferente duración (video vs audio/subtítulos). Problemas de BIOS también se han reportado en algunos sistemas, aunque menos común en NAS.
    • Solución:
      1. Intentar deshabilitar el mapeo de tonos VPP en los ajustes de Jellyfin.
      2. Probar con contenido más simple (e.g., 1080p 8-bit SDR).
      3. Asegurarse de usar versiones estables de Jellyfin y de la imagen Docker.
      4. Buscar actualizaciones de DSM (que pueden incluir nuevos drivers/kernel).

  • Problema: La reproducción falla solo para códecs específicos (e.g., HEVC 10-bit, MPEG2, VC1).

    • Causa Probable: El códec específico podría no ser totalmente estable o compatible con la aceleración QSV en esta combinación hardware/driver, aunque la opción exista en Jellyfin.
    • Solución: Desmarcar el códec problemático en los ajustes de Decodificación por Hardware de Jellyfin. Esto forzará la decodificación por software para ese códec, permitiendo la reproducción (a costa de mayor uso de CPU).

  • Problema: La reproducción falla solo cuando se habilitan subtítulos, especialmente de tipo gráfico (PGS, VOBSUB). El log de FFmpeg puede mostrar errores relacionados con filtros overlay o subtitles, o salir con código 251.

    • Causa Probable: La aceleración por hardware a menudo tiene dificultades para "quemar" (incrustar permanentemente en el video) subtítulos basados en imágenes. El proceso de superposición falla en la pipeline de hardware.
    • Solución:
      1. Configurar el cliente para que nunca queme subtítulos ("Burn-in: None") si es posible (el cliente renderizará los subtítulos).
      2. Usar subtítulos basados en texto (SRT, ASS) siempre que sea posible.
      3. Si es imprescindible quemar subtítulos gráficos, puede ser necesario desactivar la aceleración por hardware para ese contenido (forzando el quemado por CPU) o aceptar que no se podrá reproducir con esos subtítulos y QSV activo.

  • Problema: La transcodificación funciona (indicador HW aparece), pero el uso de CPU sigue siendo alto.

    • Causa Probable: QSV podría estar manejando solo la decodificación o solo la codificación. La transcodificación de audio siempre usa CPU. El quemado de subtítulos podría estar haciéndose por CPU. El mapeo de tonos podría estar recurriendo a software. El proceso puede requerir filtros complejos no acelerados.
    • Solución: Revisar los detalles del flujo activo en el panel de control para ver qué partes están marcadas como (HW). Simplificar la reproducción (desactivar subtítulos, elegir pista de audio compatible). Verificar ajustes de mapeo de tonos. Aceptar que cierto nivel de uso de CPU es normal.

  • Problema: FFmpeg termina con el código de salida genérico 1.

    • Causa Probable: Muy variable: permisos, argumentos inválidos de FFmpeg generados por Jellyfin, archivo multimedia corrupto, combinación de filtros/características no soportada, agotamiento temporal de recursos.
    • Solución: Examinar detenidamente el log completo de FFmpeg antes del exit code 1 buscando mensajes de error más específicos. Habilitar el registro de depuración de Jellyfin. Probar con diferentes archivos multimedia. Simplificar ajustes de Jellyfin (desactivar mapeo de tonos, desmarcar códecs).

  • Problema: Errores relacionados con la inicialización de VAAPI, como vaapi=va:,vendor_id=0x8086,driver=iHD.

    • Causa Probable: Problema con la configuración del driver VAAPI dentro del contenedor o su interacción con el driver/kernel del host. Posiblemente versión incorrecta del driver o componentes faltantes.
    • Solución: Asegurar mapeo correcto de dispositivos y permisos. Verificar compatibilidad de la imagen del contenedor (usar jellyfin/jellyfin oficial). Comprobar versión de DSM / kernel. Evaluar si marcar/desmarcar Preferir decodificadores nativos... ayuda.

Tabla 4: Errores Comunes en Registros FFmpeg y Pasos de Solución
Error / Código Salida Causa Probable Acciones Sugeridas
Permission denied (al acceder a /dev/dri) Permisos incorrectos en host o contenedor sin grupo correcto. Verificar/corregir permisos en host (chmod o grupo). Verificar group_add en Compose. Verificar PUID/PGID.
Device creation failed / Cannot open /dev/dri/renderD128 Dispositivo no mapeado a Docker o permisos incorrectos. Verificar sección devices: en Compose. Verificar permisos en host.
Cannot allocate memory / Can't allocate a surface Límite de memoria iGPU, bug driver/FFmpeg, stream corrupto/incompatible. Deshabilitar mapeo de tonos. Probar contenido más simple (8-bit SDR). Actualizar Jellyfin/DSM.
Error relacionado con filtro overlay / subtitles (a menudo con subtítulos gráficos) Incapacidad de QSV para quemar subtítulos gráficos. Evitar quemado de subtítulos (configuración cliente). Usar subtítulos de texto (SRT). Desactivar HW accel si es necesario.
FFmpeg exited with code 1 Error genérico. Examinar mensajes previos en el log FFmpeg. Habilitar debug log. Probar otro archivo. Simplificar ajustes Jellyfin.
FFmpeg exited with code 137 Proceso terminado externamente (posiblemente por OOM Killer si la RAM se agota). Monitorizar uso de RAM del NAS y del contenedor. Asegurarse de que el directorio de caché/transcodificación tenga espacio y permisos.
FFmpeg exited with code 251 Reportado con quemado de subtítulos PGS en HEVC con QSV. Ver soluciones para problemas de subtítulos gráficos.

Evaluación de los Intentos de Mapeo de Dispositivos del Usuario (Abordando Punto 7 de la Consulta):

  • /dev/dri/renderD128:/dev/dri/renderD128: Mapea el nodo de renderizado principal, lo cual es esencial. Sin embargo, podría ser insuficiente. Algunas operaciones o inicializaciones de QSV/VAAPI pueden requerir acceso también a /dev/dri/card0. Si esta configuración falló, podría deberse a la falta de card0 o, más probablemente, a problemas de permisos.
  • /dev/dri/:/dev/dri/: Mapea el directorio completo. Esta opción debería funcionar en términos de disponibilidad de dispositivos, ya que incluye tanto renderD128 como card0. Si esta configuración también falló, la causa casi con seguridad reside en los permisos (permisos de archivo en el host o falta de pertenencia al grupo correcto por parte del usuario del contenedor) o en una configuración incorrecta dentro de Jellyfin, no en el mapeo de dispositivos en sí.

VII. Recomendaciones Finales y Lista de Verificación

Para lograr con éxito la transcodificación por hardware QSV en Jellyfin sobre Docker en un Synology DS220+, la atención al detalle en la configuración es primordial.

Resumen de Puntos Críticos:

  • Configuración Docker Compose: La sintaxis debe ser precisa, especialmente en las secciones devices (mapear renderD128 y card0), environment (PUID/PGID no-root correctos, TZ), y group_add (si se usa permisos por grupo).
  • Permisos del Host: Los permisos sobre /dev/dri/renderD128 y /dev/dri/card0 en el Synology DSM deben permitir el acceso al usuario/grupo bajo el cual corre el contenedor. El método de pertenencia a grupo es el más seguro y recomendado.
  • Ajustes de Jellyfin: La configuración dentro de Jellyfin debe coincidir con las capacidades del J4025 (seleccionar QSV, marcar códecs soportados - excluyendo AV1, configurar mapeo de tonos VPP correctamente).
  • Verificación y Logs: Confirmar que QSV está activo y utilizar los registros de FFmpeg para diagnosticar cualquier fallo.

Lista de Verificación Rápida:

Antes de buscar ayuda adicional, revisar los siguientes puntos:

  • ¿Existen /dev/dri/renderD128 y /dev/dri/card0 en el host Synology (ls -l /dev/dri)?
  • ¿Se han verificado/establecido los permisos en /dev/dri/* del host (preferiblemente mediante grupo)?
  • ¿Se usan los PUID/PGID correctos (no root) en Docker Compose?
  • ¿Se usa el GID correcto en group_add en Docker Compose (si se aplica)?
  • ¿La sección devices: en Docker Compose mapea correctamente /dev/dri/renderD128 y /dev/dri/card0?
  • ¿Está la Aceleración por Hardware en Jellyfin configurada como Intel QuickSync (QSV)?
  • ¿Los códecs de Decodificación HW en Jellyfin coinciden con las capacidades del J4025 (AV1 desmarcado)?
  • ¿Está el Mapeo de Tonos configurado correctamente (VPP marcado, Mapeo de Tonos base desmarcado)?
  • ¿Se ha reiniciado el contenedor Jellyfin después de los cambios?
  • ¿Se ha probado la transcodificación con contenido simple (e.g., 1080p H.264 SDR)?
  • ¿Aparece el indicador (HW) en el Panel de Control de Jellyfin durante la transcodificación?
  • ¿Se han revisado los registros de FFmpeg (ffmpeg-transcode-*.log) en busca de errores si la reproducción falla?

Recursos Adicionales:

  • Documentación Oficial de Jellyfin sobre Aceleración por Hardware: https://jellyfin.org/docs/general/administration/hardware-acceleration/ (Aunque general, contiene información útil sobre Intel QSV/VAAPI en Linux/Docker).
  • Foros de la Comunidad Jellyfin y Synology: Pueden contener discusiones específicas y soluciones aportadas por otros usuarios con configuraciones similares.

Siguiendo esta guía detallada y prestando atención a los permisos y configuraciones específicas, debería ser posible habilitar y disfrutar de los beneficios de la transcodificación por hardware QSV en el Synology DS220+.