About this project

telegram-slskd-local-bot is a Docker-oriented Telegram bot for automating music acquisition and library organization. It sits beside a slskd instance and uses Spotify for release metadata, including artist, title, album, and duration, then asks slskd to search Soulseek for matching FLAC files. Search results are ranked using duration match, bit depth, sample rate, available upload slots, speed, and filename. The bot can avoid live, remix, or karaoke versions unless those terms are part of the requested title. Before saving, it sends the selected track to the Telegram chat for review. Files larger than Telegram's 50 MB limit can be sent as an Opus preview of the complete song. The project includes lossless checking by inspecting the FLAC spectrum and labeling possible MP3 transcodes or fake lossless files. Saved tracks are named in the "Artist - Title.flac" format, tagged with Spotify cover art, and placed in a configured music-library directory. It can warn when similar files already exist. Supported chat workflows include importing Spotify playlists or albums, reviewing tracks individually, automatically saving the best match, retrying failed transfers, trying the next result, monitoring download progress, and checking import status. Access is restricted to allow-listed Telegram user IDs; if the allow list is empty, the bot denies all users. Abandoned downloads can be cleaned up after a configurable interval without interrupting active transfers. Deployment requires a running slskd instance with an API key, Spotify Developer credentials, a Telegram bot token, and writable download and music directories. The documented quick start uses Docker Compose, with the container running as UID 1000; the provided image targets amd64 rather than arm64. The documentation covers configuration, usage, scoring behavior, troubleshooting, and development. The project is released under GPL-3.0-or-later.