mrrobotogit/gostream repository overview

GoStream

The most advanced BitTorrent engine and FUSE virtual filesystem for live streaming to your private Plex/Jellyfin library. Forget Real-Debrid.

GoStream exposes a custom FUSE virtual filesystem where every .mkv file is a perfect illusion: it looks like a real file on disk, but every byte is served live from a BitTorrent swarm on demand. No downloading. No temp files. No storage quota.

The BitTorrent engine runs inside the same OS process as the FUSE layer, connected by an in-memory io.Pipe(). When Plex/Jellyfin reads a byte range, there is no HTTP round-trip, no serialization, no proxy overhead — just bytes, flowing directly from peers through RAM to the media server at full speed.

The result: 4K HDR Dolby Vision, fully seekable, starting in 0.1 seconds — even on a Raspberry Pi 4.

This is not a torrent client with a media server bolted on. The FUSE filesystem is the product — custom-built from scratch around the constraints of torrent streaming: non-sequential byte-range requests, multi-gigabyte files that must be seekable at any position, and a Plex/Jellyfin scanner that probes every file in a library of hundreds of titles on startup.

⁠What's included

• Custom FUSE virtual filesystem: every .mkv is a live torrent presented to the media server as a real file. No temp files, no persistent downloads — torrent data never touches the disk.
• The embedded torrent engine is GoStorm, a fork of TorrServer Matrix 1.37⁠ and anacrolix/torrent v1.55⁠, running in-process with the FUSE layer (no separate HTTP proxy). Both upstreams carry targeted streaming patches not present in the originals.
• Built-in sync engine discovers trending and popular titles from TMDB on a schedule, finds the best torrent via Prowlarr (with Torrentio fallback), and registers them automatically. All in pure Go — no Python, no external scripts. Existing entries are upgraded when a better version becomes available (e.g. 1080p → 4K HDR).
• TV Series sync runs on schedule with a fullpack-first season pack strategy and a Plex-compatible directory structure.
• Add a title to your Plex cloud watchlist and it shows up in your library within the hour.
• NAT-PMP for WireGuard setups: GoStream requests an inbound port mapping from the VPN gateway and installs iptables REDIRECT rules, all without a restart.
• A peer blocklist of ~700,000 IP ranges is downloaded on startup and refreshed every 24 hours, injected into the torrent engine before any connection is made.
• Plex & Jellyfin Webhook integration: media.play triggers Priority Mode with aggressive piece prioritization. IMDB-ID is extracted from the raw payload via regex, so it works even when the media server sends localized titles. Jellyfin is supported natively via JSON body — no code change, no plugin hacks.
• The embedded Control Panel at :9080/control lets you adjust all FUSE and engine settings live, compiled directly into the binary.
• The Health Monitor Dashboard at :9080/dashboard shows a real-time speed graph, an active stream panel with movie poster and quality badges, sync controls, and system stats — all embedded in the Go binary.
• Everything ships as a single binary: GoStorm engine, GoStream, metrics, control panel, and webhook receiver in one gostream executable.

⁠Control Panel

⁠Table of Contents

• The Setup: GoStream + Plex/Jellyfin/Infuse on Apple TV⁠
• How the Magic Works⁠
• AI GoStream Pilot - Experimental⁠
• Architecture⁠
• Core Engineering⁠
• Performance⁠
• Requirements⁠
• Quick Install⁠
• How-To Guide⁠
• Control Panel⁠
• Health Monitor⁠
• Configuration Reference⁠
• Sync Engine⁠
• Prowlarr Integration⁠
• Plex/Jellyfin & Samba Setup⁠
• Build from Source⁠
• Docker⁠
• API Reference⁠
• Troubleshooting⁠
• Donate⁠
• License⁠

⁠The Setup: GoStream + Plex/Jellyfin/Infuse on Apple TV

The end result: you open Infuse on your Apple TV, your entire movie library appears with posters and metadata, you press Play on a 4K Dolby Vision film and it starts in under a second. No buffering. No "downloading...". No subscription to Real-Debrid or any external service. Everything runs on a single board computer or any always-on Linux box in your home.

⁠How the three pieces fit together

GoStream runs on your Linux device — a Raspberry Pi, a NAS, a VPS, or any always-on machine. It creates a virtual hard drive that looks completely real to the rest of your network: it contains thousands of .mkv files, each the correct size, each seekable. In reality, none of those files exist on disk. When anything reads a byte, GoStream silently fetches it in real-time from the BitTorrent network and passes it through.

Plex (or Jellyfin, or any media server) sees this virtual hard drive as a normal media library. It scans the files, downloads posters and descriptions from the internet, tracks what you've watched, and makes everything available on your home network, just like it would with a real NAS.

Infuse on Apple TV connects to your Plex/Jellyfin library and plays the files using Direct Play: it reads the video stream directly from the file, with no conversion or re-encoding. This is why it handles 4K HDR Dolby Vision effortlessly, even though it is coming from a torrent in real time.

Because GoStream exposes standard .mkv files on a standard filesystem, any player or media server that can read a network share works: Plex, Jellyfin, Emby, Kodi, VLC, mpv, or anything else. No plugins, no special configuration.

⁠How your library gets populated automatically

GoStream includes a built-in sync engine that runs on a schedule and keeps your library up to date without any manual intervention.

Every day, the engine queries TMDB (The Movie Database) for the latest releases, trending titles, and popular movies. For each title it finds, it searches Prowlarr (with Torrentio fallback) for the best available torrent (preferring 4K Dolby Vision, falling back to 1080p). If a good torrent is found, it registers it in GoStorm and creates the corresponding virtual .mkv file in the library.

The next time the media server scans, it finds a new file, downloads the poster and description, and the film appears in your library ready to play.

If a better version of a film becomes available later (for example a 4K HDR release of a title you already have in 1080p), the engine replaces it automatically.

TV series work the same way: the sync engine finds new seasons and episodes, organises them in the Plex/Jellyfin-compatible folder structure (Show Name (Year)/Season.01/), and they appear in your library within the week.

You can also add a title to your Plex Watchlist from any device and it will appear in your library within the hour.

⁠Prowlarr Integration (Resilience)

To ensure the system remains functional even when public aggregators like Torrentio are down, GoStream includes a Prowlarr Adapter. This allows you to use your own self-hosted Prowlarr instance as the primary source for torrents.

The sync engine implements a Strict Fallback logic: it first queries your Prowlarr indexers using IMDB IDs for maximum precision. If no results are found locally, it automatically falls back to Torrentio.

Configuration is done via config.json (or the Control Panel → Prowlarr Indexer section):

"prowlarr": {
  "enabled": true,
  "api_key": "your-api-key",
  "url": "http://192.168.1.x:9696"
}

See the Prowlarr Adapter Documentation⁠ for technical details.

⁠100% local, no subscriptions

GoStream has no external dependency at playback time. No third-party service, no monthly fee, no data leaving your home. Your library is always available, even without an internet connection, and it never disappears because a remote service went down.

⁠Why Infuse starts in under a second

When you press Play, Infuse immediately reads the beginning and end of the file to load the video index and seek tables. On a real hard drive this is instant. GoStream replicates this with an SSD warmup cache: the first 64 MB and last few MB of every file are pre-cached on the Pi's SSD during the initial Plex/Jellyfin library scan. By the time you press Play, those bytes are already on disk and Infuse gets them in milliseconds.

⁠Why your library survives a reboot

Every file on a real filesystem has a permanent ID called an inode. Plex/Jellyfin and Infuse use these IDs to recognize files across restarts, so they know "this is the same film I scanned last week" and do not re-download metadata or reset your watch history.

On a standard virtual filesystem, these IDs are random and change every time the system restarts. GoStream solves this by persisting a permanent inode map to a SQLite database (STATE/gostream.db). After a reboot, every virtual .mkv gets back the exact same ID it had before. To Plex/Jellyfin and Infuse, it is indistinguishable from a file that never moved.

⁠When you press Play: the full chain

1. You press Play on Infuse (Apple TV) -> Infuse requests the file from Plex/Jellyfin
2. Plex/Jellyfin reads the file from GoStream's virtual filesystem
3. Plex or Jellyfin sends a webhook to GoStream: "user started playing this film"
4. GoStream identifies the torrent from the IMDB ID and switches to Priority Mode: all bandwidth focuses on the film you are watching, background activity is paused
5. Bytes flow: BitTorrent peers -> GoStream RAM -> Plex/Jellyfin -> Infuse -> your TV
6. If you seek, GoStream jumps directly to that position in the torrent with no re-buffering from the start

⁠How the Magic Works

Plex/Jellyfin reads /mnt/gostream-mkv-virtual/movies/Interstellar.mkv. From Plex/Jellyfin's perspective, it's a normal 55 GB file on a local disk. In reality, the file does not exist. The FUSE kernel module intercepts the read, calls into GoStream, and GoStream serves the exact bytes from a three-layer cache — backed by a live BitTorrent swarm.

What makes this non-trivial: a FUSE filesystem that backs a real directory of static files is straightforward. A FUSE filesystem that must handle non-sequential byte-range requests across hundreds of files, each backed by an independent torrent with variable peer availability, while a Plex/Jellyfin scanner hammers every inode in parallel — that required building every subsystem from scratch.

⁠Architecture

BitTorrent Peers ←→ GoStorm Engine (:8090)
                         │
              Native Bridge (In-Memory Pipe)
              Zero-Network, Zero-Copy Hot Path
                         │
         ┌───────────────────────────────────┐
         │       GoStream FUSE Layer         │
         │  L1: Read-Ahead Cache (256 MB)    │
         │  L2: SSD Warmup Head (64 MB/file) │
         │  L3: SSD Warmup Tail (16 MB/file) │
         └───────────────────────────────────┘
                         │
         /mnt/gostream-mkv-virtual/*.mkv  (FUSE mount)
                         │
         Samba share (smbd, oplocks=no, vfs objects=fileid)
                         │
         Synology CIFS mount (serverino, vers=3.0)
                         │
         Plex/Jellyfin Media Server libraries

⁠Port Map

⁠Core Engineering

⁠1. Zero-Network Native Bridge

GoStream runs as a single process — GoStorm engine and GoStream FUSE compiled into one binary. When Plex/Jellyfin reads a .mkv byte range, the FUSE layer calls directly into GoStorm via an in-memory io.Pipe(): no TCP round-trip, no HTTP header parsing, no serialization, no proxy overhead. Metadata operations are direct Go function calls. This eliminates the network RTT that causes stuttering in every HTTP-based torrent streaming proxy on constrained hardware.

⁠2. Two-Layer SSD Warmup Cache (optional)

An optional SSD cache that improves performance for repeat playback. It can be enabled and configured in the Control Panel → GoStorm settings, and is independent of the core streaming path — GoStream works without it, just with a longer cold-start time.

When enabled, the head cache stores the first 64 MB of each file on SSD on first play. On repeat playback, TTFF drops to < 0.01 s (SSD reads at 150–200 MB/s, compared to 2–4 s for cold torrent activation).

The tail cache stores the last 16 MB separately. MKV files keep their Cues (seek index) near the end, and Plex/Jellyfin probes that region before confirming playback. Without tail cache, the seek bar may render as unavailable on first open.

The default quota is 32 GB with LRU eviction by write time, enough for around 150 films. Media server library scans read the first 1 MB of every file, which is enough to populate the head cache automatically — no manual warming needed.

⁠3. Webhook Integration & Smart Streaming

GoStream embeds a webhook receiver at :9080/plex/webhook (also /webhook). Both Plex and Jellyfin are supported. When a media.play event arrives:

1. IMDB extraction — Extracts the IMDB ID from the raw JSON payload using imdb://(tt\d+) regex before json.Unmarshal. This is intentional: Plex uses a non-standard Guid array format that causes a silent UnmarshalTypeError when decoded normally.
2. Priority Mode — GoStorm is instructed to aggressively prioritize pieces covering the exact byte range being played.
3. Tail freeze — The MKV Cues segment is not evicted while the film is playing.
4. Fast-drop on stop — Torrent retention shrinks from 60 s to 10 s, freeing peers immediately.

Plex — Settings → Webhooks → Add Webhook:

http://<your-pi-ip>:9080/plex/webhook

Jellyfin — Install the Webhook plugin⁠, then add one webhook with events PlaybackStart, PlaybackStop, PlaybackProgress:

Template:

{"event":"{{NotificationType}}","Metadata":{"title":"{{{Name}}}","grandparentTitle":"{{{SeriesName}}}","librarySectionType":"{{ItemType}}","guid":"imdb://{{Provider_imdb}}","Guid":[{"id":"imdb://{{Provider_imdb}}"}]}}

GoStream normalizes Jellyfin's native event names (PlaybackStart→media.play, PlaybackStop→media.stop) and item types (Movie→movie, Episode→show) internally.

⁠4. Adaptive Responsive Shield

Two read modes, automatically managed:

When a corrupt piece is detected (MarkNotComplete()), the Adaptive Shield switches to Strict Mode for 60 seconds and then automatically restores Responsive. The mode transition uses an atomic boolean, so there is no mutex contention on the hot read path.

⁠5. Seek-Master Architecture

Accurate, low-latency seeking in large 4K files required five coordinated fixes:

⁠6. 32-Shard Read-Ahead Cache

The 256 MB read-ahead budget is split across 32 independent shards, each keyed by hash of file path and offset, each with its own LRU and mutex. Multiple Plex/Jellyfin sessions and scanner threads read concurrently without contending on a single lock. Both Put() and Get() use defensive copies to prevent use-after-free races from channel-pool reuse.

⁠7. Native Sync Engine (Go)

All sync logic runs natively inside the Go binary — no Python, no external scripts, no subprocess overhead.

Quality ladder: 4K DV > 4K HDR10+ > 4K HDR > 4K > 1080p REMUX > 1080p
Minimum seeders: 15 (main sync), 10 (watchlist sync, for older films)

All sync state (episode registry, negative caches, scheduler state) is persisted in STATE/gostream.db (SQLite). The built-in scheduler replaces system cron and is configurable from the Control Panel.

⁠8. NAT-PMP Native VPN Port Forwarding

When BitTorrent traffic is routed through a WireGuard VPN, the home router's port forwarding rules are bypassed by the tunnel. GoStream runs a NAT-PMP sidecar that periodically requests a TCP+UDP port mapping from the VPN gateway, installs iptables PREROUTING REDIRECT rules, and updates GoStorm's listen port — all without a restart.

⁠9. IP Blocklist ~700k Ranges

GoStream downloads a gzipped BGP/country blocklist on startup and refreshes it every 24 hours. The ranges are injected directly into anacrolix/torrent's IP filter, so known-bad actors are blocked before any connection attempt.

⁠10. Profile-Guided Optimization (PGO)

The binary is compiled with -pgo=auto. Go 1.24 reads default.pgo to inline hot paths and optimize branch prediction using real production profiling data. On Pi 4 Cortex-A72 (no hardware AES/SHA1), PGO alone accounts for ~5–7% CPU reduction.

⁠11. GoStorm Engine Deep Fork of TorrServer Matrix + anacrolix/torrent

GoStorm is a fork of TorrServer Matrix 1.37⁠ (BitTorrent management layer) and anacrolix/torrent v1.55⁠ (peer protocol engine). Both upstreams have been patched extensively for streaming correctness and performance — fixes that are not present in the original projects:

⁠Performance

⁠Requirements

⁠Quick Install

curl -fsSL https://raw.githubusercontent.com/MrRobotoGit/gostream/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

The interactive installer handles everything end-to-end:

1. Installs system dependencies (fuse3, libfuse3-dev, gcc, samba, git)
2. Prompts for all required paths, Plex credentials, TMDB key, and NAT-PMP settings
3. Generates config.json from config.json.example
4. Creates `GoStrea