molinaig/spotify-downloader repository overview

⁠🎵 Spotify Downloader (Docker)

Spotify Downloader es una potente aplicación web autocontenida en Docker para descargar canciones, álbumes completos, playlists y podcasts oficiales de Spotify a máxima calidad (320 kbps MP3) con carátulas en alta resolución y metadatos ID3 oficiales.

Cuenta con una interfaz web oscura (Dark Mode), reproductor de audio integrado para escuchar directamente en el navegador, gestión unificada de álbumes multi-artista y barra de progreso en vivo con porcentaje de avance.

⁠✨ Características Principales

• ⚡ Descarga Digital Oficial (320 kbps): Descarga de audio optimizado a 320 kbps en formato MP3 con máxima fidelidad sonora.
• 🖼️ Metadatos y Carátulas ID3v2 Completas: Incorpora portada oficial, título, artista, artista del álbum, año, número de pista y disco.
• 💿 Agrupación Inteligente de Álbumes Multi-Artista: Si un álbum cuenta con colaboraciones o múltiples artistas (recopilatorios, DJ sets, bandas sonoras), todas las pistas se agrupan en una única carpeta y tarjeta de álbum (Varios Artistas o artista principal), evitando duplicados.
• ⏱️ Alineación Exacta de Duración: Ajusta y recorta silencios finales o cortinillas para que coincida exactamente con la duración oficial de Spotify.
• 📊 Cola de Descargas en Vivo con % de Progreso: Visualización en tiempo real del progreso de cada pista con barra porcentual animada y botón de cancelación inmediata.
• ▶️ Reproductor Integrado en Navegador: Escucha cualquier canción almacenada directamente desde el modal web antes de descargarla a tu equipo.
• 📻 Soporte para Podcasts: Extractor inteligente con resolución automática de feeds RSS oficiales.
• 🔒 Seguridad con Autenticación HTTP Basic: Protegido mediante usuario y contraseña configurables por variables de entorno.
• 💾 Persistencia Completa mediante Volúmenes Docker: Todo se almacena en el volumen montado en /data.

⁠🚀 Inicio Rápido con Docker Compose (Recomendado)

Crea un archivo docker-compose.yml:

services:
  spotify-downloader:
    image: molinaig/spotify-downloader:latest
    container_name: spotify-downloader
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - AUTH_USER=admin
      - AUTH_PASS=spotify2026
    volumes:
      # Volumen persistente para la biblioteca musical y descargas
      - ./output:/data

Inicia el servicio en segundo plano:

docker compose up -d

Accede a la interfaz web en tu navegador: 👉 http://localhost:5000 (o la IP de tu servidor)

• Usuario por defecto: admin
• Contraseña por defecto: spotify2026

⁠🐳 Inicio con Docker CLI (docker run)

También puedes ejecutar el contenedor directamente con un solo comando:

docker run -d \
  --name spotify-downloader \
  --restart unless-stopped \
  -p 5000:5000 \
  -e AUTH_USER=admin \
  -e AUTH_PASS=spotify2026 \
  -v $(pwd)/output:/data \
  molinaig/spotify-downloader:latest

⁠⚙️ Variables de Entorno

⁠📂 Estructura de Volúmenes y Persistencia

El contenedor utiliza la ruta interna /data como directorio raíz para todo el almacenamiento.

Al montar un volumen del host (ej: ./output:/data):

• Todas las descargas y álbumes quedan guardados directamente en la carpeta ./output de tu host.
• La música persiste tras reiniciar, detener o actualizar el contenedor Docker.
• Las carpetas se organizan de forma limpia siguiendo el estándar canónico de bibliotecas musicales:

output/
├── Artista/
│   └── Álbum/
│       ├── 01 - Título de la Canción.mp3
│       └── 02 - Otra Canción.mp3
└── Álbum Recopilatorio (Varios Artistas)/
    ├── 01 - Primera Pista.mp3
    └── 02 - Segunda Pista.mp3

⁠🖥️ Uso de la Aplicación

1. Descargar Canción, Álbum o Playlist:

   • Pega cualquier enlace de Spotify (https://open.spotify.com/album/..., .../playlist/..., .../track/...) en el campo superior.
   • Haz clic en ⬇ Descargar (320k).
   • Observa el progreso en vivo y porcentaje en la pestaña Descargas en Curso.

2. Biblioteca Musical y Reproducción:

   • Cambia a la pestaña 💿 Álbumes y Biblioteca.
   • Haz clic en 📂 Ver Canciones para abrir el modal del álbum.
   • Pulsa ▶ Escuchar para reproducir la canción en streaming directo dentro del navegador.
   • Pulsa ⬇ Descargar para bajar el MP3 a tu ordenador o dispositivo móvil.
   • Pulsa 🗑 Borrar para eliminar canciones o álbumes completos.

⁠🛠️ Tecnologías Utilizadas

• Python 3.10 & Flask
• SpotDL & yt-dlp para extracción de metadatos y audio digital
• FFmpeg para remuestreo, codificación a 320 kbps y corte de precisión
• Mutagen para lectura y escritura avanzada de etiquetas ID3v2
• PulseAudio & Librespot integrados en la imagen base

⁠📄 Licencia

Este proyecto está bajo la Licencia MIT.