AIOStreams Service Documentation¶

Table of Contents¶

Overview
Architecture
Configuration Details
Stremio Integration
Supported Debrid Services
Common Use Cases
API Endpoints
Security Considerations
Troubleshooting
Comparison with Stremthru
Backup Considerations

Overview¶

AIOStreams is a lightweight Stremio addon that provides streaming capabilities by bridging Stremio media players with multiple debrid services. It offers a simpler alternative to Stremthru with no database dependencies, using only local SQLite storage for configuration and caching.

Key Features: - Multi-Debrid Support: Integrates with Real-Debrid, AllDebrid, Premiumize, Debrid-Link, Put.io, EasyNews, PikPak, and Seedr - Lightweight Architecture: No external database dependencies - uses local SQLite storage - Stremio Integration: Direct addon integration with Stremio media center - Preset Addons: Pre-configured integration with popular Stremio addons (Torrentio, Comet, MediaFusion, etc.) - Custom Addon Support: Add any Stremio addon via manifest URL - Built-in Security: Optional password protection and access control - Rate Limiting: Configurable to prevent API abuse - Health Monitoring: Built-in health check endpoints

The service is deployed at https://aiostreams.rbnk.uk and operates independently without requiring Redis or PostgreSQL databases.

Architecture¶

Container Configuration¶

Image: ghcr.io/viren070/aiostreams:latest
Port: 3000 (internal), exposed via Traefik
Networks: traefik_proxy (external access via HTTPS)
Storage: Local SQLite database in ./data volume

Service Dependencies¶

graph TD
    A[AIOStreams] --> B[Local SQLite DB]
    A --> C[External Debrid APIs]
    A --> D[External Stremio Addons]

    C --> E[Real-Debrid]
    C --> F[AllDebrid]
    C --> G[Premiumize]
    C --> H[Debrid-Link]
    C --> I[Put.io]
    C --> J[EasyNews]
    C --> K[PikPak]
    C --> L[Seedr]

    D --> M[Torrentio]
    D --> N[Comet]
    D --> O[MediaFusion]
    D --> P[Custom Addons]

    Q[Stremio Client] --> R[Traefik]
    R --> A

    style A fill:#f9f,stroke:#333,stroke-width:4px
    style B fill:#ff9,stroke:#333,stroke-width:2px
    style C fill:#9ff,stroke:#333,stroke-width:2px

Data Flow¶

Addon Configuration: User configures AIOStreams in Stremio using manifest URL
Content Request: Stremio requests streams for specific content via AIOStreams API
Addon Routing: AIOStreams routes requests to appropriate configured addons
Debrid Integration: Available streams are processed through configured debrid services
Response Aggregation: Streams from multiple sources are aggregated and formatted
Content Delivery: Final stream list returned to Stremio for playback

Configuration Details¶

Environment Variables¶

Core Configuration¶

# Service Identity
ADDON_NAME=AIOStreams
ADDON_ID=aiostreams.rbnk.uk
PORT=3000
BASE_URL=https://aiostreams.rbnk.uk

# Security
SECRET_KEY=generated_secret_key_for_session_management

# Optional password protection (uncomment to enable)
# ADDON_PASSWORD=changeme

Debrid Service API Keys¶

# Real-Debrid
REAL_DEBRID_API_KEY=your_api_key

# AllDebrid
ALL_DEBRID_API_KEY=your_api_key

# Premiumize
PREMIUMIZE_API_KEY=your_api_key

# Debrid-Link
DEBRID_LINK_API_KEY=your_api_key

# Put.io
PUT_IO_CLIENT_ID=your_client_id
PUT_IO_OAUTH_TOKEN=your_oauth_token

# EasyNews
EASYNEWS_USERNAME=your_username
EASYNEWS_PASSWORD=your_password

# PikPak
PIKPAK_USERNAME=your_username
PIKPAK_PASSWORD=your_password

# Seedr
SEEDR_API_KEY=your_api_key

Security & Access Control¶

# Regex filter for access control
REGEX_FILTER_ACCESS=none

# Disable self-scraping (prevents recursive addon calls)
DISABLE_SELF_SCRAPING=false

Logging Configuration¶

# Logging level: debug, info, warn, error
LOG_LEVEL=info

# Log format: text or json
LOG_FORMAT=text

# Log sensitive information (API keys, tokens)
LOG_SENSITIVE_INFO=false

Performance Settings¶

# Default cache size for addon responses
DEFAULT_MAX_CACHE_SIZE=1000

# Rate limiting
DISABLE_RATE_LIMITS=false

Configuration Files¶

Database: /app/data/db.sqlite (local SQLite database)
Data Directory: /app/data (persistent storage for configuration and cache)

Preset Addon Configuration¶

AIOStreams comes with pre-configured support for popular Stremio addons:

Torrentio¶

Purpose: Provides torrent streams from multiple providers
Features: Debrid support, extensive provider selection
Default Providers: YTS, EZTV, RARBG, 1337X, The Pirate Bay, and 20+ others

Comet¶

Purpose: Fast torrent/debrid addon
Features: P2P and debrid streams, trash filtering, multiple debrid services
Specialty: Optimized for speed and reliability

MediaFusion¶

Purpose: Universal addon for movies, series, live TV, and sports
Features: Cached searches, watchlist catalogs, certification filtering
Content: Wide range including live events

StremThru Integration¶

Torz: Crowdsourced torrent library with DMM hashlists
Store: Access debrid library through catalogs and streams

Custom Addons¶

Flexibility: Add any Stremio addon via manifest URL
Options: Configure timeout, resources, library marking
Passthrough: Support for custom formatting and result filtering

Stremio Integration¶

Installation Process¶

Access AIOStreams Web Interface:
```
https://aiostreams.rbnk.uk
```
Configure Debrid Services:
Add API keys for your debrid services
Configure service priorities and settings
Test connectivity to ensure services are working
Select Addons:
Choose from preset addons (Torrentio, Comet, MediaFusion, etc.)
Configure addon-specific settings
Add custom addons via manifest URLs
Generate Manifest:
Review configuration and generate Stremio manifest
Copy the manifest URL provided
Install in Stremio:
Open Stremio application
Go to Add-ons section
Paste the AIOStreams manifest URL
Install the addon

Manifest URL Structure¶

https://aiostreams.rbnk.uk/manifest.json?config=base64_encoded_config

Configuration Parameters¶

Addon Selection¶

Preset Addons: Select from pre-configured popular addons
Custom Addons: Add any Stremio-compatible addon
Resource Types: Configure which resources each addon provides (stream, catalog, meta)

Service Configuration¶

Debrid Services: Enable/disable specific debrid services
Service Priority: Order of preference for multiple services
Timeout Settings: Configure request timeouts per addon

Filtering Options¶

Content Filters: Age ratings, certification levels, nudity filters
Quality Filters: Resolution, codec, file size preferences
Language Filters: Subtitle and audio language preferences

Multiple Configurations¶

User Profiles: Create different configurations for different users
Device-Specific: Separate configurations for different devices
Content-Specific: Different settings for movies vs. TV shows

Supported Debrid Services¶

Primary Services¶

Real-Debrid¶

Features: Premium file hosting, instant streaming, torrent caching
API Integration: REST API with authentication via API key
Configuration: REAL_DEBRID_API_KEY
Benefits: Extensive hoster support, reliable performance
Limits: Account-based bandwidth and storage quotas

AllDebrid¶

Features: Multi-hoster support, torrent downloading, streaming
API Integration: RESTful API with JSON responses
Configuration: ALL_DEBRID_API_KEY
Benefits: Wide range of supported hosters, competitive pricing
Specialty: Good for European users, reliable uptime

Premiumize¶

Features: Cloud storage, VPN service, torrent handling
API Integration: Comprehensive REST API
Configuration: PREMIUMIZE_API_KEY
Benefits: Built-in VPN, large storage quotas, privacy-focused
Limits: Higher cost but includes additional services

Secondary Services¶

Debrid-Link¶

Features: Service aggregator with multi-provider support
Configuration: DEBRID_LINK_API_KEY
Benefits: Combines multiple debrid services in one account

Put.io¶

Features: Cloud torrent client with streaming interface
Configuration: PUT_IO_CLIENT_ID and PUT_IO_OAUTH_TOKEN
Benefits: User-friendly interface, good mobile apps

EasyNews¶

Features: Usenet provider with web-based downloading
Configuration: EASYNEWS_USERNAME and EASYNEWS_PASSWORD
Benefits: Access to Usenet content, complementary to torrent services

PikPak¶

Features: Cloud storage with streaming capabilities
Configuration: PIKPAK_USERNAME and PIKPAK_PASSWORD
Benefits: Good Asian content availability

Seedr¶

Features: Browser-based torrent client with streaming
Configuration: SEEDR_API_KEY
Benefits: Free tier available, easy to use

Service Selection Logic¶

AIOStreams handles service selection through: 1. User Configuration: Services are used in the order configured 2. Content Availability: Checks which services have the requested content 3. Service Health: Monitors API response times and success rates 4. Load Balancing: Distributes requests across available services

Common Use Cases¶

1. Simplified Stremio Setup¶

Problem: Complex configuration of multiple addons and debrid services Solution: Single addon that aggregates multiple sources

# Configure once in AIOStreams web interface
# Install single addon in Stremio
# Access content from multiple sources seamlessly

2. Debrid Service Aggregation¶

Problem: Different content available on different debrid services Solution: Configure multiple services in AIOStreams

# Add API keys for Real-Debrid, AllDebrid, Premiumize
# AIOStreams checks all services for content
# Best available stream automatically selected

3. Content Discovery Enhancement¶

Problem: Limited content discovery with single addons Solution: Combine multiple addon sources

# Enable Torrentio for general content
# Enable MediaFusion for live TV and sports
# Enable Comet for fast reliable streams
# All results aggregated in single interface

4. Simplified User Management¶

Problem: Managing multiple addon configurations for family members Solution: Create different AIOStreams configurations

# Create family-friendly configuration with content filters
# Create unrestricted configuration for adults
# Generate separate manifest URLs for each user

5. Development and Testing¶

Problem: Testing custom Stremio addons and configurations Solution: Use custom addon feature in AIOStreams

# Add custom addon via manifest URL
# Test different configurations without permanent installation
# Monitor addon performance and reliability

API Endpoints¶

Health and Status¶

# Service health check
GET /api/v1/status
Response: {"success": true, "data": {"version": "2.8.2", ...}}

# Service health (Docker health check)
GET /health
Response: 200 OK

Stremio Addon Endpoints¶

# Addon manifest
GET /manifest.json?config=base64_config
Response: Stremio addon manifest JSON

# Stream endpoint
GET /{user_id}/stream/{type}/{id}.json
Response: Array of stream objects

# Catalog endpoint (if enabled)
GET /{user_id}/catalog/{type}/{id}.json
Response: Array of catalog items

# Meta endpoint (if enabled)
GET /{user_id}/meta/{type}/{id}.json
Response: Meta information object

Configuration Management¶

# Web interface (configuration UI)
GET /
Response: HTML configuration interface

# Save configuration
POST /configure
Content-Type: application/json
Body: Configuration object

# Export configuration
GET /export
Response: Configuration download

Addon Proxy Endpoints¶

# Proxy requests to configured addons
GET /proxy/{addon_id}/{endpoint}
Headers: Forward original request headers
Response: Proxied addon response

Security Considerations¶

1. Authentication & Authorization¶

Password Protection: Optional addon-level password protection
Secret Key: Session management and security token generation
API Key Storage: Secure storage of debrid service credentials

2. Network Security¶

HTTPS Only: All external traffic encrypted via Traefik
Internal Access: No direct external access to container ports
Firewall Protection: Service protected by host firewall rules

3. Data Security¶

Local Storage: SQLite database stored in persistent volume
Credential Encryption: API keys encrypted in local storage
Session Security: Secure session management with secret keys

4. Access Control¶

Regex Filtering: Optional content filtering based on regex patterns
Rate Limiting: Built-in protection against API abuse
Self-Scraping Prevention: Prevents recursive addon calls

5. Privacy Protection¶

Log Filtering: Sensitive information excluded from logs
No External Dependencies: No data sent to external services except debrid APIs
Local Processing: All configuration and caching handled locally

Troubleshooting¶

Common Issues¶

1. Addon Installation Failures¶

Symptoms: Stremio cannot install the addon, manifest errors Diagnosis:

# Check service health
curl https://aiostreams.rbnk.uk/api/v1/status

# Verify manifest accessibility
curl "https://aiostreams.rbnk.uk/manifest.json?config=your_config"

# Check service logs
docker compose -f aiostreams/docker-compose.yml logs -f

Solutions: - Verify AIOStreams service is running and accessible - Check configuration encoding - ensure Base64 encoding is correct - Validate JSON configuration format - Test manifest URL in browser before adding to Stremio

2. Debrid Service Authentication¶

Symptoms: No streams returned, authentication errors in logs Diagnosis:

# Test debrid service APIs directly
curl -H "Authorization: Bearer $REAL_DEBRID_API_KEY" \
  https://api.real-debrid.com/rest/1.0/user

# Check API key validity in AIOStreams
# View service logs for authentication errors
docker compose -f aiostreams/docker-compose.yml logs | grep -i auth

Solutions: - Verify API keys are correct and not expired - Check debrid service account status and subscription - Update API keys in AIOStreams configuration - Test each service individually

3. No Streams Available¶

Symptoms: Stremio shows "No streams available" for content Diagnosis:

# Check addon configuration
# Verify debrid services are enabled and working
# Test with different content types (movies vs. TV shows)

# Monitor AIOStreams logs during stream requests
docker compose -f aiostreams/docker-compose.yml logs -f

Solutions: - Ensure at least one debrid service is configured and working - Check that appropriate addons are enabled for content type - Verify content is available in debrid service libraries - Test with popular content that should be widely available

4. Performance Issues¶

Symptoms: Slow stream loading, timeouts, poor responsiveness Diagnosis:

# Check resource usage
docker stats aiostreams

# Monitor response times
curl -w "%{time_total}\n" -o /dev/null -s \
  "https://aiostreams.rbnk.uk/api/v1/status"

# Check SQLite database performance
docker exec aiostreams sqlite3 /app/data/db.sqlite ".timeout 1000; VACUUM;"

Solutions: - Increase cache size: DEFAULT_MAX_CACHE_SIZE=2000 - Reduce addon timeout values - Optimize addon selection - disable unused addons - Clear SQLite database if corrupted

5. Configuration Persistence Issues¶

Symptoms: Settings not saved, configuration reset after restart Diagnosis:

# Check volume mount
docker inspect aiostreams | grep -A 10 Mounts

# Verify data directory permissions
docker exec aiostreams ls -la /app/data/

# Check SQLite database accessibility
docker exec aiostreams sqlite3 /app/data/db.sqlite ".tables"

Solutions: - Verify ./data volume is properly mounted - Check file permissions on host data directory - Ensure SQLite database is writable - Backup and restore configuration if database is corrupted

Advanced Troubleshooting¶

Database Maintenance¶

# Backup SQLite database
docker exec aiostreams cp /app/data/db.sqlite /app/data/db.sqlite.backup

# Analyze database
docker exec aiostreams sqlite3 /app/data/db.sqlite "PRAGMA integrity_check;"

# Vacuum database (optimize)
docker exec aiostreams sqlite3 /app/data/db.sqlite "VACUUM;"

# Reset database (nuclear option)
docker exec aiostreams rm /app/data/db.sqlite
docker compose -f aiostreams/docker-compose.yml restart

Network Debugging¶

# Test external connectivity
docker exec aiostreams curl -I https://api.real-debrid.com

# Check DNS resolution
docker exec aiostreams nslookup torrentio.strem.fun

# Monitor network traffic
docker exec aiostreams netstat -an

Performance Monitoring¶

# Real-time resource monitoring
docker stats aiostreams --no-stream

# Check disk I/O
docker exec aiostreams iostat 1 5

# Monitor SQLite queries (if available)
docker exec aiostreams sqlite3 /app/data/db.sqlite ".log stderr .timer on"

Comparison with Stremthru¶

When to Use AIOStreams¶

Choose AIOStreams when: - Simplicity is Priority: No database setup required - Lightweight Deployment: Minimal resource requirements - Stremio-Focused: Primary use case is Stremio integration - Easy Configuration: Web-based setup preferred - Preset Addons: Want pre-configured popular addons - Self-Contained: Prefer everything in one container

When to Use Stremthru¶

Choose Stremthru when: - Advanced Features: Need proxy functionality and IP bypassing - Multiple Clients: Supporting various media players beyond Stremio - Complex Workflows: Integration with databases and external services - Analytics: Detailed usage tracking and monitoring required - Enterprise Use: Multi-user environments with complex requirements - Custom Development: Need to build on top of the service

Feature Comparison¶

Feature	AIOStreams	Stremthru
Database	SQLite (local)	PostgreSQL + Redis
Setup Complexity	Simple	Complex
Resource Usage	Low	Medium-High
Stremio Integration	Native	Supported
Proxy Functionality	No	Yes
IP Bypass	No	Yes
Multi-Client Support	Limited	Extensive
Analytics	Basic	Advanced
Custom Addons	Web UI	API/Config
Preset Configurations	Many	Limited
Web Interface	Full featured	Basic
API Flexibility	Limited	Extensive

Migration Considerations¶

From Stremthru to AIOStreams¶

Advantages: - Simplified maintenance and updates - Reduced resource consumption - Better Stremio-specific features - Easier configuration management

Limitations: - Loss of proxy functionality - No IP restriction bypassing - Reduced analytics capabilities - Limited multi-client support

From AIOStreams to Stremthru¶

Advantages: - Advanced proxy features - Better multi-client support - Enhanced analytics and monitoring - More flexible API

Considerations: - Increased complexity and resource requirements - Database setup and maintenance - More complex configuration process

Backup Considerations¶

Critical Data¶

Configuration Database:
SQLite database: /app/data/db.sqlite
Contains addon configurations, API keys, user settings
Environment Configuration:
.env file with service settings
docker-compose.yml with service definition
Data Directory:
Complete /app/data directory (logs, cache, database)

Backup Strategy¶

# Stop service for consistent backup
docker compose -f aiostreams/docker-compose.yml stop

# Backup SQLite database
cp aiostreams/data/db.sqlite _backup/aiostreams-db-$(date +%Y%m%d).sqlite

# Backup entire data directory
tar -czf _backup/aiostreams-data-$(date +%Y%m%d).tar.gz aiostreams/data/

# Backup configuration
cp aiostreams/.env _backup/aiostreams-env-$(date +%Y%m%d)
cp aiostreams/docker-compose.yml _backup/aiostreams-compose-$(date +%Y%m%d)

# Restart service
docker compose -f aiostreams/docker-compose.yml start

Automated Backup¶

# Add to daily backup script
#!/bin/bash
DATE=$(date +%Y%m%d)
BACKUP_DIR="_backup"

# Create consistent backup
docker compose -f aiostreams/docker-compose.yml exec aiostreams \
  sqlite3 /app/data/db.sqlite ".backup /app/data/db-backup-$DATE.sqlite"

# Copy to backup directory
docker cp aiostreams:/app/data/db-backup-$DATE.sqlite \
  $BACKUP_DIR/aiostreams-db-$DATE.sqlite

# Cleanup old backups (keep 14 days)
find $BACKUP_DIR -name "aiostreams-*" -mtime +14 -delete

Restoration Process¶

Service Stop: docker compose -f aiostreams/docker-compose.yml down
Restore Configuration: Copy .env and docker-compose.yml
Restore Database: Copy SQLite database to ./data/db.sqlite
Restore Data Directory: Extract full data backup if needed
Service Start: docker compose -f aiostreams/docker-compose.yml up -d
Verify Configuration: Check service health and addon functionality

Backup Testing¶

# Test database integrity
sqlite3 aiostreams/data/db.sqlite "PRAGMA integrity_check;"

# Test service after restoration
curl https://aiostreams.rbnk.uk/api/v1/status

# Verify configuration import
# Test addon manifest generation in web interface

Backup Schedule¶

Daily: Included in infrastructure backup (4 AM via Rclone to Cloudflare R2)
Retention: 14 days as per infrastructure backup policy
Critical: Configuration database contains API keys - secure backup required
Testing: Monthly restoration tests to verify backup integrity

Integration with Infrastructure¶

AIOStreams integrates seamlessly with the existing infrastructure:

Monitoring: Health checks via Docker health check, monitored by Uptime Kuma
Logging: Container logs available via Docker Compose
Notifications: Service alerts can be configured via monitoring stack
Backup: Included in automated infrastructure backup system
Updates: Managed by Watchtower for automated container updates
DNS: Managed via Cloudflare DNS with automatic SSL certificates
SSL: Automatic HTTPS via Traefik with Cloudflare certificates

For additional support and configuration details, refer to: - Official AIOStreams Repository - Stremio Addon SDK Documentation - Infrastructure Monitoring Guide - Backup and Recovery Documentation