Step 20: Audio Output
Play sounds from your browser or server for alarm notifications and custom audio feedback.
Full reference
For complete details, field tables, and limitations, see the Audio Output reference.
Two Audio Systems
ControlBird offers two ways to play audio: Session Audio for browser-based playback, and the PulseAudio Service for server-side audio on kiosks and industrial panels.
Session Audio (Browser)
Audio plays directly in the user's browser. Each logged-in session can receive audio commands independently, which suits web-based operator stations.
PulseAudio Service (Server)
Audio plays on the server through PulseAudio, a good fit for dedicated kiosk terminals, industrial HMI panels, or any headless display with speakers.
Session Audio
Session audio plays sounds directly in each operator's browser. To trigger playback, an automation writes a reference to an AudioFile against the active session, and the browser plays that sound.
The VolumeControl Widget
The taskbar includes a VolumeControl widget that shows the current audio state and lets users adjust volume or mute sounds:
Browser Autoplay Restrictions
Modern browsers block autoplay audio until the user interacts with the page. The first click anywhere in the ControlBird UI enables audio playback. If sounds aren't playing, try clicking in the application first.
Session Audio Controls
Each session exposes controls that automations can drive: which audio file to play, the playback volume (from mute to full), and whether the sound loops until stopped. These let you tailor alerts per operator station without affecting other sessions.
AudioFile Entities
Audio files are stored as AudioFile entities in the tree, typically under /Root/Audio/Files. Each AudioFile contains the raw audio data as a blob.
Supported audio formats:
- WAV: Uncompressed, best compatibility
- MP3: Compressed, smaller file size
- OGG: Open format, good compression
Alarm Sound Integration
ControlBird includes an Alarm Sound Player program that automatically plays sounds when high-severity alarms are active. This creates an audible alert system that draws operator attention.
How It Works
An alarm entity transitions to Active or Latched state
The player evaluates active alarms on a regular interval
Among unacknowledged alarms, it selects the one with the highest severity priority
The sound configured for that severity plays in all active operator sessions
Configuring Alarm Sounds
Each AlarmSeverity can have an associated sound file. Configure this in the Alarms Config app under the Severities tab:
Distinct Sounds for Severities
Use different sounds for each severity level so operators can recognize alarm importance by sound alone. A loud, urgent tone for Critical, a softer chime for Low/Info.
PulseAudio Service
For server-side audio (kiosks, industrial panels, headless displays), use the PulseAudio Service. This service connects to PulseAudio on the server and plays audio through physical speakers.
When to Use PulseAudio
- Dedicated kiosk terminals: Audio should play from the kiosk, not the operator's browser
- Industrial HMI panels: Built-in speakers on touch panels
- Control room annunciators: Centralized audio alert systems
- Headless displays: Screens without a full browser interface
PulseAudio Configuration
Configure audio output using PulseAudioController and PulseAudioMapper entities:
PulseAudioController
PulseAudioMapper
Triggering Audio Programmatically
You can play sounds from Rule Chains, Scripts, or any code that can write to the Store.
From a Script
A Script Engine script can locate an audio file by name and play it across the active operator sessions. For the script API and full examples, see the Store API reference.
From a Rule Chain
Use an Output node to write to Session.PlayAudioFile:
Troubleshooting
Sound doesn't play in browser
- Autoplay blocked: Click anywhere in the UI to enable audio, then retry
- Volume muted: Check the VolumeControl widget in the taskbar
- Invalid AudioFile: Verify the AudioFile entity has valid Data blob
- Browser tab inactive: Some browsers throttle audio in background tabs
Alarm sounds not triggering
- Check SoundFile field: Ensure AlarmSeverity.SoundFile references a valid AudioFile
- Check alarm state: Sound only plays for alarms in the Active or Latched state
- Check acknowledgment: Already-acknowledged alarms don't trigger sound
- Check scheduler: Verify Alarm Sound Player scheduler is Enabled
PulseAudio not working
- Check sink name: Run
pactl list sinksto find valid sink names - Check service status: Verify the PulseAudio output service is running
- Check permissions: The service needs access to the PulseAudio audio device
- Check volume: Both controller and system volume should be > 0
Audio plays multiple times
If multiple alarms are active, the Alarm Sound Player may trigger repeatedly. Consider:
- Acknowledge alarms promptly to stop repeated sounds
- Adjust the scheduler interval if sounds are too frequent
- Use AudioLoop=false to prevent infinite loops