FluxCast

FluxCast streams a Linux desktop to a TV.

Release Python Platform Issues PRs

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

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.

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.

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

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 then run it without sudo; elsewhere (including Arch) it falls back to sudo - see the file for details.

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.

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.

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

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)

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.

yay -S fluxcast-git
# or
paru -S fluxcast-git

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.

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

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