feat(audio): select the playback output device #1001

Merged
HumanBean merged 9 commits from Phishinabowl/Longshot:feat/audio-output-selector into main 2026-11-16 03:16:11 +00:00
Member

Type: feat · Risk: medium · Tested on: historical Windows RTX 3080 and Linux RX Vega M GH play-tests; review fixes in game-free Windows/Linux checks · Needs: PR 979 integration and live validation of revised recovery

Review source: 96c91754b7228cf18afae35da2db1770c1a5a496, rebased and tested against main 1764fed2. Main advanced to 6fb13fe5 before this update; the next rebase/integration remains pending while #979 is open. Earlier play-tests and measurements retain their actual commit labels and do not validate the new stalled-device recovery fix.

Why

Players using several audio devices or virtual mixers need to route Longshot to a particular output without changing Windows' default for other applications. The existing Audio output setting chooses speaker layout, not a playback endpoint.

Add Output device in Audio, rename the layout setting Speaker layout, and group the existing microphone selector in Audio. The guide-source review gate also requires updating reviewed hashes for shared menu/API inputs; the upstream Graphics illustration is retained. Named playback selection is Windows-only; Linux keeps system-default playback.

Changes addressing review

  • Fixed named-device stall recovery, retained retry backoff until 30 seconds of completed audio, and probed named retries before closing a working fallback. Six new native cases cover repeated stalls, backoff, failed-open preservation, completed-playback reset, failed-write health counting and stereo-only recovery.
  • Removed two-second render-thread enumeration. The device list refreshes on menu opening; close/reopen after device changes to refresh the displayed list. Audio-thread recovery still retries missing endpoints.
  • Added missing output row, help and status translations to all 13 language tables. Device names remain untouched. Speaker layout now retains its settings key by value pointer.
  • Resolved the 24 translation conflicts with reviewed main, keeping upstream Auto/shadow/FPS changes. Reviewed main 1764fed2 uses ABI 23, topic 24; the next rebase must reconcile #822 if it has landed before this PR.
  • Retained the four A/B and three gameplay records under docs/tested; suite/build/website/UTF-8 records are represented below rather than added to the hardware catalogue. Verified private backups and Git history preserve the removed records.
  • Restored upstream's Graphics PNG/caption and original main capture provenance. A limited source-review update is required because the audio change touches shared menu/API/translation inputs; the review uses content hashes and a permanent topic-named note rather than unreachable branch commits. No Graphics image replacement remains.
  • Development docs now describe the permanent pre-mix/recovery behavior; historical attribution and control evidence stay here.
  • #979 is still open. Its shared options reader will be integrated after it lands, as requested; no parallel copy or competing parser is added.

What changed

Adds a Windows output-device selector that applies routing changes before audio mixing. Groups microphone selection in Audio and clarifies the existing speaker-layout setting. Linux keeps system-default playback, and existing Mono and text input behavior is preserved.

  • Devices: host/audio_output_devices.c/.h enumerate Windows endpoint metadata and store a requested persistent endpoint ID in a synchronized preference mailbox. Display names are labels, not identity.
  • Playback: host/nn_audio.c applies output switching before the next frame is mixed. Recovery drops PCM when the reopened channel count differs from the layout used to mix it. Missing endpoints retain their preference while falling back to Default.
  • Menu/settings: gpu/vk/vk_menu.cpp adds Output device, renames Audio output to Speaker layout without changing its key or Mono value, and moves Microphone from Gameplay to Audio. Adds audio_output_device_id and audio_output_device_name.
  • Interface: API 24 appends four callbacks, audio_output_count/info/select/state, after existing take_text and options_path. Startup uses shared hos_options_file(), including --user and HOS_OPTIONS_FILE.
  • Tests/docs: endpoint metadata, settings parser/path, ABI order, pre-mix switching, layout recovery, Mono and text-input checks; atomic-save fixture covers the new settings. Related menu/source expectations and documentation are updated.

Recovery is reconciled with jarynclouatre's PR 448, originally reviewed at 4093570fe98e3d47a061412cdec04243310cf534. Pinned main already includes its guard; historical failing-main recovery controls are not presented as current-main failures.

The independent mic-limit and shader fixes arrive through main. Mic test, meter and gain are excluded.

Measurements

Verdict: no clear slowdown or speedup in the measured scene. Topic median is 0.78% lower, within observed run-to-run spread. Two pairs on one PC/scene cannot rule out smaller costs elsewhere.

Baseline: clean main 3dec76818058c2c3eb66b4aca302962b79d96305; topic ca70a6b82831f78c8147e558b1d59fd55e94b827.

Hardware: Windows 10 Pro 19045; RTX 3080, driver 32.0.16.2124; Ryzen 9 5900XT, 16 cores/32 threads; 63.9 GiB usable RAM.
Scene: stationary child Link in Kakariko Village at night, same copied save/position/camera. Game output 2048x1152, swapchain 2560x1440; Custom, Catmull-Rom, render resolution 100%, frame generation Off, V-sync Auto/mailbox, HOS_FPS_MAX=1000; Default stereo audio enabled.
Method: separate 45-second warm-ups, then main/topic/main/topic, each 30 seconds settling plus 60 seconds recording. Median native logged FPS over complete 120-present intervals; median of two run medians. Profiling enabled only during warm-up. Position, scene and effective settings verified; no new pipelines or shader translations during timed windows.
How to reproduce: load a stationary Kakariko child/night save with these settings, independently warm both clean builds, alternate two runs each, and retain native FPS log lines and settings readback. Display/generated FPS and percentile frame times were not measured.

Native FPS Before: main @ 3dec7681 After: this PR @ ca70a6b8
Run 1 median 51.7 50.9
Run 2 median 51.2 51.2
Median of run medians 51.45 51.05

The table summarizes all recorded samples; representative original native lines from each run follow. Full sample lists remain retained locally.

main-01: [hos host] vk: 3720 presents, 48.6 fps; a frame: 2340 draws (0 skipped), 177 dispatches, 187 passes, 155 barriers, 6 submits, 0.0 uploads (0.0 MB), 80 ub updates (56 overlays), GPU-bound wait 0.1 ms (recording slots only); 7066 pipelines (1989 ms), 0 programs (0 failed), 1561 textures (3416 MB)
topic-01: [hos host] vk: 3720 presents, 49.5 fps; a frame: 2342 draws (0 skipped), 177 dispatches, 187 passes, 155 barriers, 6 submits, 0.1 uploads (0.0 MB), 80 ub updates (56 overlays), GPU-bound wait 0.1 ms (recording slots only); 7006 pipelines (2040 ms), 0 programs (0 failed), 1584 textures (3425 MB)
main-02: [hos host] vk: 3840 presents, 51.0 fps; a frame: 2341 draws (0 skipped), 177 dispatches, 187 passes, 154 barriers, 6 submits, 0.0 uploads (0.0 MB), 80 ub updates (56 overlays), GPU-bound wait 0.1 ms (recording slots only); 7066 pipelines (2058 ms), 0 programs (0 failed), 1584 textures (3432 MB)
topic-02: [hos host] vk: 3720 presents, 49.6 fps; a frame: 2340 draws (0 skipped), 177 dispatches, 187 passes, 155 barriers, 6 submits, 0.0 uploads (0.0 MB), 80 ub updates (56 overlays), GPU-bound wait 0.1 ms (recording slots only); 7006 pipelines (1987 ms), 0 programs (0 failed), 1554 textures (3396 MB)

Rebase evidence: the audio implementation and atomic-save fixture are unchanged from the measured commits. The two conflict resolutions preserve the new Debug warning while keeping audio refresh before dispatch. These historical pairs predate the review recovery fix. They remain historical feature-overhead evidence, not a measurement of local 96c91754 or the newer renderer. No speedup or zero-cost guarantee is claimed.

Flags and settings

Adds one playback row and two persisted keys; retains layout values and microphone preferences.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
Output device Audio row Absent Default initially; named Windows endpoints Live routing Windows owner verified named/Default routes and restart persistence; physical hotplug untested Default unless a named route is wanted
audio_output_device_id Persisted endpoint identity Absent Empty for Default, otherwise ID Restores route Settings/native fixtures and Windows restart pass Retain missing preference during fallback
audio_output_device_name Persisted display label Absent Selected label Names a missing selection Metadata fixtures pass Display only; identify by ID
Speaker layout / audio_output Existing row/key Audio output; 0 Auto, 1 Stereo, 2 5.1, 3 Mono Renamed; values/default unchanged Separates layout and route Windows/Linux owner verified Mono and persistence Auto default; retain existing choice
Microphone Existing row Gameplay Audio; keys unchanged Groups device controls Windows/Linux selection and persistence verified; end-to-end capture not claimed Retain existing choice
HOS_AUDIO_DEVICE Existing numeric override Takes priority Priority retained Per-run diagnostic route Native fixtures; real override untested Testing only; normal play uses selector

Testing

Tested: Review source 96c91754: all 31 native output cases and six shared recovery controls pass on Windows; 26 portable scripts pass on Windows (11.02 s), and 27 pass on native Linux (4.88 s), including POSIX atomic-save. Four original stalled/retry regressions fail against the pre-fix implementation. Independent cold review found a failed-write health-counter error in the first fix; its added regression fails there and passes after successful-submission tracking. Whole-file syntax checks pass on Windows/Linux with the same 129 baseline warnings and no new warning messages. Nine translation tests and 14 screenshot tests pass; the seven retained gameplay fragments parse correctly. Full review suites are complete: Windows 596 passed, 24 failed, 42 skipped, 322.81 s; Linux 625 passed, 20 failed, 17 skipped, 665.33 s. Every failed name reproduced in selected controls against main 1764fed2 (Windows 116.61 s; Linux 43.27 s). No topic-only or untested failure names; sources unchanged. These controls match failure names, not necessarily identical causes.

Review Windows exceptions (under tests/): test_auto_handheld.py, test_bug_report_defaults.py, test_crash_dialog.py, test_crt_options.py, test_fastfp_fma.py, test_fpx_sticky.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_import_reach.py, test_linux_preflight.py, test_longshot_ctl.py, test_make_game_cache.py, test_missing_nup.py, test_pads_after_menu.py, test_parallel_init_order.py, test_pending_guest_import.py, test_release.py, test_replay_write_order.py, test_run_all_changed.py, test_spawn_emit.py, test_tested_configurations.py, test_vk_occlusion_queries.py, test_walk_key.py, test_work_lock.py.

Review Linux exceptions (under tests/): test_bug_report.py, test_bug_report_defaults.py, test_crt_options.py, test_dev_packs.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_hardware_report.py, test_import_reach.py, test_linux_preflight.py, test_linux_update.py, test_make_game_cache.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_parallel_init_order.py, test_pending_guest_import.py, test_replay_write_order.py, test_run_all_changed.py, test_vk_occlusion_queries.py, test_walk_key.py.

These are fake-device/compiler checks, not a live run of the revised recovery logic. No game rebuild, device access or installed-game change was performed for this review increment.

Historical published-source check: topic 05bc3681 on pinned main a0be15b3: Windows full suite 594 passed, 23 failed, 42 skipped, 333.10 s, source hashes unchanged. Every failure reproduced in selected main controls (0 passed, 23 failed, 0 skipped, 111.55 s); no topic-only or untested failure names. Affected audio/ABI/settings/pre-mix/Mono/text-input checks passed. Linux full suite: 623 passed, 19 failed, 17 skipped, 924.63 s; selected main controls 0 passed, 19 failed, 0 skipped, 82.27 s. All failed names reproduced, with no topic-only or untested failure names; sources unchanged. Refreshed Windows host build and manual playback/virtual-endpoint recovery checks have passed. Refreshed Linux host build/smoke remains pending.

Current Linux exceptions (under tests/): test_bug_report.py, test_crt_options.py, test_dev_packs.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_hardware_report.py, test_import_reach.py, test_linux_preflight.py, test_linux_update.py, test_make_game_cache.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_parallel_init_order.py, test_pending_guest_import.py, test_replay_write_order.py, test_run_all_changed.py, test_vk_occlusion_queries.py, test_walk_key.py.

Current Windows exceptions (under tests/): test_auto_handheld.py, test_crash_dialog.py, test_crt_options.py, test_fastfp_fma.py, test_fpx_sticky.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_import_reach.py, test_linux_preflight.py, test_longshot_ctl.py, test_make_game_cache.py, test_missing_nup.py, test_pads_after_menu.py, test_parallel_init_order.py, test_pending_guest_import.py, test_release.py, test_replay_write_order.py, test_run_all_changed.py, test_spawn_emit.py, test_tested_configurations.py, test_vk_occlusion_queries.py, test_walk_key.py, test_work_lock.py.

Historical tested configurations: the following records name topic ca70a6b8 on main 3dec7681. They predate the review fix and retain their actual source labels.

  • Affected native checks on Windows and native Linux include ABI, shared settings path, PR 448 recovery, pre-mix switching, Mono, text input and dependency tracking. Atomic-save fixture now passes.
  • Full game-free suite, four workers: Windows 577 passed, 28 failed, 41 skipped, 296.92 s; Linux 605 passed, 24 failed, 17 skipped, 651.21 s. Sources unchanged. Every failed name reproduced in selected checks against pinned main 3dec7681; no topic-only or untested failure names. This is not a full main-suite comparison or proof of identical causes.
  • Full host builds and static binary/dependency inspection passed on both platforms. Additional full host builds with non-ASCII work/output paths passed: Windows 326.95 s, Linux 203.02 s, source hashes unchanged. Source paths remained ASCII. Those Unicode validation binaries were not launched.
  • Owner-operated Windows playback, named/Default switching, Mono, microphone selection and moved controls passed. All choices survived restart with playback working. Linux default playback, Mono, microphone selection, moved controls and restart persistence passed. Runtime component fingerprints match ca70a6b8; its final commit changes only a test fixture.
  • Warmed paired gameplay comparison above passed scene/settings checks.
  • UI-only matching Audio captures: main 3dec7681 has three rows; topic ca70a6b8 has five. Source/image/fixture hashes verified and images visually reviewed. Same software fixture, 1280x720, English, Medium, compiled defaults, synthetic SDR/null host; not live endpoint-list proof. Three explicitly fingerprinted fixture-only capability stand-ins are shared by both captures.
  • Canonical Graphics guide image/provenance refreshed to ca70a6b8. Seven images and local source review pass; 14 screenshot tests pass. Unchanged external Launcher sources remain NOT CHECKED.
  • Website build passed, 18 pages in 1m26s. Six headless desktop/mobile light/dark checks passed, including served-image hash and keyboard full-size link; representative views visually inspected. Native zoom through 200% was reviewed on the earlier guide, not repeated on this refreshed image.
  • Website units: 100 passed, 2 failed. Selected pinned-main controls: 20 passed, 2 failed, reproducing HDR negative-control and Windows save-scrubber CRLF/LF assertions. Deferred progress-feed/HDR source unchanged. No all-green website claim.

Windows failed names (under tests/):
test_appimage_player_build.py, test_auto_handheld.py, test_bug_report.py, test_cpp_preflight.py, test_crash_dialog.py, test_crt_options.py, test_env_on.py, test_fpx_sticky.py, test_fsr_uniform_ownership.py, test_hardware_report.py, test_lift_cleanup_error.py, test_linux_preflight.py, test_make_game_cache.py, test_make_game_prepare.py, test_missing_nup.py, test_options_budget_once.py, test_pads_after_menu.py, test_parallel_init_order.py, test_readback_late.py, test_release.py, test_replay_write_order.py, test_run_all_changed.py, test_spawn_emit.py, test_tested_configurations.py, test_vk_occlusion_queries.py, test_vk_pgo.py, test_walk_key.py, test_work_lock.py.

Linux failed names (under tests/):
test_appimage_player_build.py, test_bug_report.py, test_crash_dialog.py, test_crt_options.py, test_dev_packs.py, test_env_on.py, test_fsr_uniform_ownership.py, test_hardware_report.py, test_lift_cleanup_error.py, test_linux_preflight.py, test_linux_update.py, test_make_game_cache.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_options_budget_once.py, test_parallel_init_order.py, test_pipeline_tour.py, test_readback_late.py, test_replay_write_order.py, test_run_all_changed.py, test_vk_occlusion_queries.py, test_vk_pgo.py, test_walk_key.py.

Historical records retain their original commits and counts; they are not silently upgraded to current evidence.

Not tested: live-device playback of review source 96c91754, physical USB hotplug, real diagnostic override, end-to-end microphone capture, physical-mobile or screen-reader behavior. Prior virtual endpoint disable/re-enable and ordinary playback tests passed before this recovery revision. No game rebuild or installed-game update was performed for the review changes.

Must be tested:

  • Windows, any GPU, by hand after an authorized rebuild: exercise normal named/Default switching and endpoint disable/re-enable, expecting fallback, retained preference and restored output. Where a test endpoint can open without playing or refuses an open, check repeated retries, expecting fallback to keep playing without exhausting recovery or interrupting fallback on failed probes.
  • Windows/Linux, by hand after PR 979 lands: rerun shared-reader parser/long-line controls and playback/settings smoke, expecting over-long ID rejection, stable settings paths and unchanged default behavior.

Risks

What could break: device reopen/recovery, callback layout, startup settings routing and live channel layout changes. Reopening can briefly interrupt audio. Linux must retain default playback.

Turning it off: choose Default to stop requesting a named route. Revert the feature to remove its code; Default is not a complete feature-disable switch for benchmarking.

Compatibility: existing layout/microphone keys and Mono values stay valid. API 24 requires matching rebuilt host/renderer binaries. No game/save-format or shader-algorithm changes. Main/topic translator stamps matched during warm tests; cache validity remains enforced. No new third-party runtime dependency.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main. Reviewed/tested against 1764fed2; main advanced to 6fb13fe5. Rebase again with #979 integration before ready.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). Review source 96c91754 compared on both platforms; all failed names also fail on main 1764fed2.
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen.
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost or MkwVkRenderer changed).
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Review-fix whole-file syntax checks pass on both platforms; game rebuilds are deferred by instruction. Earlier UTF-8 builds retain their original source labels.
  • Docs updated.

This PR remains WIP. PR 979 integration, the next main rebase and live validation of the revised recovery remain outstanding. The attached Audio screenshots retain their actual capture captions (main 3dec7681 and topic ca70a6b8); no new capture is claimed. The repository's canonical Graphics PNG/caption now remain identical to upstream.

Before: main @ 3dec7681

After: this PR @ ca70a6b8

**Type:** feat · **Risk:** medium · **Tested on:** historical Windows RTX 3080 and Linux RX Vega M GH play-tests; review fixes in game-free Windows/Linux checks · **Needs:** PR 979 integration and live validation of revised recovery Review source: `96c91754b7228cf18afae35da2db1770c1a5a496`, rebased and tested against main `1764fed2`. Main advanced to `6fb13fe5` before this update; the next rebase/integration remains pending while #979 is open. Earlier play-tests and measurements retain their actual commit labels and do not validate the new stalled-device recovery fix. ## Why Players using several audio devices or virtual mixers need to route Longshot to a particular output without changing Windows' default for other applications. The existing Audio output setting chooses speaker layout, not a playback endpoint. Add Output device in Audio, rename the layout setting Speaker layout, and group the existing microphone selector in Audio. The guide-source review gate also requires updating reviewed hashes for shared menu/API inputs; the upstream Graphics illustration is retained. Named playback selection is Windows-only; Linux keeps system-default playback. ## Changes addressing review - Fixed named-device stall recovery, retained retry backoff until 30 seconds of completed audio, and probed named retries before closing a working fallback. Six new native cases cover repeated stalls, backoff, failed-open preservation, completed-playback reset, failed-write health counting and stereo-only recovery. - Removed two-second render-thread enumeration. The device list refreshes on menu opening; close/reopen after device changes to refresh the displayed list. Audio-thread recovery still retries missing endpoints. - Added missing output row, help and status translations to all 13 language tables. Device names remain untouched. Speaker layout now retains its settings key by value pointer. - Resolved the 24 translation conflicts with reviewed main, keeping upstream Auto/shadow/FPS changes. Reviewed main 1764fed2 uses ABI 23, topic 24; the next rebase must reconcile #822 if it has landed before this PR. - Retained the four A/B and three gameplay records under docs/tested; suite/build/website/UTF-8 records are represented below rather than added to the hardware catalogue. Verified private backups and Git history preserve the removed records. - Restored upstream's Graphics PNG/caption and original main capture provenance. A limited source-review update is required because the audio change touches shared menu/API/translation inputs; the review uses content hashes and a permanent topic-named note rather than unreachable branch commits. No Graphics image replacement remains. - Development docs now describe the permanent pre-mix/recovery behavior; historical attribution and control evidence stay here. - #979 is still open. Its shared options reader will be integrated after it lands, as requested; no parallel copy or competing parser is added. ## What changed Adds a Windows output-device selector that applies routing changes before audio mixing. Groups microphone selection in Audio and clarifies the existing speaker-layout setting. Linux keeps system-default playback, and existing Mono and text input behavior is preserved. - Devices: `host/audio_output_devices.c/.h` enumerate Windows endpoint metadata and store a requested persistent endpoint ID in a synchronized preference mailbox. Display names are labels, not identity. - Playback: `host/nn_audio.c` applies output switching before the next frame is mixed. Recovery drops PCM when the reopened channel count differs from the layout used to mix it. Missing endpoints retain their preference while falling back to Default. - Menu/settings: `gpu/vk/vk_menu.cpp` adds Output device, renames Audio output to Speaker layout without changing its key or Mono value, and moves Microphone from Gameplay to Audio. Adds `audio_output_device_id` and `audio_output_device_name`. - Interface: API 24 appends four callbacks, `audio_output_count/info/select/state`, after existing `take_text` and `options_path`. Startup uses shared `hos_options_file()`, including `--user` and `HOS_OPTIONS_FILE`. - Tests/docs: endpoint metadata, settings parser/path, ABI order, pre-mix switching, layout recovery, Mono and text-input checks; atomic-save fixture covers the new settings. Related menu/source expectations and documentation are updated. Recovery is reconciled with jarynclouatre's [PR 448](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/448), originally reviewed at `4093570fe98e3d47a061412cdec04243310cf534`. Pinned main already includes its guard; historical failing-main recovery controls are not presented as current-main failures. The independent mic-limit and shader fixes arrive through main. Mic test, meter and gain are excluded. ## Measurements **Verdict:** no clear slowdown or speedup in the measured scene. Topic median is 0.78% lower, within observed run-to-run spread. Two pairs on one PC/scene cannot rule out smaller costs elsewhere. Baseline: clean main `3dec76818058c2c3eb66b4aca302962b79d96305`; topic `ca70a6b82831f78c8147e558b1d59fd55e94b827`. Hardware: Windows 10 Pro 19045; RTX 3080, driver 32.0.16.2124; Ryzen 9 5900XT, 16 cores/32 threads; 63.9 GiB usable RAM. Scene: stationary child Link in Kakariko Village at night, same copied save/position/camera. Game output 2048x1152, swapchain 2560x1440; Custom, Catmull-Rom, render resolution 100%, frame generation Off, V-sync Auto/mailbox, `HOS_FPS_MAX=1000`; Default stereo audio enabled. Method: separate 45-second warm-ups, then main/topic/main/topic, each 30 seconds settling plus 60 seconds recording. Median native logged FPS over complete 120-present intervals; median of two run medians. Profiling enabled only during warm-up. Position, scene and effective settings verified; no new pipelines or shader translations during timed windows. How to reproduce: load a stationary Kakariko child/night save with these settings, independently warm both clean builds, alternate two runs each, and retain native FPS log lines and settings readback. Display/generated FPS and percentile frame times were not measured. | Native FPS | Before: main @ 3dec7681 | After: this PR @ ca70a6b8 | |---|---:|---:| | Run 1 median | 51.7 | 50.9 | | Run 2 median | 51.2 | 51.2 | | Median of run medians | 51.45 | 51.05 | The table summarizes all recorded samples; representative original native lines from each run follow. Full sample lists remain retained locally. ```text main-01: [hos host] vk: 3720 presents, 48.6 fps; a frame: 2340 draws (0 skipped), 177 dispatches, 187 passes, 155 barriers, 6 submits, 0.0 uploads (0.0 MB), 80 ub updates (56 overlays), GPU-bound wait 0.1 ms (recording slots only); 7066 pipelines (1989 ms), 0 programs (0 failed), 1561 textures (3416 MB) topic-01: [hos host] vk: 3720 presents, 49.5 fps; a frame: 2342 draws (0 skipped), 177 dispatches, 187 passes, 155 barriers, 6 submits, 0.1 uploads (0.0 MB), 80 ub updates (56 overlays), GPU-bound wait 0.1 ms (recording slots only); 7006 pipelines (2040 ms), 0 programs (0 failed), 1584 textures (3425 MB) main-02: [hos host] vk: 3840 presents, 51.0 fps; a frame: 2341 draws (0 skipped), 177 dispatches, 187 passes, 154 barriers, 6 submits, 0.0 uploads (0.0 MB), 80 ub updates (56 overlays), GPU-bound wait 0.1 ms (recording slots only); 7066 pipelines (2058 ms), 0 programs (0 failed), 1584 textures (3432 MB) topic-02: [hos host] vk: 3720 presents, 49.6 fps; a frame: 2340 draws (0 skipped), 177 dispatches, 187 passes, 155 barriers, 6 submits, 0.0 uploads (0.0 MB), 80 ub updates (56 overlays), GPU-bound wait 0.1 ms (recording slots only); 7006 pipelines (1987 ms), 0 programs (0 failed), 1554 textures (3396 MB) ``` Rebase evidence: the audio implementation and atomic-save fixture are unchanged from the measured commits. The two conflict resolutions preserve the new Debug warning while keeping audio refresh before dispatch. These historical pairs predate the review recovery fix. They remain historical feature-overhead evidence, not a measurement of local 96c91754 or the newer renderer. No speedup or zero-cost guarantee is claimed. ### Flags and settings Adds one playback row and two persisted keys; retains layout values and microphone preferences. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | Output device | Audio row | Absent | Default initially; named Windows endpoints | Live routing | Windows owner verified named/Default routes and restart persistence; physical hotplug untested | Default unless a named route is wanted | | audio_output_device_id | Persisted endpoint identity | Absent | Empty for Default, otherwise ID | Restores route | Settings/native fixtures and Windows restart pass | Retain missing preference during fallback | | audio_output_device_name | Persisted display label | Absent | Selected label | Names a missing selection | Metadata fixtures pass | Display only; identify by ID | | Speaker layout / audio_output | Existing row/key | Audio output; 0 Auto, 1 Stereo, 2 5.1, 3 Mono | Renamed; values/default unchanged | Separates layout and route | Windows/Linux owner verified Mono and persistence | Auto default; retain existing choice | | Microphone | Existing row | Gameplay | Audio; keys unchanged | Groups device controls | Windows/Linux selection and persistence verified; end-to-end capture not claimed | Retain existing choice | | HOS_AUDIO_DEVICE | Existing numeric override | Takes priority | Priority retained | Per-run diagnostic route | Native fixtures; real override untested | Testing only; normal play uses selector | ## Testing **Tested:** Review source 96c91754: all 31 native output cases and six shared recovery controls pass on Windows; 26 portable scripts pass on Windows (11.02 s), and 27 pass on native Linux (4.88 s), including POSIX atomic-save. Four original stalled/retry regressions fail against the pre-fix implementation. Independent cold review found a failed-write health-counter error in the first fix; its added regression fails there and passes after successful-submission tracking. Whole-file syntax checks pass on Windows/Linux with the same 129 baseline warnings and no new warning messages. Nine translation tests and 14 screenshot tests pass; the seven retained gameplay fragments parse correctly. Full review suites are complete: Windows **596 passed, 24 failed, 42 skipped**, 322.81 s; Linux **625 passed, 20 failed, 17 skipped**, 665.33 s. Every failed name reproduced in selected controls against main 1764fed2 (Windows 116.61 s; Linux 43.27 s). No topic-only or untested failure names; sources unchanged. These controls match failure names, not necessarily identical causes. Review Windows exceptions (under `tests/`): test_auto_handheld.py, test_bug_report_defaults.py, test_crash_dialog.py, test_crt_options.py, test_fastfp_fma.py, test_fpx_sticky.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_import_reach.py, test_linux_preflight.py, test_longshot_ctl.py, test_make_game_cache.py, test_missing_nup.py, test_pads_after_menu.py, test_parallel_init_order.py, test_pending_guest_import.py, test_release.py, test_replay_write_order.py, test_run_all_changed.py, test_spawn_emit.py, test_tested_configurations.py, test_vk_occlusion_queries.py, test_walk_key.py, test_work_lock.py. Review Linux exceptions (under `tests/`): test_bug_report.py, test_bug_report_defaults.py, test_crt_options.py, test_dev_packs.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_hardware_report.py, test_import_reach.py, test_linux_preflight.py, test_linux_update.py, test_make_game_cache.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_parallel_init_order.py, test_pending_guest_import.py, test_replay_write_order.py, test_run_all_changed.py, test_vk_occlusion_queries.py, test_walk_key.py. These are fake-device/compiler checks, not a live run of the revised recovery logic. No game rebuild, device access or installed-game change was performed for this review increment. **Historical published-source check:** topic `05bc3681` on pinned main `a0be15b3`: Windows full suite **594 passed, 23 failed, 42 skipped**, 333.10 s, source hashes unchanged. Every failure reproduced in selected main controls (**0 passed, 23 failed, 0 skipped**, 111.55 s); no topic-only or untested failure names. Affected audio/ABI/settings/pre-mix/Mono/text-input checks passed. Linux full suite: **623 passed, 19 failed, 17 skipped**, 924.63 s; selected main controls **0 passed, 19 failed, 0 skipped**, 82.27 s. All failed names reproduced, with no topic-only or untested failure names; sources unchanged. Refreshed Windows host build and manual playback/virtual-endpoint recovery checks have passed. Refreshed Linux host build/smoke remains pending. Current Linux exceptions (under `tests/`): test_bug_report.py, test_crt_options.py, test_dev_packs.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_hardware_report.py, test_import_reach.py, test_linux_preflight.py, test_linux_update.py, test_make_game_cache.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_parallel_init_order.py, test_pending_guest_import.py, test_replay_write_order.py, test_run_all_changed.py, test_vk_occlusion_queries.py, test_walk_key.py. Current Windows exceptions (under `tests/`): test_auto_handheld.py, test_crash_dialog.py, test_crt_options.py, test_fastfp_fma.py, test_fpx_sticky.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_import_reach.py, test_linux_preflight.py, test_longshot_ctl.py, test_make_game_cache.py, test_missing_nup.py, test_pads_after_menu.py, test_parallel_init_order.py, test_pending_guest_import.py, test_release.py, test_replay_write_order.py, test_run_all_changed.py, test_spawn_emit.py, test_tested_configurations.py, test_vk_occlusion_queries.py, test_walk_key.py, test_work_lock.py. **Historical tested configurations:** the following records name topic ca70a6b8 on main 3dec7681. They predate the review fix and retain their actual source labels. - Affected native checks on Windows and native Linux include ABI, shared settings path, PR 448 recovery, pre-mix switching, Mono, text input and dependency tracking. Atomic-save fixture now passes. - Full game-free suite, four workers: Windows **577 passed, 28 failed, 41 skipped**, 296.92 s; Linux **605 passed, 24 failed, 17 skipped**, 651.21 s. Sources unchanged. Every failed name reproduced in selected checks against pinned main 3dec7681; no topic-only or untested failure names. This is not a full main-suite comparison or proof of identical causes. - Full host builds and static binary/dependency inspection passed on both platforms. Additional full host builds with non-ASCII work/output paths passed: Windows **326.95 s**, Linux **203.02 s**, source hashes unchanged. Source paths remained ASCII. Those Unicode validation binaries were not launched. - Owner-operated Windows playback, named/Default switching, Mono, microphone selection and moved controls passed. All choices survived restart with playback working. Linux default playback, Mono, microphone selection, moved controls and restart persistence passed. Runtime component fingerprints match ca70a6b8; its final commit changes only a test fixture. - Warmed paired gameplay comparison above passed scene/settings checks. - UI-only matching Audio captures: main 3dec7681 has three rows; topic ca70a6b8 has five. Source/image/fixture hashes verified and images visually reviewed. Same software fixture, 1280x720, English, Medium, compiled defaults, synthetic SDR/null host; not live endpoint-list proof. Three explicitly fingerprinted fixture-only capability stand-ins are shared by both captures. - Canonical Graphics guide image/provenance refreshed to ca70a6b8. Seven images and local source review pass; 14 screenshot tests pass. Unchanged external Launcher sources remain NOT CHECKED. - Website build passed, 18 pages in 1m26s. Six headless desktop/mobile light/dark checks passed, including served-image hash and keyboard full-size link; representative views visually inspected. Native zoom through 200% was reviewed on the earlier guide, not repeated on this refreshed image. - Website units: **100 passed, 2 failed**. Selected pinned-main controls: **20 passed, 2 failed**, reproducing HDR negative-control and Windows save-scrubber CRLF/LF assertions. Deferred progress-feed/HDR source unchanged. No all-green website claim. Windows failed names (under `tests/`): test_appimage_player_build.py, test_auto_handheld.py, test_bug_report.py, test_cpp_preflight.py, test_crash_dialog.py, test_crt_options.py, test_env_on.py, test_fpx_sticky.py, test_fsr_uniform_ownership.py, test_hardware_report.py, test_lift_cleanup_error.py, test_linux_preflight.py, test_make_game_cache.py, test_make_game_prepare.py, test_missing_nup.py, test_options_budget_once.py, test_pads_after_menu.py, test_parallel_init_order.py, test_readback_late.py, test_release.py, test_replay_write_order.py, test_run_all_changed.py, test_spawn_emit.py, test_tested_configurations.py, test_vk_occlusion_queries.py, test_vk_pgo.py, test_walk_key.py, test_work_lock.py. Linux failed names (under `tests/`): test_appimage_player_build.py, test_bug_report.py, test_crash_dialog.py, test_crt_options.py, test_dev_packs.py, test_env_on.py, test_fsr_uniform_ownership.py, test_hardware_report.py, test_lift_cleanup_error.py, test_linux_preflight.py, test_linux_update.py, test_make_game_cache.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_options_budget_once.py, test_parallel_init_order.py, test_pipeline_tour.py, test_readback_late.py, test_replay_write_order.py, test_run_all_changed.py, test_vk_occlusion_queries.py, test_vk_pgo.py, test_walk_key.py. Historical records retain their original commits and counts; they are not silently upgraded to current evidence. **Not tested:** live-device playback of review source 96c91754, physical USB hotplug, real diagnostic override, end-to-end microphone capture, physical-mobile or screen-reader behavior. Prior virtual endpoint disable/re-enable and ordinary playback tests passed before this recovery revision. No game rebuild or installed-game update was performed for the review changes. **Must be tested:** - Windows, any GPU, by hand after an authorized rebuild: exercise normal named/Default switching and endpoint disable/re-enable, expecting fallback, retained preference and restored output. Where a test endpoint can open without playing or refuses an open, check repeated retries, expecting fallback to keep playing without exhausting recovery or interrupting fallback on failed probes. - Windows/Linux, by hand after PR 979 lands: rerun shared-reader parser/long-line controls and playback/settings smoke, expecting over-long ID rejection, stable settings paths and unchanged default behavior. ## Risks **What could break:** device reopen/recovery, callback layout, startup settings routing and live channel layout changes. Reopening can briefly interrupt audio. Linux must retain default playback. **Turning it off:** choose Default to stop requesting a named route. Revert the feature to remove its code; Default is not a complete feature-disable switch for benchmarking. **Compatibility:** existing layout/microphone keys and Mono values stay valid. API 24 requires matching rebuilt host/renderer binaries. No game/save-format or shader-algorithm changes. Main/topic translator stamps matched during warm tests; cache validity remains enforced. No new third-party runtime dependency. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [ ] Rebased on current `main`. Reviewed/tested against 1764fed2; main advanced to 6fb13fe5. Rebase again with #979 integration before ready. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). Review source 96c91754 compared on both platforms; all failed names also fail on main 1764fed2. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen. - [x] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [x] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` or `MkwVkRenderer` changed). - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Review-fix whole-file syntax checks pass on both platforms; game rebuilds are deferred by instruction. Earlier UTF-8 builds retain their original source labels. - [x] Docs updated. This PR remains WIP. PR 979 integration, the next main rebase and live validation of the revised recovery remain outstanding. The attached Audio screenshots retain their actual capture captions (main 3dec7681 and topic ca70a6b8); no new capture is claimed. The repository's canonical Graphics PNG/caption now remain identical to upstream. ![Before: main @ 3dec7681](https://git.magicbean.dev/attachments/16e9a6b5-3244-44a8-a145-e7e16837f8e5) ![After: this PR @ ca70a6b8](https://git.magicbean.dev/attachments/05fb609d-a281-4a69-b500-b4da35b419bd)
Add persistent Windows playback endpoint selection and audio-thread routing,
including default fallback and reconnect handling. Group microphone selection
under Audio and distinguish Speaker layout while preserving existing settings,
Mono and text input. Use main's shared settings path and append playback
callbacks under API 24.

Keep the UI-only screenshot fixture compatible with main's GPU card records and
shared settings path, using empty synthetic cards and aborting any settings-path
lookup. No real settings, device or game initialization is added to the fixture.

Adapt and credit the overlapping recovery safety behavior from jarynclouatre's
PR 448, pinned 4093570fe9:
#448
Apply explicit selection before mixing; drop already-mixed frames after a
channel-layout change and retain same-layout recovery frames.

Add ABI, shared-path, recovery, translation and cache-dependency regressions.
Record the Windows and WSL fixture results and their limits. The last full
Windows run on the aa95d35f-based working copy had 540 passed, 20 failed and
35 skipped; all 20 failure names reproduced on pinned main. Twenty-one affected
Windows checks and 22 WSL scripts passed. The subsequently added recovery-only
test passed separately on both platforms: an identical driver compiled on main
and topic, with three expected main runtime failures and six passing topic cases
per phase across two interleaved pairs. No full-suite rerun including that new
test or current-main game/device play-test is claimed.

Assisted-by: OpenAI Codex
Declare output-selection state in the isolated save fixture and test stable IDs, default-device cleanup, and full-disk recovery. Preserve the original atomic-save scenarios.

Assisted-by: OpenAI Codex
Supply synthetic SDR and unavailable-XeSS stand-ins for UI-only captures.
Update speaker-layout label expectations while keeping restart controls.

Assisted-by: OpenAI Codex
docs(audio): record cross-platform output selector validation
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 3s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
fc3dba3a0d
Record host builds, playback and persistence checks, game-free comparisons,
paired native FPS measurements, and guide rendering checks with their actual
source revisions and evidence limits. Refresh the canonical illustration and
record its source review after rebasing.

Assisted-by: OpenAI Codex
Author
Member

Tested in game: Windows 10 RTX 3080 driver 32.0.16.2124: owner verified playback, named output switching, Default, Mono, microphone selection, moved Audio controls and restart persistence. Native Ubuntu 26.04.1 RX Vega M GH/RADV: owner verified default playback, Mono, microphone selection, moved controls and restart persistence. These play-tests ran the ca70a6b8-equivalent runtime component fingerprint; rebased 05bc3681 preserves the audio implementation. Refreshed rebased-source builds and virtual-endpoint disable/re-enable test are pending and the PR remains WIP.

Tested in game: Windows 10 RTX 3080 driver 32.0.16.2124: owner verified playback, named output switching, Default, Mono, microphone selection, moved Audio controls and restart persistence. Native Ubuntu 26.04.1 RX Vega M GH/RADV: owner verified default playback, Mono, microphone selection, moved controls and restart persistence. These play-tests ran the ca70a6b8-equivalent runtime component fingerprint; rebased 05bc3681 preserves the audio implementation. Refreshed rebased-source builds and virtual-endpoint disable/re-enable test are pending and the PR remains WIP.
Collaborator

Possibly related, for context:

  • PR #979 refactor(host): one reader for longshot_options.ini's lines, not six — Overlaps nn_audio.c/options parsing and audio setting changes
Possibly related, for context: - PR #979 refactor(host): one reader for longshot_options.ini's lines, not six — Overlaps nn_audio.c/options parsing and audio setting changes
Author
Member

Matching UI-only Audio views, 1280x720, English, Medium menu size, compiled defaults and synthetic null-host state. These are software-rendered menu captures, not live endpoint-list screenshots.

Before: main @ 3dec7681

After: this PR @ ca70a6b8

The source review retains these captures for rebased runtime 05bc3681: its upstream UI changes affect Debug controls and declarations, while Graphics and this feature's Audio rows remain unchanged. Actual capture revisions stay in the captions. Capture/fixture/source provenance is recorded in the guide review documents; no game files or private device names are included.

Matching UI-only Audio views, 1280x720, English, Medium menu size, compiled defaults and synthetic null-host state. These are software-rendered menu captures, not live endpoint-list screenshots. ![Before: main @ 3dec7681](https://git.magicbean.dev/attachments/16e9a6b5-3244-44a8-a145-e7e16837f8e5) ![After: this PR @ ca70a6b8](https://git.magicbean.dev/attachments/05fb609d-a281-4a69-b500-b4da35b419bd) The source review retains these captures for rebased runtime 05bc3681: its upstream UI changes affect Debug controls and declarations, while Graphics and this feature's Audio rows remain unchanged. Actual capture revisions stay in the captions. Capture/fixture/source provenance is recorded in the guide review documents; no game files or private device names are included.
Author
Member

Final rebased-source game-free checks are complete on both platforms. Windows: 594 pass, 23 fail, 42 skip; every failure reproduced in selected pinned-main controls. Linux: 623 pass, 19 fail, 17 skip; every failure reproduced in selected pinned-main controls. No topic-only or untested failure names on either platform; source hashes unchanged. Matching failure names are not proof of identical causes. Description now includes the reviewed before/after Audio screenshots. Refreshed host builds and virtual-endpoint recovery smoke remain pending, so this stays WIP.

Final rebased-source game-free checks are complete on both platforms. Windows: 594 pass, 23 fail, 42 skip; every failure reproduced in selected pinned-main controls. Linux: 623 pass, 19 fail, 17 skip; every failure reproduced in selected pinned-main controls. No topic-only or untested failure names on either platform; source hashes unchanged. Matching failure names are not proof of identical causes. Description now includes the reviewed before/after Audio screenshots. Refreshed host builds and virtual-endpoint recovery smoke remain pending, so this stays WIP.
HumanBean left a comment

I read the whole diff at fc3dba3a (no builds or tests run here). The design holds up: the endpoint is stored by its persistent ID rather than its place in the list, there is a locked mailbox between the menu and the audio thread, the route switch happens before the next frame is mixed, and Speaker layout keeps its audio_output key and values. I'm requesting changes for one bug and a few things that should land before pr ready.

Before ready

  • It conflicts with main. Main moved after a0be15b3 (PR 604, PR 994, PR 773, PR 998). A trial rebase onto 1764fed2 hits 24 textual conflicts, all in gpu/vk/menu_i18n.h: PR 998 added {"Auto", "Auto"} next to the old "Audio output" entry, and the hint line you changed sits next to PR 773's new shadow strings. Keeping both sides should resolve all of them. vk_api.h is still at 23 on main, so your bump to 24 stays valid for now.
  • A named endpoint that opens but never plays leads to silence (inline on host/nn_audio.c). The 6-reopen stall cap ends up stuck on the bad device.
  • The device list is enumerated on the render thread every 2 s while the menu is open (inline on vk_menu.cpp).
  • The new row isn't translated. Every other Audio row is in all 13 tables. "Output device" and its texts aren't, so a non-English menu shows this one row in English.
  • docs/tested/ has 34 new files. Most of them record suite runs, website builds, WSL portability checks and UTF-8 builds, not game runs. docs/tested-configurations.md is for measured runs on hardware, and the website lists every file there. I'd keep the four A/B files and the Windows and Linux play runs, and move the rest into this description.
  • The provenance names commits that won't be on main. PRs are squash-merged, so ca70a6b8, 05bc3681 and 5e0891c1 will not be reachable after merge. Those are the hashes in the Graphics caption, manifest.json and the three new source-review-*.md files. source-review-5e0891c1.md is superseded and not linked from the guide README, so it could go. Graphics-image churn in an audio PR is also outside its one topic. If the guide check forces a refresh, say so in Why.

Testing: the owner's runs on Windows (RTX 3080) and Linux (RX Vega M) in the comments cover named and Default switching, Mono, moving the Microphone row, and persistence across a restart. What is still missing is what the PR lists itself: final validation of the rebased source (Linux suite comparison, rebuilt host and renderer), and disabling and re-enabling a virtual endpoint. The stall case below is worth adding to that endpoint test.

Overlaps

  • PR 979 adds host/options_read.h, one reader for longshot_options.ini, and rewrites au_menu_output in nn_audio.c. This PR adds another reader (audio_output_read_id). I'd merge 979 first, then read the ID through its hos_options_each with a buffer large enough for an endpoint ID. Your rule of rejecting over-long lines would need to sit on top, because 979 splits a long line into pieces.
  • PR 822 (the item wheel) also bumps MKWVK_API_VERSION and claims 24 for its MkwVkHost fields. Whichever merges second renumbers its version and appends after the other's callbacks.
  • PR 286, PR 218 and PR 980 make small edits to nn_audio.c and vk_menu.cpp. Those will be textual conflicts only.
I read the whole diff at fc3dba3a (no builds or tests run here). The design holds up: the endpoint is stored by its persistent ID rather than its place in the list, there is a locked mailbox between the menu and the audio thread, the route switch happens before the next frame is mixed, and Speaker layout keeps its `audio_output` key and values. I'm requesting changes for one bug and a few things that should land before `pr ready`. **Before ready** - **It conflicts with main.** Main moved after a0be15b3 ([PR 604](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/604), [PR 994](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/994), [PR 773](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/773), [PR 998](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/998)). A trial rebase onto 1764fed2 hits 24 textual conflicts, all in `gpu/vk/menu_i18n.h`: [PR 998](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/998) added `{"Auto", "Auto"}` next to the old `"Audio output"` entry, and the hint line you changed sits next to [PR 773](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/773)'s new shadow strings. Keeping both sides should resolve all of them. `vk_api.h` is still at 23 on main, so your bump to 24 stays valid for now. - **A named endpoint that opens but never plays leads to silence** (inline on `host/nn_audio.c`). The 6-reopen stall cap ends up stuck on the bad device. - **The device list is enumerated on the render thread every 2 s while the menu is open** (inline on `vk_menu.cpp`). - **The new row isn't translated.** Every other Audio row is in all 13 tables. "Output device" and its texts aren't, so a non-English menu shows this one row in English. - **docs/tested/ has 34 new files.** Most of them record suite runs, website builds, WSL portability checks and UTF-8 builds, not game runs. `docs/tested-configurations.md` is for measured runs on hardware, and the website lists every file there. I'd keep the four A/B files and the Windows and Linux play runs, and move the rest into this description. - **The provenance names commits that won't be on main.** PRs are squash-merged, so ca70a6b8, 05bc3681 and 5e0891c1 will not be reachable after merge. Those are the hashes in the Graphics caption, `manifest.json` and the three new `source-review-*.md` files. `source-review-5e0891c1.md` is superseded and not linked from the guide README, so it could go. Graphics-image churn in an audio PR is also outside its one topic. If the guide check forces a refresh, say so in Why. **Testing:** the owner's runs on Windows (RTX 3080) and Linux (RX Vega M) in the comments cover named and Default switching, Mono, moving the Microphone row, and persistence across a restart. What is still missing is what the PR lists itself: final validation of the rebased source (Linux suite comparison, rebuilt host and renderer), and disabling and re-enabling a virtual endpoint. The stall case below is worth adding to that endpoint test. **Overlaps** - [PR 979](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/979) adds `host/options_read.h`, one reader for `longshot_options.ini`, and rewrites `au_menu_output` in `nn_audio.c`. This PR adds another reader (`audio_output_read_id`). I'd merge 979 first, then read the ID through its `hos_options_each` with a buffer large enough for an endpoint ID. Your rule of rejecting over-long lines would need to sit on top, because 979 splits a long line into pieces. - [PR 822](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/822) (the item wheel) also bumps `MKWVK_API_VERSION` and claims 24 for its `MkwVkHost` fields. Whichever merges second renumbers its version and appends after the other's callbacks. - [PR 286](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/286), [PR 218](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/218) and [PR 980](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/980) make small edits to `nn_audio.c` and `vk_menu.cpp`. Those will be textual conflicts only.
@ -1136,0 +1149,4 @@
Explicit playback changes are applied by `output_route_update()` on the audio thread before `render_frame()` mixes its
next PCM frame. Recovery in `output_frame()` can still reopen a sink after mixing; it drops that frame only when the
reopened sink has another channel count. A same-layout recovery keeps the frame. This recovery rule and its sentinel
Owner

This paragraph and the next mostly tell the history of this PR: PR 448's pinned commit, which main commit fails which fixture, and "not evidence of real-device playback". That belongs in the PR description. After a squash merge the commits it names (aa95d35f is cited as "pinned main") stop meaning much to a reader of development.md. I'd keep the rule: explicit changes apply before mixing, and a recovery reopen drops the frame only on a channel-count change. Then name the check, tests/test_audio_output_recovery.py, and move the rest here.

This paragraph and the next mostly tell the history of this PR: PR 448's pinned commit, which main commit fails which fixture, and "not evidence of real-device playback". That belongs in the PR description. After a squash merge the commits it names (aa95d35f is cited as "pinned main") stop meaning much to a reader of development.md. I'd keep the rule: explicit changes apply before mixing, and a recovery reopen drops the frame only on a channel-count change. Then name the check, `tests/test_audio_output_recovery.py`, and move the rest here.
@ -1398,3 +1454,3 @@
"Silences the game while another window has the focus. The sound comes back when you switch to the game.", nullptr,
false, true},
{TAB_AUDIO, "Audio output", &opts.audio_output, 0, 3, 1, tx_audio_output,
{TAB_AUDIO, "Output device", &output_pick, 0, 0, 1, tx_output_device,
Owner

"Output device", its description, the hn_output_device hints, "Default", "Overridden by HOS_AUDIO_DEVICE" and "(not connected)" are missing from the menu_i18n.h tables, while every other Audio row (Mute in background, Speaker layout, Microphone) is translated in all 13. A test in the style of test_speaker_layout_texts_are_translated would keep them covered.

"Output device", its description, the `hn_output_device` hints, "Default", "Overridden by HOS_AUDIO_DEVICE" and "(not connected)" are missing from the menu_i18n.h tables, while every other Audio row (Mute in background, Speaker layout, Microphone) is translated in all 13. A test in the style of `test_speaker_layout_texts_are_translated` would keep them covered.
@ -1942,6 +2000,7 @@ bool env_holds(const int* value) {
Out player_custom_output{0, 0}; // (the player's own Output resolution size when HOS_OUTPUT_RES names another of its own)
std::string ini_path() { return options_path(); } // (the user folder's when --user names one: vk_paths.h)
const char* ini_key(const Row& r) {
if (!strcmp(r.name, "Speaker layout")) return "audio_output"; // Existing preferences keep their original key.
Owner

Nit: the other renamed rows in this function are keyed by their value under the "rows renamed since their values were first saved keep their keys" comment (r.value == &opts.resolution, ...). if (r.value == &opts.audio_output) return "audio_output"; there keeps to that pattern, and it won't break if the row's English name changes again.

Nit: the other renamed rows in this function are keyed by their value under the "rows renamed since their values were first saved keep their keys" comment (`r.value == &opts.resolution`, ...). `if (r.value == &opts.audio_output) return "audio_output";` there keeps to that pattern, and it won't break if the row's English name changes again.
@ -5656,2 +5762,4 @@
if (open_now.load()) refresh_mics(); // (the microphones as they are now)
if (open_now.load()) refresh_outputs();
}
if (open_now.load() && host && host->now_ns && host->now_ns() - output_list_checked >= 2000000000LL) refresh_outputs();
Owner

menu_tick runs on the render thread (vk_replay.cpp). So while the menu is open, every 2 s this does CoInitializeEx and CoCreateInstance, plus waveOutMessage twice and GetDevice/OpenPropertyStore for each endpoint, all on the frame path. Bluetooth or virtual endpoints can make that take many milliseconds, which is a regular hitch in the menu. Could the list be refreshed off the render thread? Options: IMMNotificationClient, or enumerating on the audio thread or a worker and publishing a snapshot. Otherwise, refresh only when the menu opens or the Audio tab is shown, as refresh_mics does.

`menu_tick` runs on the render thread (`vk_replay.cpp`). So while the menu is open, every 2 s this does `CoInitializeEx` and `CoCreateInstance`, plus `waveOutMessage` twice and `GetDevice`/`OpenPropertyStore` for each endpoint, all on the frame path. Bluetooth or virtual endpoints can make that take many milliseconds, which is a regular hitch in the menu. Could the list be refreshed off the render thread? Options: `IMMNotificationClient`, or enumerating on the audio thread or a worker and publishing a snapshot. Otherwise, refresh only when the menu opens or the Audio tab is shown, as `refresh_mics` does.
@ -0,0 +15,4 @@
memmove(out, id, strlen(id) + 1);
return 1;
}
static inline void audio_output_read_id(FILE *f, char *out, size_t capacity) {
Owner

This is another reader of longshot_options.ini, and PR 979 replaces six of them with host/options_read.h. Once 979 is on main, this could use hos_options_each with an ID-sized buffer, keeping your rule that rejects over-long lines (979 splits a long line into pieces, so that rule would sit on top). There would then be one parser, not two that can drift apart.

This is another reader of longshot_options.ini, and [PR 979](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/979) replaces six of them with `host/options_read.h`. Once 979 is on main, this could use `hos_options_each` with an ID-sized buffer, keeping your rule that rejects over-long lines (979 splits a long line into pieces, so that rule would sit on top). There would then be one parser, not two that can drift apart.
host/nn_audio.c Outdated
@ -987,0 +1050,4 @@
} else if (*out_wanted && !out_named_active && !(getenv("HOS_AUDIO_DEVICE") && *getenv("HOS_AUDIO_DEVICE")) &&
au_ms() >= out_named_retry_at) {
out_named_retry_at = au_ms() + out_named_retry_wait;
if (hos_audio_output_resolve(out_wanted) >= 0) {
Owner

There's a loop here that ends in silence. Say the named endpoint opens, then takes no sound for 1.5 s. output_reopen counts it in out_reopens and falls back to the default. 3 s later this branch reopens the named device, and that open resets out_named_retry_wait to 3000 because out_named_active is 1. It stalls again. out_reopens is reset only after 30 s of sound, and that never happens here: 3 s of default, then 1.5 s of silence, six times. On the seventh stall output_reopen returns early, and the game stays on the dead named device with every frame dropped until the player changes the row. A related case: when the endpoint resolves but waveOutOpen on it fails, every retry closes and reopens the working default stream for nothing, which is a short dropout each minute once the backoff hits its cap. Suggestion: treat a stall on the named device as a failed attempt. Keep the backoff growing and don't reset out_named_retry_wait until the named device has played for a while (say the same 30 s rule). Then reopen only once the named device has actually opened, for example by trying it first and closing the default only on success.

There's a loop here that ends in silence. Say the named endpoint opens, then takes no sound for 1.5 s. `output_reopen` counts it in `out_reopens` and falls back to the default. 3 s later this branch reopens the named device, and that open resets `out_named_retry_wait` to 3000 because `out_named_active` is 1. It stalls again. `out_reopens` is reset only after 30 s of sound, and that never happens here: 3 s of default, then 1.5 s of silence, six times. On the seventh stall `output_reopen` returns early, and the game stays on the dead named device with every frame dropped until the player changes the row. A related case: when the endpoint resolves but `waveOutOpen` on it fails, every retry closes and reopens the working default stream for nothing, which is a short dropout each minute once the backoff hits its cap. Suggestion: treat a stall on the named device as a failed attempt. Keep the backoff growing and don't reset `out_named_retry_wait` until the named device has played for a while (say the same 30 s rule). Then reopen only once the named device has actually opened, for example by trying it first and closing the default only on success.
docs(audio): record rebased suites and endpoint recovery play-test
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 3s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
aa4cf22b74
Record the final Linux main comparison, refreshed Windows build and manual
virtual-endpoint disable/re-enable check, retaining physical-hotplug limits.

Assisted-by: OpenAI Codex
Author
Member

Pushed aa4cf22b with the completed rebased Linux comparison, refreshed Windows build and manual endpoint-recovery records. Windows build and static inspection passed. Owner reports playback, virtual endpoint disable/re-enable fallback, retained selection, restored output, Mono and microphone selection all pass. Physical USB hotplug was not tested. Refreshed Linux host build is still running, so this stays WIP until its smoke check completes; existing native Linux playback/persistence evidence is retained with its actual source revision.

Pushed aa4cf22b with the completed rebased Linux comparison, refreshed Windows build and manual endpoint-recovery records. Windows build and static inspection passed. Owner reports playback, virtual endpoint disable/re-enable fallback, retained selection, restored output, Mono and microphone selection all pass. Physical USB hotplug was not tested. Refreshed Linux host build is still running, so this stays WIP until its smoke check completes; existing native Linux playback/persistence evidence is retained with its actual source revision.
Phishinabowl force-pushed feat/audio-output-selector from aa4cf22b74
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 3s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
to 96c91754b7
Some checks failed
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Failing after 3s
2026-11-16 02:54:57 +00:00
Compare
Author
Member

Pushed review fixes through 96c91754. Named-output retries now preserve working fallback audio, retain backoff across failed opens/stalls, and reset it only after 30 seconds of successfully submitted and returned blocks. Added six native regressions, including the seventh-stall silence, failed-open queued-buffer preservation, failed-write health counting and stereo-only retry. Removed periodic render-thread enumeration, translated output controls in all 13 tables, keyed Speaker layout by value, resolved the 1764fed2 translation conflicts and reduced docs/tested to seven gameplay/A-B records. Restored the upstream Graphics image/caption and retained only content-addressed source review. Validation: 26 focused Windows scripts and 27 Linux scripts pass; 31 output cases pass; whole-file syntax checks add no warnings. Full suites: Windows 596 pass/24 fail/42 skip; Linux 625 pass/20 fail/17 skip. Every failed name reproduces on main 1764fed2, with no topic-only or untested failure names. No game rebuild or live-device test of the revised recovery was performed. Keeping WIP: #979 is still open; shared-reader integration, the next main rebase and live recovery validation remain outstanding. Main advanced to 6fb13fe5 while these fixes were tested, and the description records the exact tested base rather than claiming latest-main validation.

Pushed review fixes through 96c91754. Named-output retries now preserve working fallback audio, retain backoff across failed opens/stalls, and reset it only after 30 seconds of successfully submitted and returned blocks. Added six native regressions, including the seventh-stall silence, failed-open queued-buffer preservation, failed-write health counting and stereo-only retry. Removed periodic render-thread enumeration, translated output controls in all 13 tables, keyed Speaker layout by value, resolved the 1764fed2 translation conflicts and reduced docs/tested to seven gameplay/A-B records. Restored the upstream Graphics image/caption and retained only content-addressed source review. Validation: 26 focused Windows scripts and 27 Linux scripts pass; 31 output cases pass; whole-file syntax checks add no warnings. Full suites: Windows 596 pass/24 fail/42 skip; Linux 625 pass/20 fail/17 skip. Every failed name reproduces on main 1764fed2, with no topic-only or untested failure names. No game rebuild or live-device test of the revised recovery was performed. Keeping WIP: #979 is still open; shared-reader integration, the next main rebase and live recovery validation remain outstanding. Main advanced to 6fb13fe5 while these fixes were tested, and the description records the exact tested base rather than claiming latest-main validation.
HumanBean changed title from WIP: feat(audio): select the playback output device to feat(audio): select the playback output device 2026-11-16 03:15:33 +00:00
HumanBean deleted branch feat/audio-output-selector 2026-11-16 03:16:11 +00:00
Some checks failed
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Failing after 3s
Some workflows are waiting to be reviewed.
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1001
No description provided.