drumsergio/telegram-slskd-local-bot repository overview
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
- 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
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
| Variable | Required | Default | Description |
|---|---|---|---|
TELEGRAM_BOT_TOKEN | Yes | — | Telegram bot token from @BotFather |
TELEGRAM_ALLOWED_USERS | Yes | (deny all) | Comma-separated Telegram user IDs allowed to use the bot. Empty means the bot denies everyone (fail-closed) — the denial reply shows you your ID |
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 | Default auto-download state for chats that never toggled /auto: best match is downloaded and saved without asking |
MAX_RESULTS | No | 10 | 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 |
DOWNLOAD_CLEANUP_HOURS | No | 24 | Hours before abandoned files in DOWNLOAD_DIR are auto-deleted (hourly sweep; 0 disables). In-flight transfers are never touched |
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 |
Telegram Bot Commands
| Command | Description |
|---|---|
| (any text) | Search for a song and show download options |
/import <spotify url> | Import a Spotify playlist or album — review each track or auto-save all |
/cancel | Cancel the active import or search |
/auto | Toggle auto-download per chat: best match is downloaded and saved without picking or approval (persists across restarts) |
/status | Show active searches and downloads |
/history | Show recent download history |
/help | Show help message |
Scoring Algorithm
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.
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
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
Tag summary
Content type
Image
Digest
sha256:7a429f81d…
Size
278.5 MB
Last updated
about 1 month ago
docker pull drumsergio/telegram-slskd-local-bot