https://github.com/IlyaP358/fluxcast
Stream your Linux desktop to a Smart TV via Miracast/WFD, DLNA, or Chromecast.
https://github.com/IlyaP358/fluxcast
cast gnome hyprland kde-plasma linux miracast pipewire python screencast screencasting screensharing screensharing-tool sway xdg-portal
Last synced: about 2 hours ago
JSON representation
Stream your Linux desktop to a Smart TV via Miracast/WFD, DLNA, or Chromecast.
- Host: GitHub
- URL: https://github.com/IlyaP358/fluxcast
- Owner: IlyaP358
- License: gpl-3.0
- Created: 2026-05-01T23:23:33.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-07-03T00:16:02.000Z (2 days ago)
- Last Synced: 2026-07-03T02:15:16.153Z (2 days ago)
- Topics: cast, gnome, hyprland, kde-plasma, linux, miracast, pipewire, python, screencast, screencasting, screensharing, screensharing-tool, sway, xdg-portal
- Language: Python
- Homepage: https://fluxcast.secweb.cloud/
- Size: 1.37 MB
- Stars: 251
- Watchers: 5
- Forks: 9
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-smart-tv - Fluxcast - A user-friendly Python utility for mirroring Linux desktops to Smart TVs via Miracast and DLNA, supporting GNOME, KDE, and wlroots/Wayland. (Cross-platform tools / Google Chromecast)
README
# FluxCast
FluxCast streams a Linux desktop to a TV.
[](https://github.com/IlyaP358/fluxcast/releases)
[](https://www.python.org/)
[](https://www.linux.org/)
[](https://github.com/IlyaP358/fluxcast/issues)
[](https://github.com/IlyaP358/fluxcast/pulls)
## 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):
```bash
python3 src/main.py
```
WFD with latency/session JSONL log:
```bash
python3 src/main.py --wfd-latency-log
```
DLNA fallback:
```bash
python3 src/main.py --protocol dlna --transport hls
```
Cast mode (optional, if your TV supports it):
```bash
python3 src/main.py --protocol cast
```
Force backend manually (if auto is not suitable on your session):
```bash
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)
```text
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)
```text
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](https://github.com/IlyaP358/fluxcast/releases) page, then:
```bash
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
```bash
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
```bash
yay -S fluxcast-git
# or
paru -S fluxcast-git
```
### From source
```bash
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:
```bash
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](documentation/DOCUMENTATION.md) -> "WFD and firewalld".
## Documentation
Detailed flags, modes, and usage examples:
[documentation/DOCUMENTATION.md](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)