telegram-slskd-local-bot

Automated music discovery and download via Telegram bot. Resolves track metadata from Spotify, searches and downloads FLAC files from Soulseek (via slskd), renames them to Artist - Title.flac, and places them in your music library. Docker-ready.

How It Works

You: "Nancy Sinatra Bang Bang"
Bot: Found: Nancy Sinatra - Bang Bang (My Baby Shot Me Down) (2:42)
     Searching slskd for FLAC...
     #1 [free] 2:42 | 16bit/44.1kHz | 30MB
     #2 [free] 2:41 | 16bit/44.1kHz | 28MB
     [Download #1] [Download #2] [Auto-pick best] [Cancel]
You: (taps Download #1)
Bot: Downloaded! Nancy Sinatra - Bang Bang (My Baby Shot Me Down).flac -> /music/

Flow

1. Send a song name to the Telegram bot (text message)
2. Bot resolves the track on Spotify (artist, title, duration, album)
3. Bot searches slskd (Soulseek) for FLAC files matching the track
4. Results are scored by duration match, audio quality, source reliability, and filename relevance
5. Bot presents the top matches — you pick one (or enable auto-mode)
6. File is downloaded, renamed to Artist - Title.flac, and placed in your output directory
7. Your existing tools (e.g., audio-transcode-watcher, Navidrome) pick it up from there

Quick Start

Prerequisites

• A running slskd instance with an API key
• A Spotify Developer app (free — Client ID + Secret)
• A Telegram bot token (via @BotFather)

Docker Compose

services:
  slskd-importer:
    image: drumsergio/telegram-slskd-local-bot:0.12.0
    container_name: slskd_importer
    restart: unless-stopped
    environment:
      TELEGRAM_BOT_TOKEN: "your-bot-token"
      TELEGRAM_ALLOWED_USERS: "your-telegram-user-id"
      SPOTIFY_CLIENT_ID: "your-spotify-client-id"
      SPOTIFY_CLIENT_SECRET: "your-spotify-client-secret"
      SLSKD_HOST: "http://your-slskd-host:5030"
      SLSKD_API_KEY: "your-slskd-api-key"
    volumes:
      # Read-write: the bot deletes rejected files and sweeps abandoned ones
      - /path/to/slskd/downloads:/downloads
      - /path/to/music/library:/music
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"

Local Development

# Clone the repo
git clone https://github.com/GeiserX/telegram-slskd-local-bot.git
cd telegram-slskd-local-bot

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -e ".[dev]"

# Copy and configure environment
cp .env.example .env
# Edit .env with your credentials

# Run
python -m music_downloader run

Environment Variables

Telegram Bot Commands

Scoring Algorithm

Search results are ranked by:

1. Duration match (40 pts): Compared to Spotify duration. Within ±5s = perfect, ±10s = acceptable, >30s = excluded
2. Audio quality (25 pts): Prefers 16-bit/44.1kHz (CD quality) for consistency
3. Source reliability (20 pts): Free upload slots, fast upload speed, short queue
4. Filename relevance (15 pts): Artist and title words found in the filename

Results containing excluded keywords (live, remix, etc.) are automatically filtered out, unless the original track title also contains that keyword.

Architecture

┌──────────────────┐     ┌──────────────┐     ┌──────────────────┐
│  Telegram Bot    │────▶│  Spotify API │     │  slskd (Soulseek)│
│  (user input)    │     │  (metadata)  │     │  (search/download)│
└──────────────────┘     └──────────────┘     └──────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Music Downloader Service                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐│
│  │ Resolver │─▶│ Searcher │─▶│  Scorer  │─▶│ File Processor   ││
│  │(Spotify) │  │ (slskd)  │  │(ranking) │  │(rename + move)   ││
│  └──────────┘  └──────────┘  └──────────┘  └──────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                                                      │
                                                      ▼
                                              ┌──────────────┐
                                              │ Music Library │
                                              │  (FLAC files) │
                                              └──────────────┘

Related Projects

Music Pipeline:

• slskd-transform — Bulk upgrade lossy to lossless FLAC via Soulseek
• audio-transcode-watcher — Automated multi-format audio transcoding
• jellyfin-encoder — Automatic 720p HEVC/AV1 transcoding for Jellyfin

Telegram Bots:

• paperless-telegram-bot — Manage Paperless-NGX documents through Telegram
• AskePub — Telegram bot for ePub annotation with GPT-4
• telegram-delay-channel-cloner — Relay messages between channels with delay
• jellyfin-telegram-channel-sync — Sync Jellyfin access with Telegram membership
• Telegram-Archive — Automated Telegram backup with local web viewer

License

GPL-3.0

Links

• Repository: https://github.com/GeiserX/telegram-slskd-local-bot
• Telegram Bot: @slskdimporterbot — the author's personal instance, allow-listed; it won't respond to other users. Deploy your own to try it.
• Changelog: docs/CHANGELOG.md