Development¶
Set up¶
git clone https://github.com/GeiserX/telegram-slskd-local-bot.git
cd telegram-slskd-local-bot
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,analysis]"
cp .env.example .env
# edit .env with your own tokens, slskd address and folders
python -m music_downloader run
ffmpeg and ffprobe must be on the PATH for the Opus conversion and the tests that use it.
uv sync --all-extras works instead of the venv and pip lines; uv.lock is committed.
Architecture¶
The code under src/music_downloader/ has three layers. The pipeline knows nothing about Telegram, the
Telegram bot is one front end on top of it, and SQLite holds everything that must outlive a restart.
The pipeline (music_downloader.pipeline)¶
Pipeline (in pipeline/__init__.py) owns the Spotify resolver, the slskd client, the scorer, the file
processor, the database repositories and the library index. It covers everything between "we have a query"
and "we have a file ready to hand over". Its methods take and return plain dataclasses and async callables:
| Module | What it does |
|---|---|
pipeline/resolve.py |
Free text to Spotify candidates (lookup), "Artist - Title" parsing, the synthetic track a direct search uses |
pipeline/search.py |
The search query helpers (version-noise stripping, keyword-reduction fallbacks), the title guard, and rank, which turns slskd responses into a RankedResults list for the library or chat profile |
pipeline/fetch.py |
fetch: enqueue, wait, find the file on disk, run the lossless check, all returned as a FetchOutcome; a transfer it gives up on is cancelled in slskd (abandon). fetch_gated and lossy_source: the lossless gate for library deliveries, a GatedFetch with the copies rejected. Also the Opus conversion and the bitrate ladder that fits the upload cap, and the /format send formats (transcode to MP3 320 or Opus 192) |
pipeline/album.py |
Album delivery: browse_folder (the audio files of the peer folder a copy came from, through slskd's user directory endpoint; an empty listing with a reason when the peer is offline or silent), fetch_folder (one enqueue for the folder, falling back to one by one; each file waited on in turn until its transfer moves no byte for DOWNLOAD_TIMEOUT_SECS, the album under ALBUM_TIMEOUT_SECS; a cancel event stops the waiting; one outcome per file, never raising), track_info_for (tags, then "NN - Title" style file names, then the chosen track's artist and album), AlbumArt (the album's Spotify cover, looked up once). Pipeline.album composes them and delivers each file as it lands: library saves it (skipping a file the library already has under that name), path leaves it, chat hands it to the front end's hook, which sends it; Pipeline.album_recover handles a restart |
pipeline/library.py |
Cover art, the download-history row, deleting sources, the hourly orphan sweep |
pipeline/wishlist.py |
The wishlist checker: which wishes are due, which copies satisfy one (search/scorer.py quality_tier), the sequential search pass that hands hits to the front end's delivery callback |
The pieces it drives sit next to it: metadata/ (Spotify, playlists), search/slskd_client.py and
search/scorer.py, processor/ (renaming and moving files, the lossless analyzer), tools/embed_artwork.py.
tests/test_pipeline_no_telegram.py imports every pipeline and MCP module in a fresh interpreter and fails if
any of them pulls in telegram.
Front ends¶
- Telegram (
music_downloader.bot, this repository):bot/handlers.pyparses updates, keeps the per-chat state, edits messages (always HTML, every outside value through_esc) and sends files.bot/keyboards.pybuilds the buttons.bot/poll_request.pyreports every successfulgetUpdatespoll to the health state.create_bot()wires it up and starts the background tasks: the orphan sweep, the library index rescan, the one-off recovery of albums a restart interrupted, the slskd health probe, the wishlist checker and, withMCP_PORT, the MCP HTTP server. - MCP (
music_downloader.mcp):mcp/tools.pyis the tool logic over aPipeline(plain dicts out, short track and copy ids kept in memory for an hour);mcp/server.pyregisters the tools on the officialmcpSDK'sMCPServerand serves them over stdio (python -m music_downloader mcp, its ownPipeline) or over streamable HTTP inside the bot process whenMCP_PORTis set (create_botstartsserve_httpon the bot'sPipeline, behind a bearer-token check). See MCP server.
State in SQLite¶
Everything lives in one database, importer.db in DATA_DIR (persistence/database.py creates every table
with CREATE TABLE IF NOT EXISTS):
| Table | Holds | Written by |
|---|---|---|
download_history |
One row per finished, failed, delivered or rejected download (/history); note is album for a file of an album download |
history_repo.py |
import_jobs, import_tracks |
/import jobs and the state of each track |
import_repo.py |
chat_settings |
Per-chat /auto and /deliver choices |
settings_repo.py |
pending_searches |
One row per chat with a live result list: the query, the track, the ranked results (JSON), the page, the profile and how many copies the title guard hid | pending_repo.py |
pending_downloads |
One row per download waiting on Save, Reject, Retry or Try next: track and result (JSON), the file path, the slskd transfer id, the import job if any. Once the track is saved or sent the row stays with delivered 1 and no file, behind the "Whole album from this source" button, until DOWNLOAD_CLEANUP_HOURS |
pending_repo.py |
wish_searches |
One row per list the wishlist checker sent, keyed by chat and search id: the same fields as pending_searches plus the wish it belongs to (NULL once the wish is gone). Kept apart so a chat's own search and a wish's list never replace each other |
pending_repo.py |
wishlist |
One row per wished track: chat, track (JSON), profile, any or better than a baseline quality tier, last check, number of checks, last notification |
wishlist_repo.py |
album_jobs |
One row per album download: the peer, the remote folder, library, path or chat, the owner (bot, or stdio for a stdio MCP server), the chosen track (JSON), the folder's audio files (JSON) and one outcome per file (JSON, null while unfinished), and running, done, cancelled (/cancel) or interrupted. At startup Pipeline.album_recover marks the bot's jobs left running as interrupted and saves the files of theirs that are already in DOWNLOAD_DIR (a chat job's are left to the sweep), and the bot tells each job's chat how far it got; transfers are not re-enqueued, slskd keeps them |
album_repo.py |
library_index |
One row per audio file under OUTPUT_DIR, subfolders included: relative path, stem, accent-free lowercase stem, extension, mtime |
library_index.py |
The bot keeps the pending rows in three dicts (WriteThroughDict): every set and delete is written through, so
after a restart the buttons on old messages still work. A button whose row is gone answers that it expired
after a restart. At startup and in the hourly sweep, pending downloads older than DOWNLOAD_CLEANUP_HOURS
are dropped with their files and their slskd transfers.
The library index replaces walking OUTPUT_DIR on every message. It is rebuilt in a thread at startup and
every hour (whether or not the orphan sweep is on), each save adds its own row, and the duplicate check runs
in a thread: a LIKE prefilter on the accent-free stem keeps at most 300 rows, best first, and only those go
through the fuzzy match (threshold 0.6, the same as before).
Health¶
health.py holds two timestamps. GET /health (served by __main__.py on HEALTH_PORT) answers 200 only
while the Telegram application runs, a getUpdates poll succeeded in the last 120 s, and slskd answered
application/state in the last 60 s (a background probe asks every 20 s). Otherwise it answers 503 with a
JSON body naming the failed check, for example {"status": "unhealthy", "failed": "slskd", "reason":
"application/state last answered 75 s ago"}. GET /ready is a constant 200. The Docker HEALTHCHECK
calls /health.
Test and lint¶
ruff check . && ruff format --check .
python -m pytest tests/ -v --tb=short
python -m pytest tests/ --cov=src/music_downloader --cov-report=term-missing
The same three commands run on every pull request as the ruff and test checks, plus CodeQL as Analyze.
pre-commit install runs ruff and the YAML and whitespace checks before each commit.
Build the image¶
The image installs the packages of the analysis extra (they are in requirements.txt), ffmpeg and
libsndfile1; the plain PyPI package installs none of them.
Release¶
- Bump
versioninpyproject.toml, the image pin indocker-compose.ymland in Getting started, and add the section to the changelog. - Push to
main, then push a new tagvX.Y.Z. Never move an existing tag. - The tag runs two workflows: Docker Publish pushes
drumsergio/telegram-slskd-local-bot:X.Y.Zto Docker Hub, and GitHub Release creates the release from the changelog section and uploads the package to PyPI.
Docs¶
The site is built by Zensical from docs/ and zensical.toml. To build it locally:
pip install -r docs/requirements-docs.txt
python -m zensical build --clean --strict
python -I .github/scripts/site-check.py site
The Docs workflow runs the same two steps on every pull request, and a push to main deploys the site. The strict
build fails on a broken link or anchor; site-check.py fails on what the build lets through: a page left out of the
nav, a nav entry for a missing file, a missing image, a link rooted at /.