gio2chi/music-downloader repository overview

⁠🎵 Song Downloader Server (Telegram + Spotify)

A containerized server that lets users download their Spotify playlists in FLAC or MP3 quality with full metadata embedding.
Users interact via a Telegram bot, while the backend handles Spotify authentication, metadata fetching, and Telegram communication.

⁠⚠️ Disclaimer

This project is provided for educational purposes only.
The server does not host or distribute copyrighted music — it only provides the infrastructure to interact with Telegram bots and fetch metadata from Spotify.
The choice of which Telegram bot to use, and the act of downloading music, are entirely the user’s responsibility.
By running this container, you agree that the author assumes no liability for misuse, copyright violations, or illegal activity.

⁠✨ Features

• Login to Spotify via Telegram
• Select and download Spotify playlists
• Output in FLAC (lossless) or MP3 (compressed)
• Full metadata embedding (title, artist, album, cover, release date, genre)
• Telegram-based control — no external UI
• Load balancing between multiple Telegram download bots
• Lightweight, fully Dockerized deployment

⁠🚀 Quick Start

docker run -d \
  --name music-downloader \
  -p 3000:3000 \
  -e SPOTIFY_CLIENT_ID=your_spotify_client_id \
  -e SPOTIFY_CLIENT_SECRET=your_spotify_client_secret \
  -e SPOTIFY_REDIRECT_URI=https://example.com:3000\
  -e TELEGRAM_BOT_TOKEN=your_telegram_bot_token \
  -e TELEGRAM_CLIENT_API_ID=your_telegram_api_id \
  -e TELEGRAM_CLIENT_API_HASH=your_telegram_api_hash \
  -e DB_URL=your_database_url \
  gio2chi/music-downloader:latest

version: "3.8"
services:
  music-downloader:
    image: gio2chi/music-downloader:latest
    container_name: music-downloader
    ports:
      - "3000:3000"
    environment:
      - SPOTIFY_CLIENT_ID=your_spotify_client_id
      - SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
      - SPOTIFY_REDIRECT_URI=https://example.com:3000
      - TELEGRAM_BOT_TOKEN=your_telegram_bot_token
      - TELEGRAM_CLIENT_API_ID=your_telegram_api_id
      - TELEGRAM_CLIENT_API_HASH=your_telegram_api_hash
      - DB_URL=your_mongodb_url # only database supported yet
    restart: unless-stopped

⁠⚙️ Configuration

• telegram_clients → array of cookie sessions for Telegram clients.
  Generate these by running:

  node config.helper.js

  Copy
• resolvers → list of Telegram bots that can download songs.
  Each resolver object includes a name and priority:

  {
    "botUsername": "",
    "config": {
      "timeout": 0,
      "msgPerDownload": 1,
      "songsPerMinute": 0
    },
    "priority": 0
  }

  Copy
  Lower priority = tried first; same priority = load-balanced.

#config.json
{
    "telegram_clients": ["client-cookie"],
    "resolvers": [
        {
            "botUsername": "@bot-username",
            "config": {
                "timeout": 0,
                "msgPerDownload": 1,
                "songsPerMinute": 0
            },
            "priority": 0
        }
    ]
}

⁠🧱 Architecture Overview

1. Telegram Bot – user login and playlist selection
2. MTProto Client – handles Telegram sessions
3. Spotify API – retrieves playlist metadata
4. Downloader Module – uses Telegram bots to fetch and tag songs

⁠🧩 Requirements

• Valid Spotify API credentials
• A configured Telegram bot via @BotFather⁠
• MTProto API ID and hash
• Node.js or Docker environment
• Database connection (MongoDB)

⁠📌 Notes

• This software does not bypass Spotify DRM.
• The author does not endorse or distribute Telegram bots.
• Users are responsible for complying with copyright laws.

⁠📜 License

MIT License – see the LICENSE file in the GitHub repository⁠.