How I turned my Linux Mint laptop into an automated streaming station with a single command 📺🚀

# How I turned my Linux Mint laptop into an automated streaming station with a single command 📺🚀

Hi everyone!

I want to share a weekend project born out of pure engineering frustration that eventually turned into a fully automated CLI utility for Linux open-source streaming setups.

If you've ever tried using **Sunshine + Moonlight** on Linux to stream a **completely separate virtual display** instead of mirroring your primary monitor, you know how quickly things become messy. You end up juggling kernel modules, `xrandr` positioning, virtual audio routing, and firewall rules every single time.

To solve that problem once and for all, I built **GDEV TV Mode**.

---

# The Problem: The X11 Virtual Monitor Nightmare

Streaming an independent workspace to a TV, tablet, or handheld device requires a headless display. On Linux, one of the cleanest ways to accomplish this is with **VKMS (Virtual Kernel Mode Setting)**.

The problem is that the setup process is repetitive and error-prone.

Every session usually involves:

1. Loading the `vkms` kernel module.
2. Creating and positioning a virtual monitor with `xrandr`.
3. Routing audio to a virtual sink so Sunshine captures it correctly.
4. Opening the required firewall ports.
5. Launching Sunshine.
6. Hoping everything starts in the correct order.

Doing this manually every time gets old very quickly.

---

# The Solution: `gdev-tv`

I wrote a modular Bash CLI that automates the entire lifecycle.

Instead of running dozens of commands, everything becomes:

```bash
gdev-tv start
```

Internally, the workflow looks like this:

```text
User
   │
   ▼
gdev-tv start
   │
   ▼
Doctor Diagnostics
   │
   ▼
Load VKMS
   │
   ▼
Create Virtual Display
   │
   ▼
Configure xrandr Layout
   │
   ▼
Create Virtual Audio Sink
   │
   ▼
Configure Firewall
   │
   ▼
Launch Sunshine
   │
   ▼
Ready for Moonlight
```

---

# The Engineering Highlight: `doctor`

One of the goals of the project was reliability.

Scripts that manipulate kernel modules, displays, networking, and audio can fail for dozens of reasons depending on the environment.

That's why I implemented a built-in diagnostic system.

```bash
gdev-tv doctor
```

The command validates the entire environment **before** changing anything.

It currently checks:

- GPU detection (Intel / AMD / NVIDIA)
- Running display server (currently X11)
- Required kernel modules
- Sunshine installation
- Firewall configuration
- Virtual display support
- Audio subsystem
- Required dependencies
- User permissions

Instead of failing halfway through execution, the tool reports exactly what is missing so the issue can be fixed immediately.

---

# Other Features

## One-command cleanup

Stopping the streaming session is just as simple.

```bash
gdev-tv stop
```

The tool automatically:

- Stops Sunshine
- Removes the virtual display
- Unloads VKMS
- Restores firewall rules
- Returns audio to the default device
- Cleans temporary resources

No manual cleanup required.

---

## Centralized configuration

Everything is configurable from a single `.conf` file.

Examples include:

```bash
RESOLUTION="1280x720"
DISPLAY_POSITION="right"
FPS="60"
```

No need to edit the scripts themselves.

---

## Modular architecture

The project is intentionally organized as independent shell modules.

Current components include:

- doctor
- display
- audio
- firewall
- sunshine
- lifecycle management

Installation is handled through a simple Makefile.

---

# Current Status

The project is currently tested on:

- Linux Mint 22.x
- Ubuntu 22.04+
- X11 sessions

Wayland support is on the roadmap.

---

# Why I built it

The original goal was simply to stream a second monitor to my TV without buying a dummy HDMI adapter or constantly typing the same commands.

It quickly evolved into a reusable tool that makes the entire setup reproducible with a single command.

I also wanted something that could diagnose itself instead of failing silently—a common problem with shell automation projects.

---

# Source Code

The repository is available here:

**GitHub:**  
https://github.com/guadalupe182/Gdev-Monitor

> **Note:** The repository still uses its historical name **Gdev-Monitor**, although the CLI itself is now focused on **GDEV TV Mode**.

---

# Feedback Welcome

I'd love to hear how other Linux users handle headless streaming setups.

If you have suggestions, bug reports, ideas for Wayland support, or simply want to test it on your hardware, feel free to open an issue or submit a PR.

And if the project saves you some setup time, consider leaving a ⭐ on the repository.

Happy streaming! 🚀