OnAirScreen – User Manual

Version: 1.0.10
Author: Sascha Ludwig, astrastudio.de
Project: OnAirScreen
German version: Bedienungsanleitung

---

Table of Contents

1. Overview
2. Installation and Startup
3. Main Screen
4. Keyboard Shortcuts (Hotkeys)
5. Settings Dialog
6. Features in Detail
7. Remote Control and API
8. Presets (Profiles)
9. Command-Line Options
10. Configuration Storage Location
11. Troubleshooting

---

1. Overview

OnAirScreen is a versatile on-air lamp solution for professional broadcast environments. The application combines:

• 4 status LEDs (switchable, blinking, timed flash)
• 4 AIR timers (microphone, phone, radio timer, stream timer); AIR3 with ▲/▼ and Top-of-Hour
• Digital or analog clock with optional text clock mode and lock LED (Local / NTP / PTP / LTC)
• Stereo audio meters (local input, Axia Livewire, or AES67 AoIP): L/R, programme LUFS, or both, optional I+LRA
• Silence Detection with optional on-screen WARN and API/MQTT boolean
• Instance name (DNS-safe, e.g. Studio-1) to tell several OnAirScreens apart
• Text lines NOW, NEXT, and WARN (with priority system)
• Weather widget (OpenWeatherMap)
• Remote control via keyboard, mouse (double-click/right-click/long-click), UDP, HTTP, Web UI, MQTT, OSC, SNMP, REST API, and Bitfocus Companion
• Home Assistant integration via MQTT Autodiscovery
• GPIO inputs on Raspberry Pi (mixer GPI via optocoupler), Axia Livewire GPIO (multicast or LWRP TCP 93, e.g. mic ON lamp), and MIDI (Note/CC from one interface)
• Instance links: 1→n replicas (full LED/AIR/NOW/NEXT/WARN status) and per-signal mappings (e.g. hallway tallies from several studios)

The application starts in fullscreen mode by default with the mouse cursor hidden, making it suitable for dedicated studio monitors, Raspberry Pi setups, and touch-free operation.

OnAirScreen automatically adapts to different monitor aspect ratios and works on both 4:3 and 16:9/16:10 displays.

---

2. Installation and Startup

Ready-to-run builds for Windows, macOS, Linux, and Raspberry Pi are available from the astrastudio shop. One license covers one PC or one Raspberry Pi. Each additional computer needs its own license. The same license can be moved to a replacement computer when the previous one is no longer in use.

OnAirScreen starts in fullscreen with the mouse cursor hidden. Open Settings with Ctrl+S (macOS: Cmd+S). Changes apply only after Apply.

Windows

1. Download OnAirScreen_*_Win_x64.msi (inside OnAirScreen_Win_x64.zip).
2. Double-click the MSI and follow the installer. A per-machine install needs administrator rights.
3. OnAirScreen is installed to C:\Program Files\OnAirScreen.
4. Start it from the Start menu or the desktop shortcut.

The Start menu folder also contains OAS Send (command sender) and OAS Send (no console). Settings live in the Windows Registry; logs under %LOCALAPPDATA%\astrastudio\OnAirScreen\logs\.

An older portable .exe is not removed by the MSI. Delete that copy yourself after installing.

Windows only syncs internet time about once a week by default, which can show the wrong clock if the time source is Local. Shorten the OS sync interval, or use NTP / PTP / LTC in OnAirScreen (see 5.8 Time Source).

macOS

1. Download OnAirScreen_*_macOS.dmg.
2. Open the DMG and drag OnAirScreen.app into Applications. Do not run it from the DMG.
3. Start OnAirScreen from Applications, Launchpad, or Spotlight.

Shop builds are signed with an Apple Developer ID and notarized. After you copy the app to Applications, start it from Applications, Launchpad, or Spotlight. For local audio meters, grant Microphone permission.

Linux (Debian / Ubuntu / Raspberry Pi OS)

Official builds are a .deb. After install the app lives in /opt/onairscreen, starts as onairscreen, and appears in the application menu.

Check with dpkg --print-architecture. The two packages are not interchangeable.

Raspberry Pi: 64-bit OS on Zero 2 W, Pi 3 / 4 / 400, CM4, Pi 5 / 500, CM5. Not supported: Pi 1 and classic Zero. You need a graphical desktop, not Lite without a GUI.

Unzip the download, then install with apt (not dpkg -i alone) so PortAudio, OpenGL, and Xcb are pulled in. The ./ in front of the file is required:

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

Start from the application menu or run onairscreen. Updates: install the new .deb the same way; settings are kept. Uninstall with sudo apt remove onairscreen (config in ~/.config stays).

If you used dpkg -i and dependencies are missing: sudo apt -f install.

Packages are OpenPGP-signed. Optional verification: Package signing (GPG).

Fedora

The Fedora RPM is built on Fedora 44 (Fedora 44+). Older RHEL, Rocky, or Alma may fail because of glibc.

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

dnf pulls in PortAudio and other system libraries. Check the signature with rpm -K OnAirScreen_*_Fedora_x64.rpm (expected: digests signatures OK).

Raspberry Pi SD-card image

The SD-card image is a ready-to-boot 64-bit Raspberry Pi OS with OnAirScreen already installed (desktop autologin, GPIO included). Unzip the download; inside is OnAirScreen_*_RaspberryPiOS_Image.img.

Use Raspberry Pi Imager:

• macOS
• Windows
• Ubuntu x86

1. Insert a microSD card.
2. Start Raspberry Pi Imager.
3. Choose OS → Use custom → select the OnAirScreen .img file (not the .zip).
4. Choose storage (or Choose SD Card) and select the card.
5. Write.

Default user: pi / password OnAirScreen1!. Hostname: onairscreen. Change the password after first boot. SSH is enabled. Host reboot and shutdown from OnAirScreen (Settings, Web UI, or CMD:REBOOT / CMD:SHUTDOWN) work without a password on this image.

On the desktop: OnAirScreen, OAS Pi Settings (optional autostart), on-screen keyboard, network icon. First boot grows the root filesystem to fill the card.

If you already run Raspberry Pi OS 64-bit with a desktop, install the Pi .deb instead (see Linux above).

First Startup

On first launch, default settings are loaded. Open the settings dialog with Ctrl+S (macOS: Cmd+S). Changes are only applied and saved after clicking Apply.

---

3. Main Screen

The main screen is divided into the following areas:

Areas in Detail

Note: Status LEDs and AIR timers can be toggled by left-click, keyboard, or remote control. Double-clicking a LED/timer does not toggle fullscreen.

Fullscreen Mode

• Default: fullscreen with hidden mouse cursor
• Toggle: F or Ctrl+F (macOS: Cmd+F), double-click an empty area of the main screen, or right-click / long-click → Toggle Fullscreen
• Right-click / long-click menu: Toggle Fullscreen, Settings, Hotkeys, Quit OnAirScreen; when meters are enabled also Start I+LRA, Stop I+LRA, and Reset I+LRA
• Fullscreen state is saved in settings (General/fullscreen)
• Settings → General → Always start in fullscreen mode (General/always_start_fullscreen, default off) forces fullscreen on every start, even if the last session was windowed. Apply takes effect on the next start.
• In windowed mode, position and size are saved (Window/geometry) and restored on the next start

---

4. Keyboard Shortcuts (Hotkeys)

On macOS, Ctrl is replaced by Cmd (⌘).

Application

The overlay lists these shortcuts on the main screen. Close it with H, Esc, or a click on the dimmed background. Other main-window hotkeys are blocked while it is open; Esc does not quit until the overlay is closed. Right-click / long-click → Hotkeys opens the same overlay.

While quitting, the main screen shows WARN QUITTING ONAIRSCREEN until the window closes.

Status LEDs

Left-click on a status LED toggles it as well.

AIR Timers

Left-click on an AIR timer starts or stops it (same as M / P / Space / S). Reset, TOTH, and the timer dialog stay keyboard or remote.

OAS USB Keyboard (Special Mapping)

---

5. Settings Dialog

The settings dialog opens with Ctrl+S or Ctrl+, (or right-click / long-click → Settings). If it is already open, the existing window is brought to the front without reloading values. Running AIR timers (including TOTH) stay intact. It contains several tabs (arranged vertically on the left):

Buttons (bottom bar)

---

5.1 General

Instance Name

The instance name appears in the Web UI (title and status), in /api/status (instance), on MQTT {base}/instance/state, and as a Home Assistant sensor. The HA device name becomes OnAirScreen (Studio-1) unless the instance name is already part of the device name. Remote: CONF:General:instancename=TEXT.

The name must be unique on the LAN. If another OnAirScreen announces the same name, Settings → General, Settings → Links, and the Web UI show a warning with the other host(s). Nearby lists each colliding host separately (name collision). Linking does not guess which IP to use — set the host, or rename one instance. Apply is rejected while the name still collides.

Station Name and Slogan

A live preview (StationNameDemo, SloganDemo) shows your input immediately.

Status LEDs 1–4

For each LED (groups LED1–LED4):

Default LED texts:

Shared inactive colors (group LEDS):

Logo

Buttons: ... (file picker), reset (restore default logo).

OnAir Clock Mode / Colors

Display

Apply does not switch the current window; the option applies on the next start. Without it, OnAirScreen still restores the last fullscreen state (General/fullscreen, default on).

5.2 Updates

Update Check (compiled versions)

The update feature is intended for precompiled (paid) versions.

To use update checking in the paid version, an Update Key must be entered. You can find it in the customer portal at customer.astrastudio.de after placing your order. One license covers one PC or one Raspberry Pi. The field is masked; use the slashed-eye icon to show it.

Activation (paid builds)

Shop builds must be activated. Self-built OpenSource builds are not.

1. Copy the update key from the customer portal into Update Key.
2. Activate (needs internet) or copy the Hardware ID, download a license file in the portal, and Import license file.
3. The activation is valid for one year unless your order is set differently. The Updates tab shows whether this computer can renew online now. If the license server is not reachable, download a new license file in the portal and import it before the activation expires. The update key stays the same. You do not buy a new key.
4. To move the license, choose Return license, then redeem the return code in the portal (or it is redeemed automatically when this computer is online). Activate the new computer. A dead computer can only be released by astrastudio support.
5. Without a license, OnAirScreen runs fully for 14 days. After that it stays visible but cannot go fullscreen, use GPIO or audio meters, or save settings. The window is limited to 1280×800 and the app closes after 15 minutes. The same limits apply when a license has expired.
6. At startup the update key is checked with the license server even when Check for Updates is off. If the server rejects the key, the license on this computer is removed at once and the same limits apply. Later starts do not repeat that automatic check or the notice. Check now still runs. A missing network connection does not remove the license. A new activation checks the key again.

If this activation does not fit your use case, contact us via the contact form. We will work out a custom solution.

The same actions are in the Web UI settings overlay.

---

5.3 Network

UDP / HTTP / Multicast

MQTT

MQTT password and API keys are masked; use the slashed-eye icon to show them.

MQTT Base Topic: onairscreen + last 6 hex characters of the MAC address, e.g. onairscreen_a1b2c3.

OSC

Send Host is only needed for unsolicited status push (Companion button feedback). Queries always reply to the UDP sender.

SNMP

At least a v2c community or a v3 user must be set, or the agent will not start. Community and v3 passwords are masked.

---

5.4 Links

Link several OnAirScreens on the LAN (multicast discovery by instance name) or by typing a host and HTTP port. Instance names must be unique; a collision is flagged in Settings and the Web UI, and Apply is rejected. There are no exclusive master/slave roles: any instance can publish replicas and subscribe to sources.

Replicas (this screen is the source): add nearby instances. Apply writes a Follow on each target and pushes the full runtime status: LED1–4 (state, caption, autoflash/timedflash), AIR1–4 (state, seconds, ToH/countdown), NOW / NEXT / WARN (including the warning stack). Clock, meters, GPIO wiring, network ports, and the instance name stay local. Configure 1→n once on the source — you do not walk to each replica.

Sources (this screen is the destination): map Studio-1 / LED1 → LED1 and Studio-2 / LED1 → LED2 for a hallway tally. Signals: LED1–4, AIR1–4, NOW, NEXT, WARN, silence, or Follow all. Follow all copies the full runtime status, so Local target and Invert are unused. Invert applies to boolean signals. Custom is extra API commands (semicolon-separated) that fire when the source is active; they run in addition to Local target. Choose Local target Custom only if you want those commands without driving a local LED, AIR, or text field.

A screen may have only one full Follow. If it is already a replica of Studio-1, Studio-2 cannot add it as a replica (HTTP 409). Mappings from other instances are allowed for fields the Follow does not occupy. Offline sources keep the last state (no automatic all-off). Removing a replica clears Follow on the target and leaves lamps as they are.

Discovery uses multicast 239.194.0.2 UDP 3311 (not the command group 239.194.0.1:3310). Runtime status is pushed on change to replicas and to screens that mapped this instance; there is no continuous HTTP poll of every peer. Host-local WARN text (QUITTING ONAIRSCREEN, reboot/shutdown, NTP) stays on that screen. HTTP /api/link/follow, /api/link/unfollow, /api/link/snapshot, and /api/link/watch do not use the Web Settings PIN (same model as UDP/HTTP commands).

---

5.5 Advanced

Available text clock languages: English, German, Dutch, French

Date format placeholders (Qt notation, excerpt):

Weather Widget (OpenWeatherMap)

Type a city name next to City ID, press Find (or Return), and pick a match from the dropdown. The City ID is filled automatically; you can still enter an ID by hand. The widget shows the searched city name, not the OpenWeatherMap station or neighborhood name. The API key is masked; use the slashed-eye icon to show it.

Test API: Button to test the API connection with current settings.

Available weather languages: 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

More information: WeatherWidget Guide

---

5.6 Timers

For each AIR timer (group Timers):

Default AIR labels and icons:

---

5.7 Fonts

Font family, size, and weight can be set individually for each UI element:

The family combo lists application fonts (including bundled Roboto and Noto Sans). Size is a point spin box (8–96 pt), Bold toggles weight, and Reset restores Roboto with the default size and bold for that row. The preview shows sample text in the selected font.

Fonts from the fonts/ directory are also loaded at startup.

---

5.8 Time Source

The display clock can follow the local system clock, an NTP server, a PTPv2 (IEEE 1588-2008) master, or SMPTE LTC (Leo Bodnar LBE-1110 USB serial or decoded from a local audio input). OnAirScreen never changes the operating-system clock. NTP and PTP steer an independent timebase (time.monotonic()), so a jump of the system clock does not move the studio clock. LTC may jump, freeze, and includes frames (HH:MM:SS:FF).

Date, text clock, and AIR3 top-of-hour follow the same wall time as the large clock when the source is Local, NTP, or PTP. With LTC they keep using the system date/time, because LTC has no calendar date.

Local System Clock: The display uses the OS clock. With NTP-Check enabled, the OS clock is compared to the NTP server (deviation > 0.3 s or errors → warning, priority -1).

NTP Server: OnAirScreen queries the NTP Server field and steers its own clock. The OS time is not used after the first successful sample. The field stays editable even when NTP-Check is off. Loss of NTP: last time keeps running and a warning is shown.

PTPv2 IEEE 1588-2008: Software slave on multicast 224.0.1.129 UDP 319/320 (event/general), delay mechanism E2E. Typical accuracy is milliseconds (no hardware timestamping). Choose the studio/AoIP VLAN interface independently of the Audio Meters AoIP interface. Loss of Sync: last time keeps running plus warning. If UDP 319/320 cannot be bound (another stack already holds the ports), the slave retries every few seconds; the lock LED and WARN show PTP ERROR until the ports are free. Details stay in the log. On Linux and Raspberry Pi OS, shop .deb/.rpm/SD images install the /usr/lib/onairscreen/oas-ptp-bind helper for UDP 319/320.

LTC: One time source with two inputs. Frame rate is inferred from incoming frames (24 / 25 / 30). Loss of LTC: last timecode is frozen (LTC NOT LOCKED). The large WARN messages (waiting for LTC lock, Clock not LTC synchronized, LTC reader not connected) are off by default so video scrubbing does not flood WARN; enable Show LTC unlock warning if you want them. The lock LED always shows LTC LOCK / LTC NOT LOCKED. NTP-Check still compares the OS clock to the NTP server, not the timecode.

LBE-1110 Serial: USB CDC virtual serial port of a Leo Bodnar LBE-1110; no drivers. Auto selects a Leo Bodnar device (USB VID 0x1DD2) or an LBE-1110 / CDC port.

Audio Input: Decodes SMPTE LTC (biphase-mark) from a local PortAudio capture device, independent of Audio Meters (not Livewire/AES67). Choose Left or Right (default Left). On some hosts the same device cannot be opened twice — if meters already use that input, pick a different device for LTC.

The clock lock LED (bottom right) is green when the selected source is locked and red when it is not. Next to it: PTP LOCK / PTP NOT LOCKED / PTP ERROR, NTP LOCK / NTP NOT LOCKED, LTC LOCK / LTC NOT LOCKED, or LOCAL.

Recommendation: Use a local NTP server on your studio network, as pool.ntp.org can be unreliable at times.

---

5.9 Audio Meters

Stereo level meters on the left side of the screen: L/R (sample peak, true peak, or BBC PPM), a single programme LUFS bar (EBU R128), or both. L/R bars fill with RMS and overlay the current peak. Programme LUFS is one bar (momentary M, short-term S tick). Integrated I and loudness range (LRA) are off by default and start with LUFSI:START (Web UI, MQTT Home Assistant switch, Companion, OSC, UDP/HTTP, or right-click / long-click). LUFSI:RESET restarts a running session; if the session is stopped it hides I and LRA on the meter. Right-click or long-click the main screen → Start I+LRA, Stop I+LRA, or Reset I+LRA. Configure under Settings → Audio Meters.

Existing configs with Audio/unit=lufs (no layout key) are migrated to layout lufs and L/R unit dbtp.

Silence Detection uses the same audio source as the meters (Local Input, Livewire, or AES67). The threshold is always sample-peak dBFS, independent of the meter display unit. Capture keeps running when Silence Detection is on, even if the meters are hidden.

The alarm latches after the level stays below the threshold for the configured duration, and clears after the signal stays above the threshold for the recovery time. Show WARN in OAS is independent of the API/MQTT boolean: the boolean is always updated while detection is enabled. An optional HTTP GET is fired only on the rising edge (false → true).

Device/Stream absent: when this option is on (default), a source that never starts (no device, AES67 with None, capture start failed) is treated like silence after the same duration. When the option is off, only real level callbacks count; stopping capture clears a stuck alarm. Packet loss on a running stream (RTP timeout / silence injection) is always treated as silence.

The on-screen WARN uses priority 2 (high), so it is shown above TooLoud (priority 1). The silence API/MQTT flag is independent of texts.warn and of warning/active.

Livewire: The PC must be on the AoIP/Livewire VLAN (IGMP/multicast). While Settings (desktop dialog or Web UI overlay) are open, advertised sources appear in the Livewire Source combo (239.192.255.3 UDP 4001, standard stereo streams only). Pick a source or type a channel. Channel N maps to multicast 239.192.0.0 + N on UDP port 5004 (48 kHz / 24‑bit stereo RTP). After Apply, capture continues from the stored channel if advertisements stop.

AES67: SAP discovery uses multicast 239.255.255.255 and RFC 2974 224.2.127.254 UDP 9875 while the settings dialog or Web UI overlay is open. The stream list updates live only when streams appear or disappear (no flicker while the set is unchanged). The combo always has None (no stream). SAP entries disappear after they stop announcing (deletion or timeout). Use Paste SDP if a device does not announce via SAP — those entries stay in the list and are labeled pasted SDP. Supported: L16/L24 at 44.1/48/96 kHz, 1–64 channels (meters show channels 1–2). Dante AES67 SAP streams are listed like others (a=keywords:Dante is label-only). No PTP and no playout — metering only. After Apply, capture continues from the stored address/port even if SAP is silent. Apply with None stops AES67 capture and clears the meter.

Local input: on macOS grant microphone permission to OnAirScreen.

---

5.10 GPIO / MIDI

GPIO maps contacts, Livewire source pins, and MIDI messages to the same LED and AIR commands as the network API. Configure under Settings → GPIO. Inner tabs at the top: Raspberry Pi, Axia Livewire, MIDI, and Logic. Pi, Livewire, and MIDI can be enabled at the same time. Logic combines On/Off levels from all three.

Raspberry Pi

Raspberry Pi GPIO inputs map mixer GPI contacts. Available on Raspberry Pi only; other platforms show “not available” on this sub-tab.

Pi GPIO is 3.3 V. Mixer GPI is often 5–24 V or open collector — always use a PC817 isolation module. Dry relay contacts to GND may be wired directly (internal pull-up, Invert on).

Level (typical tally / fader): closed sends LED1:ON / AIR3:ON for each selected action, open sends OFF. Custom commands fire only while the contact is closed. Rising / Falling / Both send TOGGLE (or Reset / the custom commands) on that edge. Legacy CUSTOM in the action field still means “custom commands only”.

Factory mapping for a two-wire mixer GPI: GPI1 BCM 17 → LED1 (ON AIR), GPI2 BCM 27 → AIR3 (radio timer). Enable GPIO and connect the contacts through a PC817 module (or dry relays to GND).

Safe BCM pins: 5, 6, 12, 13, 16, 17, 22, 23, 24, 25, 26, 27 (not I2C 2/3 or UART 14/15).

Wiring

The 40-pin GPIO header is the same on Raspberry Pi 3, 4, 400, 5, 500, Zero 2 W, and the CM4/CM5 IO-board header. Settings use BCM numbers, not physical pin numbers.

PC817 module (recommended for mixer GPI 5–24 V or open collector):

Each mixer GPI is two wires: that channel’s IN1–IN8 and the input-side GND. On the Pi side the matching OUT1–OUT8 goes to the BCM pin and the output-side GND to Pi GND (GPI1 → IN1/OUT1, GPI2 → IN2/OUT2, …). Leave Invert on (active = pin pulled to GND). Example: Hailege 8-channel PC817 isolation module (Amazon affiliate link).

Dry relay contact only (already isolated, no voltage on the mixer GPI):

Do not feed 5 V or 12/24 V into a GPIO pin.

Factory defaults on the header (board oriented with the USB/Ethernet ports down, pin 1 is the corner 3.3 V next to the SD card / power end on most boards):

Safe BCM pins and their header pins (use these in BCM pin):

Pinout references (40-pin header, BCM numbering):

• Raspberry Pi GPIO and 40-pin header (official)
• pinout.xyz (interactive; same header on Pi 3 / 4 / 5 / Zero 2 W)
• Pi 5 overview: Raspberry Pi 5
• Compute Module IO boards: Compute Module

Axia Livewire

Axia Livewire GPIO follows source pins (Operator Mic, Guest Mic, Line, …) and maps them to the same LED and AIR commands. OnAirScreen only reads GPIO (it does not write GPI back to the console). Available on all platforms. Use the Axia Livewire inner tab.

Two modes:

• Multicast (default): CMsg2 on 239.192.255.4. The mapping Channel is the Livewire audio channel of that source. Put the machine on the AoIP / Livewire VLAN with IGMP, and pick the same interface as the Livewire audio meters (empty = default route).
• LWRP (TCP): connect to a device (xNode GPIO, iPort, console, …) at IP:93. The mapping column is Port — the GPIO port on that device, not a Livewire audio channel. No IGMP join; the host must be reachable on the Livewire/AoIP network.

Typical microphone ON-AIR profile: GPO pin 1 is the ON lamp (latched while the channel is ON; often off during TALK/MUTE). GPI 1 would be the ON command to the console — OAS does not send that.

Factory mapping (master Enable Livewire GPIO stays off): row 1 channel/port 1 GPO pin 1 → LED1, row 2 channel/port 2 GPO pin 1 → AIR3.

Multicast is 239.192.255.4 UDP 2055 (GPIO node → console) and 2060 (console → node). OAS joins both. After the join, OAS requests the current pin state so a microphone that is already ON at start lights the LED.

LWRP: OAS opens TCP 93, sends LOGIN (with password if set), ADD GPI, ADD GPO, then queries each watched port so a microphone that is already ON at start lights the LED. Reconnects if the socket drops.

Level (typical ON lamp): GPO 1 low sends LED1:ON, high sends OFF. Invert stays off unless the console polarity is reversed.

MIDI

MIDI reads one input interface (Settings → GPIO → MIDI) and maps Note or CC messages to the same LED and AIR commands. Learn waits up to 10 seconds for the next Note or CC and fills channel, type, and number. Clock, Active Sensing, and SysEx are ignored.

On/Off holds the level: Note On (velocity > 0) or a CC at the threshold sends LED1:ON, Note Off or a CC below the threshold sends OFF. Oneshot sends LED1:ON once per press, or LED1:OFF when Invert is on. Toggle sends LED1:TOGGLE once per press. Reset and custom commands fire once for both, including an inverted Oneshot. Both fire again even when the controller never sends Note Off. A fader that keeps sending CCs above the threshold stays one burst. Two enabled rows on the same channel, type, and number both fire, and the tab shows a warning. While Settings is open, an enabled row flashes when a Note or CC arrives on its channel, type, and number.

Only On/Off rows appear in Logic. Oneshot and Toggle are missing from the Logic input menu even when the row is enabled and named, because they do not hold a level. Every On/Off row is listed, including rows whose Enable box is off. That disabled input counts as off inside a rule. Unnamed On/Off rows are labeled MIDI1 … MIDI8. A name is shown as PAD (MIDI1). To use a MIDI row in Logic, set Behavior to On/Off.

Logic

Logic combines Raspberry Pi, Livewire, and MIDI On/Off inputs. Each rule has one operator, one or more inputs, and one or more outputs. The outputs follow the combined level: a command is sent only when that result changes. The input menu lists every Pi input, every Livewire input, and every MIDI row set to On/Off. MIDI Oneshot and Toggle rows are left out. A MIDI On/Off row stays in the menu when Enable is off.

Example: name Pi GPI1 MIC1 and Pi GPI2 MIC2. Rule OR with those two inputs and outputs LED1 and AIR1 stays on while either microphone is open, and turns both off only when both are closed.

Inputs that are disabled, missing, or not yet seen count as off. An empty input list stays off. Resets and custom commands fire when the rule becomes true, not when it becomes false. Direct row actions (including edge modes) keep working beside the rules. If the same LED or AIR timer is also set on a row or on another rule, that Logic row shows a warning.

Eight rules. A microphone that is already on when OnAirScreen starts turns a matching rule on as soon as that input level is known.

---

5.11 About

---

6. Features in Detail

6.1 Status LEDs

Each LED can be switched on and off individually (keys 1–4, left-click, or remote control). In the active state, configured foreground and background colors are used; in the inactive state, the shared inactive colors apply.

Blink modes:

• Autoflash: Blinks continuously at 500 ms intervals while the LED is on
• 20sec flash: Blinks for 20 seconds, then turns off automatically

6.2 AIR Timers

All AIR timers display elapsed time in M:SS format (e.g. 3:45). AIR3 shows ▲ (count-up) or ▼ (count-down) under the timer icon.

AIR1 (Microphone) and AIR2 (Phone)

• Simple stopwatch: start/stop, seconds reset to 0 on start
• Control: M// (AIR1), P/* (AIR2), or left-click the timer

AIR3 (Radio Timer)

The most versatile timer with three operating modes:

1. Count-Up: Default mode, counts from 0:00 upward
2. Count-Down: Set via AIR3TIME:seconds or timer dialog
3. Top-of-Hour (TOH): Countdown to the next full hour (format MM:SS, e.g. 22:38)

Start/stop: Space, , / ., or left-click the timer.

Top-of-Hour behavior:

• First call: Calculates remaining time until :00, starts countdown, label shows the configured TOTH Timer text (default TOTH Timer)
• Second call (or OFF/TOGGLE while active): Stops and restores the configured AIR3 label
• Synchronized with the display clock, stops automatically at hour change and restores the configured label
• API status: "topOfHour": true and "text" set to the configured TOTH Timer text in air[3] when active

Timer input dialog (Enter):

AIR4 (Stream Timer)

• Like AIR3, but without Top-of-Hour function
• Control: S or left-click (start/stop), Alt+S (reset)

6.3 Text Lines NOW, NEXT, WARN

Maximum text length: 500 characters (input is automatically sanitized and truncated).

Warning System with Priorities

Display rule: The warning with the highest priority is shown. NTP warnings (-1) only appear when no other warning is active. When a warning is active, NOW and NEXT are hidden.

Clearing warnings:

6.4 Displaying IP Addresses

Press I (or automatically at startup) to show all local IPv4 addresses in NOW and IPv6 addresses in NEXT for 10 seconds.

If Replace IPs after 10s is enabled, the NOW line is replaced with the configured replacement text (replacenowtext) afterwards.

6.5 Clock

• Digital: LED-style digit display with configurable colors
• Analog: Classic ticks and hands without numerals
• Analog Numbers: Classic analog face with 1–12
• Analog Studio: White face, black ticks, numerals 1–12
• Analog Railway: White station face without numerals, pointed black hands, sweeping red second hand with a ring
• Analog 24h smooth: Cream face, black 1–12 and red 13–24, sweeping second hand
• Analog 24h ticking: Same cream 24h face with a ticking second hand

• Text clock: Spoken time display (e.g. "it's a quarter past three")
• Time source: Local, NTP, PTPv2, or LTC — see 5.8 Time Source; the OS clock is never set
• Lock LED bottom right: green = locked, red = not locked (PTP LOCK / NTP LOCK / LTC LOCK, or LOCAL)
• Weather widget: Optionally displayed next to the clock (OpenWeatherMap)

6.6 System Commands

Reboot and Shutdown are also in Settings → About and the Web UI System section. Both ask for confirmation. HTTP CMD:REBOOT / CMD:SHUTDOWN require the Web Settings PIN when one is set (X-Settings-Token). UDP, MQTT, OSC, GPIO, and SNMP stay unauthenticated. CMD:QUIT remains API-only.

6.7 GPIO Inputs

Mixer GPI (contact closure) can drive LEDs and AIR timers through Raspberry Pi GPIO. Axia consoles can drive the same LED and AIR actions through Livewire GPIO (multicast source channel or LWRP TCP 93, e.g. mic ON lamp). A MIDI controller can drive them from Note and CC messages on one input. All three can run at the same time. See 5.10 GPIO for Pi wiring, Livewire channel/port mapping, MIDI Learn, and the AoIP interface. Pi GPIO is local hardware; Livewire GPIO is multicast or a TCP session on the AoIP network; MIDI is the selected input port.

---

7. Remote Control and API

OnAirScreen supports remote control via UDP, HTTP, Web UI, MQTT, OSC, SNMP, REST API, and Bitfocus Companion.

7.1 UDP (Port 3310)

# Turn on LED1
echo "LED1:ON" > /dev/udp/127.0.0.1/3310
 
# Set NOW text
echo "NOW:Current Song Title" > /dev/udp/127.0.0.1/3310
 
# Change configuration
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:Current%20Song"

7.3 Web UI

Open in browser: http://<IP-address>:8010/

Web UI features:

• Real-time status for LEDs, AIR timers, text fields, silence alarm, and loudness I+LRA (I and LRA values plus running state)
• Instance name in the title and status (from /api/status instance)
• WebSocket updates (with HTTP polling fallback; WebSocket is retried after polling)
• Dark mode with persistent theme setting
• LED and timer controls with toggle buttons
• Start / Stop / Reset for programme I + LRA (LUFSI)
• Top-of-Hour button for AIR3
• AIR3 time input (m:ss, m,ss, or seconds)
• AIR3 count-up vs. countdown in the status tile
• Keys 1–4 toggle LEDs (ignored while typing)
• Text input for NOW, NEXT, WARN (NOW/NEXT follow live status unless you are editing)
• Warnings with priority and delete button
• Version and distribution information
• Persistent connection badge (Live / Polling / Offline) plus error modal
• Settings gear (top right): tabbed overlay for all editable settings, optional PIN, Apply, and preset load/save
• Links in the overlay: same Nearby list, Add as replica / Use as source, and Replicas / Sources grids as the desktop Settings
• Audio Meters in the overlay: Livewire Source and AES67 Stream dropdowns (live discovery while the overlay is open) plus Paste SDP

7.4 REST API

Query status:

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

Response (simplified):

{
  "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.10",
  "distribution": "OpenSource",
  "link": { "enabled": false, "follow": null, "replicas": [], "peers": 0 }
}

The silence field is true while Silence Detection has latched, even if the on-screen WARN is disabled. lufsIntegrated is true while a gated I + LRA session is running (LUFSI:START). lufsI is gated integrated loudness in LUFS (one decimal) and lra is loudness range in LU; both are null until enough audio has been measured. instance is the configured instance name. For AIR3, topOfHour indicates whether the Top-of-Hour countdown is active, and countDown is true while the radio timer is counting down.

Send command:

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

Instance links (no Web Settings PIN):

curl http://127.0.0.1:8010/api/link/peers
curl -X POST http://127.0.0.1:8010/api/link/follow -H 'Content-Type: application/json' \
  -d '{"source_instance":"Studio-1","source_http_port":8010}'
curl -X POST http://127.0.0.1:8010/api/link/unfollow -H 'Content-Type: application/json' \
  -d '{"source_instance":"Studio-1"}'

link in /api/status shows whether this screen is a replica (follow) and which instances it pushes to (replicas).

Web settings (optional PIN via X-Settings-Token after 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"}}}'

Secrets (updatekey, MQTT password, OpenWeatherMap API key) are returned in plaintext so the settings overlay can show them. The PIN is returned as __unchanged__ (only a hash is stored). Send that sentinel to keep the PIN, or - to clear it. UDP/HTTP port changes are stored immediately but need an application restart.

7.5 MQTT

Send commands (topic: {base_topic}/...):

Status topics (published automatically):

Home Assistant Autodiscovery automatically creates:

• LED switches (LED1–4)
• AIR timer switches (AIR1–4)
• AIR time sensors (AIR1–4 Time)
• Reset buttons (AIR3/AIR4)
• Top-of-Hour button (AIR3)
• Text entities (NOW, NEXT, WARN)
• Binary sensors: Warning Active, Silence
• Sensor: Instance (instance name)
• Loudness I+LRA switch (start resets; stop freezes last values)
• Loudness I+LRA Reset button (restart if running; hide I and LRA if stopped)
• Sensors: Loudness I (LUFS), Loudness LRA (LU)

The Home Assistant device name becomes OnAirScreen (Studio-1) unless the instance name is already part of the MQTT Device Name.

7.6 Bitfocus Companion (recommended)

The dedicated astrastudio-OnAirScreen Companion module is the recommended way to drive Stream Decks and similar surfaces. Commands use HTTP (port 8010): GET /api/command?cmd=LED1:ON. Live status prefers the OnAirScreen WebSocket on HTTP port + 1 (so 8011 when HTTP is 8010) and falls back to polling GET /api/status (default every 500 ms). OSC is not required. Button AIR times stay close to the studio display (MIC = AIR1). Allow both ports through the firewall.

OnAirScreen: HTTP must be reachable (default). You can leave OSC off.

Companion (local module until it is in the Companion Store):

1. In the OAS-Companion repo: yarn install && yarn build
2. Symlink that folder into Companion's module-local-dev directory as companion-module-astrastudio-onairscreen (or add the path under Companion Developer settings)
3. Restart Companion and add connection astrastudio / OnAirScreen
4. Host = OnAirScreen IP, HTTP port 8010 (must match Settings → Network). Leave WebSocket enabled unless you must poll only.

Drag presets for LED1–4 (toggle + colour), AIR1–4 with live caption and time on the button (MIC = AIR1), TOTH, Reset AIR3/4, NOW / NEXT / WARN, Silence, Loudness I+LRA, and Reset I+LRA.

Variables such as $(oas:air1_time), $(oas:lufs_i), and $(oas:lra) and feedbacks (LED on, AIR running, TOTH, Silence, WARN, Loudness I+LRA) update from WebSocket or the status poll. Set the connection Label to oas so those examples match. The connection status shows instance name and version, for example Studio-1 · 1.0.10. The module HELP.md lists every action, feedback, and variable.

If you cannot load a custom module, Generic OSC remains available (next section). Status push over OSC is slower (every 5 seconds) than the HTTP poll / WebSocket.

7.7 OSC (Port 8000)

Enable OSC under Settings → Network. Prefix is /oas. Integers 1/0 mean ON/OFF; no argument means TOGGLE. Text uses a string argument.

Set (commands):

Query (reply to the UDP sender, no Send Host needed): send the /state address (or /oas/status for everything). Replies use integer 0/1 for booleans and strings for text. /oas/lufs/integrated/state reports whether I + LRA is running. /oas/lufs/i and /oas/lufs/lra report the current I (LUFS) and LRA (LU) as one-decimal strings, or empty when unknown.

Push (Companion feedback): set OSC Send Host to the Companion PC and OSC Send Port to the Generic OSC feedback port. OnAirScreen then sends /oas/led1/state etc. after changes and every 5 seconds.

# Toggle LED1
python3 utils/oas_osc_send.py /oas/led1
 
# LED1 on
python3 utils/oas_osc_send.py /oas/led1 1
 
# Query LED2 (reply goes to this process only if you listen; use Companion or a dump tool)
python3 utils/oas_osc_send.py /oas/led2/state

Alternative: Generic OSC

If you prefer OSC or cannot load the HTTP module, use the built-in OSC Generic connection.

Commands only:

1. OnAirScreen: enable OSC, listen port 8000
2. Companion: add OSC Generic, target = OnAirScreen IP, port 8000
3. Button action Send integer, path /oas/led1, value 1 (on) or 0 (off). Omit the argument for toggle. Use Send string for /oas/text/now.

Button feedback (Stream Deck color):

1. Companion: set the OSC Generic feedback listen port (e.g. 9000)
2. OnAirScreen: OSC Send Host = Companion IP, OSC Send Port = that feedback port
3. Feedback Listen for OSC messages (Integer) on /oas/led1/state, compare to 1

Query-reply to the command socket is not used by Companion (it listens on a different UDP port).

7.8 SNMP (Port 1161)

Enable SNMP under Settings → Network. The agent speaks SNMPv2c and SNMPv3 (USM, SHA-256, AES-128). The default listen port is 1161 (unprivileged). Port 161 is possible but needs OS privileges on Linux/macOS.

The MIB is mibs/ASTRASTUDIO-ONAIRSCREEN-MIB.txt and on the wiki for download. Enterprise OID .1.3.6.1.4.1.66873 (IANA PEN 66873, astrastudio broadcast solutions). MIB-2 system (sysDescr, sysUpTime, sysName, …) is included.

GET / WALK (same status as /api/status): LEDs, AIR timers, NOW/NEXT/WARN, silence, loudness I+LRA, version, instance.

SET (same semantics as OSC): LED state 0/1/2 = OFF/ON/TOGGLE, AIR state 0/1/2/3 = OFF/ON/TOGGLE/RESET, AIR3 seconds, AIR3 TOTH, texts, oasLufsIntegrated, or oasCommand with a raw COMMAND:VALUE. v2c SET needs a write community. v3 SET is allowed once an auth password is set.

Traps: silence, WARN text change, optional LED change. Version v2c or v3 (v3 uses the same USM user).

# Status walk (v2c)
snmpwalk -v2c -c public localhost:1161 .1.3.6.1.4.1.66873
 
# Turn LED1 on
snmpset -v2c -c private localhost:1161 .1.3.6.1.4.1.66873.1.2.1.2.1 i 1
 
# Walk with SNMPv3 authPriv
snmpwalk -v3 -l authPriv -u nms -a SHA-256 -A 'auth-secret' -x AES -X 'priv-secret' localhost:1161 .1.3.6.1.4.1.66873

With an empty write community (the default), v2c is read-only. noAuthNoPriv is for testing only.

7.9 Command Reference

Control Commands

Remote Configuration (CONF)

Format: CONF:GROUP:PARAMETER=VALUE

Changes are only applied and saved after CONF:CONF:APPLY=TRUE.

CONF:Audio:unit=lufs is still accepted as an alias that sets layout to lufs (L/R unit stays dbtp).

Colors: Hex format (#FF0000) or color names.

---

8. Presets (Profiles)

Presets allow saving and loading complete configurations.

Storage location: <configuration directory>/presets/<name>.json

Presets contain metadata (name, version) and the full configuration as JSON. After loading, Apply must be clicked for settings to take effect.

Note: MQTT settings are saved in the configuration file but are intentionally not included in preset exports. MQTT credentials are installation- and environment-specific and should not be exported together with visual profiles.

---

9. Command-Line Options

python start.py --loglevel DEBUG
python start.py -l WARNING
python start.py --start-time 2026-09-14T12:00:00

The log level from settings (About/Loglevel) additionally supports NONE (no logging).

---

10. Configuration Storage Location

Settings are stored via Qt QSettings:

• Organization: astrastudio
• Application: OnAirScreen

The exact path is shown in the About tab under Settings Path. Typical locations:

Logs and crash reports are stored separately. The exact path is shown in the About tab under Log Folder:

Files in that folder:

• onairscreen.log — rotating application log (same content as stderr, follows the log level)
• crash-YYYYMMDD-HHMMSS.txt — uncaught Python exceptions (traceback, version, OS; no settings or passwords). After a main-thread or Qt fatal crash the application quits; errors in background threads are logged only.
• fault.log — native crash dumps (segfaults in Qt or C extensions)

Crash files are always written, even if the log level is NONE. Send the log folder to support when asked; do not post it publicly (DEBUG logs may contain host names or commands). After a process crash, the next start shows a dialog with Open log folder; it closes automatically after 30 seconds.

---

11. Troubleshooting

OnAirScreen won't start / port in use

• Check if UDP port 3310 or HTTP port 8010 is already in use
• Change ports in Network

Remote control not working

• Check firewall rules for UDP/HTTP/OSC/SNMP ports
• Use correct IP address and ports
• Test locally with curl http://127.0.0.1:8010/api/status

GPIO not switching LEDs or timers

Raspberry Pi (inner tab Raspberry Pi):

• Pi GPIO works on Raspberry Pi only. Other platforms show “not available” on that sub-tab
• Check Settings → GPIO → Raspberry Pi status
• Use a PC817 module; never feed mixer 5–24 V into Pi pins
• Confirm Invert (default on for contacts to GND) and Level vs edge mode
• Enable GPIO and the individual GPI row, then Apply

Axia Livewire (inner tab Axia Livewire):

• Enable Livewire GPIO and the mapping row, then Apply
• Typical mic ON lamp: direction GPO, pin 1, Invert off, mode level
• Multicast: use the same Livewire channel number as the source’s audio (GPIO is not advertised). Machine must be on the AoIP / Livewire VLAN with IGMP; pick the same interface as Audio Meters. Status “join failed”: wrong interface or no multicast route
• LWRP: set Mode to LWRP (TCP), enter the device Host (TCP 93). Mapping Port is the GPIO port on the device, not a Livewire audio channel. Status “host is empty” / “LWRP failed”: missing IP or the device is not reachable. VLAN still applies; IGMP is not used
• No packets / LED stays off: confirm the console/device is sending GPIO, the channel or port number, and that OAS is on the Livewire network
• Mic already ON at OAS start: OAS requests the current state after join/connect; if the LED stays dark, check that the device answers that read (or toggle the channel once)

Companion module shows Disconnected

• HTTP must be reachable on the configured port (default 8010); OSC is not used by this module
• Confirm curl http://<OnAirScreen-IP>:8010/api/status returns JSON
• After yarn build, restart Companion so it reloads the local module

Silence Detection does not trigger

• Is Enable Silence Detection enabled and saved with Apply?
• Check the audio source (device selected, Livewire channel, AES67 stream not None)
• Lower the dBFS threshold or shorten the duration if the residual noise sits above −50 dBFS
• If the device or stream is missing, enable Trigger silence warning when Device/Stream is absent

MQTT connection fails

• Is the MQTT broker reachable? (mqttserver, mqttport)
• Are credentials correct?
• Is enable MQTT support enabled and saved with Apply?

NTP warning appears permanently

• Configure a local NTP server (NTP/ntpcheckserver)
• If the time source is Local, synchronize system time or switch the time source to NTP/PTP
• Disable NTP check if not needed

Weather widget shows nothing

• Enter a valid OpenWeatherMap API key
• Search the city name with Find next to City ID, or enter the ID by hand
• Run Test API in settings

Livewire meters show no levels

• Source set to Livewire and channel number correct (or pick an advertised source)?
• PC on the AoIP/Livewire VLAN? IGMP/multicast not filtered?
• Correct network interface selected (not “Default” if multiple NICs)?
• UDP port 5004 allowed?
• No names in Livewire Source: advertisements are 239.192.255.3:4001 and only run while Settings (desktop or Web UI overlay) is open. You can still type the channel number.

AES67 meters: no streams or no levels

• No streams in the combo: AoIP interface, VLAN, and IGMP; SAP is 239.255.255.255:9875 and 224.2.127.254:9875 and only runs while Settings (desktop or Web UI overlay) is open. If the device does not announce, use Paste SDP.
• Stream listed, meter silent: RTP address/port and codec (L16 vs L24). Dante must be in AES67/SAP mode. No PTP is required for metering.

Reset settings

1. Open settings dialog (Ctrl+S)
2. Tab About → enable Enable Reset all settings button
3. Click Reset all OnAirScreen settings to default
4. Click Apply

Sending logs for support

If OnAirScreen crashes or behaves unexpectedly:

1. Open Settings → About
2. Click Open log folder (or copy the Log Folder path)
3. Send onairscreen.log and any crash-*.txt files (plus fault.log if it is not empty)

The reports do not include settings, MQTT passwords, or API keys. Prefer --loglevel DEBUG only for a short reproduction run before sending logs. After a crash, OnAirScreen also shows this dialog on the next start (auto-closes after 30 seconds).

---

Appendix: Event Logging

OnAirScreen internally logs the following event types:

• LED changes (source: manual, autoflash, timedflash, API)
• AIR timer start/stop/reset
• Received commands (UDP/HTTP/OSC/SNMP)
• Warnings added/removed
• Settings changes
• System events (start, quit, reboot)

The log level controls output verbosity. For troubleshooting, temporarily use --loglevel DEBUG. Logs are also written to onairscreen.log in the log folder (see About).

---

© 2012–2026 Sascha Ludwig · astrastudio.de