Settings Guide

⚙️ Settings Guide

Open Flux Settings anytime by pressing ⌘ + , (Command + Comma) or selecting Flux → Settings… from the macOS menu bar.

Flux organizes all preferences into five focused tabs:

---

1. General Settings

👤 Account & Cloud Sync

Flux includes an integrated cloud synchronization engine powered by PocketBase:

• Sign In / Sign Out: Create a free Flux cloud account or sign in with your email and password.
• Live Sync Indicator:
  • 🟢 Green Dot: Synced and up to date, displaying the exact timestamp of your latest cloud sync.
  • 🟠 Orange Dot: Actively transmitting library or playback changes to the server.
• Sync Now: Forces an immediate bidirectional synchronization of all watchlist items, continue-watching states, profile settings, and playback history.
• Display Name Editor: Click the pencil icon next to your name to change your account display name across all your devices.

👥 Watching Profiles

Switch between family and personal profiles directly from Settings or the Profile Gate:

• Profile Strip: Click any profile badge to switch active users.
• 3D Avatar Badges: Displays custom stylized pet and cat avatars (avatar-cat-1..8, avatar-pet-1..12).
• KIDS Tag: Indicates that the profile is locked into Kid-Safe Mode (restricting content ratings to G/PG/TV-Y7).
• Manage Profiles: Launches the full Profile Manager to create, edit, or delete profiles, assign avatars, and configure parental PINs.
• Parental PIN Prompt: If exiting a Kids profile or entering a PIN-locked profile, Flux automatically prompts for a 4-digit PIN.

🎬 Catalog & Metadata (TMDB)

Flux retrieves artwork, summaries, cast lists, and trailers using The Movie Database (TMDB) API:

• Keyless Catalog (Default): Out of the box, Flux works keyless without any setup required.
• Personal TMDB API Key: For power users who want guaranteed high-rate metadata enrichment and personal quotas, click Add Key, paste your 32-character hex key from themoviedb.org/settings/api, and click Save. Flux validates the key against TMDB in real time before saving.
• Enrich Discovery Rails with TMDB:
  • Enabled (Recommended): Overlays community-rated high-resolution backdrops, genre tags, and cast lists onto Home rows and OTT channels.
  • Disabled: Uses raw catalog metadata directly without external enrichment.

🌐 App Language

Flux features a comprehensive 10-language translation matrix:

• Supported languages: English, 日本語 (Japanese), Español (Spanish), Français (French), Deutsch (German), Italiano (Italian), Português (Portuguese), 한국어 (Korean), हिन्दी (Hindi), and 中文 (Chinese).
• Dynamic Instant Switching: Changing the language instantly updates every view, sidebar item, context menu, and setting in real time without restarting the app.

---

2. Streaming Settings

📡 Stream Sources

• Stream Filter:
  • HTTP & Torrent Streams (Both): Loads direct HTTP debrid streams alongside peer-to-peer torrent streams simultaneously.
  • HTTP Streams Only: Hides torrent swarms and strictly displays direct HTTP streams (useful for VPN-free streaming via Debrid).
  • Torrent Streams Only: Restricts playback solely to peer-to-peer torrent swarms.

⚡ Flux Mode

Flux Mode is the flagship autonomous stream selection engine:

• Enable Flux Mode: When turned on, clicking any movie or episode bypasses manual stream picker lists. Flux automatically races the candidate streams and begins playback on the fastest, healthiest source in under 3 seconds.
• Maximum Resolution: Sets the ceiling resolution for autonomous stream selection:
  • 4K (2160p) — Prioritizes pristine Ultra HD releases.
  • 2K (1440p) — High-clarity QHD.
  • 1080p — Full HD (ideal for balanced bandwidth).
  • 720p / 480p — Data-saving modes for mobile hotspots or metered connections.
• Language Filter in Flux Mode:
  • Enabled: Restricts the autonomous racer to streams explicitly tagged with your default audio language.
  • Disabled: Races the absolute fastest and healthiest stream regardless of audio tags.

---

3. Addons Settings

🧩 Installed Addons List

• Installed Addons Count: Shows the total number of active extensions.
• Refresh / Cloud Pull: Pulls your synced addon list from your Flux cloud account.
• STOCK Badges: Distinguishes bundled system providers (like Cinemeta) from user-installed community addons.
• Configure Gear (⚙️): For addons supporting external settings (e.g. Torrentio, CyberFlix), clicking the gear opens their configuration portal in your default browser with your current settings pre-filled.
• Enable / Disable Toggle: Temporarily disable an addon without uninstalling it.
• Uninstall (Trash Can): Permanently removes a custom addon and prunes its catalogs from your sidebar.

🔗 Install Custom Addon

• Paste any Stremio-compatible manifest.json URL or click any stremio:// deep link in your browser.
• Flux automatically parses the addon manifest, verifies its capabilities (catalog, meta, stream, subtitles), and adds it to your active library instantly.

---

4. Playback Settings

📺 Video Player

• Hardware Acceleration: Employs Apple Silicon VideoToolbox hardware decoding via libmpv. Enables silky-smooth 4K 60fps, 10-bit HEVC, and AV1 playback with minimal CPU and battery consumption.

⏭️ Playback Behavior

• Auto-play Next Episode: When watching TV series, Flux automatically pre-fetches and transitions into the next episode as the current episode finishes.

🔊 Audio & Passthrough

• Audio Passthrough (Atmos / DTS):
  • Enabled: Bitstreams raw audio data (Dolby Atmos / TrueHD / DTS-HD MA) directly over HDMI to an external AV Receiver (AVR) or soundbar, bypassing macOS audio downmixing.
  • Disabled (Default): Use when listening through Mac built-in speakers, headphones, or AirPods.

🗣️ Languages

• Default Audio: Automatically selects audio tracks matching your preferred language when a file contains multiple audio channels.
• Default Subtitles: Automatically enables and matches subtitle tracks in your chosen language, or set to Off to hide subtitles by default.

---

5. Advanced Settings

💾 Storage & Torrent Cache

Flux streams torrents sequentially directly to disk:

• Torrent Cache Limit: Set the maximum disk storage allocated for torrent streaming:
  • Options: 1 GB, 2 GB, 5 GB, 10 GB, 20 GB, or 50 GB.
  • LRU Auto-Eviction: When the limit is reached, Flux automatically prunes the oldest, least-recently-watched torrent chunks to make room for new streams without interrupting active playback.
• Disk Cache Used: Real-time storage gauge displaying the exact disk footprint used by torrent streams.
• Clear Images: Instantly purges all in-memory image caches (NSCache), network disk caches (URLCache), and cached poster/backdrop files (FluxImageCache).
• Purge Torrent Cache: Manually deletes all downloaded torrent chunks from disk.

🔄 About & Updates

• Displays the currently installed version of Flux.
• Check for Updates…: Queries the Sparkle 2 update feed (appcast.xml) for cryptographically signed (Ed25519) over-the-air updates.