FluxCast

FluxCast streams a Linux desktop to a TV.

🌐 Need a free subdomain for your project? Check out sub.fluxcast.dev (GitHub repo) — a free GitOps subdomain registry for developers!

Demo

https://github.com/user-attachments/assets/ce01804c-2f86-4a5d-8ecf-d6f2a72f55d1

Project Status

Current validated scope:

• wfd is the primary path and the only mode tested as release-ready.
• dlna works as fallback.
• cast is experimental and currently not working in the tested Samsung setup.

The project currently focuses on WFD/Miracast on Linux (Hyprland/wlroots class setups).
DLNA and Cast are available, but they are best treated as fallback or experimental paths.

Current limitation:

• KDE/GNOME Wayland desktop capture uses xdg-desktop-portal in WFD mode.
• For portal mode, install Python dependency dbus-next and allow screen-share in the desktop picker dialog.

Translations

The tray picks your language up from the system locale, no configuration needed.

Adding your language means editing one JSON file and no code at all. See CONTRIBUTING.md.

Quick Start

Default WFD run (interactive monitor/peer selection):

python3 src/main.py

WFD with latency/session JSONL log:

python3 src/main.py --wfd-latency-log

DLNA fallback:

python3 src/main.py --protocol dlna --transport hls

Cast mode (optional, if your TV supports it):

python3 src/main.py --protocol cast

Force backend manually (if auto is not suitable on your session):

python3 src/main.py --capture-backend wf-recorder
python3 src/main.py --capture-backend x11grab
python3 src/main.py --protocol wfd --wfd-capture-backend portal
python3 src/main.py --protocol wfd --wfd-capture-backend wf-recorder
python3 src/main.py --protocol wfd --wfd-capture-backend x11grab

Android-based sinks (TV boxes, projectors) that connect but stay on a black screen:

python3 src/main.py --protocol wfd --wfd-aosp-pmt-pid

WFD P2P connection troubleshooting - talk to wpa_supplicant directly instead of going through NetworkManager, and optionally pin the group to a 2.4GHz channel for sinks that don't support Wi-Fi Direct on 5GHz:

python3 src/main.py --protocol wfd --wfd-p2p-backend wpas
python3 src/main.py --protocol wfd --wfd-p2p-backend wpas --wfd-p2p-channel 6

Needs the D-Bus policy in meta/zz-dev.fluxcast.wpa-supplicant.conf installed to /usr/share/dbus-1/system.d/. On Debian/Ubuntu, a user in the netdev group can run it without sudo, courtesy of the netdev grant in the distro's own wpa_supplicant.conf; elsewhere (including Arch) it falls back to sudo - see the file for details.

What Works Best

WFD (Primary)

screen + audio capture -> H.264/AAC RTP -> Wi-Fi Direct + RTSP -> TV WFD receiver

This is the lowest-latency and most predictable path in the current codebase.

DLNA (Fallback)

desktop capture -> HTTP stream -> DLNA/UPnP AVTransport -> native TV player

• Prefer --transport hls on Samsung TVs.
• progressive-ts can freeze or stutter on some models.

Cast (Optional)

• Requires a TV/device with real Google Cast support.
• Requires pychromecast.
• Not reliable on many Samsung TV models.

Installation

AppImage

Download the latest FluxCast-x86_64.AppImage from the Releases page, then:

chmod +x FluxCast-x86_64.AppImage
./FluxCast-x86_64.AppImage

On first launch FluxCast will ask for your password once to install a system file for Wi-Fi Direct.

Depending on your desktop environment, you may need to install:

• Hyprland / Sway: wf-recorder, ffmpeg
• KDE / GNOME: gst-plugins-ugly (package name varies by distro)

Debian / Ubuntu - .deb

Download the .deb matching your release from the Releases page and install it:

sudo apt install ./fluxcast_<version>~<codename>_amd64.deb

amd64 only - there is no arm64 build. A release stays in the table for as long as it has upstream support, and its .deb stops being published once that ends.

python3 --version   # e.g. 3.13.7 on Ubuntu 25.10 -> use the ~trixie build

There is no separate privileged step: the package installs the D-Bus policy for Wi-Fi Direct and reloads dbus for you.

The builds are not interchangeable. FluxCast bundles the Python dependencies apt does not carry at a usable version (upnpclient is absent from the archive, python3-pychromecast is 9.4.0 against a 14.0.5 requirement) in a virtualenv under /opt/fluxcast, and those wheels are tied to the Python version they were built against. Each package therefore declares the exact python3 minor version it was built for, and apt refuses a package whose Python does not match rather than installing something that fails on first import.

PyPI

pip install fluxcast
sudo fluxcast-install-system

fluxcast-install-system installs the D-Bus policy, desktop entry, and system packages (GStreamer, ffmpeg, NetworkManager, etc.). Run it once after the pip install.

Arch Linux - AUR

yay -S fluxcast
# or
paru -S fluxcast

fluxcast tracks the latest release. fluxcast-git builds the current main instead, if you want to run ahead of a release.

From source

git clone https://github.com/IlyaP358/fluxcast.git
cd fluxcast
pip install -r requirements.txt
sudo meta/install.sh
sudo systemctl reload dbus
sudo gtk-update-icon-cache /usr/share/icons/hicolor

DLNA/Cast features require additional packages listed in requirements.txt.

System tools (just as important)

WFD mode also depends on system binaries, not only Python packages:

• ffmpeg
• wf-recorder (Wayland/wlroots capture path)
• xdg-desktop-portal (+ desktop backend: xdg-desktop-portal-kde / xdg-desktop-portal-gnome / xdg-desktop-portal-wlr)
• nmcli, gdbus, iw, wpa_cli (Wi-Fi Direct and diagnostics)
• pactl (audio monitor autodetect)

Use:

python3 src/main.py --doctor

to check your machine before running WFD.

Note: on KDE/GNOME Wayland, WFD auto backend now prefers portal first.

Note: on firewalld systems, FluxCast opens the WFD RTSP port (7236/tcp) for the duration of a session and closes it on exit (no-op without firewalld; disable with --wfd-no-firewall). See DOCUMENTATION.md -> "WFD and firewalld".

If you use ufw, open the WFD RTSP port before connecting:

sudo ufw allow 7236/tcp

Documentation

Detailed flags, modes, and usage examples:
documentation/DOCUMENTATION.md

Tested Environment

TVs and receivers:

Wi-Fi adapters:

Hardware:

Software: