Skip to content

telegram-slskd-local-bot

telegram-slskd-local-bot

Docker Pulls GitHub Stars Release License: GPL-3.0-or-later

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. Start with Getting started, then Usage.

  • Getting started

    Fetch the compose file, fill in the three tokens and the two folders, start the container. Also from PyPI.

  • Usage

    What the chat shows from the first message to the saved file, the commands, and how the copies are ranked.

  • Configuration

    Every environment variable, its default, and which ones the compose file needs on the host side.

  • How it works

    Resolve on Spotify, search and score on slskd, listen and approve in the chat, save and sweep.

What the chat looks like

You text the bot a song name. When Spotify returns more than one distinct track it shows them as buttons; you pick one. It searches Soulseek through your slskd, keeps the FLAC copies, ranks them, and shows the best ones with duration, bit depth, sample rate and size. You tap one, or Auto-pick best. The download shows its progress, then the file itself arrives in the chat, the FLAC when it is under Telegram's 50 MB limit and an Opus copy of the whole song when it is over, with a verdict line: Lossless OK, or Possible transcode, Likely transcode or Fake lossless with the frequency where the spectrum stops. You tap Save to library or Reject. Usage walks through it step by step.

What it does

  • Resolves artist, title, album and duration on Spotify, and warns when similar files are already in your library before it searches.
  • Ranks the copies by duration against Spotify, bit depth and sample rate (hi-res first), the uploader's free slot, speed and queue, and the file name; drops live, remix and karaoke cuts unless the title has them.
  • Checks the spectrum of a FLAC found from a song name and flags an MP3-style cutoff before you save. /import skips the check.
  • 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; /auto per chat saves the best match without a tap; a failed transfer gets Retry and Try next result.
  • Sweeps abandoned downloads after DOWNLOAD_CLEANUP_HOURS and never touches a transfer in flight.

How it runs

  • One container, drumsergio/telegram-slskd-local-bot, pinned to a release tag, amd64 only, running as user id 1000 with a read-only root filesystem. It needs a running slskd with an API key, a Spotify Developer app and a Telegram bot token.
  • Three folders: slskd's completed downloads, your music library, and a data folder for the SQLite history and import state. All three must be writable by uid 1000. See Configuration.
  • Without Docker, pip install 'telegram-slskd-local-bot[analysis]' plus ffmpeg runs the same bot as slskd-importer run. See Getting started.

What it does not do

  • It does not run a Soulseek client. slskd does; the bot talks to slskd's API.
  • It does not download anything without a tap unless you turn /auto on for that chat or pick Auto-save all for an import.
  • It does not check /import tracks for a lossy cutoff, and in auto-mode it saves the best copy whatever the check says.
  • It does not build for arm64.

Privacy

  • The bot answers only the Telegram user ids in TELEGRAM_ALLOWED_USERS, and answers nobody while the list is empty; the denial reply shows the sender their own id.
  • Spotify is used for metadata only, through the Client Credentials flow: no Spotify login, no listening data.
  • Nothing leaves your host but the searches sent to your slskd, the metadata requests to Spotify and the messages to Telegram.

Getting help

License

telegram-slskd-local-bot is released under the GPL-3.0-or-later license.