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 FLAC in your music library. It looks the song up on Spotify, searches Soulseek for lossless copies, ranks them by duration, bit depth and source, 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.flac. 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 for FLAC copies through your slskd.
• Ranks copies by duration against Spotify, bit depth and sample rate (hi-res first), 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 FLAC itself, or an Opus copy of the whole song when the file is over Telegram's 50 MB limit.
• Checks the spectrum of a FLAC found from a song name (by you or /auto) and flags an MP3-style cutoff ("Possible transcode", "Likely transcode", "Fake lossless") before Save. /import skips it.
• Warns when similar files are already in the library before it searches.
• Saves as Artist - Title.flac with 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.
• /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.
• Sweeps abandoned downloads after DOWNLOAD_CLEANUP_HOURS and never touches a transfer in flight.

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.13.1

The container is slskd_importer, and the log line Music Downloader v0.13.1 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 FLAC 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
• How it works: the path from a message to a file in the library
• Troubleshooting: the four 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