Metadata-Version: 2.5
Name: hdmi-monitor
Version: 1.0.0
Summary: Use your laptop as a monitor for another computer through a USB HDMI capture card - low latency, full screen, with audio.
Author-email: Prosper Magara <prospermagara@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: capture card,display,hdmi,monitor,ms2109,usb video,viewer
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video :: Display
Requires-Python: >=3.10
Requires-Dist: pyside6-addons>=6.8
Requires-Dist: pyside6-essentials>=6.8
Description-Content-Type: text/markdown

# HDMI Monitor

Use your laptop as a monitor for another computer (a mini PC, Raspberry Pi, Jetson, console...) through a cheap **USB HDMI capture card**.

Plug the other computer's HDMI output into the capture card, plug the card into your laptop, and run `hdmi-monitor`. You get a low-latency, full-screen picture with sound.

## Install

### Linux (Ubuntu, Debian, Mint, Fedora, Arch...)

```bash
sudo apt install pipx libxcb-cursor0     # Fedora: sudo dnf install pipx xcb-util-cursor
pipx ensurepath                          # then open a new terminal
pipx install hdmi-monitor
hdmi-monitor --create-shortcut           # optional: add it to your applications menu
```

### Windows 10/11

Install [Python 3.10 or newer](https://www.python.org/downloads/) first if you don't have it. Then, in PowerShell:

```powershell
py -m pip install --user pipx
py -m pipx ensurepath                    # then open a new terminal
pipx install hdmi-monitor
hdmi-monitor --create-shortcut           # optional: add it to the Start menu
```

If you already use [uv](https://docs.astral.sh/uv/), `uv tool install hdmi-monitor` works on both systems.

**Update:** `pipx upgrade hdmi-monitor` · **Uninstall:** `hdmi-monitor --remove-shortcut`, then `pipx uninstall hdmi-monitor`

## Why not just use the Camera app?

- It finds the capture card automatically (skipping the built-in webcam) and uses its best mode, e.g. **1920x1080 @ 60 fps**.
- **It plays the HDMI audio** through the laptop speakers.
- True borderless full screen. The mouse pointer hides when idle, and the screen won't sleep or blank.
- It remembers your source, resolution, audio, volume, and window options.
- It reconnects automatically when the capture card is unplugged and plugged back in.
- Only one copy runs at a time, because a capture card can only be read by one program. Opening it again brings the existing window to the front.

## Controls

| Key / action | Does |
|---|---|
| F11 or double-click | Full screen on / off |
| Esc | Leave full screen |
| Right-click | All options (source, resolution, audio...) |
| M | Mute |
| Ctrl+T | Always on top |
| Ctrl+S | Save a screenshot to Pictures |
| F5 | Reconnect |
| Ctrl+H | Show / hide toolbar |
| Ctrl+Q | Exit |

## Troubleshooting

- **Black picture or "Could not open the capture device":** close any other app using the card (Camera, OBS, Teams, Zoom, a browser tab).
- **Linux: `Could not load the Qt platform plugin "xcb"`:** install `libxcb-cursor0` (Debian/Ubuntu) or `xcb-util-cursor` (Fedora).
- **Linux: `ImportError: lib....so: cannot open shared object file`** (only on very minimal installs): on Debian/Ubuntu run `sudo apt install libgl1 libegl1 libglib2.0-0 libgssapi-krb5-2 libxkbcommon-x11-0 libpulse0`.
- **Windows: install fails with a "Long Path" hint:** use Python from python.org rather than the Microsoft Store, or [enable long paths](https://pip.pypa.io/warnings/enable-long-paths).
- **Linux: no picture, or permission denied:** make sure your user can access `/dev/video*` (usually the `video` group).
- **What did it detect?** Run `hdmi-monitor --diagnose`. After 6 s it writes the devices, mode, and frame rate to `hdmi_monitor_diagnose.txt` in your temp folder (`/tmp` on Linux, `%TEMP%` on Windows).

## Alternatives

- **OBS Studio:** add a *Video Capture Device*, then right-click → *Fullscreen Projector*. Heavier, and audio needs extra setup.
- **VLC:** *Open Capture Device*. Set caching to about 0 ms, or the picture lags.
- **Over the network** (no capture card): NoMachine, VNC, RustDesk, or Sunshine/Moonlight. These also give you keyboard and mouse control, but the other computer must be booted and on the network.

A capture card sees everything, including BIOS and boot screens, and needs no software on the other computer. Expect about 50–100 ms of delay with typical MS2109-based cards.

## For developers

```bash
pip install -e .              # run from source: python -m hdmi_monitor
python -m build               # build the PyPI wheel + sdist into dist/
```

Stand-alone installers that don't need Python, built from Windows:
- `powershell -ExecutionPolicy Bypass -File build.ps1` builds the Windows setup `.exe`. It needs [Inno Setup 6](https://jrsoftware.org/isinfo.php).
- `wsl -d Ubuntu -u root -- sh linux/wsl_build.sh` builds the Linux `.deb` and AppImage inside an Ubuntu 22.04 chroot in WSL.

Built with PySide6 / Qt Multimedia (FFmpeg backend). MIT licensed.
