mediastorm

A streaming media server with native mobile and TV apps. mediastorm supports:

• Usenet
• Real Debrid/Torbox/AllDebrid

Scraping supports:

• Torrentio
• Jackett
• AIOStreams
• Zilean
• Newznab indexers

Discord: https://discord.gg/kT74mwf4bu

Setup

mediastorm requires both a backend server and a frontend app. The frontend app on its own does nothing - it needs a running backend to connect to.

Backend Deployment

Deploy the backend using Docker Compose (or use the example in the repo):

1. Create a docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    container_name: mediastorm-postgres
    environment:
      POSTGRES_DB: mediastorm
      POSTGRES_USER: mediastorm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-mediastorm}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mediastorm"]
      interval: 5s
      timeout: 5s
      retries: 5

  mediastorm:
    image: godver3/mediastorm:latest
    container_name: mediastorm
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "7777:7777"
    volumes:
      # User data folder containing settings.json, streams, and cache
      - /path/to/your/cache:/root/cache
    environment:
      - TZ=${TZ:-UTC}
      - DATABASE_URL=postgres://mediastorm:${POSTGRES_PASSWORD:-mediastorm}@postgres:5432/mediastorm?sslmode=disable
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "http://localhost:7777/health"]
      interval: 30s
      timeout: 3s
      start_period: 15s
      retries: 3

volumes:
  postgres_data:

The cache folder will contain settings.json and stream metadata. All user data (accounts, watch history, playback progress, etc.) is stored in PostgreSQL.

1. Start the containers:

docker compose up -d

The backend will be available at http://localhost:7777. The default login is admin/admin for both the frontend app and the admin web UI.

Upgrading from a previous version: On first startup with the new compose file, mediastorm will automatically migrate your existing JSON data into PostgreSQL. Your original JSON files are preserved with a .migrated suffix in the cache directory.

Custom Postgres password: Set the POSTGRES_PASSWORD environment variable before starting:

POSTGRES_PASSWORD=your_secure_password docker compose up -d

⚠️ Notice: mediastorm is developed with the assistance of large language models (LLMs). While best efforts have been made to ensure security and code integrity, use this software at your own risk. mediastorm is not designed to be directly exposed to the internet — for safe remote access, use a VPN or overlay network like Tailscale to keep your server private while still accessible from your devices.

Connection Invites / Iroh Remote Access

mediastorm includes an Iroh-based connection invite system for remote app access without opening ports or setting up a reverse proxy. In the admin panel, create a connection invite, share the generated code with the person you want to connect, and have them enter it from the app Login screen. They still need a valid mediastorm username and password, either for your account or a sub-account you created for them.

At a high level, the backend creates both a full Iroh invite and a shorter connection code. The backend publishes a temporary DHT rendezvous record that lets the frontend use the short code to find the full invite. That record is signed with a key derived from the short code, so the public DHT record does not directly identify your backend. Once the frontend receives the full invite, it dials the backend over Iroh, using direct connectivity or hole punching where possible. Initial reachability can use Iroh relays when needed, but direct connections are preferred.

Traffic remains encrypted between the frontend and your backend even when a relay is used. A relay can forward packets, but it cannot read the HTTP requests, API responses, or media bytes inside the Iroh connection. After the app connects successfully, the short code is claimed and is no longer reusable.

Remote access through this path depends on network conditions and may not work everywhere. It may also be slower than LAN or local-network playback, especially for high-bitrate video. When connected through an Iroh bridge, only the built-in player is supported; external players such as VLC or Infuse will not work.

Frontend Apps

The frontend is built with React Native and supports iOS, tvOS, Android, and Android TV.

iOS / tvOS

Available on TestFlight:

• iOS: Join TestFlight
• tvOS: Join TestFlight

Updates: Incremental updates are delivered automatically via OTA. Larger updates require updating through TestFlight.

Android / Android TV

Download the latest APK: Releases

Updates: Incremental updates are delivered automatically via OTA. Larger updates require manually downloading the new APK from GitHub Releases or using Downloader (code listed with each release).

Configuration

Access the admin panel at http://localhost:7777/admin to configure all settings.

Required API Keys

mediastorm requires API keys from TMDB and TVDB for metadata (posters, descriptions, cast info, etc.):

Enter these keys in the admin panel under Settings → Metadata.

AI Recommendations (Gemini)

mediastorm can use Google's Gemini AI to generate personalized "Recommended For You" lists based on your watch history and watchlist. This is entirely optional — without a key, mediastorm still provides TMDB-based "Because you watched..." recommendations.

Setup:

1. Go to Google AI Studio and sign in with a Google account
2. Click Create API Key and copy it
3. In the mediastorm admin panel, go to Settings → Metadata and paste the key into the Gemini API Key field
4. Save — recommendations will appear in the Lists tab under "Recommended For You"

Cost: Gemini 2.0 Flash is used, which has a generous free tier (1,500 requests/day). A typical user generates ~1 request per day (results are cached for 24 hours per user), so this should remain free for personal use.

Acknowledgments

Thanks to nzbdav and altmount for paving the way with usenet streaming.

Inspired by plex_debrid and Riven.

Special thanks to Parsett (PTT) for media title parsing.

Powered by FFmpeg for media processing and yt-dlp for trailer fetching.

Native playback powered by KSPlayer on iOS/tvOS, ExoPlayer and MPV on Android/Android TV.

License

MIT