audio: add dynamic playback and capture route selection

Runner/suites/Multimedia/Audio/AudioLoopback/README.md

@@ -4,11 +4,29 @@
 media. It generates a deterministic 48 kHz, unsigned 8-bit stereo WAV, starts
 capture, plays the reference, and validates the resulting WAV.
 
-Automatic selection uses an active PipeWire or PulseAudio session and its
-physical speaker and microphone routes. PipeWire requires `wpctl`, `pw-record`,
-and `pw-play` or `pw-cat`. PulseAudio requires `pactl`, `parecord`, and `paplay`.
+Automatic selection uses an active PipeWire or PulseAudio session and discovers
+playback and capture independently. Playback tries speakers and then headphones.
+Capture tries mic and then headset-mic. PipeWire requires `wpctl`, `pw-record`,
+and `pw-play` or `pw-cat`.
+PulseAudio requires `pactl`, `parecord`, and `paplay`.
+Playback aliases `speaker`/`speakers` and
+`headphone`/`headphones`/`headset` map to the same canonical routes. Capture
+aliases `mic`/`microphone` and
+`headset-mic`/`headset_mic`/quoted `headset mic` are normalized before runtime
+route discovery. The effective selections and targets are emitted to standard
+output in an `AUDIO_ROUTE` record.
 If no managed backend is usable, the suite falls back to image-provided `aplay`
-and `arecord`. The suite never installs runtime packages.
+and `arecord`. Direct ALSA mode retrieves `PlaybackPCM` and `CapturePCM` from
+the matching UCM HiFi devices instead of encoding card or PCM numbers. It
+enables both devices in one UCM session when they share a card and verifies
+both through `_enadevs`. Private `_ucmNNNN.` prefixes are removed only from
+standard `hw:` or `plughw:` PCM names. UCM-only private virtual names are not
+used as standalone direct PCM routes. Auto-discovered raw `hw:` playback PCMs
+use the corresponding `plughw:` target so ALSA can convert the generated U8
+reference to the hardware PCM capabilities. Capture keeps its probed hardware
+format and device. Legacy speaker/microphone discovery
+remains available for images without usable UCM routes. The suite never
+installs runtime packages.
 
 On Debian and CentOS, a root invocation prepares the regular desktop audio user
 and re-launches the complete test as that user. Automatic selection also
@@ -20,9 +38,9 @@ execution behavior.
 
 The selected output must reach the selected input through an acoustic or
 electrical fixture. Automatic selection prefers the active managed backend and
-its physical speaker and microphone endpoints. Supplying either device option
-selects direct ALSA mode, where the unspecified side is discovered. Explicit
-ALSA devices are recommended for fixtures that require fixed PCM endpoints:
+its requested physical endpoints. Supplying either device option selects direct
+ALSA mode, where the unspecified side is discovered. Explicit ALSA devices are
+recommended for fixtures that require fixed PCM endpoints:
 
 ```sh
 ./run.sh \
@@ -31,10 +49,19 @@ ALSA devices are recommended for fixtures that require fixed PCM endpoints:
     --duration 5
 ```
 
-When no backend or device inventory exists, the suite reports SKIP with the
-missing prerequisite. When a managed backend is active but its physical routes
-are unusable and direct ALSA fallback also fails, the suite reports FAIL so the
-image or routing regression remains visible. An all-zero capture reports FAIL.
+Route-only examples use runtime endpoint and UCM discovery:
+
+```sh
+./run.sh --sink speakers --source mic --duration 5
+./run.sh --sink headphones --source headset-mic --duration 5
+```
+
+An explicit semantic route or PCM device is used only after runtime discovery
+and an open probe succeed. Explicit unavailable or malformed choices report
+FAIL with the requested route/device and retained probe evidence. Automatic
+discovery with no applicable route pair reports SKIP. A ready backend with
+missing required clients, a broken applicable route, or an all-zero capture
+reports FAIL.
 The default policy does not claim waveform correlation when the input contains
 some other non-zero signal, so retained metrics and the fixture setup remain
 important evidence.
@@ -46,17 +73,28 @@ WAV integrity: corrupt or empty files, header-only payloads, all-zero audio, and
 materially short captures fail. RMS, peak, clipping, digital-silence runs, DC
 offset, large sample transitions, and silent-channel counts are emitted in
 `AUDIO_VALIDATION` records as diagnostic metrics. They do not fail the default
-policy.
+policy. The generated two-level square-wave reference is validated with its
+known signal shape, so it does not produce a near-constant diagnostic. Complete
+RIFF chunks after a WAV `data` chunk are reported as metadata rather than as
+trailing audio.
 
 ## Options
 
 - `--duration SECONDS` selects 2 to 30 seconds.
-- `--playback-device DEVICE` overrides playback discovery.
-- `--capture-device DEVICE` overrides capture discovery and probes a supported
+- `--sink auto|speaker|speakers|headphone|headphones|headset` selects playback.
+- `--source auto|mic|microphone|headset-mic|headset_mic|"headset mic"` selects
+  capture.
+- `--playback-device DEVICE|auto` overrides playback discovery. `auto` and an
+  empty LAVA parameter retain discovery.
+- `--capture-device DEVICE|auto` overrides capture discovery and probes a supported
   format on that exact device.
 - `--dmesg-scan 0|1` controls retained kernel-log evidence.
 - `--no-dmesg` disables the kernel-log scan.
 
+An explicit `--playback-device` value is used exactly as supplied. Use
+`plughw:CARD,DEVICE` when the fixture's hardware PCM does not natively accept
+the generated U8 stereo reference.
+
 Artifacts are retained below `results/AudioLoopback/run-<timestamp>-<pid>/`.
 
 ## Yocto CI