Library Doctor para Jellyfin — guía

Instalación

Necesitas Jellyfin Server 12.2 o posterior 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 para Jellyfin o la prueba gratuita de 30 días).

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

En tu cuenta de MediaLab Works abre Licencias → Repositorio de plugins para Jellyfin y pulsa Crear URL del repositorio. Cópiala: es privada (contiene un token), así que no la compartas; puedes regenerarla o revocarla en cualquier momento.
En Jellyfin abre Panel de control → Complementos → Repositorios, pulsa +, dale un nombre (por ejemplo MediaLab Works), pega la dirección y guarda.
En Panel de control → Complementos → Catálogo busca Library Doctor by MediaLab, pulsa Instalar y reinicia Jellyfin.

El repositorio solo muestra los plugins que cubren tus licencias, 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 nueva.

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

Manualmente, desde un archivo zip.

En Cuenta → Licencias descarga jf-librarydoctor_x.y.z.zip (el SHA-256 del archivo se muestra junto al botón).
Extráelo en una carpeta nueva Library 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\
Reinicia Jellyfin.

Activación de la licencia

Abre la página del plugin en Panel de control → Complementos → Library Doctor by MediaLab y pulsa License.
Pega tu clave de licencia y pulsa Activate with key. El plugin contacta con el servidor de licencias, vincula la clave a este servidor de Jellyfin y muestra la licencia como Active.
¿Todavía no tienes clave? En la misma página introduce tu dirección de correo e inicia la prueba gratuita de 30 días (necesitas tarjeta, hoy no pagas nada) o compra una licencia; el plugin se activa solo cuando se completa el pago.

La licencia se comprueba una vez al día y en cada arranque de Jellyfin. Sin internet el plugin sigue funcionando 7 días después de la última comprobación correcta. Sin una licencia válida el plugin detiene su trabajo y solo sigue funcionando su página License (prueba, clave, renovación); no se borra 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 versiones nuevas en Panel de control → Complementos y puede actualizar el plugin automáticamente; reinicia Jellyfin para cargar la versión nueva.
Desde la página License del plugin: con una licencia válida, Install update instala la versión más reciente que permite tu licencia 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 comprueban con la suma de control 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 con 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 siguiente Install update en la página License, de modo que la tarea programada Update Plugins (en el arranque y cada día) no vuelva a traer la versión 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 reciente. Cuando el período de actualizaciones de una licencia de por vida ha terminado, las versiones publicadas después no tienen licencia: 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 permite tu licencia, en lugar del catálogo público, o quita los desencadenantes de la tarea programada Update Plugins en Panel de control → Tareas programadas (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 Cuenta → Licencias (Código fuente), junto a la descarga, como archivo .tar.gz creado a partir del commit exacto de esa versión.

Configuración

Abre Library Doctor en el menú del panel de Jellyfin (solo administradores). No hay nada que configurar: la página lee tus bibliotecas de películas y episodios cada vez que se abre.

Antes de usar la cuarentena, da a Jellyfin acceso de escritura a las carpetas de las bibliotecas. La cuarentena crea una carpeta .medialab-de-sters (en rumano, «para borrar») en la raíz de cada carpeta de biblioteca y saca los archivos de sus carpetas, así que el usuario con el que corre Jellyfin (en Linux, normalmente jellyfin) necesita permiso de escritura en las carpetas de biblioteca y en las carpetas que contienen. En Docker, monta los volúmenes de medios de lectura y escritura (sin :ro). Todo lo demás del plugin solo lee.

Uso diario

Los números de arriba: archivos de vídeo, grupos de duplicados, el espacio que puedes recuperar de los duplicados, las películas sin identificar y el tamaño total.
Duplicates: cada grupo muestra las versiones, la mejor primero y marcada como best (primero mayor resolución, después HDR, después un códec más eficiente — AV1, HEVC, VP9 — y después bitrate).
- Las películas se comparan por su id de TMDb o IMDb; los episodios, por serie, temporada y número de episodio.
- Las películas sin id de TMDb ni IMDb se comparan por título y año. Sus grupos se marcan como by title and year (no metadata id) — check: abre ambas y asegúrate de que realmente son la misma película antes de agruparlas o poner una en cuarentena (un remake puede tener el mismo título y, a veces, el mismo año).
- Group as versions conserva todos los archivos y los convierte en un solo título con elección de versión al reproducir (el agrupamiento de versiones propio de Jellyfin). No se mueve ningún archivo.
- Quarantine, sobre una versión inferior, pide confirmación y mueve ese archivo y sus acompañantes a la cuarentena (ver abajo).
Unmatched movies: películas sin id de metadatos. Pulsa Open y usa Identify en Jellyfin para elegir la película correcta; desaparece de la lista la próxima vez que abras la página.
Archivos que faltan, rotos o truncados: pulsa Check the files. La comprobación se ejecuta en segundo plano, archivo por archivo, y muestra su progreso; en una biblioteca grande tarda un rato y puedes salir de la página. Para cada archivo comprueba que existe, lo lee con ffprobe (como máximo 30 segundos) y después descodifica los últimos 3 segundos del vídeo con ffmpeg (como máximo 60 segundos). Cada problema se enumera con su causa:
- missing from disk (falta en el disco);
- cannot be read (no se puede leer), con el error;
- no video track (sin pista de vídeo): el único «vídeo» es una imagen (las carátulas no cuentan como vídeo), como en un archivo de bytes aleatorios;
- no duration (broken header) (sin duración: cabecera rota);
- zero duration (duración cero);
- the end is missing (incomplete download/copy) (falta el final: descarga o copia incompleta): los últimos segundos no se pueden descodificar. Un archivo cortado muy cerca de su final (por ejemplo, sobre el 98 %) puede pasar la comprobación, porque sus últimos segundos aún pueden contener fotogramas descodificables.
El resultado se conserva hasta que Jellyfin se reinicia.
Space: el espacio por biblioteca, por resolución y por códec, y los 20 archivos más grandes que ningún usuario ha visto.

La cuarentena

Qué se mueve: el archivo de vídeo y los archivos de la misma carpeta cuyo nombre empieza con el mismo nombre seguido de . o - — por ejemplo Movie (2010).mkv con Movie (2010).en.srt, Movie (2010).nfo y Movie (2010)-poster.jpg. Los demás archivos de la carpeta se quedan donde están.
Dónde: a .medialab-de-sters, en la raíz de la carpeta de biblioteca que contiene el archivo, conservando las mismas subcarpetas (/media/movies/Movie (2010)/Movie (2010).mkv pasa a /media/movies/.medialab-de-sters/Movie (2010)/Movie (2010).mkv). Si ya hay en cuarentena un archivo con el mismo nombre, el nuevo va a una subcarpeta con un nombre único, así que nada se sobrescribe.
Si una mudanza falla a mitad (por ejemplo, un archivo acompañante no se puede mover): los archivos ya movidos se devuelven a su sitio y se elimina la copia que un movimiento interrumpido entre discos haya podido dejar en .medialab-de-sters, así nunca acabas con el mismo archivo en dos sitios. Si los archivos tampoco se pueden devolver, la entrada se queda en la lista Quarantine y Restore trae de vuelta lo movido. La página muestra el error.
Tras el movimiento, Jellyfin reescanea la biblioteca y la versión en cuarentena desaparece de ella; Jellyfin no importa la carpeta .medialab-de-sters.
Restore: la lista Quarantine muestra cada título con sus rutas originales y su tamaño. Restore devuelve los archivos exactamente a donde estaban y reescanea la biblioteca. Si un archivo está a la vez en cuarentena y en su ruta original (por ejemplo, porque añadiste la película otra vez), la restauración se rechaza y no se toca nada.
El borrado definitivo es cosa tuya: el plugin nunca borra. Cuando estés seguro, elimina tú la carpeta .medialab-de-sters (o los archivos que contiene) del disco; solo entonces se libera el espacio.
La lista de archivos en cuarentena se guarda en la carpeta de datos del plugin, así que sobrevive a un reinicio de Jellyfin. No renombres ni muevas la carpeta .medialab-de-sters mientras algo de su interior pueda necesitar todavía una restauración.

Solución de problemas

Quarantine, Restore o Group as versions muestra «It could not be done»: el mensaje posterior da el motivo.
Quarantine falla: normalmente Jellyfin no tiene acceso de escritura a la carpeta de la biblioteca; ver Configuración. También se rechazan los archivos fuera de las carpetas de tus bibliotecas de Jellyfin y los archivos que ya están en .medialab-de-sters.
Restore falla: hay un archivo ya en la ruta original (por ejemplo, porque añadiste la película otra vez). Mueve o elimina ese archivo y restaura después.
Todos los archivos aparecen como «cannot be read»: no se encontró ffprobe; instala jellyfin-ffmpeg y comprueba su ruta en Panel de control → Reproducción → Transcodificación.
Un grupo marcado como «by title and year — check» contiene dos películas distintas: no agrupes ni pongas nada en cuarentena; identifica ambas películas en Jellyfin y, en cuanto tengan sus ids de TMDb o IMDb, dejan de agruparse.
Una película está dos veces en la biblioteca pero no aparece entre los duplicados: los dos elementos tienen ids distintos, o uno tiene id y el otro no (entonces identifícalo).
Un archivo que no se reproduce no aparece en el informe: el daño puede estar en mitad del archivo, que no se comprueba, o el archivo se cortó muy cerca de su final.