UsenetStreamer Documentation

UsenetStreamer provides several modes to handle stream reliability and health checks:

• none: No health checks, no auto-advance.
• auto-advance: No health checks; fallback only when a stream fails.
• health-check: Upfront triage (downloads samples) before returning the stream list.
• health-check-auto-advance: Upfront filtering plus fallback queueing.
• smart-play: Background health checks; returns results immediately, verifies in background, and picks healthy results.
• smart-play-auto-advance: Background health checks + Smart Play + auto-advance protection.

To use UsenetStreamer in Stremio, you need two distinct tokens for security:

1. Admin Token (ADDON_SHARED_SECRET): Used to access the dashboard and manage settings.
2. Stream Token (ADDON_STREAM_TOKEN): A separate token used specifically for streaming requests. It cannot access the admin dashboard.

Manifest URL Pattern: https://<your-addon-domain>/<ADDON_STREAM_TOKEN>/manifest.json

Use Docker Compose for a structured deployment. Ensure you define the ADDON_SHARED_SECRET and map a volume to CONFIG_DIR to ensure your admin settings survive container recreations.

services:
  usenetstreamer:
    image: ghcr.io/sanket9225/usenetstreamer:latest
    container_name: usenetstreamer
    restart: unless-stopped
    ports:
      - "7000:7000"
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "1"
    environment:
      ADDON_SHARED_SECRET: super-secret-token
      CONFIG_DIR: /data/config
    volumes:
      - ./usenetstreamer-config:/data/config

The Admin Dashboard allows you to edit runtime settings, test connections to indexers/NNTP/NZBDav, and copy your manifest URL. Access it using your ADDON_SHARED_SECRET (the ADDON_SHARED_SECRET environment variable).

URL Pattern: https://<your-addon-domain>/<ADDON_SHARED_SECRET>/admin/

Run these commands on a fresh Ubuntu 22.04 VPS to install the Docker engine and Compose plugin required to run the UsenetStreamer stack.

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER
newgrp docker

After creating your docker-compose.yml, launch the stack and perform the following configuration steps:

1. Launch:

   docker compose pull
   docker compose up -d

2. Configure NZBDav: Visit http://your-vps-ip:3000. Add your Usenet provider credentials, set up WebDAV username/password, and note the API URL.
3. Configure UsenetStreamer: Visit http://your-vps-ip:7000/<ADDON_SECRET>/admin/.
   • Paste your NZBDav API/WebDAV info and test the connection.
   • Enter Easynews credentials or add direct Newznab endpoints.
   • (Optional) Connect Prowlarr/NZBHydra if running externally.

UsenetStreamer is compatible with most platforms that can load HTTPS manifests and handle externalPlayer hints. The following platforms have been tested and verified:

• Stremio 4.x desktop (Windows/Linux)
• Stremio 5.x beta
• Android TV / Mobile
• iOS (via Safari or TestFlight)
• Web (Chromium-based browsers)
• tvOS / Apple TV (Omni, Vidi, or Fusion)

To expose UsenetStreamer to the internet securely, follow these steps:

1. Open UFW Ports: Allow traffic for SSH, HTTP, HTTPS, and your service ports (3000, 7000).

   sudo ufw allow 22/tcp
   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   sudo ufw allow 3000/tcp
   sudo ufw allow 7000/tcp
   sudo ufw enable

   *Note: You must also allow these ports in your Cloud Provider's firewall (e.g., Oracle Security Lists, AWS Security Groups).* 

2. **Install Caddy**: Install Caddy to handle HTTPS via reverse proxy.

3. **Configure Caddyfile**: Create `/etc/caddy/Caddyfile` with your DuckDNS subdomain:

mystreamer.duckdns.org { reverse_proxy 127.0.0.1:7000 }

4. **Reload Caddy**: `sudo systemctl reload caddy`.

Once the setup is complete and connection tests pass in the UsenetStreamer dashboard, add the addon to Stremio using the following URL format:

https://<your-duckdns-subdomain>.duckdns.org/<ADDON_SECRET>/manifest.json

Before starting the installation, ensure you have the following services and accounts ready:

1. Usenet Provider: An account with a provider like Newshosting, Easynews, or Eweka.
2. Indexer/API Access: You can use the built-in Easynews bridge (requires username/password), add direct Newznab APIs (e.g., NZBGeek, Usenet-Crawler) via the admin panel, or optionally use Prowlarr/NZBHydra.
3. DuckDNS Account (Optional): Required only if you want public HTTPS access. For local/LAN use, you can use your server's IP directly.

Once the container is configured, you can add the addon to Stremio v5 (Windows Desktop version).

Option A: Web Interface In the UsenetStreamer admin panel, click "Install via Stremio Web" or "Open in Stremio App".

Option B: Manual Installation

1. Open Stremio.
2. Navigate to Settings → Addons.
3. Paste the following URL into the search/addon bar: http://localhost:7000/manifest.json.
4. Click Install.

To run UsenetStreamer in Windows Native Mode (streaming NZBs directly to Stremio v5), you must first install Docker Desktop with WSL 2 enabled. Once Docker is running, use the following command in PowerShell to create and run the container.

Note: Replace MySecretToken123 with a unique password to protect your admin panel.

docker run -d `
  --name usenetstreamer `
  --restart unless-stopped `
  -p 7000:7000 `
  -v usenetstreamer_config:/app/config `
  -e STREAMING_MODE=native `
  -e ADDON_BASE_URL=http://localhost:7000 `
  -e ADDON_SHARED_SECRET=MySecretToken123 `
  ghcr.io/sanket9225/usenetstreamer:latest