drumsergio/telegram-slskd-local-bot repository overview

⁠telegram-slskd-local-bot

telegram-slskd-local-bot is a Telegram bot, run in Docker next to your slskd⁠, that turns a song name typed on your phone into a lossless file in your music library. It looks the song up on Spotify, searches Soulseek, ranks the lossless copies by duration, bit depth and source with any lossy copies listed below them, and sends you the file in the chat so you can listen to it and read its lossless check before it is saved as Artist - Title in its own format. Doing the same by hand in the slskd web UI means reading file lists, guessing which copy is the studio version and finding out after the fact that the FLAC was an MP3.

⁠Features

• Send a song name; the bot resolves artist, title, album and duration on Spotify and searches Soulseek through your slskd for every audio format: lossless (FLAC, WAV, AIFF, ALAC, APE, WavPack, TTA, TAK) and lossy (MP3, AAC, M4A, Ogg, Opus, WMA).
• Lists every lossless copy of known length before every lossy one, so a song with no lossless copy still gets the best MP3 or AAC. Within each group it ranks by duration against Spotify, bit depth and sample rate (hi-res first) or bitrate, free slots, speed and file name; drops live, remix and karaoke cuts unless the title has them.
• Sends you the track in the chat before it is saved: the file itself, or an Opus copy of the whole song when the file is over Telegram's 50 MB limit. With a local Bot API server⁠ (compose profile bigfiles) the limit is 2000 MB and originals go as they are.
• Checks the spectrum of a lossless file and flags an MP3-style cutoff ("Possible transcode", "Likely transcode", "Fake lossless") before Save. A copy clearly made from a lossy file never reaches the library: the bot deletes it and tries the next copy (LOSSLESS_GATE). FLAC, WAV and AIFF are checked; other lossless formats say "not checked".
• Warns when similar files are already in the library before it searches.
• Saves as Artist - Title with its own extension (.flac, .wav, .mp3...) and the Spotify cover art embedded, in the folder your player or audio-transcode-watcher⁠ watches.
• /import a Spotify playlist or album and review each track or auto-save them all; /status shows the progress.
• Chat delivery (/deliver, or fixed per account with TELEGRAM_CHAT_DELIVERY_USERS) sends the track into the chat under 50 MB and saves nothing anywhere, so you can share the bot without sharing your library. It ranks copies by quality for their size instead: an MP3 at 320 kbps counts as much as a lossless file, and the smaller file wins.
• /format per chat sends tracks as the original, MP3 320 kbps or Opus 192 kbps, for whoever wants MP3 whatever the source.
• A wishlist: "Tell me when it appears" when nothing is found, "Wait for a better copy" under every result list. The bot searches again every WISHLIST_CHECK_HOURS and tells you, or fetches the copy with /auto on; /wishlist lists and removes wishes.
• Whole album from this source under a saved or sent track lists the folder it came from on that peer and fetches every file: saved to the library named from its tags with the album cover, skipping files you already have, or sent into the chat in your /format, with live progress and /cancel.
• /auto per chat saves the best match without a tap; a failed transfer gets Retry and Try next result; downloads show live progress.
• Answers only allow-listed Telegram users, and denies everyone while the list is empty.
• Cancels in slskd every transfer it gives up on, and sweeps leftover downloads after ORPHAN_SWEEP_HOURS (6) without touching a transfer in flight.
• A library sweep⁠, off until you set LIBRARY_SWEEP_USERS. Once a week it measures every song in the library and looks on Soulseek for a better copy of the weak ones. When a Chromaprint fingerprint says the copy is the same recording, only better, it replaces the song and keeps the old file for a week. When the copy may be a different recording, it sends you both files in Telegram with Keep mine, Take new and Keep both. Every sweep ends with a summary of what changed.
• An MCP server⁠ over the same pipeline, so an agent like Claude Code can resolve, search, download and wishlist tracks: stdio with python -m music_downloader mcp, or HTTP from the bot process with a bearer token (MCP_PORT, MCP_TOKEN).

⁠Quick start

You need a running slskd⁠ with an API key, a Spotify Developer⁠ app and a Telegram bot⁠ token, on an amd64 host (the image has no arm64 build).

mkdir slskd-importer && cd slskd-importer
curl -fsSLO https://raw.githubusercontent.com/GeiserX/telegram-slskd-local-bot/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/GeiserX/telegram-slskd-local-bot/main/.env.example -o .env
# edit .env: TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USERS (your Telegram user id), SPOTIFY_CLIENT_ID and
# SPOTIFY_CLIENT_SECRET, SLSKD_HOST and SLSKD_API_KEY, SLSKD_DOWNLOAD_PATH (slskd's completed-downloads
# folder) and MUSIC_OUTPUT_PATH (your library); the last two must be writable by uid 1000
mkdir -p data && sudo chown 1000:1000 data    # the container runs as uid 1000
docker compose up -d                          # starts drumsergio/telegram-slskd-local-bot:0.20.2

The container is slskd_importer, and the log line Music Downloader v0.20.2 starting means it is up. A message to your bot (for example Nancy Sinatra Bang Bang) is answered with the Spotify matches to pick from, or with the ranked copies when there is only one match; an empty TELEGRAM_ALLOWED_USERS answers nobody, and the denial reply shows your id. Getting started⁠ has the other install paths.

⁠Documentation

The docs are at geiserx.github.io/telegram-slskd-local-bot⁠.

• Getting started⁠: prerequisites, Docker Compose, running from PyPI
• Configuration⁠: every environment variable and its default
• Usage⁠: what the chat shows, the commands, how results are scored
• MCP server⁠: the tools, the stdio and HTTP setup for Claude Code and Claude Desktop, the token
• How it works⁠: the path from a message to a file in the library
• Troubleshooting⁠: the failures people hit and what to report in an issue
• Development⁠: running from a checkout, tests, releases

Release notes are in the changelog⁠. Bugs and questions go to the issues⁠; security problems to the security policy⁠, never a public issue.

⁠Related projects

Music pipeline: slskd-transform⁠, audio-transcode-watcher⁠, quality-gate-encoder⁠. Other Telegram bots: paperless-telegram-bot⁠, jellyfin-telegram-channel-sync⁠, Telegram-Archive⁠. The rest are in Related projects⁠.

⁠License

GPL-3.0-or-later⁠