fluxcast 0.1.3

Stream your Linux desktop to a Smart TV via Miracast/WFD, DLNA, or Chromecast

FluxCast

FluxCast streams a Linux desktop to a TV.

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.

[!WARNING] Fedora / SELinux users: fluxcast-install-system copies a D-Bus policy file to /usr/share/dbus-1/system.d/ without restoring its SELinux label. On SELinux-enforcing systems the file can end up mislabeled, which blocks dbus-broker.service and may hang boot. Until this is fixed in the installer, relabel it once right after running fluxcast-install-system:

sudo restorecon -Fv /usr/share/dbus-1/system.d/zz-dev.fluxcast.wpa-supplicant.conf

If you already hit the boot hang, boot from a live USB, delete that file from your installed system, then reboot normally. If you reinstall later, run the restorecon command above immediately after the install and before rebooting — otherwise the installer recreates the mislabeled file and the next boot hangs again.

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.

Documentation

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

Tested Environment

Hardware:

ThinkBook 14 G4+ IAP

• CPU: Intel i5-1240P (16 threads) up to 4.40 GHz
• GPU: Intel Iris Xe Graphics
• RAM: 16 GB

Dell XPS 13 Plus

• CPU: Intel i5-1260P (16 threads) up to 4.70 GHz
• GPU: Intel Iris Xe Graphics
• RAM: 16 GB LPDDR5

ThinkPad T14 Gen 4

• CPU: Intel i7-1355U (12 threads) up to 5.00 GHz
• GPU: Intel Iris Xe Graphics
• RAM: 32 GB

Software:

Arch Linux

• Kernels: 7.0.8-arch1-1, 6.12.91-1-lts612
• WMs: Hyprland (0.55.2)
• DEs (for testing): KDE Plasma (6.6.5) | GNOME (50.1)
• Shell: zsh (5.9), fish (4.7.1)
• Terminal: kitty (0.46.2, 0.47.1)

CachyOS

• Kernels: 7.0.3-1-cachyos
• DEs (for testing): KDE Plasma (6.6.4)
• Shell: bash (5.3.9)
• Terminal: konsole (26.4.0)