This is an old revision of the document!

---

OnAirScreen – Bedienungsanleitung

Version: 1.0.0beta12
Autor: Sascha Ludwig, astrastudio.de
Projekt: OnAirScreen
English version: User Manual

---

Inhaltsverzeichnis

1. Überblick
2. Installation und Start
3. Hauptbildschirm
4. Tastaturkürzel (Hotkeys)
5. Einstellungsdialog
6. Funktionen im Detail
7. Fernsteuerung und API
8. Presets (Profile)
9. Kommandozeilenoptionen
10. Konfigurationsspeicherort
11. Fehlerbehebung

---

1. Überblick

OnAirScreen ist eine vielseitige On-Air-Lampe für professionelle Broadcast-Umgebungen. Die Anwendung kombiniert:

• 4 Status-LEDs (ein-/ausschaltbar, blinkend, zeitgesteuert)
• 4 AIR-Timer (Mikrofon, Telefon, Radio-Timer, Stream-Timer); AIR3 mit ▲/▼ und Top-of-Hour
• Digitale oder analoge Uhr mit optionalem Textuhr-Modus und Lock-LED (Local / NTP / PTP / LTC)
• Stereo-Audio-Meter (lokaler Eingang, Axia Livewire oder AES67 AoIP): L/R, Programme-LUFS oder beides, optional I+LRA
• Silence Detection mit optionalem WARN auf dem Bildschirm und Boolean in API/MQTT
• Instanzname (DNS-sicher, z. B. Studio-1) zur Unterscheidung mehrerer OnAirScreens
• Textzeilen NOW, NEXT und WARN (mit Prioritätssystem)
• Wetter-Widget (OpenWeatherMap)
• Fernsteuerung per Tastatur, Maus (Doppelklick/Rechtsklick/Lang-Klick), UDP, HTTP, Web-UI, MQTT, OSC, REST-API und Bitfocus Companion
• Home-Assistant-Integration via MQTT Autodiscovery
• GPIO-Eingänge auf dem Raspberry Pi (Mixer-GPI über Optokoppler → LEDs und AIR-Timer)

Die Anwendung startet standardmäßig im Vollbildmodus mit ausgeblendetem Mauszeiger und eignet sich für dedizierte Studio-Monitore, Raspberry-Pi-Setups und Touch-freie Bedienung.

OnAirScreen passt sich automatisch an verschiedene Monitor-Seitenverhältnisse an und funktioniert sowohl auf 4:3- als auch auf 16:9/16:10-Displays.

---

2. Installation und Start

Fertige Builds für Windows, macOS, Linux und Raspberry Pi gibt es im astrastudio-Shop.

OnAirScreen startet im Vollbild mit ausgeblendetem Mauszeiger. Einstellungen: Ctrl+S (macOS: Cmd+S). Änderungen gelten erst nach Apply.

Windows

1. OnAirScreen_*_Win_x64.msi herunterladen (in OnAirScreen_Win_x64.zip).
2. Die MSI doppelklicken und dem Installer folgen. Die rechnerweite Installation braucht Administratorrechte.
3. OnAirScreen liegt unter C:\Program Files\OnAirScreen.
4. Start über das Startmenü oder das Desktop-Symbol.

Im Startmenü-Ordner liegen außerdem OAS Send (Befehlssender) und OAS Send (no console). Einstellungen stehen in der Windows-Registry, Logs unter %LOCALAPPDATA%\astrastudio\OnAirScreen\logs\.

Eine ältere portable .exe wird vom MSI nicht entfernt. Die Datei nach der Installation selbst löschen.

Windows gleicht die Internetzeit standardmäßig nur etwa einmal pro Woche ab. Bei Zeitquelle Local kann die Uhr falsch gehen. Sync-Intervall im Betriebssystem verkürzen oder in OnAirScreen NTP / PTP / LTC nutzen (siehe 5.3 Time Source).

macOS

1. OnAirScreen_*_macOS.dmg herunterladen.
2. Das DMG öffnen und OnAirScreen.app nach Programme (Applications) ziehen. Nicht direkt aus dem DMG starten.
3. OnAirScreen aus Programme, Launchpad oder Spotlight starten.

macOS versieht Downloads mit einem Quarantäne-Flag. OnAirScreen ist nicht mit einer Apple-Developer-ID signiert, daher blockiert Gatekeeper den ersten Start („Apple kann nicht prüfen, ob Schadsoftware enthalten ist“ / „der Entwickler kann nicht überprüft werden“).

Finder: OnAirScreen.app mit Control-Klick (Rechtsklick) → Öffnen → nochmals Öffnen. macOS merkt sich das für spätere Starts.

Terminal (wenn die App in Programme liegt):

sudo xattr -d com.apple.quarantine /Applications/OnAirScreen.app

Startet die App weiter nicht: Systemeinstellungen → Datenschutz & Sicherheit und Trotzdem öffnen. Für lokale Audio-Meter die Mikrofon-Berechtigung erteilen.

Linux (Debian / Ubuntu / Raspberry Pi OS)

Offizielle Builds sind ein .deb. Nach der Installation liegt die App in /opt/onairscreen, startet als onairscreen und erscheint im Anwendungsmenü.

Prüfen mit dpkg --print-architecture. Die beiden Pakete sind nicht austauschbar.

Raspberry Pi: 64-bit-OS auf Zero 2 W, Pi 3 / 4 / 400, CM4, Pi 5 / 500, CM5. Nicht unterstützt: Pi 1 und klassisches Zero. Es braucht eine grafische Desktop-Sitzung, kein Lite ohne GUI.

ZIP entpacken, danach mit apt installieren (nicht allein dpkg -i), damit PortAudio, OpenGL und Xcb nachgezogen werden. Das ./ vor der Datei ist Pflicht:

unzip OnAirScreen_Linux_x64.zip
cd ~/Downloads
sudo apt update
sudo apt install ./OnAirScreen_*.deb

Start über das Anwendungsmenü oder onairscreen. Update: neues .deb ebenso installieren; Einstellungen bleiben. Deinstallieren: sudo apt remove onairscreen (Config unter ~/.config bleibt).

Falls dpkg -i Abhängigkeiten vermisst hat: sudo apt -f install.

Pakete sind OpenPGP-signiert. Optionale Prüfung: Paketsignatur (GPG).

Fedora

Das Fedora-RPM wird auf Fedora 44 gebaut (Fedora 44+). Ältere RHEL-, Rocky- oder Alma-Versionen können wegen glibc scheitern.

sudo rpm --import https://www.astrastudio.de/GPG-KEY-astrastudio
sudo dnf install ./OnAirScreen_*_Fedora_x64.rpm

dnf zieht PortAudio und weitere Systembibliotheken nach. Signatur prüfen: rpm -K OnAirScreen_*_Fedora_x64.rpm (erwartet: digests signatures OK).

Raspberry-Pi-SD-Karten-Image

Das SD-Karten-Image ist ein startfertiges 64-bit-Raspberry-Pi-OS mit installiertem OnAirScreen (Desktop-Autologin, GPIO inklusive). ZIP entpacken; darin liegt OnAirScreen_*_RaspberryPiOS_Image.img.

Raspberry Pi Imager verwenden:

• macOS
• Windows
• Ubuntu x86

1. microSD-Karte einlegen.
2. Raspberry Pi Imager starten.
3. OS wählen → Eigenes Image verwenden (Use custom) → die OnAirScreen-.img wählen (nicht die .zip).
4. Speicher wählen (bzw. SD-Karte wählen) und die Karte auswählen.
5. Schreiben.

Standardbenutzer: pi / Passwort OnAirScreen1!. Hostname: onairscreen. Passwort nach dem ersten Start ändern. SSH ist eingeschaltet.

Auf dem Desktop: OnAirScreen, OAS Pi Settings (optionaler Autostart), Bildschirmtastatur, Netzwerk-Symbol. Beim ersten Boot wächst das Root-Dateisystem auf die Kartengröße.

Wer bereits Raspberry Pi OS 64-bit mit Desktop nutzt, installiert stattdessen das Pi-.deb (siehe Linux oben).

Erster Start

Beim ersten Start werden Standardeinstellungen geladen. Der Einstellungsdialog öffnet sich mit Ctrl+S (macOS: Cmd+S). Änderungen werden erst nach Klick auf Apply übernommen und gespeichert.

---

3. Hauptbildschirm

Der Hauptbildschirm ist in folgende Bereiche gegliedert:

Bereiche im Detail

Hinweis: Status-LEDs und AIR-Timer lassen sich per Linksklick, Tastatur oder Fernsteuerung umschalten. Doppelklick auf LED/Timer ändert den Vollbildmodus nicht.

Vollbildmodus

• Standard: Vollbild mit verstecktem Mauszeiger
• Umschalten: F oder Ctrl+F (macOS: Cmd+F), Doppelklick auf eine leere Fläche des Hauptbildschirms, oder Rechtsklick / Lang-Klick → Toggle Fullscreen
• Rechtsklick-/Lang-Klick-Menü: Toggle Fullscreen, Settings, Quit OnAirScreen; bei aktiven Metern zusätzlich Start I+LRA, Stop I+LRA und Reset I+LRA
• Der Vollbild-Zustand wird in den Einstellungen (General/fullscreen) gespeichert
• Einstellungen → General → Always start in fullscreen mode (General/always_start_fullscreen, Standard aus) startet immer im Vollbild, auch wenn die letzte Session im Fenster war. Apply gilt erst beim nächsten Start.
• Im Fenstermodus werden Position und Größe gespeichert (Window/geometry) und beim nächsten Start wiederhergestellt

---

4. Tastaturkürzel (Hotkeys)

Auf macOS wird Ctrl durch Cmd (⌘) ersetzt.

Anwendung

Beim Beenden erscheint die WARN-Meldung QUITTING ONAIRSCREEN auf dem Hauptbildschirm, bis das Fenster schließt.

Status-LEDs

Linksklick auf eine Status-LED schaltet sie ebenso um.

AIR-Timer

Linksklick auf einen AIR-Timer startet oder stoppt ihn (wie M / P / Leertaste / S). Reset, TOTH und Timer-Dialog bleiben Tastatur bzw. Fernsteuerung.

OAS-USB-Tastatur (Sonderbelegung)

---

5. Einstellungsdialog

Der Einstellungsdialog öffnet sich mit Ctrl+S oder Ctrl+, (oder Rechtsklick / Lang-Klick → Settings). Ist er bereits offen, kommt das Fenster nach vorne, ohne die Werte neu zu laden. Laufende AIR-Timer (inkl. TOTH) bleiben dabei unverändert. Der Dialog enthält mehrere Registerkarten (vertikal links angeordnet):

Schaltflächen (unten)

---

5.1 General

Instanzname

Der Instanzname erscheint in der Web-UI (Titel und Status), in /api/status (instance), auf MQTT {base}/instance/state und als Home-Assistant-Sensor. Der HA-Gerätename wird zu OnAirScreen (Studio-1), sofern der Instanzname nicht schon im Device Name steht. Remote: CONF:General:instancename=TEXT.

Stationsname und Slogan

Eine Live-Vorschau (StationNameDemo, SloganDemo) zeigt die Eingaben sofort an.

Status-LEDs 1–4

Für jede LED (Gruppen LED1–LED4):

Standard-LED-Texte:

Gemeinsame inaktive Farben (Gruppe LEDS):

Logo

Schaltflächen: ... (Dateiauswahl), reset (Standard-Logo wiederherstellen).

OnAir Clock Mode / Colors

Anzeige

Apply wechselt das aktuelle Fenster nicht; die Option gilt beim nächsten Start. Ohne sie stellt OnAirScreen weiterhin den letzten Vollbild-Zustand wieder her (General/fullscreen, Standard an).

Update-Prüfung (kompilierte Versionen)

Die Update-Funktion ist für vorkompilierte (kostenpflichtige) Versionen gedacht.

Für die Update-Prüfung in der kostenpflichtigen Version muss ein Update Key eingegeben werden. Diesen erhältst du nach der Bestellung im Kundenportal unter customer.astrastudio.de. Das Feld ist maskiert; mit dem durchgestrichenen Auge wird es sichtbar.

---

5.2 Network

UDP / HTTP / Multicast

MQTT

MQTT-Passwort und API-Keys sind maskiert; mit dem durchgestrichenen Auge werden sie sichtbar.

MQTT Base Topic: onairscreen + letzte 6 Hex-Zeichen der MAC-Adresse, z. B. onairscreen_a1b2c3.

OSC

Send Host wird nur für unaufgeforderten Status-Push gebraucht (Companion-Button-Feedback). Abfragen antworten immer an den UDP-Absender.

---

5.3 Time Source

Die Anzeigeuhr kann der lokalen Systemuhr, einem NTP-Server, einem PTPv2-Master (IEEE 1588-2008) oder SMPTE-LTC folgen (Leo-Bodnar-LBE-1110-USB-Serial oder Dekodierung von einem lokalen Audioeingang). OnAirScreen ändert die Betriebssystem-Uhr nie. NTP und PTP steuern eine eigene Zeitbasis (time.monotonic()); ein Sprung der Systemuhr bewegt die Studio-Uhr nicht. LTC darf springen, stehenbleiben und enthält Frames (HH:MM:SS:FF).

Datum, Textuhr und AIR3-Top-of-Hour folgen derselben Wandzeit wie die große Uhr, wenn die Quelle Local, NTP oder PTP ist. Bei LTC bleiben sie auf der Systemzeit, weil LTC kein Kalenderdatum hat.

Local System Clock: Anzeige = Systemuhr. Mit NTP-Check wird die Systemuhr mit dem NTP-Server verglichen (Abweichung > 0,3 s oder Fehler → Warnung, Priorität -1).

NTP Server: OnAirScreen fragt das Feld NTP Server ab und steuert eine eigene Uhr. Nach dem ersten gültigen Sample wird die OS-Zeit nicht mehr verwendet. Das Feld bleibt editierbar, auch wenn NTP-Check aus ist. Bei NTP-Verlust läuft die letzte Zeit weiter, plus Warnung.

PTPv2 IEEE 1588-2008: Software-Slave auf Multicast 224.0.1.129 UDP 319/320, Delay-Mechanismus E2E. Typische Genauigkeit im Millisekundenbereich (kein Hardware-Timestamping). Das Interface unabhängig vom AoIP-Interface der Audio Meters wählen. Bei Sync-Verlust: letzte Zeit läuft weiter, plus Warnung.

LTC: Eine Zeitquelle mit zwei Eingängen. Die Framerate wird aus den eingehenden Frames abgeleitet (24 / 25 / 30). Bei LTC-Verlust wird der letzte Timecode gehalten (LTC NOT LOCKED). Die großen WARN-Meldungen (waiting for LTC lock, Clock not LTC synchronized, LTC reader not connected) sind standardmäßig aus, damit Scrubben/Videoschnitt WARN nicht flutet; Show LTC unlock warning einschalten, wenn sie gewünscht sind. Die Lock-LED zeigt immer LTC LOCK / LTC NOT LOCKED. NTP-Check vergleicht weiterhin die OS-Uhr mit dem NTP-Server, nicht den Timecode.

LBE-1110 Serial: USB-CDC-virtueller Seriellport eines Leo-Bodnar-LBE-1110; keine Treiber. Auto wählt ein Leo-Bodnar-Gerät (USB-VID 0x1DD2) oder einen LBE-1110-/CDC-Port.

Audio Input: Dekodiert SMPTE-LTC (Biphase-Mark) von einem lokalen PortAudio-Capture-Gerät, unabhängig von den Audio Meters (kein Livewire/AES67). Kanal Links oder Rechts (Standard Links). Auf manchen Hosts kann dasselbe Gerät nicht zweimal geöffnet werden — wenn die Meters diesen Eingang schon nutzen, für LTC ein anderes Gerät wählen.

Die Lock-LED unten rechts ist grün, wenn die gewählte Quelle eingerastet ist, sonst rot. Daneben: PTP LOCK / PTP NOT LOCKED, NTP LOCK / NTP NOT LOCKED, LTC LOCK / LTC NOT LOCKED oder LOCAL.

Empfehlung: Einen lokalen NTP-Server im Studio-Netzwerk verwenden, da pool.ntp.org zeitweise unzuverlässig sein kann.

---

5.4 Advanced

Verfügbare Textuhr-Sprachen: English, German, Dutch, French

Datumsformat-Platzhalter (Qt-Notation, Auszug):

Weather Widget (OpenWeatherMap)

Städtenamen neben City ID eingeben, Find (oder Return) drücken und einen Treffer in der Liste wählen. Die City-ID wird automatisch eingetragen; die ID kann weiterhin manuell gesetzt werden. Der API-Key ist maskiert; mit dem durchgestrichenen Auge wird er sichtbar.

Test API: Schaltfläche zum Testen der API-Verbindung mit aktuellen Einstellungen.

Verfügbare Wetter-Sprachen: Arabic, Bulgarian, Catalan, Czech, German, Greek, English, Persian (Farsi), Finnish, French, Galician, Croatian, Hungarian, Italian, Japanese, Korean, Latvian, Lithuanian, Macedonian, Dutch, Polish, Portuguese, Romanian, Russian, Swedish, Slovak, Slovenian, Spanish, Turkish, Ukrainian, Vietnamese, Chinese Simplified, Chinese Traditional

Weitere Informationen: WeatherWidget Guide

---

5.5 Timers

Für jeden AIR-Timer (Gruppe Timers):

Standard-AIR-Bezeichnungen und Icons:

---

5.6 Fonts

Für jedes UI-Element kann Schriftart, -größe und -stärke individuell gesetzt werden:

Die Familien-Combo listet Application Fonts (inkl. mitgeliefertem Roboto und Noto Sans). Die Größe ist ein Punkt-SpinBox (8–96 pt), Bold schaltet die Stärke, Reset stellt Roboto mit Default-Größe und Bold für die Zeile wieder her. Die Vorschau zeigt Beispieltext in der gewählten Schrift.

Zusätzlich werden Schriftarten aus dem fonts/-Verzeichnis beim Start geladen.

---

5.7 About

---

5.8 Audio Meters

Stereo-Pegelanzeige am linken Bildschirmrand: L/R (Sample-Peak, True Peak oder BBC PPM), ein einzelner Programme-LUFS-Balken (EBU R128) oder beides. L/R füllen mit RMS und legen den aktuellen Peak darüber. Programme-LUFS ist ein Balken (Momentary M, Short-term-S-Tick). Integrated I und LRA sind standardmäßig aus und starten mit LUFSI:START (Web-UI, MQTT-Home-Assistant-Schalter, Companion, OSC, UDP/HTTP oder Rechtsklick / Lang-Klick). LUFSI:RESET startet eine laufende Session neu; ist sie gestoppt, verschwinden I und LRA im Meter. Rechtsklick oder Lang-Klick auf den Main Screen → Start I+LRA, Stop I+LRA oder Reset I+LRA. Konfiguration unter Settings → Audio Meters.

Bestehende Configs mit Audio/unit=lufs (ohne layout) werden auf Layout lufs und L/R-Unit dbtp gemappt.

Silence Detection nutzt dieselbe Audioquelle wie die Meter (Local Input, Livewire oder AES67). Der Schwellwert ist immer Sample-Peak dBFS, unabhängig von der Meter-Anzeige. Capture läuft weiter, wenn Silence Detection an ist, auch wenn die Meter ausgeblendet sind.

Der Alarm rastet, wenn der Pegel die Duration lang unter dem Schwellwert bleibt, und löst nach der Recovery-Zeit über dem Schwellwert wieder. Show WARN in OAS ist unabhängig vom API/MQTT-Boolean: der Boolean wird aktualisiert, solange die Detection aktiv ist. Ein optionales HTTP GET wird nur bei der steigenden Flanke (false → true) ausgelöst.

Device/Stream absent: Wenn die Option an ist (Default), gilt eine Quelle, die nicht startet (kein Device, AES67 mit None, Startfehler), nach derselben Duration als Stille. Wenn die Option aus ist, zählen nur echte Pegel-Callbacks; Capture-Stop löscht einen hängenden Alarm. Paketverlust bei laufendem Stream (RTP-Timeout / Silence-Injection) zählt immer als Stille.

Das Bildschirm-WARN nutzt Priorität 2 (hoch) und liegt damit über TooLoud (Priorität 1). Das Flag silence in API/MQTT ist unabhängig von texts.warn und von warning/active.

Livewire: Der Rechner muss im AoIP-/Livewire-VLAN liegen (IGMP/Multicast). Solange die Settings (Desktop-Dialog oder WebUI-Overlay) offen sind, erscheinen announced Quellen in Livewire Source (239.192.255.3 UDP 4001, nur Standard-Stereo-Streams). Quelle wählen oder Kanalnummer eintippen. Kanal N entspricht Multicast 239.192.0.0 + N auf UDP-Port 5004 (48 kHz / 24‑Bit Stereo RTP). Nach Apply läuft der Empfang mit gespeichertem Kanal weiter, auch wenn die Ads verstummen.

AES67: SAP-Discovery lauscht auf 239.255.255.255 und RFC 2974 224.2.127.254 UDP 9875, solange der Einstellungsdialog oder das WebUI-Overlay offen ist. Die Stream-Liste aktualisiert sich live nur wenn Streams dazukommen oder verschwinden (kein Flackern bei unveränderter Liste). Die Combo hat immer None (kein Stream). SAP-Einträge verschwinden, wenn sie nicht mehr announced werden (Deletion oder Timeout). Paste SDP, falls ein Gerät nicht per SAP announced — diese Einträge bleiben in der Liste und sind mit pasted SDP gekennzeichnet. Unterstützt: L16/L24 bei 44,1/48/96 kHz, 1–64 Kanäle (Meter zeigt Kanal 1–2). Dante-AES67-SAP-Streams erscheinen wie andere (a=keywords:Dante nur als Label). Kein PTP und kein Playout — nur Metering. Nach Apply läuft der Empfang mit gespeicherter Adresse/Port weiter, auch wenn SAP gerade schweigt. Apply mit None beendet den AES67-Empfang und setzt das Meter zurück.

Lokaler Eingang: unter macOS Mikrofon-Berechtigung für OnAirScreen.

---

5.9 GPIO

Raspberry-Pi-GPIO-Eingänge legen Mixer-GPI-Kontakte auf dieselben LED- und AIR-Kommandos wie die Netzwerk-API. Einstellen unter Settings → GPIO. Nur auf dem Raspberry Pi verfügbar.

Pi-GPIO ist 3,3 V. Mixer-GPI ist oft 5–24 V oder Open Collector — immer ein PC817-Isolationsmodul verwenden. Potenzialfreie Relaiskontakte nach GND dürfen direkt angeschlossen werden (interner Pull-up, Invert an).

Level (typisch Tally/Fader): geschlossen sendet LED1:ON / AIR3:ON, offen sendet OFF. Rising / Falling / Both senden TOGGLE (oder Reset / das Custom-Kommando) auf dieser Flanke.

Werks-Mapping für zwei Mixer-GPI-Leitungen: GPI1 BCM 17 → LED1 (ON AIR), GPI2 BCM 27 → AIR3 (Radio-Timer). GPIO aktivieren und Kontakte über ein PC817-Modul (oder trockene Relais nach GND) anschließen.

Sichere BCM-Pins: 5, 6, 12, 13, 16, 17, 22, 23, 24, 25, 26, 27 (nicht I2C 2/3 oder UART 14/15).

Verdrahtung

Der 40-polige GPIO-Header ist derselbe auf Raspberry Pi 3, 4, 400, 5, 500, Zero 2 W und dem CM4/CM5-IO-Board-Header. In den Settings gelten BCM-Nummern, nicht die physischen Stiftnummern.

PC817-Modul (empfohlen bei Mixer-GPI 5–24 V oder Open Collector):

Jeder Mixer-GPI besteht aus zwei Adern: IN1–IN8 dieses Kanals und das GND der Eingangsseite. Auf der Pi-Seite denselben Kanal OUT1–OUT8 an den BCM-Pin und das GND der Ausgangsseite an Pi-GND (GPI1 → IN1/OUT1, GPI2 → IN2/OUT2, …). Invert anlassen (aktiv = Pin nach GND gezogen). Beispiel: Hailege 8-Kanal-PC817-Isolationsmodul (Amazon-Affiliate-Link).

Nur trockener Relaiskontakt (bereits isoliert, keine Spannung am Mixer-GPI):

Keine 5 V oder 12/24 V direkt auf einen GPIO-Pin legen.

Werks-Defaults am Header (Platine mit USB/Ethernet nach unten; Stift 1 ist bei den meisten Boards die 3,3-V-Ecke am SD-/Power-Ende):

Sichere BCM-Pins und zugehörige Header-Stifte (diese Werte unter BCM pin):

Pinout-Referenzen (40-poliger Header, BCM-Nummerierung):

• Raspberry Pi GPIO and 40-pin header (offiziell)
• pinout.xyz (interaktiv; gleicher Header auf Pi 3 / 4 / 5 / Zero 2 W)
• Pi 5 Überblick: Raspberry Pi 5
• Compute-Module-IO-Boards: Compute Module

---

6. Funktionen im Detail

6.1 Status-LEDs

Jede LED kann einzeln ein- und ausgeschaltet werden (Tasten 1–4, Linksklick, oder Fernsteuerung). Im aktiven Zustand werden konfigurierte Vorder- und Hintergrundfarben verwendet; im inaktiven Zustand die gemeinsamen Inaktiv-Farben.

Blinkmodi:

• Autoflash: Blinkt dauerhaft im 500-ms-Takt, solange die LED eingeschaltet ist
• 20sec flash: Blinkt 20 Sekunden, schaltet sich dann automatisch aus

6.2 AIR-Timer

Alle AIR-Timer zählen die verstrichene Zeit im Format M:SS (z. B. 3:45). AIR3 zeigt ▲ (Hochzählen) oder ▼ (Runterzählen) unter dem Timer-Icon.

AIR1 (Mikrofon) und AIR2 (Telefon)

• Einfache Stoppuhr: Start/Stopp, Sekunden werden bei Start auf 0 zurückgesetzt
• Steuerung: M// (AIR1), P/* (AIR2), oder Linksklick auf den Timer

AIR3 (Radio-Timer)

Der vielseitigste Timer mit drei Betriebsarten:

1. Hochzählen (Count-Up): Standardmodus, zählt von 0:00 aufwärts
2. Runterzählen (Count-Down): Wird per AIR3TIME:seconds oder Timer-Dialog gesetzt
3. Top-of-Hour (TOH): Countdown bis zur nächsten vollen Stunde (Format MM:SS, z. B. 22:38)

Start/Stopp: Leertaste, , / ., oder Linksklick auf den Timer.

Top-of-Hour-Verhalten:

• Erster Aufruf: Berechnet verbleibende Zeit bis :00, startet Countdown, Beschriftung ist der konfigurierte TOTH-Timer-Text (Standard TOTH Timer)
• Zweiter Aufruf (oder OFF/TOGGLE während aktiv): Stoppt und stellt die konfigurierte AIR3-Beschriftung wieder her
• Synchronisiert mit der Anzeigeuhr, stoppt automatisch bei Stundenwechsel und stellt die konfigurierte Beschriftung wieder her
• API-Status: "topOfHour": true und "text" mit dem konfigurierten TOTH-Timer-Text in air[3] wenn aktiv

Timer-Eingabedialog (Enter):

AIR4 (Stream-Timer)

• Wie AIR3, aber ohne Top-of-Hour-Funktion
• Steuerung: S oder Linksklick (Start/Stopp), Alt+S (Reset)

6.3 Textzeilen NOW, NEXT, WARN

Maximale Textlänge: 500 Zeichen (Eingaben werden automatisch bereinigt und gekürzt).

Warnungssystem mit Prioritäten

Anzeigeregel: Die Warnung mit der höchsten Priorität wird angezeigt. NTP-Warnungen (-1) erscheinen nur, wenn keine andere Warnung aktiv ist. Bei aktiver Warnung werden NOW und NEXT ausgeblendet.

Warnung löschen:

6.4 IP-Adressen anzeigen

Taste I (oder automatisch beim Start) zeigt alle lokalen IPv4-Adressen in NOW und IPv6-Adressen in NEXT für 10 Sekunden an.

Wenn Replace IPs after 10s aktiviert ist, wird die NOW-Zeile danach durch den konfigurierten Ersatztext (replacenowtext) ersetzt.

6.5 Uhr

• Digital: LED-Style-Ziffernanzeige mit konfigurierbaren Farben
• Analog: Klassisches Zifferblatt
• Textuhr: Sprachliche Zeitanzeige (z. B. „it's a quarter past three")
• Zeitquelle: Local, NTP, PTPv2 oder LTC — siehe 5.3 Time Source; die OS-Uhr wird nie gesetzt
• Lock-LED unten rechts: grün = eingerastet, rot = nicht eingerastet (PTP LOCK / NTP LOCK / LTC LOCK oder LOCAL)
• Wetter-Widget: Optional rechts neben der Uhr (OpenWeatherMap)

6.6 Systembefehle (nur API)

Diese Befehle sind nicht über die Einstellungs-UI erreichbar, sondern nur per API/MQTT.

6.7 GPIO-Eingänge (Raspberry Pi)

Mixer-GPI (Kontakt) kann LEDs und AIR-Timer über die Raspberry-Pi-GPIO ansteuern. Schaltplan, PC817-Modul, Header-Stifte und Pinout-Links stehen unter 5.9 GPIO. GPIO ist lokale Hardware, keine Netzwerk-API.

---

7. Fernsteuerung und API

OnAirScreen unterstützt Fernsteuerung über UDP, HTTP, Web-UI, MQTT, OSC, REST-API und Bitfocus Companion.

7.1 UDP (Port 3310)

# LED1 einschalten
echo "LED1:ON" > /dev/udp/127.0.0.1/3310
 
# NOW-Text setzen
echo "NOW:Aktueller Songtitel" > /dev/udp/127.0.0.1/3310
 
# Konfiguration ändern
echo "CONF:LED1:text=STUDIO LIVE" > /dev/udp/127.0.0.1/3310
echo "CONF:CONF:APPLY=TRUE" > /dev/udp/127.0.0.1/3310

7.2 HTTP (Port 8010)

curl "http://127.0.0.1:8010/?cmd=LED1:ON"
curl "http://127.0.0.1:8010/?cmd=NOW:Aktueller%20Song"

7.3 Web-UI

Browser öffnen: http://<IP-Adresse>:8010/

Funktionen der Web-UI:

• Echtzeit-Status für LEDs, AIR-Timer, Textfelder, Silence-Alarm und Loudness I+LRA (I- und LRA-Werte plus Laufstatus)
• Instanzname in Titel und Status (aus /api/status instance)
• WebSocket-Updates (mit HTTP-Polling-Fallback; nach Polling wird wieder WebSocket versucht)
• Dark Mode mit persistenter Theme-Einstellung
• LED- und Timer-Steuerung mit Toggle-Buttons
• Start / Stop / Reset für Programme-I + LRA (LUFSI)
• Top-of-Hour-Button für AIR3
• AIR3-Zeit setzen (m:ss, m,ss oder Sekunden)
• AIR3 Count-up vs. Countdown in der Statuskachel
• Tasten 1–4 schalten LEDs (nicht während der Texteingabe)
• Texteingabe für NOW, NEXT, WARN (NOW/NEXT folgen dem Live-Status, solange nicht editiert wird)
• Warnungen mit Priorität und Lösch-Button
• Versions- und Distributionsinformationen
• Dauerhaftes Connection-Badge (Live / Polling / Offline) plus Fehler-Modal
• Zahnrad oben rechts: Settings-Overlay für alle editierbaren Einstellungen, optionale PIN, Apply sowie Presets laden/speichern
• Audio Meters im Overlay: Dropdowns Livewire Source und AES67 Stream (Live-Discovery solange das Overlay offen ist) plus Paste SDP

7.4 REST-API

Status abfragen:

curl http://127.0.0.1:8010/api/status

Antwort (vereinfacht):

{
  "leds": { "1": { "status": true, "text": "ON AIR", "autoflash": false } },
  "air": { "3": { "status": false, "seconds": 0, "text": "Timer", "topOfHour": false, "countDown": false } },
  "texts": { "now": "Song", "next": "Next Song", "warn": "" },
  "warnings": [],
  "silence": false,
  "lufsIntegrated": false,
  "lufsI": null,
  "lra": null,
  "instance": "Studio-1",
  "version": "1.0.0beta12",
  "distribution": "OpenSource"
}

Das Feld silence ist true, solange Silence Detection eingerastet ist, auch wenn das Bildschirm-WARN ausgeschaltet ist. lufsIntegrated ist true, solange eine I+LRA-Session läuft (LUFSI:START). lufsI ist die gated Integrated Loudness in LUFS (eine Nachkommastelle), lra die Loudness Range in LU; beide sind null, bis genug Audio gemessen wurde. instance ist der konfigurierte Instanzname. Bei AIR3 zeigt topOfHour, ob der Top-of-Hour-Countdown aktiv ist, und countDown, ob der Radio-Timer runterzählt.

Befehl senden:

curl "http://127.0.0.1:8010/api/command?cmd=LED1:ON"

Web-Settings (optionale PIN über X-Settings-Token nach POST /api/settings/auth):

curl http://127.0.0.1:8010/api/settings/auth
curl -X POST http://127.0.0.1:8010/api/settings/auth -H 'Content-Type: application/json' -d '{"pin":"1234"}'
curl http://127.0.0.1:8010/api/settings
curl "http://127.0.0.1:8010/api/settings/aoip?source=livewire&channel=1"
curl -X PUT http://127.0.0.1:8010/api/settings -H 'Content-Type: application/json' -d '{"config":{"General":{"slogan":"On air"}}}'

Geheimnisse (updatekey, MQTT-Passwort, OpenWeatherMap-API-Key) kommen im Klartext zurück, damit das Overlay sie anzeigen kann. Die PIN kommt als __unchanged__ zurück (gespeichert wird nur der Hash). Diesen Sentinel senden, um die PIN zu behalten; - entfernt sie. Änderungen an UDP-/HTTP-Port werden gespeichert, greifen aber erst nach einem App-Neustart.

7.5 MQTT

Befehle senden (Topic: {base_topic}/...):

Status-Topics (automatisch publiziert):

Home Assistant Autodiscovery erstellt automatisch:

• LED-Schalter (LED1–4)
• AIR-Timer-Schalter (AIR1–4)
• AIR-Zeit-Sensoren (AIR1–4 Time)
• Reset-Buttons (AIR3/AIR4)
• Top-of-Hour-Button (AIR3)
• Text-Entitäten (NOW, NEXT, WARN)
• Binary Sensoren: Warning Active, Silence
• Sensor: Instance (Instanzname)
• Loudness-I+LRA-Schalter (Start setzt zurück; Stop friert die letzten Werte)
• Loudness-I+LRA-Reset-Taste (laufend neu starten; gestoppt I und LRA ausblenden)
• Sensoren: Loudness I (LUFS), Loudness LRA (LU)

Der Home-Assistant-Gerätename lautet OnAirScreen (Studio-1), wenn der Instanzname noch nicht im MQTT Device Name steht.

7.6 Bitfocus Companion (empfohlen)

Das eigene Companion-Modul astrastudio-OnAirScreen ist der empfohlene Weg für Stream Decks und ähnliche Oberflächen. Befehle gehen über HTTP (Port 8010): GET /api/command?cmd=LED1:ON. Der Live-Status nutzt bevorzugt den OnAirScreen-WebSocket auf HTTP-Port + 1 (also 8011, wenn HTTP 8010 ist) und fällt auf Polling von GET /api/status zurück (Standard alle 500 ms). OSC ist nicht nötig. Die AIR-Zeiten auf den Buttons bleiben nah am Studiobildschirm (MIC = AIR1). Beide Ports in der Firewall freigeben.

OnAirScreen: HTTP muss erreichbar sein (Standard). OSC kann aus bleiben.

Companion (lokales Modul, bis es im Companion Store liegt):

1. Im Repo OAS-Companion: yarn install && yarn build
2. Ordner als companion-module-astrastudio-onairscreen nach Companion module-local-dev verlinken (oder unter Companion Developer den Pfad eintragen)
3. Companion neu starten und Connection astrastudio / OnAirScreen anlegen
4. Host = OnAirScreen-IP, HTTP-Port 8010 (wie unter Settings → Network). WebSocket anlassen, außer du musst nur pollen.

Presets: LED1–4 (Toggle + Farbe), AIR1–4 mit Live-Beschriftung und Zeit auf dem Button (MIC = AIR1), TOTH, Reset AIR3/4, NOW / NEXT / WARN, Silence, Loudness I+LRA, Reset I+LRA.

Variablen wie $(oas:air1_time), $(oas:lufs_i) und $(oas:lra) und Feedbacks (LED an, AIR läuft, TOTH, Silence, WARN, Loudness I+LRA) kommen aus WebSocket oder Status-Poll. Connection-Label auf oas setzen, damit die Beispiele passen. Der Connection-Status zeigt Instanzname und Version, z. B. Studio-1 · 1.0.0beta12. Die HELP.md des Moduls listet alle Aktionen, Feedbacks und Variablen.

Wenn kein eigenes Modul geladen werden kann, bleibt Generic OSC als Alternative (nächster Abschnitt). OSC-Status-Push ist langsamer (alle 5 Sekunden) als HTTP-Poll / WebSocket.

7.7 OSC (Port 8000)

OSC unter Settings → Network einschalten. Prefix ist /oas. Integer 1/0 bedeutet AN/AUS; ohne Argument = TOGGLE. Texte als String.

Setzen (Befehle):

Abfrage (Antwort an den UDP-Absender, kein Send Host nötig): /state-Adresse senden (oder /oas/status für alles). Antworten sind Integer 0/1 für Booleans und Strings für Texte. /oas/lufs/integrated/state zeigt, ob I + LRA läuft. /oas/lufs/i und /oas/lufs/lra liefern I (LUFS) und LRA (LU) als String mit einer Nachkommastelle, oder leer wenn unbekannt.

Push (Companion-Feedback): OSC Send Host auf den Companion-Rechner, OSC Send Port auf den Generic-OSC-Feedback-Port. OnAirScreen sendet dann /oas/led1/state usw. nach Änderungen und alle 5 Sekunden.

# LED1 toggeln
python3 utils/oas_osc_send.py /oas/led1
 
# LED1 an
python3 utils/oas_osc_send.py /oas/led1 1

Alternative: Generic OSC

Wenn OSC bevorzugt wird oder das HTTP-Modul nicht geladen werden kann, eingebaute Connection OSC Generic.

Nur steuern:

1. OnAirScreen: OSC an, Listen-Port 8000
2. Companion: OSC Generic, Target = OnAirScreen-IP, Port 8000
3. Button-Action Send integer, Pfad /oas/led1, Wert 1 (an) oder 0 (aus). Ohne Argument = Toggle. Send string für /oas/text/now.

Button-Feedback (Stream-Deck-Farbe):

1. Companion: OSC-Generic-Feedback-Listen-Port setzen (z. B. 9000)
2. OnAirScreen: OSC Send Host = Companion-IP, OSC Send Port = dieser Feedback-Port
3. Feedback Listen for OSC messages (Integer) auf /oas/led1/state, Vergleich 1

Query-Reply an den Command-Socket nutzt Companion nicht (anderer UDP-Port).

7.8 Befehlsreferenz

Steuerungsbefehle

Remote-Konfiguration (CONF)

Format: CONF:GRUPPE:PARAMETER=WERT

Änderungen werden erst nach CONF:CONF:APPLY=TRUE aktiv und gespeichert.

CONF:Audio:unit=lufs wird weiterhin akzeptiert und setzt das Layout auf lufs (L/R-Einheit bleibt dbtp).

Farben: Hex-Format (#FF0000) oder Farbnamen.

---

8. Presets (Profile)

Presets ermöglichen das Speichern und Laden kompletter Konfigurationen.

Speicherort: <Konfigurationsverzeichnis>/presets/<name>.json

Presets enthalten Metadaten (Name, Version) und die vollständige Konfiguration als JSON. Nach dem Laden muss Apply geklickt werden, damit die Einstellungen aktiv werden.

Hinweis: MQTT-Einstellungen werden in der Konfigurationsdatei gespeichert, sind aber bewusst nicht im Preset-Export enthalten. MQTT-Zugangsdaten sind installations- und umgebungsspezifisch und sollen nicht mit visuellen Profilen mitexportiert werden.

---

9. Kommandozeilenoptionen

python start.py --loglevel DEBUG
python start.py -l WARNING

Das Log-Level aus den Einstellungen (About/Loglevel) kann zusätzlich die Werte NONE (kein Logging) enthalten.

---

10. Konfigurationsspeicherort

Einstellungen werden über Qt QSettings gespeichert:

• Organisation: astrastudio
• Anwendung: OnAirScreen

Der genaue Pfad wird im Register About unter Settings Path angezeigt. Typische Speicherorte:

Logs und Crash-Reports liegen separat. Der genaue Pfad steht im Register About unter Log Folder:

Dateien in diesem Ordner:

• onairscreen.log — rotierendes Anwendungs-Log (gleicher Inhalt wie stderr, folgt dem Log-Level)
• crash-YYYYMMDD-HHMMSS.txt — ungefangene Python-Exceptions (Traceback, Version, OS; keine Settings oder Passwörter). Nach einem Main-Thread- oder Qt-Fatal-Crash beendet sich die Anwendung; Fehler in Hintergrund-Threads werden nur geloggt.
• fault.log — native Abstürze (Segfaults in Qt oder C-Erweiterungen)

Crash-Dateien werden immer geschrieben, auch wenn das Log-Level NONE ist. Den Log-Ordner nur an den Support schicken, nicht öffentlich posten (DEBUG-Logs können Hostnamen oder Befehle enthalten). Nach einem Prozess-Absturz zeigt der nächste Start einen Dialog mit Open log folder; er schließt sich nach 30 Sekunden automatisch.

---

11. Fehlerbehebung

OnAirScreen startet nicht / Port belegt

• Prüfen, ob UDP-Port 3310 oder HTTP-Port 8010 bereits belegt ist
• Ports in Network ändern

Fernsteuerung funktioniert nicht

• Firewall-Regeln für UDP/HTTP/OSC-Ports prüfen
• Korrekte IP-Adresse und Ports verwenden
• Mit curl http://127.0.0.1:8010/api/status lokal testen

GPIO schaltet LEDs oder Timer nicht

• GPIO funktioniert nur auf dem Raspberry Pi. Status unter Settings → GPIO prüfen
• Status „gpiozero library not available“: sudo apt install python3-gpiozero python3-lgpio python3-rpi-lgpio (auf dem OnAirScreen-Pi-Image bereits enthalten)
• PC817-Modul verwenden; niemals 5–24 V vom Mixer direkt auf Pi-Pins
• Invert (Standard an für Kontakt nach GND) sowie Level- vs. Flanken-Modus prüfen
• GPIO und die jeweilige GPI-Zeile aktivieren, dann Apply

Companion-Modul zeigt Disconnected

• HTTP muss auf dem konfigurierten Port erreichbar sein (Standard 8010); OSC nutzt dieses Modul nicht
• Mit curl http://<OnAirScreen-IP>:8010/api/status JSON prüfen
• Nach yarn build Companion neu starten, damit das lokale Modul neu geladen wird

Silence Detection löst nicht aus

• Ist Enable Silence Detection aktiviert und mit Apply gespeichert?
• Audioquelle prüfen (Device gewählt, Livewire-Kanal, AES67-Stream nicht None)
• dBFS-Schwellwert senken oder Duration verkürzen, wenn Restgeräusch über −50 dBFS liegt
• Fehlt Device oder Stream, Trigger silence warning when Device/Stream is absent einschalten

MQTT-Verbindung schlägt fehl

• MQTT-Broker erreichbar? (mqttserver, mqttport)
• Zugangsdaten korrekt?
• enable MQTT support aktiviert und mit Apply gespeichert?

NTP-Warnung erscheint dauerhaft

• Lokalen NTP-Server konfigurieren (NTP/ntpcheckserver)
• Bei Quelle Local die Systemzeit synchronisieren oder die Zeitquelle auf NTP/PTP umstellen
• NTP-Prüfung deaktivieren, falls nicht benötigt

Wetter-Widget zeigt nichts

• Gültigen OpenWeatherMap API-Key eingeben
• Städtenamen mit Find neben City ID suchen oder die ID manuell eingeben
• Test API in den Einstellungen ausführen

Livewire-Meter zeigt keine Pegel

• Source auf Livewire gesetzt und Channel-Nummer korrekt (oder announced Quelle gewählt)?
• Rechner im AoIP-/Livewire-VLAN? IGMP/Multicast nicht gefiltert?
• Passendes Netzwerk-Interface gewählt (nicht „Default“, falls mehrere NICs)?
• UDP-Port 5004 freigegeben?
• Keine Namen unter Livewire Source: Ads laufen auf 239.192.255.3:4001 nur bei offenen Settings (Desktop oder WebUI-Overlay). Die Kanalnummer kann trotzdem manuell eingegeben werden.

AES67-Meter: keine Streams oder keine Pegel

• Keine Streams in der Liste: AoIP-Interface, VLAN und IGMP prüfen; SAP ist 239.255.255.255:9875 und 224.2.127.254:9875 und läuft nur bei offenem Settings-Dialog oder WebUI-Overlay. Wenn das Gerät nicht announced, Paste SDP verwenden.
• Stream da, Meter bleibt stumm: RTP-Adresse/Port und Codec (L16 vs. L24). Dante muss im AES67-/SAP-Modus sein. PTP ist fürs Metering nicht nötig.

Einstellungen zurücksetzen

1. Einstellungsdialog öffnen (Ctrl+S)
2. Register About → Enable Reset all settings button aktivieren
3. Reset all OnAirScreen settings to default klicken
4. Apply klicken

Logs an den Support schicken

Wenn OnAirScreen abstürzt oder sich unerwartet verhält:

1. Settings → About öffnen
2. Open log folder klicken (oder den Pfad unter Log Folder kopieren)
3. onairscreen.log und vorhandene crash-*.txt-Dateien schicken (plus fault.log, falls nicht leer)

Die Reports enthalten keine Settings, MQTT-Passwörter oder API-Keys. --loglevel DEBUG nur kurz zum Reproduzieren nutzen, bevor die Logs verschickt werden. Nach einem Absturz erscheint dieser Dialog auch beim nächsten Start (schließt sich nach 30 Sekunden).

---

Anhang: Ereignisprotokollierung

OnAirScreen protokolliert intern folgende Ereignistypen:

• LED-Änderungen (Quelle: manual, autoflash, timedflash, API)
• AIR-Timer Start/Stopp/Reset
• Empfangene Befehle (UDP/HTTP/OSC)
• Warnungen hinzugefügt/entfernt
• Einstellungsänderungen
• Systemereignisse (Start, Beenden, Neustart)

Das Log-Level steuert die Ausgabemenge. Bei Problemen empfiehlt sich temporär --loglevel DEBUG. Logs werden zusätzlich nach onairscreen.log im Log-Ordner geschrieben (siehe About).

---

© 2012–2026 Sascha Ludwig · astrastudio.de