hdmiviewer/README.md

HDMI Viewer

Ein schlanker Qt6/C++ HDMI-Viewer für Arch Linux mit V4L2 (Video) und ALSA (Audio). Gedacht als Companion zu OBS Studio: Anzeigen ohne Aufnehmen.

Features

• Live-Vorschau vom HDMI-Grabber via V4L2, mit automatischer Formatpriorität MJPEG → YUYV → NV12 (MJPEG braucht deutlich weniger USB-Bandbreite und erlaubt so höhere Auflösungen/Framerates)
• ALSA-Audio direkt vom Grabber-Gerät (Capture → Wiedergabe, per Thread)
• Gerät-Auswahl beim Start (Video, Audio, Ziel-Framerate), alle Einstellungen werden gespeichert und beim nächsten Start vorausgewählt
• F → Vollbild / F oder Esc im Vollbild → Fenstermodus
• Esc im Fenstermodus → zurück zur Gerät-Auswahl (Device wird sauber freigegeben)
• Seitenverhältnis immer bewahrt (Letterbox/Pillarbox)
• Titelleiste und Statusleiste zeigen tatsächliche Auflösung, FPS und Pixelformat
• GPU-Rendering per OpenGL 3.3 (kein Ruckeln durch CPU-seitiges Skalieren)
• Bildglättung (standardmäßig an, Taste S): GPU-Shader trennt Luma/Chroma und behandelt sie getrennt – Chroma wird stärker weichgezeichnet (killt Dot-Crawl/Farbrauschen billiger Composite→HDMI-Scaler), Luma wird leicht geglättet und dezent gegengeschärft (nimmt harte Scaler-Kanten raus, ohne matschig zu wirken). Keine Optik-Spielerei, sondern eine echte Bildverbesserung.
• Retro-Optik (standardmäßig aus, Taste C): separater Nostalgie-Look – Scanlines, Phosphor-/Aperture-Grille-Maske, leichte Wölbung wie bei einem alten Röhrenfernseher. Lässt sich mit der Bildglättung kombinieren.
• Nachschärfen (Unsharp Mask, Taste X zum Umschalten, +/- zum Fein-Justieren): unabhängig von der Bildglättung, live einstellbar und persistiert.
• Hardware-Helligkeit/-Kontrast/-Sättigung (Tasten ,/., 1/2, 3/4): steuert die entsprechenden V4L2-Regler direkt am Grabber-Chip, also VOR der JPEG-Kompression – das rettet tatsächlich Schattendetails, statt nur nachträglich am fertig komprimierten Bild zu strecken (was sichtbare Artefakte/Banding erzeugt). Beim Start wird der jeweilige Ausgangswert des Chips ausgelesen und gemerkt; beim Beenden wird er exakt wiederhergestellt, sodass der Grabber für andere Programme unverändert bleibt. Im Startdialog lassen sich für alle drei Regler feste Zielwerte vorgeben (unverändert = Regler beim Start gar nicht anfassen).
• Studio-/Full-Range-Korrektur: Das fertig dekodierte Bild wird von einem komprimierten Kontrastumfang (Schwarzpunkt niedrig angesetzt, Weißpunkt ≈235/255) auf den vollen 0–255-Kontrastumfang gedehnt. Ohne diese Korrektur wirkt das Bild dumpf, kontrastarm und zu dunkel – viele billige HDMI-Grabber liefern (oder kodieren, auch bei MJPEG) genau in diesem komprimierten Bereich. Greift direkt im GPU-Shader auf dem fertigen RGB-Bild, also unabhängig vom Pixelformat.
• Roh-Modus (Taste R): Diagnose-Umschalter, der sämtliche Verarbeitung (Bildglättung, Retro-Optik, Studio-Range-Korrektur, Kontrast-/ Sättigungs-Punch, Gamma) umgeht und das Bild 1:1 anzeigt.
• Live-Vergleich (Taste V): zeigt links das rohe und rechts das bearbeitete Bild nebeneinander – praktisch zum Fein-Tunen der Hardware-Regler.
• Screenshot (Taste P): speichert das aktuell angezeigte (bearbeitete) Frame als PNG im Home-Verzeichnis.
• Frame-Dump (Taste D, nur bei MJPEG): speichert das nächste rohe, unveränderte MJPEG-Frame direkt vom Chip als JPEG – nützlich, um zu prüfen, ob Abweichungen schon in den Rohdaten liegen oder erst bei der eigenen Verarbeitung entstehen.

Abhängigkeiten (Arch Linux)

sudo pacman -S qt6-base cmake alsa-lib base-devel

qt6-base bringt auf Arch bereits die benötigten Qt6OpenGL- und Qt6OpenGLWidgets-Module mit. linux/videodev2.h ist Teil von linux-api-headers, das über die base-Gruppe ohnehin installiert ist.

Installation über AUR

yay -S hdmi-viewer
# oder mit einem anderen AUR-Helper, bzw. manuell:
git clone https://aur.archlinux.org/hdmi-viewer.git
cd hdmi-viewer
makepkg -si

Quellcode

git clone https://git.projekt-hirnfrei.de/diabolus/hdmiviewer.git

Manuell bauen

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Starten

./hdmi-viewer

Tastenkürzel

Taste	Funktion
F	Vollbild ein/aus
S	Bildglättung ein/aus
C	Retro-Optik (Scanlines/Maske) ein/aus
X	Nachschärfen ein/aus (letzter Wert ↔ aus)
+ / -	Nachschärfen stärker / schwächer
, / .	Hardware-Helligkeit dunkler / heller
1 / 2	Hardware-Kontrast runter / hoch
3 / 4	Hardware-Sättigung runter / hoch
R	Roh-Modus (Diagnose, alle Effekte umgangen) ein/aus
V	Live-Vergleich (links roh, rechts bearbeitet) ein/aus
P	Screenshot speichern (PNG)
D	Rohes MJPEG-Frame dumpen (Diagnose)
Esc	Vollbild verlassen ODER zurück zum Gerätedialog

Einstellungen

Werden gespeichert in: ~/.config/hdmi-viewer/HDMIViewer.conf (Standard XDG-Pfad, kein manuelles Anlegen nötig)

Audio-Gerät finden

# Alle ALSA-Capture-Geräte auflisten
arecord -l

# Testen (hw:X,Y aus arecord -l, z.B. hw:2,0)
arecord -D hw:2,0 -f S16_LE -r 48000 -c 2 /tmp/test.wav
aplay /tmp/test.wav

Das Gerät dann im Dialog so eingeben: z.B. hw:2,0 oder plughw:2,0 (plughw macht automatische Sample-Rate-Konvertierung, falls nötig)