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.

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

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)

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-git
# or
paru -S fluxcast-git

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

[!WARNING] If PIP refuses to install the required libraries to your system, you will need to do that yourself using your distro's package manager.

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".

Documentation

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

Tested Environment

Hardware:

Software: