Sootio - The Ultimate Stremio Debrid Addon

Sootio is an intelligent, multi-source streaming engine for Stremio that delivers the highest quality cached torrents, Usenet downloads, and direct HTTP streams from your Debrid services with smart tiered prioritization.

✨ Key Features

🎯 Multiple Content Sources

7 Debrid Providers: Real-Debrid, All-Debrid, TorBox, Premiumize, OffCloud, Debrid-Link, Debrider.app
14 Torrent Scrapers: Jackett, Zilean, Torrentio, Comet, StremThru, Bitmagnet, Snowfl, 1337x, BTDigg, MagnetDL, TorrentGalaxy, Torrent9, Wolfmax4K, BluDV
Usenet Support: Full Newznab + SABnzbd integration with progressive streaming
HTTP Streaming: 4KHDHub, UHDMovies with PixelDrain/Google Drive support
Personal Cloud: Home media server integration with fuzzy matching

🧠 Intelligent Stream Prioritization

Tiered Quality System: Remux > BluRay > WEB-DL > WEBRip > Lower quality
Smart Codec Balancing: Configurable H.264 vs H.265 distribution
Early Exit Optimization: Stops searching when quality threshold is met
Per-Quality Limits: Fine-grained control over results per tier
Audio Codec Filtering: Skip AAC/Opus if desired
Junk Release Filtering: Automatically filters YIFY, RARBG, and other low-quality groups

⚡ Performance & Scalability

Multi-Worker Clustering: Up to 32 workers for high-load scenarios (configurable)
Dual-Layer Caching: 5000-entry in-memory + SQLite persistent cache
Rate Limiting: Per-provider rate limit management (250 req/min for RD, 600/min for AD)
Progressive Results: Returns cached results while fetching fresh data
Concurrent Processing: Parallel scraper execution with smart coordination

🌍 Advanced Features

42 Language Support: Multi-audio detection with flag emojis (🇬🇧 🇫🇷 🇪🇸 🇩🇪 etc.)
Season Pack Inspection: Smart episode extraction from season packs
Year-Based Filtering: Prevents wrong sequel/remake matches
SOCKS5/HTTP Proxy Support: Per-service proxy configuration (WARP-friendly)
SQLite Cache: Persistent cache with TTL and auto-cleanup
Usenet Progressive Streaming: Starts streaming at 3% download completion
HTTP Range Requests: Full seeking support for all streams
Docker Ready: Complete Docker + docker-compose setup

📊 Monitoring & Debugging

Prometheus Metrics: Built-in performance monitoring
Configurable Logging: Debug, info, warn, error levels
Per-Provider Debug Logs: Detailed debugging for each debrid service
SQLite Cache Debugging: Detailed logging for SQLite operations and performance
Cache Hit/Miss Tracking: Monitor cache efficiency

🛠️ How It Works

When you search for a movie or episode in Stremio:

Parallel Scraping → Queries all enabled scrapers simultaneously (Jackett, Zilean, 1337x, etc.)
Quality Categorization → Groups results by quality tier (Remux, BluRay, WEB-DL, WEBRip)
Cache Checking → Verifies torrent availability on your Debrid providers
Smart Filtering → Applies codec diversity, audio filtering, and quality limits
Prioritized Ranking → Sorts by tier, then resolution, then file size
Early Exit → Returns results as soon as quality threshold is reached
Multi-Layer Caching → Stores results in memory + SQLite for instant future lookups

Result: Streams are ordered from best → worst with instant playback and no waiting.

🚀 Installation

Method 1: Docker (Recommended)

Prerequisites

Steps

Clone the repository

git clone https://github.com/sooti/sootio-stremio-addon.git
cd sootio-stremio-addon

Configure environment

cp .env.example .env
# Edit .env with your settings (see Configuration section below)
nano .env  # or use your preferred editor

Build and run

# Basic setup (no SQLite)
docker-compose up -d

# With SQLite for persistent cache (recommended)

Access the addon

Open http://localhost:55771 (or your configured ADDON_URL)
Configure your Debrid provider API keys
Click Install to Stremio

Docker Management

# View logs
docker-compose logs -f

# Restart addon
docker-compose restart

# Stop addon
docker-compose down

# Rebuild after code changes
docker-compose up -d --build

Method 2: Manual Installation

Prerequisites

Node.js v20.x
pnpm v9.x (recommended) or npm
Git

Steps

Clone the repository

git clone https://github.com/your-username/sootio-stremio-addon.git
cd sootio-stremio-addon

Install dependencies

# Using pnpm (recommended)
pnpm install

# Or using npm
npm install

Configure environment

cp .env.example .env
# Edit .env with your settings
nano .env  # or use your preferred editor

Run the addon

# Production mode with clustering (recommended)
npm start

# Single worker mode (for debugging)
npm run standalone

# Development mode with auto-reload
npm run dev

Access the addon

Open http://localhost:55771 (or your configured port)
Configure your Debrid provider API keys
Click Install to Stremio

Method 3: Optional SQLite Setup

SQLite is optional but highly recommended for:

Multi-user scenarios
Persistent cache across restarts
Better performance with frequent searches
Shared cache across multiple addon instances
Simpler setup (no separate database server needed)

Configure SQLite in .env

SQLITE_CACHE_ENABLED=true
SQLITE_CACHE_TTL_DAYS=180

# Optional: Enable detailed SQLite debugging
SQLITE_DEBUG_LOGS=true
# Alternative variable name
DEBUG_SQLITE=true

SQLite database files will be created automatically in the data/ directory.

When debugging is enabled, you'll see detailed logs about:

Database connection establishment
Query execution times
Cache hit/miss statistics
Bulk operations performance
Cleanup job execution

⚙️ Configuration

Sootio is configured via the .env file. See .env.example for all available options.

Essential Settings

# Addon URL (your domain or localhost)
ADDON_URL=http://localhost:55771
PORT=55771

# Logging
LOG_LEVEL=error
DEBRID_DEBUG_LOGS=false

Debrid Provider Configuration

Debrid providers are configured via the Stremio UI when installing the addon:

Real-Debrid
All-Debrid
TorBox
Premiumize
OffCloud
Debrid-Link
Debrider.app

Torrent Scrapers

Enable/disable scrapers individually:

JACKETT_ENABLED=true
JACKETT_URL=http://your-jackett-ip:9117
JACKETT_API_KEY=your_api_key

ZILEAN_ENABLED=true
TORRENT_1337X_ENABLED=true
BTDIG_ENABLED=true
MAGNETDL_ENABLED=true
SNOWFL_ENABLED=false
TORRENTIO_ENABLED=false
COMET_ENABLED=false
STREMTHRU_ENABLED=false
BITMAGNET_ENABLED=false
TORRENT_GALAXY_ENABLED=false
TORRENT9_ENABLED=false
WOLFMAX4K_ENABLED=false
BLUDV_ENABLED=false

# Scraper timeout (ms)
SCRAPER_TIMEOUT=5000

Quality & Filtering

# Skip certain quality tiers
PRIORITY_SKIP_WEBRIP_ENABLED=true
PRIORITY_SKIP_AAC_OPUS_ENABLED=true

# Per-quality result limits
MAX_RESULTS_REMUX=2
MAX_RESULTS_BLURAY=2
MAX_RESULTS_WEBDL=2
MAX_RESULTS_WEBRIP=1

# Codec diversity
DIVERSIFY_CODECS_ENABLED=true
MAX_H265_RESULTS_PER_QUALITY=2
MAX_H264_RESULTS_PER_QUALITY=2

# Overall limits
TARGET_CODEC_COUNT=10
EARLY_EXIT_QUALITY_THRESHOLD=BluRay

Performance Tuning

# Clustering (auto uses cluster mode)
MAX_WORKERS=10

# Rate limits
RD_RATE_PER_MINUTE=250
RD_CONCURRENCY=10
AD_RATE_PER_MINUTE=600
AD_CONCURRENCY=50

# Caching
SCRAPER_CACHE_TTL_MOVIE_MIN=360
SCRAPER_CACHE_TTL_SERIES_MIN=60

SQLite Cache

SQLITE_CACHE_ENABLED=true
SQLITE_CACHE_TTL_DAYS=30

Proxy Support

# Proxy URL (supports HTTP/HTTPS/SOCKS5)
DEBRID_HTTP_PROXY=socks5h://warp:1080

# Which services to proxy
DEBRID_PROXY_SERVICES=*:true
# Or specific: realdebrid:true,scrapers:true

Usenet (Optional)

USENET_FILE_SERVER_URL=http://localhost:8765
USENET_FILE_SERVER_API_KEY=your_api_key

Usenet services (Newznab indexers and SABnzbd) are configured via the Stremio UI.

Advanced Options

See .env.example for 100+ additional configuration options including:

HTTP streaming settings
Season pack handling
Cache TTL values
Request timeouts and retries
Debug options for debrid services and SQLite cache operations

📋 Supported Content Sources

Debrid Providers (7)

Provider	Cache Check	Personal Cloud	Season Packs	Notes
Real-Debrid	✅ Hash-based	✅	✅	Full support
All-Debrid	✅ Magnet-based	✅	✅	Full support
TorBox	✅	✅	✅	Usenet support
OffCloud	✅ Hash-based	✅	✅	Full support
Premiumize	✅	✅	✅	Full support
Debrid-Link	❌	✅ Seedbox	❌	Personal files only
Debrider.app	✅	✅	✅	Usenet support

Torrent Scrapers (14)

Scraper	Type	Language	Notes
Jackett	TorZNab API	Multi	Multi-indexer support
Zilean	DMM Database	Multi	Fast hash-based search
1337x	HTML Scraper	English	Multi-page support
BTDigg	DHT	Multi	Optional proxy rotation
MagnetDL	HTML Scraper	English	Fast direct scraping
Snowfl	API	Multi	snowfl-api integration
TorrentGalaxy	Aggregator	Multi	Wide coverage
Wolfmax4K	Specialty	Multi	High-quality 4K content
Torrent9	Regional	French	French content focus
BluDV	Regional	Portuguese	Brazilian content
Torrentio	Addon Bridge	Multi	Stremio integration
Comet	Debrid-focused	Multi	Optimized for debrid
StremThru	Premium	Multi	Premium service
Bitmagnet	Self-hosted	Multi	DHT crawler

HTTP Streaming (2)

4KHDHub: PixelDrain, Google Drive/Workers.dev links
UHDMovies: Direct HTTP streams with multi-quality support

Usenet

Newznab: Multi-indexer support with category-based search
SABnzbd: Progressive streaming starting at 3% completion

🔧 Advanced Usage

Clustering for High Load

# Single process (debugging)
npm run standalone

# Multi-worker with default settings
npm start

# Custom worker count
MAX_WORKERS=16 npm start

Usenet Progressive Streaming Setup

Install Python file server

cd media-file-server
pip install -r requirements.txt  # if using FastAPI version
python usenet_file_server.py    # zero-dependency version

Configure in .env

USENET_FILE_SERVER_URL=http://localhost:8765
USENET_FILE_SERVER_API_KEY=your_secret_key

Configure via Stremio UI

Add Newznab indexer URLs and API keys
Add SABnzbd URL and API key
Streams will start at 3% download completion

WARP Proxy for Debrid Services

Some regions may have debrid services blocked. Use Cloudflare WARP:

# docker-compose.yml
services:
  warp:
    image: caomingjun/warp:latest
    container_name: warp
    restart: unless-stopped
    ports:
      - "1080:1080"
    environment:
      - WARP_SLEEP=2

# .env
DEBRID_HTTP_PROXY=socks5h://warp:1080
DEBRID_PROXY_SERVICES=*:true

⚠️ Important Notes

Cache Checking Support

Provider	Method	Speed
Real-Debrid	Hash-based instant	⚡ Moderate
All-Debrid	Magnet upload + check	⚡⚡ Fast
OffCloud	Hash-based instant	⚡⚡⚡ Very Fast
TorBox	Cache check API	⚡⚡⚡ Very Fast
Premiumize	Cache check API	⚡⚡⚡ Very Fast
Debrider.app	Cache check API	⚡⚡⚡ Very Fast
Debrid-Link	Personal cloud only	⚡ Moderate

First Search Performance

Initial searches may take 10-30 seconds while caches warm up
Subsequent searches are instant (served from cache)
SQLite cache persists across restarts

Recommended Settings

Single user: 4-6 workers, SQLite optional
Multi-user (5-10): 10-16 workers, SQLite recommended
High load (50+): 24-32 workers, SQLite required

🤝 Contributing

Contributions are welcome! Here's how you can help:

Report Bugs: Open an issue describing the bug and steps to reproduce
Feature Requests: Suggest new features or improvements
Pull Requests: Submit PRs with bug fixes or new features
Documentation: Help improve documentation and examples

Development Setup

# Clone and install
git clone https://github.com/your-username/sootio-stremio-addon.git
cd sootio-stremio-addon
pnpm install

# Run in development mode
npm run dev

# Run tests (if available)
npm test

Contribution Guidelines

Follow existing code style
Add comments for complex logic
Test your changes thoroughly
Update documentation as needed
Keep PRs focused on a single feature/fix

📊 Architecture Overview

sootio-stremio-addon/
├── server.js              # Express server setup
├── cluster.js             # Multi-worker clustering
├── addon.js               # Stremio addon definition
├── lib/
│   ├── stream-provider.js      # Main stream orchestration
│   ├── catalog-provider.js     # Personal downloads catalog
│   ├── {provider}.js           # Debrid provider integrations (7)
│   ├── common/
│   │   ├── scrapers.js         # All torrent scrapers (14)
│   │   ├── sqlite-cache.js      # SQLite cache layer
│   │   └── debrid-cache-processor.js
│   ├── util/
│   │   ├── debrid-proxy.js     # Proxy management
│   │   ├── language-mapping.js # 42 language support
│   │   ├── filter-torrents.js  # Quality filtering
│   │   └── ...
│   ├── http-streams.js         # 4KHDHub integration
│   ├── uhdmovies.js           # UHDMovies integration
│   ├── usenet.js              # Usenet orchestration
│   ├── newznab.js             # Newznab indexer support
│   ├── sabnzbd.js             # SABnzbd integration
│   └── home-media.js          # Personal media server
├── media-file-server/
│   ├── usenet_file_server.py   # Python HTTP file server
│   └── fastapi_file_server.py  # FastAPI alternative
└── .env                        # Configuration

Total: ~24,000 lines of code across 40+ modules

🙏 Credits

Original Concept: Based on the Stremio Debrid Search addon by @MrMonkey42
Parse Torrent Title: Uses @TheBeastLT's fork for enhanced title parsing
Stremio SDK: Built with the official Stremio Addon SDK
Community: Thanks to all contributors and users providing feedback

🔗 Related Projects

Stremio - Official Stremio website
Torrentio - Popular torrent addon for Stremio
Jackett - Torrent indexer proxy
Zilean - DMM hash database
SABnzbd - Usenet download client

📝 License

This project is licensed under the MIT License.

💬 Support

For issues, questions, or feature requests:

Open an issue on GitHub
Check existing issues for solutions
Provide detailed information (logs, config, error messages)

Made with ❤️ by the Sootio community

Name		Name	Last commit message	Last commit date
Latest commit History 564 Commits
.github		.github
k8s		k8s
lib		lib
media-file-server		media-file-server
scripts		scripts
server		server
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
FILE_SERVER_README.md		FILE_SERVER_README.md
LICENSE		LICENSE
README.md		README.md
USENET_FEATURE.md		USENET_FEATURE.md
addon.js		addon.js
beamup.json		beamup.json
cluster.js		cluster.js
docker-compose.yml		docker-compose.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
server.js		server.js
serverless.js		serverless.js

License

elfhosted/stremio-addon-debrid-search

Folders and files

Latest commit

History

Repository files navigation

Sootio - The Ultimate Stremio Debrid Addon

✨ Key Features

🎯 Multiple Content Sources

🧠 Intelligent Stream Prioritization

⚡ Performance & Scalability

🌍 Advanced Features

📊 Monitoring & Debugging

🛠️ How It Works

🚀 Installation

Method 1: Docker (Recommended)

Prerequisites

Steps

Docker Management

Method 2: Manual Installation

Prerequisites

Steps

Method 3: Optional SQLite Setup

Configure SQLite in .env

⚙️ Configuration

Essential Settings

Debrid Provider Configuration

Torrent Scrapers

Quality & Filtering

Performance Tuning

SQLite Cache

Proxy Support

Usenet (Optional)

Advanced Options

📋 Supported Content Sources

Debrid Providers (7)

Torrent Scrapers (14)

HTTP Streaming (2)

Usenet

🔧 Advanced Usage

Clustering for High Load

Usenet Progressive Streaming Setup

WARP Proxy for Debrid Services

⚠️ Important Notes

Cache Checking Support

First Search Performance

Recommended Settings

🤝 Contributing

Development Setup

Contribution Guidelines

📊 Architecture Overview

🙏 Credits

🔗 Related Projects

📝 License

💬 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages