OnAirScreen

Multi purpose “OnAir Lamp” solution targeted for use in professional broadcast environments http://saschaludwig.github.io/OnAirScreen/

Support This Project

This project needs your help! If you find OnAirScreen useful, please consider making a donation or becoming a sponsor. Your support helps me continue working on this project, adding new features, fixing bugs, and maintaining the codebase. Every contribution, no matter how small, is greatly appreciated!

PayPal donate button

Buy Me A Coffee

Buy Me a Coffee at ko-fi.com

Precompiled Linux/Win/Mac versions

If you need ready-to-run Linux/Win/Mac executables, please visit https://www.astrastudio.de/shop/.
I also have a RaspberryPi version and a ready-to-run RaspberryPi SD-Card image in my shop.
And if you need extended support, please contact me.

Source requirements

License

OnAirScreen is provided under the OnAirScreen Source-Available License (OASL 1.0). See LICENSE. This is not an OSI open-source license.

You may:

You may not, without prior written permission from the copyright holder:

Official precompiled builds are sold by the copyright holder. Third-party libraries and assets stay under their own licenses; see THIRD_PARTY_LICENSES.md.

Documentation

Complete user manuals covering all settings, hotkeys, and remote control:

Screenshots

Pictures of OnAirScreen in use

Features

Audio Meters

OnAirScreen shows full-height stereo L/R meters on the left side of the screen (on by default, Local Input). Configure them under Settings → Audio Meters:

Livewire notes: The PC must be on the AoIP/Livewire VLAN with working IGMP/multicast. While Settings are open, advertised sources are listed from 239.192.255.3 UDP 4001 (standard stereo streams only). You can pick a name from the combo or type a channel number. Channel N maps to multicast 239.192.0.0 + N on UDP port 5004 (48 kHz / 24‑bit stereo RTP). After Apply, capture uses the stored channel even if advertisements stop.

AES67 notes: Discovery listens for SAP on 239.255.255.255 and RFC 2974 224.2.127.254 UDP 9875 (only while the settings dialog is open). Supported encodings: L16/L24 at 44.1/48/96 kHz. Stereo meters use the first two channels (mono is duplicated). Dante AES67 streams that announce via SAP are listed like any other stream (a=keywords:Dante is label-only). No PTP clocking and no audio playout — metering only. Capture uses the stored multicast address/port even if SAP is silent after Apply.

Troubleshooting: If no Livewire or AES67 sources appear, check AoIP interface, VLAN, and IGMP. Livewire ads are 239.192.255.3:4001; SAP is 239.255.255.255:9875 and 224.2.127.254:9875. If a stream is listed but the meter stays silent, check RTP port and codec (Livewire is L24/48 kHz; AES67 L16 vs L24).

System requirements for audio capture:

Top-of-Hour Countdown (AIR3)

The Top-of-Hour (TOH) countdown shows the remaining time until the next full hour in the Radio Timer display (AIR3, left timer column). The display uses the format minutes:seconds (e.g. 22:38).

Behavior:

Control:

Method Action
Hotkey T Toggle Top-of-Hour countdown
AIR3TOH:ON Start countdown
AIR3TOH:OFF Stop and reset to 0:00
AIR3TOH:TOGGLE Toggle countdown
Web-UI “Top of Hour” button at AIR3
MQTT Publish to {base_topic}/air3/toh (ON/OFF/TOGGLE)
Home Assistant “AIR3 Top of Hour” button (MQTT Autodiscovery)

Examples:

# UDP
echo "AIR3TOH:TOGGLE" > /dev/udp/127.0.0.1/3310

# HTTP
curl "http://127.0.0.1:8010/?cmd=AIR3TOH:TOGGLE"

# REST-style API
curl "http://127.0.0.1:8010/api/command?cmd=AIR3TOH:ON"

# MQTT
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air3/toh -m "TOGGLE"

OnAirScreen Function Keys

| Hotkeys | Function | |———————————–|————————-| | Ctrl+F or F | Toggle fullscreen | | Ctrl+Q or Q or Ctrl+C or ESC | Quit OnAirScreen | | Ctrl+S or Ctrl+, | Open settings dialog | | Space or 0 | Timer start/stop | | . or , or R | Timer reset to 0:00 | | 1 | LED1 on/off | | 2 | LED2 on/off | | 3 | LED3 on/off | | 4 | LED4 on/off | | M or / | Mic Timer start/stop | | P or * | Phone Timer start/stop | | T | Top-of-Hour countdown in Radio Timer (AIR3) start/stop | | Enter | opens set timer dialog |

On OSX use the command ⌘ key instead of Ctrl

OnAirScreen API Commands

API via UDP

OnAirScreen can receive API commands via UDP port 3310
Here is an easy example on how to control a local OnAirScreen instance on a linux system.

Set LED1 Text to “FOO” and switch LED1 on:

echo "CONF:LED1:text=FOO" > /dev/udp/127.0.0.1/3310
echo "LED1:ON" > /dev/udp/127.0.0.1/3310
API via HTTP

OnAirScreen can receive API commands via HTTP (port 8010 by default).
Here is an easy example of how to control a local OnAirScreen instance on a linux system.

Set LED1 Text to “FOO” and switch LED1 on:

curl http://127.0.0.1:8010/?cmd=CONF:LED1:text=FOO
curl http://127.0.0.1:8010/?cmd=LED1:ON
Web-UI

OnAirScreen provides a complete web-based remote control interface accessible via your browser.
Simply open http://127.0.0.1:8010/ (or the IP address of your OnAirScreen instance) in any modern web browser.

The Web-UI provides:

REST-style API

OnAirScreen also provides REST-style API endpoints:

Status Endpoint:

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

Returns JSON with current LED status, AIR timer status, text field values, silence boolean, loudness I+LRA session (lufsIntegrated) plus I (lufsI) and LRA (lra), version, and distribution information. For AIR3, the topOfHour field indicates whether the Top-of-Hour countdown is active, and countDown is true while the radio timer is in countdown mode (after AIR3TIME or TOTH). The silence field is independent of the on-screen WARN. lufsI and lra are null until enough audio has been measured.

Command Endpoint:

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

Sends commands and returns JSON response with status confirmation.

API via MQTT

OnAirScreen can be controlled via MQTT and integrates seamlessly with Home Assistant using MQTT Autodiscovery.
Configure MQTT settings in the OnAirScreen settings dialog (Server, Port, Username, Password, Device Name).

Base Topic: The MQTT base topic is automatically generated from onairscreen + a unique device ID (last 6 hex characters of the MAC address). This ensures each OnAirScreen instance has a unique topic, even when multiple instances are running on the same network. For example: onairscreen_a1b2c3.

Home Assistant Integration: OnAirScreen automatically publishes device configurations to Home Assistant, creating:

MQTT Topics: All commands use the same format as UDP/HTTP API commands, published to:

{base_topic}/led{1-4}/set          → ON/OFF
{base_topic}/air{1-4}/set          → ON/OFF
{base_topic}/air{3-4}/reset        → PRESS (button)
{base_topic}/air3/toh              → ON/OFF/TOGGLE
{base_topic}/lufs/integrated/set   → ON/OFF/TOGGLE/RESET
{base_topic}/lufs/integrated/reset → PRESS
{base_topic}/text/now/set          → TEXT
{base_topic}/text/next/set         → TEXT
{base_topic}/text/warn/set         → TEXT

Status updates are automatically published to:

{base_topic}/led{1-4}/state         → ON/OFF
{base_topic}/air{1-4}/state         → ON/OFF
{base_topic}/air{1-4}/time          → seconds (integer)
{base_topic}/air3/toh/state         → true/false
{base_topic}/text/{now|next|warn}/state → TEXT
{base_topic}/warning/active         → true/false
{base_topic}/silence/active         → true/false
{base_topic}/lufs/integrated/state  → ON/OFF
{base_topic}/lufs/i                 → I in LUFS (empty if unknown)
{base_topic}/lufs/lra               → LRA in LU (empty if unknown)

Example using mosquitto_pub: The base topic is automatically generated (e.g., onairscreen_a1b2c3). Replace {base_topic} with your actual base topic:

mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/led1/set -m "ON"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air3/set -m "ON"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air3/reset -m "PRESS"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air3/toh -m "TOGGLE"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/lufs/integrated/set -m "ON"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/lufs/integrated/reset -m "PRESS"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/text/now/set -m "Current Song"
API Commands
UDP Command Function
LED1:[ON/OFF/TOGGLE]    switch LED1 on/off/toggle
LED2:[ON/OFF/TOGGLE] switch LED2 on/off/toggle
LED3:[ON/OFF/TOGGLE] switch LED3 on/off/toggle
LED4:[ON/OFF/TOGGLE] switch LED4 on/off/toggle
NOW:TEXT set TEXT in first footer line
NEXT:TEXT set TEXT in second footer line
WARN:TEXT set TEXT and switch on red warning mode (priority 0)
WARN:Prio:TEXT set TEXT with priority (Prio: 1=Medium, 2=High)
AIR1:[ON/OFF/TOGGLE] start/stop/toggle Mic Timer
AIR2:[ON/OFF/TOGGLE] start/stop/toggle Phone Timer
AIR3:[ON/OFF/RESET/TOGGLE] start/stop/reset/toggle Radio Timer
AIR3TIME:seconds set Radio Timer to given value in seconds
AIR3TOH:[ON/OFF/TOGGLE] start/stop/toggle Top-of-Hour countdown in Radio Timer
AIR4:[ON/OFF/RESET/TOGGLE] start/stop/reset/toggle Stream Timer
LUFSI:[START/STOP/TOGGLE/RESET] start/stop/toggle/reset programme I + LRA session
CMD:REBOOT OS restart
CMD:SHUTDOWN OS shutdown
CMD:QUIT quit OnAirScreen instance
Remote Configuration Commands

CONF:General:stationname=TEXT
CONF:General:slogan=TEXT
CONF:General:stationcolor=COLOR
CONF:General:slogancolor=COLOR
CONF:LED[1-4]:used=[False|True]
CONF:LED[1-4]:text=TEXT
CONF:LED[1-4]:activebgcolor=COLOR
CONF:LED[1-4]:activetextcolor=COLOR
CONF:LED[1-4]:autoflash=[False|True]
CONF:LED[1-4]:timedflash=[False|True]
CONF:Clock:digital=[True|False]
CONF:Clock:showseconds=[True|False]
CONF:Clock:digitalhourcolor=COLOR
CONF:Clock:digitalsecondcolor=COLOR
CONF:Clock:digitaldigitcolor=COLOR
CONF:Clock:logopath=PathToLogo
CONF:Network:udpport=PORT
CONF:Network:tcpport=PORT
CONF:Audio:enabled=[True|False]
CONF:Audio:source=[device|livewire]
CONF:Audio:input_device=DEVICE_NAME
CONF:Audio:livewire_channel=N
CONF:Audio:livewire_iface=IP_OR_EMPTY
CONF:Audio:unit=[dbfs|dbtp|bbc_ppm] (lufs still sets layout to lufs)
CONF:Audio:layout=[lr|lufs|both]
CONF:Audio:tooloud=[True|False]
CONF:Audio:tooloudtext=TEXT
CONF:Audio:tooloud_threshold_dbtp=-1.0
CONF:Audio:tooloud_action=[warning|led]
CONF:Audio:tooloud_led=[1|2|3|4]
CONF:Audio:silence=[True|False]
CONF:Audio:silence_warn=[True|False]
CONF:Audio:silence_on_absent=[True|False]
CONF:Audio:silence_text=TEXT
CONF:Audio:silence_threshold_dbfs=-50.0
CONF:Audio:silence_duration_s=10.0
CONF:Audio:silence_recovery_s=2.0
CONF:Audio:silence_http_url=URL
CONF:Audio:lufs_reference_preset=[ebu_r128|atsc_a85|aes_16|aes_18|custom]
CONF:Audio:lufs_reference=-23.0
CONF:Audio:peak_hold=[True|False]
CONF:Audio:peak_hold_seconds=1.5
CONF:Audio:display_style=[solid|bargraph]
CONF:Audio:meter_width=79

Error Handling

OnAirScreen uses a unified error handling system with custom exceptions for consistent error tracking and debugging:

All exceptions inherit from OnAirScreenError and include context information for better debugging. The log_exception() helper function provides consistent logging across the application.

HTTP error responses are automatically mapped to appropriate status codes:

CONF:CONF:APPLY=TRUE