Streaming and Playback

⚡ Streaming & Playback Architecture

Flux combines an embedded BitTorrent streaming engine, an intelligent stream racing controller, and a hardware-accelerated libmpv player to deliver an ultra-fast streaming experience.

---

1. How Streaming Works in Flux

When you select a movie or episode in Flux, several background components coordinate to begin playback:

[Stremio Addons] ──▶ [Stream Manager] ──▶ [Stream Racing Controller]
                                                    │
                                     (Selects Fastest Stream)
                                                    │
                                                    ▼
[libmpv in CAOpenGLLayer] ◀── [Loopback Proxy] ◀── [FluxEngine (Go Daemon)]

1. Addon Resolution: Addons return candidate torrent infohashes or direct HTTP URLs.
2. Transparent Stream Proxy: A lightweight loopback HTTP server handles range requests and automatic reconnects if network packets drop.
3. FluxEngine: A high-performance, embedded Go daemon downloads video chunks sequentially (beginning with container headers at byte 0) directly into a local LRU cache.
4. Hardware Demuxing: libmpv reads the incoming stream and passes video frames directly to the Apple Silicon GPU via Metal/OpenGL.

---

2. Flux Mode: Autonomous Stream Racing

Traditional media centers require users to manually scroll through dozens of torrent streams, guessing which link has active seeders and will actually play without buffering.

Flux Mode eliminates this friction entirely.

How the Stream Racing Controller Works:

When you click Play, Flux runs an automated race across the candidate sources:

• Health Scoring: Streams are evaluated using active seeder counts, file size heuristics, and host reputation.
• Container Awareness:
  • MKV: Prioritized because Matroska files place the SeekHead index at byte 0, allowing near-instant demuxing.
  • FastStart MP4: Releases from trusted groups (PSA, QxR, GalaxyRG, FLUX) with moov atoms at the front of the file are boosted.
• Auto-Fallover: If a stream stalls during handshake or has inactive seeders, Flux seamlessly discards it and falls over to the runner-up stream in the race without interrupting the user.

---

3. Playback Engine: libmpv in CAOpenGLLayer

Rather than using basic AVPlayer or web video tags, Flux embeds libmpv linked directly to a native macOS CAOpenGLLayer:

• Universal Codec Compatibility: Plays virtually any video and audio format without transcoding—including 10-bit HEVC, AV1, VP9, H.264, VC-1, DTS-HD MA, Dolby TrueHD, FLAC, and Opus.
• Subtitles Engine (libass): High-performance ASS/SSA subtitle rendering with full font styling, positioning, and zero dropped frames.
• Color Accuracy: Full support for HDR10 and Dolby Vision (Profile 5 and Profile 8 via libdovi), tone-mapped accurately to Apple Liquid Retina XDR displays.

---

4. Intelligent Safeguards

🛡️ Frozen-Frame Watchdog

If network congestion causes a torrent stream to freeze mid-playback (> 1 second stuck on the same frame while in playing state), Flux's watchdog automatically:

1. Displays the non-intrusive buffering indicator.
2. Requests urgent piece priority from FluxEngine.
3. Seamlessly resumes playback the millisecond new frames arrive.

🎧 Disconnect Auto-Pause

Flux listens to CoreAudio default output device changes. If you are watching with AirPods or Bluetooth headphones and they disconnect or run out of battery, Flux immediately pauses playback to prevent loud audio from blasting through your Mac's built-in speakers.

🔊 Audio Passthrough (Atmos / DTS)

For home theater enthusiasts connecting their Mac to an AV Receiver or soundbar via HDMI:

• Enable Settings → Playback → Audio Passthrough.
• Flux bitstreams uncompressed multichannel audio directly over HDMI, enabling native hardware decoding for Dolby Atmos and DTS:X.