Background music loop during the install

[loki666]

A ~30-minute install is a long time staring at a progress bar in silence. A quiet background loop
would make the medium feel finished. Nice-to-have, explicitly behind anything that affects whether
an install works.

What the medium has today: nothing

install/manifest.lock carries exactly one audio-adjacent row — libpipewire, the client library,
pulled in transitively by gamescope's own depends. It is not sound; you can watch it fail
harmlessly in any installer log:

[gamescope] [Error] pipewire: pw_loop_new failed
Warning: failed to setup PipeWire, screen capture won't be available

The shipped device image has nine, for contrast:

alsa-card-profiles  alsa-lib  alsa-topology-conf  alsa-ucm-conf
pipewire  pipewire-alsa  pipewire-audio  pipewire-pulse  wireplumber

So the UCM is not on the installer medium.

Do NOT bring PipeWire/WirePlumber

WirePlumber wants a user session and the installer deliberately has none — no logind, no
/run/user/0. That is precisely the XDG_RUNTIME_DIR trap that has already cost two hardware
slots (gamescope got seatd, DRM master, Turnip and DSI-1, then aborted on its wayland socket). Do
not re-enter that class of problem for background music.

Plain ALSA instead: alsa-utils + alsa-lib + alsa-ucm-conf, three packages, no daemons.

The part that is not obvious: aplay alone makes no sound here

alsa-ucm-conf only SHIPS the use-case configs. Something has to apply them, and on the device that
something is WirePlumber — the very thing being dropped. With plain ALSA it has to be explicit:

alsaucm -c <card> set _verb HiFi     # alsa-utils. Without it the codec path is never set up.
amixer  -c <card> sset ... unmute    # gains
aplay -q /usr/share/novadeck/install/loop.wav

Skipping the alsaucm step looks exactly like "this board has no audio hardware", which is how an
afternoon disappears.

Shape

• A separate unit, not a UI child. Wants= (never Requires=) off the installer session, so a
  wedged audio path cannot touch the thing that installs a disk. install/ui already runs three
  children (SpineRun, NetJoin, VerifyRun) and this one has no reason to be a fourth.
• aplay cannot loop or decode. WAV only: while :; do aplay -q loop.wav; done, with a small
  gap per iteration. 22 kHz mono is ~44 KB/s, so a 3-minute loop is ~8 MB against a 2.1 GB medium;
  44.1 kHz stereo is ~32 MB and still fine.
• Every step guarded so SILENCE is the failure mode, never a hang. This is the tool that has to
  work when everything else on the device is broken. A SoundWire wedge needs a REBOOT to clear on
  these boards, and paying that during a 30-minute install would be a bad trade for ambience.
• Music licensing has to be settled before anything is staged into mkimage.sh — the medium is
  published.

Check first

Confirm alsa-utils actually resolves in the holo repos before committing to the design.
python-pygame and gtk2 both turned out not to exist there — which is why the SDL binding arrives
as a pinned wheel (install/pygame-ce.pin). make relock-installer is what answers it.

Related

• SM8250: speakers are quiet because the UCM BootSequence is never executed #63 — four boards share one UCM gain policy and it is already too quiet. Installer music would
  inherit exactly that, on a screen with no volume control. Worth fixing there first, or this ships
  inaudible on some boards and not others.
• Bundle streaming is latency-bound: one 128 KiB NBD readahead window per round trip #65 — while a fresh install is ~30 minutes this is more appealing than it should be. If that
  gets fixed the install may be short enough that the whole idea is moot, which is a good reason to
  leave this until after it.

[loki666]

Design refinement (user, 2026-08-25): the loop should be ~15 s, which makes size irrelevant — 2.6 MB at 44.1 kHz stereo, 660 KB at 22 kHz mono. Full quality is affordable.

But a short loop makes the seam problem worse, not better: aplay reopens the device every iteration, so a 15 s loop restarts ~120 times across a 30-minute install instead of ~10. So do not loop the process — loop the bytes. Strip the WAV header once and feed raw PCM into a single long-lived aplay:

{ while :; do cat /usr/share/novadeck/install/loop.raw; done; } \
  | aplay -q -t raw -f S16_LE -r 44100 -c 2 -

One device open, one continuous stream, gapless — provided the loop is cut on a zero crossing. This supersedes the while :; do aplay -q loop.wav; done in the body above.

Note the taste constraint that comes with it: 15 s repeated ~120 times suits ambient/textural material and does not suit anything with a melody. Another reason to land #65 first — at a two-minute install it is 8 repetitions, not 120.

[loki666]

MEASURED (2026-08-25): the pinned pygame-ce wheel already vendors the whole audio stack, so pygame.mixer costs ZERO new packages and the aplay design above is superseded.

unzip -l work/installer-prebuilt/pygame-ce.zip:

pygame/mixer.cpython-313-aarch64-linux-gnu.so
pygame/mixer_music.cpython-313-aarch64-linux-gnu.so
pygame_ce.libs/libSDL2_mixer-...so.0.800.2
pygame_ce.libs/libasound-...so.2.0.0          <- its OWN alsa-lib
pygame_ce.libs/libvorbis, libvorbisfile, libogg, libopus, libopusfile, libmpg123

So pygame.mixer.music.play(-1) loops a compressed OGG natively and gaplessly, with volume and fades, in the process that already exists. No alsa-utils, no raw-PCM header-stripping trick, no per-iteration device reopen, no separate unit. The 39 MB wheel is already on every medium with this half unused.

What this does NOT solve, and it was always the hard part — the UCM:

• the vendored libasound is CODE, not DATA: it still needs /usr/share/alsa/alsa.conf and the UCM tree, from alsa-lib + alsa-ucm-conf. Neither is in install/manifest.lock. ~2 MB of config.
• something must still APPLY the verb. WirePlumber does it on the device; alsaucm lives in alsa-utils. Opening hw:0,0 directly to dodge it leaves the codec path unrouted — most likely silence.

Architectural constraint. uiview.py is deliberately the ONLY file that imports pygame — that is what lets the state machine and its 298 offline cases run with no SDL and no display. Mixer code must live there, and install/fakepygame.py needs a mixer stub or the suite breaks. It also puts audio inside the one process that must not die, so init has to be guarded such that a mixer failure degrades to silence rather than taking the installer down. That is the isolation the separate unit was buying, traded for everything else above — worth it, but it must be deliberate.

[loki666]

UCM: the machine profiles ALREADY EXIST, but they are a layer, not a standalone set.

fs-overlay/usr/share/alsa/ucm2/ carries our own UCM2 machine profiles for all three SoCs and nine boards:

Qualcomm/sm8250/{PocketMax,ThorLite,RetroidPocket}
Qualcomm/sm8550/{Odin2,Thor,APS}
Qualcomm/sm8650/{APS2,KPF}
codecs/wsa881x/init.conf

They are card-name matched via relative paths, so the right one is selected automatically — the installer needs no board logic for this, which is a real saving given it is unified over all of them. codecs/wsa881x/init.conf is ours specifically because without it the two wsa881x amps expose no stereo Speakers device at all.

But fs-overlay/README.md is explicit that they reference codec definitions the base alsa-ucm-conf package must provide — wcd938x for SM8250/SM8550, wcd939x for SM8650. Copying our tree and skipping the package does not work.

So the real cost is four things, not "call mixer and ship an OGG":

1. alsa-lib — /usr/share/alsa/alsa.conf and the ucm2 machinery. The wheel vendors libasound as CODE; the config tree is DATA and is not in it.
2. alsa-ucm-conf — the upstream codec configs ours build on.
3. A new install/mkroot.sh stage to stage fs-overlay/usr/share/alsa/ucm2/. THE INSTALLER ROOT NEVER RUNS images/assemble-rootfs.sh — the structural cause that already cost three hardware trips (firmware, then kernel modules, then the overlay udev rules). Anything that script places beyond packages must be repeated in mkroot.sh. All 21 of its stages are audited and test-mkroot.sh fails if it grows one, so this is a known path — but it is a stage, not a copy.
4. alsa-utils, for alsaucm — something must APPLY the verb before pygame.mixer.init(). WirePlumber does it on the device and we are deliberately not shipping WirePlumber. (Still to confirm this package resolves in the holo repos — see the body.)

Revised estimate: still small, but no longer free. The mixer half costs nothing (already in the wheel); the ALSA half is ~2 MB of config, four packages-worth of lock churn, and one audited mkroot stage.