beets-janitor
Herramienta de mantenimiento para la biblioteca de música Beets. Revisa archivos nuevos, corrige etiquetas, reasembla álbumes rotos y elimina duplicados sin modificar Beets.
Ficha actualizada 22 sept 2026, 19:23 · upstream 22 sept 2026, 18:54 · release sin release detectada
Qué es beets-janitor
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
beets-janitor es un conjunto de scripts que mantiene una biblioteca de música en orden sin intervención manual. No modifica beets ni sus archivos de configuración. Se ejecuta junto a la versión original del programa, no como fork o parche.
Se utiliza para resolver problemas comunes que surgen cuando una biblioteca se construye manualmente: álbumes divididos en múltiples entradas, duplicados, etiquetas incorrectas, artefactos de importación y archivos sin portada. El script funciona como un escáner pasivo que revisa archivos nuevos cada cierto tiempo (configurable) y ejecuta una cadena de correcciones automática.
El flujo principal es: 1. Detectar archivos nuevos en la carpeta incoming. 2. Corregir el formato de las etiquetas (cp1251 → latin-1). 3. Importar los archivos con beets. 4. Normalizar nombres de artistas y títulos. 5. Reasemblar álbumes rotos por artefactos de portada. 6. Eliminar duplicados confirmados por huellas acústicas. 7. Consolidar álbumes múltiples en uno. 8. Descargar portadas para canciones individuales. 9. Limpiar residuos.
Se ejecuta una vez al día (configurable) y también puede correrse manualmente con --dry para probar sin afectar la biblioteca.
- Corregir etiquetas de artistas cuando un álbum se divide en múltiples entradas por falta de campo albumartist
- Eliminar duplicados de canciones confirmados mediante huellas acústicas (fingerprint)
- Reasemblar álbumes rotos donde la portada está incrustada pero no se detecta automáticamente
- Corregir errores de encoding en etiquetas que aparecen como mojibake o caracteres ilegibles
- Eliminar archivos duplicados que ya existen en la biblioteca sin necesidad de reimportarlos
- Consolidar álbumes múltiples (discos separados, compilaciones) en un solo álbum
- Corregir nombres de canciones y artistas para alinearse con el formato estándar de beets
- No modifica ni reemplaza la versión original de beets. Se ejecuta como script independiente junto a la biblioteca existente.
- Utiliza huellas acústicas (fingerprint) como criterio principal para eliminar duplicados, lo que permite detectar errores de importación sin depender exclusivamente del nombre o duración.
- Corrige el encoding de etiquetas (cp1251 → latin-1) antes de importar, evitando que beets busque coincidencias erróneas contra mojibake.
- Permite corrección manual con --dry para probar cambios sin afectar la biblioteca actual.
- Incluye un sistema de journaling JSON que registra cada operación realizada (tags editados, archivos movidos) antes y después del proceso.
- Soporta detección automática de portadas incrustadas en álbumes rotos mediante análisis visual de artefactos.
- No descarga música desde servidores externos. Los archivos que se importan deben estar disponibles localmente o en una URL accesible.
- No verifica el contenido real del archivo (audio). Si un archivo tiene etiquetas correctas pero audio incorrecto, no lo detectará sin una referencia externa.
- Depende de beets para la búsqueda y normalización. Si se desactualiza beets, las scripts podrían dejar archivos en estado inestable.
- No corrige problemas de copyright o derechos de autor. Solo organiza los datos existentes.
- El rendimiento puede degradarse con bibliotecas muy grandes (millones de canciones) debido a la carga de CPU durante el análisis acústico.
- Los archivos que no encajan en ningún álbum se quedan como residuos en RESIDUE_DIR y requieren intervención manual.
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Requisitos: Docker con imagen de Linux Server (beets, ffmpeg, chromaprint/fpcalc) o instalación local con PYTHONPATH configurado.,Configuración inicial: renderizar los archivos de configuración desde templates y establecer las variables de entorno (especialmente Spotify credentials).,Volumenamiento: mapear la carpeta de biblioteca a un volumen persistente para evitar pérdida al reiniciar el contenedor.,Monitoreo: usar docker logs para observar errores en tiempo real, especialmente durante importaciones masivas o correcciones de etiquetas.,Backup: mantener copias de seguridad manuales del contenido de RESIDUE_DIR y CONFIG_DIR antes de ejecutar scripts que puedan modificar archivos existentes.,Escalabilidad: para bibliotecas grandes (>10k canciones), considerar un cron job programado en lugar de la ejecución manual diaria, o usar beets como backend con beets-janitor como frontend.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.