Installation and Troubleshooting

🛠️ Installation & Troubleshooting

Everything you need to know about installing Flux, handling macOS Gatekeeper, and resolving common streaming questions.

---

1. Choosing the Right Release

Flux is distributed in two optimized editions on the Releases Page:

Release File	Supported macOS	Visual Style	Architecture
Flux.dmg	macOS 26.1+	Modern Apple Liquid Glass	Apple Silicon (arm64)
Flux-macOS15.dmg	macOS 15.0+ (Sequoia)	Translucent Vibrancy Material	Apple Silicon (arm64)

Both releases feature identical capabilities, streaming engines, and hardware-accelerated playback.

---

2. Installation & First Launch (Gatekeeper Notice)

Because Flux is independent, community-driven open-source software distributed outside the paid Apple Developer Program, macOS Gatekeeper may show an "unidentified developer" or "app cannot be opened" warning on first launch.

Standard First-Launch Approval (Finder):

1. Open the downloaded .dmg and drag Flux.app into your Applications folder.
2. Open your Applications folder in Finder.
3. Right-Click (or Control-Click) on Flux.app and select Open.
4. In the dialog that appears, click Open. macOS will permanently remember your authorization.

One-Click Terminal Approval (Alternative):

If macOS blocks launch, open your Terminal and paste this command:

xattr -cr /Applications/Flux.app

This strips the quarantine extended attribute and allows Flux to launch instantly.

---

3. Frequently Asked Questions & Troubleshooting

Q: Why is a torrent stream buffering or stuck on 0 KB/s?

• Cause: The torrent swarm may lack active seeders, or your internet service provider (ISP) may be throttling P2P BitTorrent traffic.
• Solution:
  1. Press O during playback to open the Stream Picker and select a source with $\ge 25$ active seeders.
  2. Or, configure a Debrid provider (e.g. Real-Debrid in Torrentio) in Settings → Addons to stream via high-speed encrypted HTTP without relying on seeders.

Q: Subtitles are out of sync with actor dialogue. How do I fix this?

• Press S to cycle through alternative subtitle tracks provided by the file or OpenSubtitles.
• If timing is slightly off, click the Tuning icon (🎛️) in the player control bar to open the Secret Player HUD.
• Navigate to Subtitles Calibration and adjust the delay offset in seconds or milliseconds until lip-sync is perfect.

Q: Why isn't Dolby Atmos or DTS lighting up on my home theater receiver?

• Make sure your Mac is connected directly to your AV Receiver or soundbar via HDMI.
• In Flux, open Settings (⌘,) → Playback and turn on Audio Passthrough (Atmos / DTS).
• Note: Passthrough is disabled over Bluetooth and AirPods because those connections only support 2-channel stereo.

Q: How do I reclaim disk space used by streams?

• In Flux, open Settings (⌘,) → Advanced.
• Under Storage, check your current cache footprint. You can reduce the Torrent Cache Limit (e.g. down to 2 GB) or click Purge Torrent Cache to immediately reclaim all disk space.