Transcode Doctor para Jellyfin — guía

Instalación

Necesitas Jellyfin Server 12.2 o más nuevo y una cuenta de MediaLab Works con una licencia que cubra el plugin (una suscripción activa, una licencia de por vida dentro de su período de actualizaciones, el paquete Jellyfin o la prueba gratuita de 30 días).

Desde tu repositorio de plugins (recomendado). Jellyfin instala y actualiza el plugin por sí mismo.

1. En tu cuenta de MediaLab Works abre Licenses → Jellyfin plugin repository y haz clic en Create address. Cópiala: es privada (contiene un token), así que no la compartas; puedes regenerarla o revocarla en cualquier momento.
2. En Jellyfin abre Dashboard → Plugins → Repositories, haz clic en +, ponle un nombre (por ejemplo, MediaLab Works), pega la dirección y guarda.
3. En Dashboard → Plugins → Catalog busca Transcode Doctor by MediaLab, haz clic en Install y reinicia Jellyfin.

El repositorio solo enumera los plugins que tus licencias cubren, y solo las versiones que permiten. Sus enlaces de descarga están firmados y caducan a las pocas horas, así que Jellyfin siempre lee una lista fresca.

Desde el catálogo público. https://medialab.works/jellyfin/manifest.json enumera cada plugin de MediaLab Works publicado con su compilación pública; medialab Server lo añade por sí mismo. Puedes añadirlo del mismo modo para instalar un plugin antes de tener una clave: el plugin te pedirá entonces la licencia, o iniciará la prueba, en su página License. Con una licencia de por vida cuyo período de actualizaciones ha terminado, mantente en tu repositorio privado, que solo ofrece las versiones que tu licencia permite.

Manualmente, desde un archivo zip.

1. En Account → Licenses descarga jf-transcodedoctor_x.y.z.zip (el SHA-256 del archivo se muestra junto al botón).
2. Extráelo en una carpeta nueva Transcode Doctor by MediaLab_x.y.z.0 dentro de la carpeta de plugins de Jellyfin:
   • Linux (paquete): /var/lib/jellyfin/plugins/
   • Docker (imagen oficial): /config/plugins/ en el volumen de configuración
   • Windows: %ProgramData%\Jellyfin\Server\plugins\
3. Reinicia Jellyfin.

Activación de la licencia

1. Abre la página del plugin en Dashboard → Plugins → Transcode Doctor by MediaLab y haz clic en License.
2. Pega tu clave de licencia y haz clic en Activate with key. El plugin contacta con el servidor de licencias, vincula la clave a este servidor Jellyfin y muestra la licencia como Active.
3. ¿Todavía no tienes clave? En la misma página introduce tu correo e inicia la prueba gratuita de 30 días (se necesita tarjeta, nada que pagar hoy) o compra una licencia; el plugin se activa solo cuando el pago se realiza.

La licencia se comprueba una vez al día y en cada arranque de Jellyfin. Sin internet el plugin sigue funcionando durante 7 días tras la última comprobación exitosa. Sin una licencia válida, el plugin detiene su trabajo y solo su página License sigue funcionando (prueba, clave, renovación); no se elimina nada, y todo se reanuda en cuanto la licencia vuelve a ser válida. Move license (release this server) en la misma página libera la clave para otro servidor.

Actualizaciones y reversión

• Desde el repositorio: Jellyfin muestra las nuevas versiones en Dashboard → Plugins y puede actualizar el plugin automáticamente; reinicia Jellyfin para cargar la nueva versión.
• Desde la página License del plugin: con una licencia válida, Install update instala la versión más nueva que tu licencia permite y Roll back to x.y.z vuelve a la versión anterior (por ejemplo, si algo dejó de funcionar tras una actualización). Reinicia Jellyfin después de cualquiera de las dos. Ambos paquetes se verifican contra la suma de comprobación publicada por el servidor de licencias.
• Una licencia de por vida recibe las versiones publicadas durante su período de actualizaciones; después, el plugin sigue funcionando en la última versión que puede usar.
• Tras Roll back to x.y.z, la actualización automática de Jellyfin para ese plugin se desactiva hasta el próximo Install update en la página License, así la tarea programada Update Plugins (al arrancar y cada día) no trae de nuevo la versión más nueva.
• Licencia de por vida y actualizaciones automáticas. El catálogo público de Jellyfin (https://medialab.works/jellyfin/manifest.json) siempre ofrece la versión más nueva. Cuando el período de actualizaciones de una licencia de por vida ha terminado, las versiones publicadas después no están licenciadas: si las actualizaciones automáticas de plugins de Jellyfin instalan una, el plugin se detiene con «version not licensed» hasta que vuelves atrás con Roll back to x.y.z en su página License o compras un pase de actualizaciones. Para evitarlo, no dejes que Jellyfin actualice este plugin automáticamente: añade tu repositorio privado de plugins, que solo ofrece las versiones que tu licencia permite, en lugar del catálogo público, o elimina los disparadores de la tarea programada Update Plugins en Dashboard → Scheduled Tasks (esto detiene las actualizaciones automáticas de todos los plugins).

Código fuente

El código fuente GPL-3.0 de cada versión está en Account → Licenses (Source code), junto a la descarga, como archivo .tar.gz creado a partir del commit exacto de esa versión.

Configuración

Abre Transcode Doctor en el menú del panel de control de Jellyfin.

1. Diagnóstico de aceleración por hardware: haz clic en Run the tests. El plugin comprueba ffmpeg, la tarjeta NVIDIA y los dispositivos /dev/dri, crea unos clips de prueba cortos con ffmpeg en la carpeta de caché de Jellyfin, y luego prueba cada método (NVIDIA NVENC, Intel QuickSync, VA-API) decodificando H.264, HEVC, HEVC 10-bit, MPEG-2, VP9 y AV1 y codificando H.264 y HEVC. Cada prueba tarda como máximo un minuto; la tabla muestra qué funciona y a qué velocidad.
2. Problems: si algo bloquea la aceleración, la página dice qué es y cómo arreglarlo. Lo más común es Jellyfin sin acceso a /dev/dri/renderD128: ejecuta el comando mostrado (añade el usuario de Jellyfin al grupo render), reinicia Jellyfin y vuelve a ejecutar las pruebas. En Docker, pasa el dispositivo GPU al contenedor.
3. Recommendation: el método que superó más pruebas, los códecs de decodificación, la codificación por hardware y aproximadamente cuántas transcodificaciones 1080p pueden ejecutarse a la vez, junto a tus ajustes actuales.
4. Apply the settings escribe la recomendación en Dashboard → Playback → Transcoding: el método de aceleración, los códecs de decodificación por hardware, la decodificación HEVC 10-bit, la codificación por hardware y el dispositivo VA-API / QuickSync. La decodificación VC-1, VP8 y MPEG-4, que no puede probarse, se queda como la hayas establecido; la codificación HEVC se desactiva si falló y el plugin nunca la activa.
5. Restore the previous settings restaura los ajustes de transcodificación guardados justo antes de la última aplicación. Siempre puedes cambiarlos también a mano en Jellyfin.

Uso diario

• Why it transcodes enumera las reproducciones transcodificadas recientes: cuándo, quién, qué, las razones en palabras sencillas con lo que se puede hacer, y si el trabajo lo hizo la GPU o la CPU. «CPU (GPU not used)» para una reproducción con la aceleración configurada significa que no se usó la tarjeta.
• Cuando una transcodificación de vídeo se ejecuta en la CPU aunque la aceleración esté configurada, el plugin escribe una entrada en el registro de actividad de Jellyfin.
• Vuelve a ejecutar las pruebas tras un cambio de controlador, de Jellyfin o de hardware.

Resolución de problemas

• «The diagnosis failed: ffmpeg not found»: instala jellyfin-ffmpeg y establece su ruta en Dashboard → Playback → Transcoding.
• «Every VA-API / QuickSync test fails»: revisa la lista de problemas; normalmente falta el usuario de Jellyfin en el grupo render o el dispositivo no se pasa al contenedor Docker.
• «Every NVENC test fails»: falta el controlador NVIDIA o nvidia-smi no responde.
• «No hardware method passed the tests»: la transcodificación se queda en la CPU; no se aplica nada.