Metadata-Version: 2.4
Name: fluxcast
Version: 0.1.3
Summary: Stream your Linux desktop to a Smart TV via Miracast/WFD, DLNA, or Chromecast
Project-URL: Homepage, https://fluxcast.secweb.cloud
Project-URL: Repository, https://github.com/IlyaP358/fluxcast
Project-URL: Issues, https://github.com/IlyaP358/fluxcast/issues
Author: IlyaP358
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: chromecast,dlna,linux,miracast,screen-cast,streaming,tv,wfd,wireless-display
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video :: Display
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Requires-Dist: dbus-next>=0.2.3
Requires-Dist: pillow>=10.0.0
Requires-Dist: pychromecast>=14.0.5
Requires-Dist: pygobject>=3.42.0
Requires-Dist: pystray>=0.19.0
Requires-Dist: upnpclient>=1.0.3
Description-Content-Type: text/markdown

# FluxCast

<img src="https://fluxcast.secweb.cloud/flcast_logo_512x512.png" width="150" display="block">

FluxCast streams a Linux desktop to a TV.

[![Release](https://img.shields.io/github/v/release/IlyaP358/fluxcast?style=flat-square&color=green)](https://github.com/IlyaP358/fluxcast/releases)
[![Python](https://img.shields.io/badge/python-3.10+-blue?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/platform-Linux-lightgrey?style=flat-square&logo=linux)](https://www.linux.org/)
[![Issues](https://img.shields.io/github/issues/IlyaP358/fluxcast?style=flat-square&color=red)](https://github.com/IlyaP358/fluxcast/issues)
[![PRs](https://img.shields.io/github/issues-pr/IlyaP358/fluxcast?style=flat-square)](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.

> [!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`:
> ```bash
> 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

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


## Documentation

Detailed flags, modes, and usage examples:  
[documentation/DOCUMENTATION.md](documentation/DOCUMENTATION.md)

## Tested Environment

### Hardware:

<details>
<summary>ThinkBook 14 G4+ IAP</summary>

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

</details>

<details>
<summary>Dell XPS 13 Plus</summary>

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

</details>

<details>
<summary>ThinkPad T14 Gen 4</summary>

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

</details>


### Software:

<details>
<summary>Arch Linux</summary>

- 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)

</details>

<details>
<summary>CachyOS</summary>

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

</details>