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.
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/
- Send a song name to the Telegram bot (text message)
- Bot resolves the track on Spotify (artist, title, duration, album)
- Bot searches slskd (Soulseek) for FLAC files matching the track
- Results are scored by duration match, audio quality, source reliability, and filename relevance
- Bot presents the top matches — you pick one (or enable auto-mode)
- File is downloaded, renamed to
Artist - Title.flac, and placed in your output directory - Your existing tools (e.g., audio-transcode-watcher, Navidrome) pick it up from there
- A running slskd instance with an API key
- A Spotify Developer app (free — Client ID + Secret)
- A Telegram bot token (via @BotFather)
services:
slskd-importer:
image: drumsergio/telegram-slskd-local-bot:0.1.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:
- /path/to/slskd/downloads:/downloads:ro
- /path/to/music/library:/music
logging:
driver: "json-file"
options:
max-size: "50m"
max-file: "3"# 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| Variable | Required | Default | Description |
|---|---|---|---|
TELEGRAM_BOT_TOKEN |
Yes | — | Telegram bot token from @BotFather |
TELEGRAM_ALLOWED_USERS |
No | (open) | Comma-separated Telegram user IDs allowed to use the bot |
SPOTIFY_CLIENT_ID |
Yes | — | Spotify Developer app Client ID |
SPOTIFY_CLIENT_SECRET |
Yes | — | Spotify Developer app Client Secret |
SLSKD_HOST |
Yes | — | slskd instance URL (e.g., http://192.168.1.100:5030) |
SLSKD_API_KEY |
Yes | — | slskd API key (Settings > Security > API Keys) |
DOWNLOAD_DIR |
No | /downloads |
Where slskd stores completed downloads (container path) |
OUTPUT_DIR |
No | /music |
Where to place renamed FLAC files (container path) |
AUTO_MODE |
No | false |
Auto-download best match without asking |
MAX_RESULTS |
No | 5 |
Maximum search results shown to user |
DURATION_TOLERANCE_SECS |
No | 5 |
Duration match tolerance in seconds |
SEARCH_TIMEOUT_SECS |
No | 30 |
slskd search timeout |
DOWNLOAD_TIMEOUT_SECS |
No | 600 |
Download completion timeout |
EXCLUDE_KEYWORDS |
No | live,remix,... |
Comma-separated keywords to filter out |
FILENAME_TEMPLATE |
No | {artist} - {title} |
Output filename template |
LOG_LEVEL |
No | INFO |
Logging level |
HEALTH_PORT |
No | 8080 |
Health check HTTP port |
| Command | Description |
|---|---|
| (any text) | Search for a song and show download options |
/auto |
Toggle auto-download mode on/off |
/status |
Show active searches and downloads |
/history |
Show recent download history |
/help |
Show help message |
Search results are ranked by:
- Duration match (40 pts): Compared to Spotify duration. Within ±5s = perfect, ±10s = acceptable, >30s = excluded
- Audio quality (25 pts): Prefers 16-bit/44.1kHz (CD quality) for consistency
- Source reliability (20 pts): Free upload slots, fast upload speed, short queue
- 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.
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ 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) │
└──────────────┘
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
- Repository: https://github.com/GeiserX/telegram-slskd-local-bot
- Telegram Bot: @slskdimporterbot
- Changelog: docs/CHANGELOG.md