Audio and ALSA

School Bell uses aplay for WAVE playback on Linux. ALSA configuration is a local runtime dependency: central connectivity is not involved once the audio files and device configuration are present.

Discover devices

List physical cards and named playback devices:

aplay -l
aplay -L

Test a sample directly before involving School Bell:

aplay /home/pi/samples/bell.wav
aplay -D DEVICE /home/pi/samples/bell.wav

Set the working named device in JSON:

{
    "device": "DEVICE"
}

Run school-bell schema.json --check to verify files without playing them, or --test to exercise real playback and GPIO outputs. Use --test only when ringing is safe.

Volume and permissions

Inspect and adjust the mixer with alsamixer or amixer. Confirm that channels are not muted and that systemd runs School Bell as a user with access to the audio device. Install alsa-utils and grant the service user the required device access explicitly; the current Ansible initialization playbook does not manage these audio-specific host settings.

Useful checks include:

groups pi
amixer scontrols
journalctl -u school-bell.service -n 100 --no-pager

Named PCM devices

Define site-specific devices in /etc/asound.conf. Test every definition with aplay -D NAME before using it in configuration.

Two mono zones

This example maps the left and right channels to separate named outputs:

pcm.output {
  type hw
  card 0
}
ctl.!default {
  type hw
  card 0
}
pcm.klas {
  type plug
  slave {
    pcm "output"
    channels 2
  }
  ttable.0.0 1
}
pcm.speelplaats {
  type plug
  slave {
    pcm "output"
    channels 2
  }
  ttable.0.1 1
}

Mono on both channels

pcm.output {
  type hw
  card 0
}
ctl.!default {
  type hw
  card 0
}
pcm.mono {
  type plug
  slave {
    pcm "output"
    channels 2
  }
  ttable.0.0 1
  ttable.0.1 1
}

Multi-channel USB interfaces

The following pattern splits an eight-channel ESI GIGAPORT eX into four stereo PCM devices:

pcm.Gigaport {
  type hw
  card eX
}
ctl.Gigaport {
  type hw
  card eX
}
pcm.zones {
  type dmix
  ipc_key 673138
  ipc_key_add_uid false
  ipc_perm 0666
  slave {
    pcm "Gigaport"
    rate 48000
    period_time 0
    period_size 1024
    buffer_size 8192
    channels 8
  }
  bindings {
    0 0
    1 1
    2 2
    3 3
    4 4
    5 5
    6 6
    7 7
  }
}
pcm.zone1 {
  type plug
  slave { pcm "zones" channels 8 }
  ttable.0.0 1
  ttable.1.1 1
}
pcm.zone2 {
  type plug
  slave { pcm "zones" channels 8 }
  ttable.0.2 1
  ttable.1.3 1
}
pcm.zone3 {
  type plug
  slave { pcm "zones" channels 8 }
  ttable.0.4 1
  ttable.1.5 1
}
pcm.zone4 {
  type plug
  slave { pcm "zones" channels 8 }
  ttable.0.6 1
  ttable.1.7 1
}
pcm.!default {
  type plug
  slave.pcm "zone1"
}

Select zone1 through zone4 with the top-level device setting.

Common failures

audio open error or unknown PCM

The configured name does not exist for the service user. Compare it with aplay -L and check /etc/asound.conf syntax.

device busy

Another process owns an exclusive hardware device. Use an appropriate ALSA mixing PCM or stop the conflicting process.

Playback succeeds but is silent

Check mixer mute state, physical cabling, selected output and sample format.

Works interactively but not under systemd

Compare users, groups, environment and device names. Test aplay as the configured service user.