Audio Output

Overview

ControlBird offers two complementary audio systems. Session Audio plays sound directly in the operator's browser, with per-session volume control surfaced through the volume widget in the taskbar. Server-side audio output drives hardware output for dedicated kiosks and industrial HMI panels, sending audio to a sink over the network. The two systems are independent: a single deployment can use either, or both at once for different stations.

Use Session Audio when sound should follow the logged-in user at a web-based operator station, and use server-side audio output when a fixed panel needs to play through attached speakers regardless of who is logged in. In both cases, alarm annunciation is automatic: ControlBird plays the configured sound for the highest-priority unacknowledged alarm to every active session, so you rarely trigger audio by hand once severities are configured in the Alarms Config app.

Key concepts

• Audio files hold the sound that everything else references. Upload WAV, MP3, OGG, or WebM files through the Alarms Config app; WAV is the most compatible format.
• Session playback plays a sound immediately in an operator's browser, with per-session volume and an optional loop.
• Severity-driven alarm sounds attach a sound to each alarm severity. ControlBird plays only the sound for the highest-priority unacknowledged alarm.
• Server-side output is configured with an audio controller, an endpoint (the address of the audio server) and one or more mappers that route audio to a sink.
• Browser autoplay policy blocks sound until the user interacts with the page. The volume widget shows a warning and a "Click to enable audio" option to unblock playback.

How alarm sounds are chosen

ControlBird re-evaluates alarm audio every 10 seconds. It considers all alarms whose state is Active or Latched and that are not acknowledged, ranks them by the priority of their current severity, and broadcasts the configured sound for the highest-priority one to every active session that has a logged-in user.

Configuration reference

Alarm severity audio & presentation

Each alarm severity, configured in the Alarms Config app, can carry a sound and visual styling. These fields are how you control per-severity annunciation and appearance.

PulseAudioController

Server-side audio service controller for hardware playback on kiosks and HMI panels.

PulseAudioEndpoint

Network endpoint configuration for the PulseAudio server connection.

PulseAudioMapper

Mapper configuration that routes audio commands to PulseAudio playback operations.

Configuration examples

Server-side audio mapper

Route audio to a hardware sink for 48 kHz stereo output at 80% volume.

PulseAudioMapper {
  SourcePath: '/Root/Control/AudioOutput',
  SinkName: 'alsa_output.pci-0000_00_1f.3.analog-stereo',
  SampleRate: 48000,
  Channels: 2,
  Volume: 0.8
}

Volume widget

The taskbar volume widget exposes a volume slider (0–100%), a mute toggle, and a playing indicator with an animated pulse. Its menu items are: Enable Audio (shown when autoplay is blocked), Playing: <trackname>, Stop, the volume slider, and Mute / Unmute.

Common patterns

• Per-severity annunciation. Configure a distinct sound and priority for each alarm severity in the Alarms Config app. ControlBird handles selection and broadcast automatically, with no scripting needed.
• Continuous siren. Enable looping on session playback so a critical sound repeats until the operator acknowledges the alarm or a new sound is played.
• Fixed-panel speakers. Use an audio controller, endpoint, and mapper so a kiosk plays through attached hardware regardless of session state. Run pactl list sinks on the host to discover valid sink names before configuring the mapper.
• Custom feedback. Trigger ad-hoc sounds (button confirmations, completion chimes) for a specific operator session from a Script.

Troubleshooting & limitations

• Repeated alarm sounds. Multiple active alarms re-trigger sound every 10 seconds. Acknowledge alarms promptly to stop the repetition.
• Only active, unacknowledged alarms play. ControlBird plays a sound only for alarms that are in an active or latched state and are not yet acknowledged.
• Loops run indefinitely. When looping is enabled, audio repeats until you play a new sound or disable looping.
• Exact sink names required. The audio mapper sink name must match exactly: verify with pactl list sinks before configuring.
• Operation support. Server-side audio supports play, stop, volume, and state operations. Pause, resume, and seek are not yet implemented.
• Upload size cap. Audio uploads are capped at 5 MB in the Alarms Config UI, which validates MIME types (audio/wav, audio/mpeg, audio/mp3, audio/ogg, audio/webm).
• Backgrounded tabs. Browsers throttle audio in inactive tabs; sound may not play if the ControlBird UI tab is backgrounded.
• Host audio access. Server-side audio plays through the host's audio system, so the deployment must run with permission to reach the host's audio device.