Toda biblioteca autoalojada acaba desviándose. Una película se añade dos veces porque dos archivos acabaron en carpetas distintas, algunos títulos nunca se emparejaron y se quedan ahí sin carátula, una copia se interrumpió a medias y nadie se dio cuenta, y el disco sigue llenándose. Jellyfin no tiene un informe único para todo esto, así que normalmente te enteras por casualidad. Library Doctor es un plugin de Jellyfin que reúne esos problemas en una sola página de administración, muestra cuánto espacio ocupa cada uno y te permite corregirlos sin borrar nunca un archivo.
Este tutorial recorre todo el flujo: encontrar jellyfin duplicate movies, gestionar los títulos sin identificar, comprobar la integridad de los archivos, leer el informe de espacio y usar la cuarentena como red de seguridad.
Requisitos
- Jellyfin Server 12.2 o superior (Linux, Windows o Docker).
- Una cuenta de MediaLab Works con una licencia que cubra el plugin (suscripción activa, licencia de por vida dentro de su ventana de actualizaciones, el pack de Jellyfin o la prueba gratuita de 30 días).
- ffprobe y ffmpeg para la comprobación de integridad: vienen con jellyfin-ffmpeg, y el plugin usa las mismas rutas que Jellyfin para el transcodificado.
- Permiso de escritura en las carpetas de la biblioteca para el usuario de Jellyfin, si quieres usar la cuarentena. En Linux suele ser el usuario
jellyfin; en Docker los volúmenes de medios no deben montarse en solo lectura (sin:ro). Sin permiso de escritura todos los informes siguen funcionando: solo la cuarentena no puede mover archivos.
El plugin es de código abierto (GPL-3.0), y el código fuente de cada versión está en tu cuenta.
Paso 1 — Instalar y activar
La vía recomendada es tu repositorio privado de plugins:
- En tu cuenta de MediaLab Works abre Licenses → Jellyfin plugin repository y haz clic en Create address. Cópiala: contiene un token, así que mantenla privada.
- En Jellyfin abre Dashboard → Plugins → Repositories, haz clic en +, ponle nombre (por ejemplo MediaLab Works), pega la dirección y guarda.
- En Dashboard → Plugins → Catalog busca Library Doctor by MediaLab, haz clic en Install y reinicia Jellyfin.
También hay un catálogo público en https://medialab.works/jellyfin/manifest.json, y una instalación manual por zip si lo prefieres. Tras reiniciar, abre la página del plugin en Dashboard → Plugins → Library Doctor by MediaLab, ve a License, pega tu clave y haz clic en Activate with key. ¿Aún no tienes clave? Inicia la prueba de 30 días desde la misma página.
Paso 2 — Abrir la página del panel
Library Doctor aparece en el menú del panel de Jellyfin y solo es visible para administradores. No hay nada que configurar: la página lee tus bibliotecas de películas y episodios cada vez que se abre.
Arriba tienes las cifras: archivos de vídeo, grupos de duplicados, el espacio que se puede recuperar de los duplicados, películas sin identificar y el tamaño total. Tómalo como tu foto del estado de la biblioteca antes de tocar nada.
Paso 3 — Revisar películas y episodios duplicados
Esta es la parte por la que viene la mayoría. Jellyfin ya agrupa varios archivos de la misma película como versiones cuando los reconoce, pero cuando la misma película está en dos carpetas distintas suele convertirse en dos elementos separados. Library Doctor encuentra esos grupos.
- Las películas se emparejan por su id de TMDb o IMDb.
- Los episodios se emparejan por serie, temporada y número de episodio.
- Las películas sin id de metadatos se emparejan por título y año, ignorando mayúsculas, acentos y puntuación. Esos grupos se marcan como by title and year (no metadata id) — check, porque dos películas distintas pueden compartir título y año. Abre ambas antes de actuar.
Cada grupo muestra las versiones lado a lado —resolución, HDR, códec, tasa de bits y tamaño— con la mejor primero y marcada como best (primero mayor resolución, luego HDR, luego un códec más eficiente como AV1, HEVC o VP9, y luego la tasa de bits). También ves el espacio que recuperarías quedándote solo con esa.
Tienes dos acciones, y ninguna borra nada:
- Group as versions conserva todos los archivos y los muestra como versiones de un mismo título, usando la agrupación de versiones propia de Jellyfin. No se mueve ningún archivo.
- Quarantine mueve a un lado una versión más débil (ver el Paso 6).
Paso 4 — Corregir películas sin identificar
La sección Unmatched movies lista las películas sin ningún id de metadatos. Suelen ser las que tienen título, año o carátula equivocados, y tienden a faltar en colecciones y recomendaciones.
Haz clic en Open en una entrada y usa Identify de Jellyfin en la película para elegir la coincidencia correcta. Desaparece de la lista la próxima vez que abras la página de Library Doctor.
Paso 5 — Ejecutar la comprobación de integridad y leer el informe de espacio
Haz clic en 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. Es solo bajo demanda: no hay escaneos programados.
Para cada archivo de película y episodio informa de los archivos que:
- faltan en el disco;
- no se pueden leer, con el error;
- no tienen una pista de vídeo real (por ejemplo, un archivo de bytes aleatorios en el que ffprobe adivina una imagen);
- no tienen duración (cabecera dañada) o tienen duración cero;
- están truncados: se decodifican los últimos 3 segundos, y un archivo cuyo final no se puede decodificar se marca como descarga o copia incompleta.
Ten en cuenta los límites: un archivo cortado muy cerca de su final todavía puede tener fotogramas decodificables en sus últimos segundos y pasar, no se busca daño en medio de un archivo, y un .ts truncado no se puede detectar porque no hay duración almacenada.
Más abajo, el informe de espacio te da el total y después el espacio por biblioteca, por resolución (4K, 1080p, 720p, SD) y por códec de vídeo, además de los 20 archivos más grandes que ningún usuario ha visto. Esa última lista suele ser la más útil cuando necesitas sitio para algo nuevo.
Paso 6 — Cuarentena en lugar de borrado
Cuando haces clic en Quarantine en una versión y confirmas, el plugin mueve el archivo de vídeo y los archivos que están junto a él y comparten su nombre —subtítulos, .nfo, imágenes como Movie.srt, Movie.en.srt, Movie.nfo, Movie-poster.jpg— a una carpeta llamada .medialab-de-sters en la raíz de la carpeta de biblioteca que los contiene, manteniendo sus subcarpetas. Como la carpeta está dentro de la misma carpeta de biblioteca, normalmente está en el mismo disco, así que el movimiento es instantáneo. Después Jellyfin vuelve a escanear la biblioteca.
El movimiento se registra antes de tocar ningún archivo. Si un archivo no se puede mover (por permisos, por ejemplo), los archivos ya movidos se devuelven a su sitio y no queda nada suelto; si tampoco es posible devolverlos, la entrada permanece en la lista de cuarentena para que puedas restaurarla. Se rechazan los archivos fuera de las carpetas de biblioteca y los que ya están en una carpeta .medialab-de-sters.
La lista Quarantine muestra cada título movido con su ubicación original y su tamaño. Restore devuelve los archivos exactamente a donde estaban y vuelve a escanear; se niega, sin tocar nada, si un archivo está a la vez en cuarentena y de vuelta en su ruta original. El plugin nunca sobrescribe ni borra un archivo: cuando estés seguro, borras tú mismo la carpeta .medialab-de-sters del disco.
Consejos y solución de problemas
- La cuarentena no hace nada. Comprueba que el usuario de Jellyfin puede escribir en las carpetas de biblioteca y que los volúmenes de Docker no están montados
:ro. Todos los informes funcionan sin permiso de escritura; solo falla el movimiento. - Un grupo de duplicados parece incorrecto. Si está marcado como by title and year, verifica ambas entradas antes de agrupar o poner en cuarentena: los remakes pueden compartir título y, a veces, año.
- La comprobación tarda mucho. Es normal en una biblioteca grande; se ejecuta en segundo plano y puedes salir de la página. Los resultados solo se guardan en memoria, así que no persisten entre reinicios.
- Privacidad. No hay contacto externo aparte del cliente de licencias, ni búsquedas de metadatos en línea: los duplicados y los títulos sin identificar se calculan a partir de los ids que tu servidor ya almacena. La comprobación de archivos ejecuta localmente el ffprobe del servidor. Tras mover o restaurar en la cuarentena, el plugin inicia el escaneo normal de la biblioteca, que puede contactar con los proveedores de metadatos configurados en tu servidor; eso es comportamiento del servidor, no del plugin.
Conclusión
La higiene de una biblioteca consiste sobre todo en ver los problemas antes de que crezcan. Library Doctor te da una página para las películas y episodios duplicados, los títulos sin identificar, los archivos que faltan o están dañados y dónde se va realmente el espacio, y lo arregla agrupando o moviendo archivos a una cuarentena que puedes restaurar, nunca borrando. Instálalo desde tu repositorio de plugins, ejecuta la comprobación una vez y mantén la página en tu rutina de mantenimiento mensual. La página del producto Library Doctor tiene la lista completa de funciones, la guía de usuario cubre la instalación y el uso diario en detalle, y el changelog muestra qué cambió en cada versión. ¿Dudas? La base de conocimiento, las preguntas frecuentes y la página de contacto son los puntos por donde empezar.