Jelly Torrent Throttle

❓ What is this? Jelly Torrent Throttle is a lightweight Python webhook service that listens to Jellyfin playback events and temporarily throttles qBittorrent global speeds during playback (restoring them on pause/stop).

❓ How to use it?

• Using docker-compose
• Using Python

❓ What did I use?

• Python
• Docker
• Webhooks for Jellyfin
• qBittorrent WebUI API
• Coding
• Git management

⚠️ Requirements

• Jellyfin
• Webhooks for Jellyfin
• qBittorent with WebUI 5.0+
• Python 3.13+ or Docker with docker-compose

🐳 Using docker-compose to run Jelly Torrent Throttle

1. Install Webhooks for Jellyfin:
   • Add this link to Repositories in Jellyfin settings
   • Restart your Jellyfin instance
   • Install plugin called Webhooks
   • Restart your Jellyfin instance
2. Copy docker-compose.yml file to directory of your choice
3. Edit it according to environment variables
4. Run container - docker-compose up -d
5. Grab the IP:PORT of your container
6. Create new webhook in Webhooks for Jellyfin plugin:
   • URL: http://IP:PORT
   • Payload format: Default
   • Listen to events only for: All users
   • Events: Play, Pause, Resume, Stop

🐍 Using Python to run Jelly Torrent Throttle

1. Install Webhooks for Jellyfin:
   • Add this link to Repositories in Jellyfin settings
   • Restart your Jellyfin instance
   • Install plugin called Webhooks
   • Restart your Jellyfin instance
2. Copy JellyTorrentThrottle.py, .env.example and requirements.txt to directory of your choice
3. Change name of .env.example to .env and edit it according to environment variables
4. Install requirements - python -m pip install -r requirements.txt
5. Run script - python JellyTorrentThrottle.py
6. Grab the IP:PORT
7. Create new webhook in Webhooks for Jellyfin plugin:
   • URL: http://IP:PORT
   • Payload format: Default
   • Listen to events only for: All users
   • Events: Play, Pause, Resume, Stop

🛠️ Environment variables

• WEBHOOK_HOST - IP address or hostname to bind the webhook listener to (default: 0.0.0.0)

• WEBHOOK_PORT - Port for the webhook listener (default: 18080)

• QBITTORRENT_URL - Base URL of qBittorrent WebUI (e.g. http://localhost:8080)

• QBITTORRENT_USERNAME - qBittorrent WebUI username

• QBITTORRENT_PASSWORD - qBittorrent WebUI password

• SPEED_MODE - Throttle mode: alternative (use qBittorrent alt-speed limits) or custom (use the custom limits below)

• THROTTLE_DOWNLOAD_LIMIT - Download limit to apply when throttling (KiB/s, only used with SPEED_MODE=custom)

• THROTTLE_UPLOAD_LIMIT - Upload limit to apply when throttling (KiB/s, only used with SPEED_MODE=custom)

• LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR, default: INFO)

• LOG_FILE - Optional path to a rotating log file (if set, logs will also be written to this file)

🚀 Features

• 🎛️ Listens to Jellyfin playback webhooks (Play / Resume / Pause / Stop)
• 🐢 Temporarily throttles qBittorrent global speeds during playback and restores them on pause/stop
• ⚙️ Supports alternative (qBittorrent alt-speed) and custom throttle modes
• 👥 Safely handles multiple simultaneous playback sessions
• 🌐 Configurable via a .env file or via docker-compose.yml (qBittorrent credentials, throttle limits, host/port)
• 🩺 Exposes a /health endpoint and provides clean console logging
• 🐳 Runnable via Docker Compose or directly with Python
• 🔐 Uses qBittorrent WebUI authentication for API actions; no database required

💲 Support