Sootio

✨ 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:

1. Parallel Scraping → Queries all enabled scrapers simultaneously (Jackett, Zilean, 1337x, etc.)
2. Quality Categorization → Groups results by quality tier (Remux, BluRay, WEB-DL, WEBRip)
3. Cache Checking → Verifies torrent availability on your Debrid providers
4. Smart Filtering → Applies codec diversity, audio filtering, and quality limits
5. Prioritized Ranking → Sorts by tier, then resolution, then file size
6. Early Exit → Returns results as soon as quality threshold is reached
7. 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

• Docker
• Docker Compose

Steps

1. Clone the repository

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

2. Configure environment

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

3. Build and run

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

# With SQLite for persistent cache (recommended)

4. 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

1. Clone the repository

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

2. Install dependencies

# Using pnpm (recommended)
pnpm install

# Or using npm
npm install

3. Configure environment

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

4. 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

5. 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)

Torrent Scrapers (14)

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

1. 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

2. Configure in .env

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

3. 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

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 + Redis recommended

🤝 Contributing

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

1. Report Bugs: Open an issue describing the bug and steps to reproduce
2. Feature Requests: Suggest new features or improvements
3. Pull Requests: Submit PRs with bug fixes or new features
4. 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