Skip to content

Getting started

Python versions codecov

Prerequisites

The bot at @slskdimporterbot is a private, allow-listed instance and will not answer you; deploy your own.

Docker Compose

services:
  slskd-importer:
    image: drumsergio/telegram-slskd-local-bot:0.25.0
    container_name: slskd_importer
    restart: unless-stopped
    environment:
      TELEGRAM_BOT_TOKEN: "your-bot-token"
      TELEGRAM_ALLOWED_USERS: "your-telegram-user-id"
      SPOTIFY_CLIENT_ID: "your-spotify-client-id"
      SPOTIFY_CLIENT_SECRET: "your-spotify-client-secret"
      SLSKD_HOST: "http://your-slskd-host:5030"
      SLSKD_API_KEY: "your-slskd-api-key"
    volumes:
      # Read-write: the bot deletes rejected files and sweeps abandoned ones
      - /path/to/slskd/downloads:/downloads
      - /path/to/music/library:/music
      # SQLite history and import state
      - ./data:/data
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    logging:
      driver: "json-file"
      options:
        max-size: "50m"
        max-file: "3"

Send files over 50 MB: a local Bot API server

Telegram's cloud Bot API refuses any file a bot sends over 50 MB, so chat delivery converts bigger files to Opus. A local Bot API server running next to the bot accepts up to 2000 MB. The repo's docker-compose.yml already has one, telegram-bot-api, behind the bigfiles profile. The compose file above does not. If you started from it, copy the telegram-bot-api service and the telegram-bot-api-data volume from the repo's docker-compose.yml into yours. Without them --profile bigfiles starts only the bot, which then cannot reach telegram-bot-api.

  1. Log in at my.telegram.org, open API development tools and create an application. Copy its api_id and api_hash.
  2. Put them in .env:

    TELEGRAM_API_ID=1234567
    TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef
    
  3. Log the bot out of Telegram's cloud server, once, before its first start against the local server. A bot token is logged in to one server at a time; without this step the local server may not get the bot's updates.

    curl https://api.telegram.org/bot<your-bot-token>/logOut
    

    The answer is {"ok":true,"result":true}.

  4. Point the bot at the local server in .env:

    TELEGRAM_API_BASE_URL=http://telegram-bot-api:8081
    
  5. Start both containers:

    docker compose --profile bigfiles up -d
    

    The bot's log says Talking to local Bot API server at http://telegram-bot-api:8081; upload cap 2000 MB.

The server runs as uid 101 and keeps its state in the telegram-bot-api-data volume. The named volume in the compose file gets that owner on its own; if you swap it for a host folder, give the folder to uid 101 first (sudo chown -R 101:101 /path/to/folder).

What changes:

  • The upload cap becomes 2000 MB (TELEGRAM_MAX_UPLOAD_MB still overrides it).
  • The bot sends the original file as it is, both the preview before Save and chat delivery: a 120 MB hi-res FLAC arrives as that FLAC, with no Opus conversion. /format still converts when you ask for MP3 or Opus.
  • Chat ranking only pushes copies over 2000 MB to the end; the size cost still grows from 5 MB to 50 MB.
  • Telegram clients play audio of any size, so the big file plays in the chat like a small one.
  • Requests to Telegram get 600 s read and write timeouts, enough for a 2 GB upload on a LAN (TELEGRAM_UPLOAD_TIMEOUT_SECS changes it).
  • The bot reads the whole file into memory to upload it, so a 1.5 GB FLAC needs 1.5 GB of free RAM while it is sent. On a small box set TELEGRAM_MAX_UPLOAD_MB below the RAM you can spare, for example 500 on a machine with 2 GB.

To go back to the cloud server, log the bot out of the local server with logOut, remove TELEGRAM_API_BASE_URL from .env and start the bot again with docker compose up -d. Telegram can take up to 10 minutes to accept the token on the cloud server again.

docker compose exec telegram-bot-api wget -qO- http://127.0.0.1:8081/bot<your-bot-token>/logOut

From PyPI

Without Docker, install the package with the analysis extra, which the lossless check needs, and put ffmpeg on the PATH, which the bot uses to convert large files to Opus for the chat. Create the virtual environment in the same folder as .env. The bot looks for .env in the folders above its installed package, so a .venv beside .env finds it and one elsewhere does not.

mkdir slskd-importer && cd slskd-importer
python3 -m venv .venv && . .venv/bin/activate
pip install 'telegram-slskd-local-bot[analysis]'
curl -fsSL https://raw.githubusercontent.com/GeiserX/telegram-slskd-local-bot/main/.env.example -o .env
# edit .env: the tokens, TELEGRAM_ALLOWED_USERS, SLSKD_HOST and SLSKD_API_KEY; point DOWNLOAD_DIR
# (slskd's completed-downloads folder) and OUTPUT_DIR (your library) at real folders and add
# DATA_DIR=./data, because the defaults /downloads, /music and /data are container paths
slskd-importer run

Running from a checkout, tests and releases: Development.