feat(audio): select the playback output device #1001
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
3 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1001
Loading…
Reference in a new issue
No description provided.
Delete branch "Phishinabowl/Longshot:feat/audio-output-selector"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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 main1764fed2. Main advanced to6fb13fe5before 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
1764fed2uses ABI 23, topic 24; the next rebase must reconcile #822 if it has landed before this PR.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.
host/audio_output_devices.c/.henumerate Windows endpoint metadata and store a requested persistent endpoint ID in a synchronized preference mailbox. Display names are labels, not identity.host/nn_audio.capplies 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.gpu/vk/vk_menu.cppadds Output device, renames Audio output to Speaker layout without changing its key or Mono value, and moves Microphone from Gameplay to Audio. Addsaudio_output_device_idandaudio_output_device_name.audio_output_count/info/select/state, after existingtake_textandoptions_path. Startup uses sharedhos_options_file(), including--userandHOS_OPTIONS_FILE.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; topicca70a6b82831f78c8147e558b1d59fd55e94b827.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.
3dec7681The table summarizes all recorded samples; representative original native lines from each run follow. Full sample lists remain retained locally.
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
96c91754or 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.
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 main1764fed2(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
05bc3681on pinned maina0be15b3: 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.3dec7681; no topic-only or untested failure names. This is not a full main-suite comparison or proof of identical causes.3dec7681has 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.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:
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
type(scope): description) of the status line's type.main. Reviewed/tested against1764fed2; main advanced to6fb13fe5. Rebase again with #979 integration before ready.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named). Review source96c91754compared on both platforms; all failed names also fail on main1764fed2.third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.docs/tested/for each new measured run (format indocs/tested-configurations.md).MKWVK_API_VERSIONbumped (gpu/vk/vk_api.h'sMkwVkHostorMkwVkRendererchanged).tests/that reads changed source updated in this PR, not weakened.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
3dec7681and topic ca70a6b8); no new capture is claimed. The repository's canonical Graphics PNG/caption now remain identical to upstream.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
05bc3681preserves the audio implementation. Refreshed rebased-source builds and virtual-endpoint disable/re-enable test are pending and the PR remains WIP.Possibly related, for context:
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.
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.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.
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 itsaudio_outputkey and values. I'm requesting changes for one bug and a few things that should land beforepr ready.Before ready
a0be15b3(PR 604, PR 994, PR 773, PR 998). A trial rebase onto1764fed2hits 24 textual conflicts, all ingpu/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.his still at 23 on main, so your bump to 24 stays valid for now.host/nn_audio.c). The 6-reopen stall cap ends up stuck on the bad device.vk_menu.cpp).docs/tested-configurations.mdis 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.05bc3681and 5e0891c1 will not be reachable after merge. Those are the hashes in the Graphics caption,manifest.jsonand the three newsource-review-*.mdfiles.source-review-5e0891c1.mdis 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
host/options_read.h, one reader forlongshot_options.ini, and rewritesau_menu_outputinnn_audio.c. This PR adds another reader (audio_output_read_id). I'd merge 979 first, then read the ID through itshos_options_eachwith 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.MKWVK_API_VERSIONand claims 24 for itsMkwVkHostfields. Whichever merges second renumbers its version and appends after the other's callbacks.nn_audio.candvk_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 itsnext PCM frame. Recovery in `output_frame()` can still reopen a sink after mixing; it drops that frame only when thereopened sink has another channel count. A same-layout recovery keeps the frame. This recovery rule and its sentinelThis 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 (
aa95d35fis 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,"Output device", its description, the
hn_output_devicehints, "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 oftest_speaker_layout_texts_are_translatedwould 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.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();menu_tickruns on the render thread (vk_replay.cpp). So while the menu is open, every 2 s this doesCoInitializeExandCoCreateInstance, pluswaveOutMessagetwice andGetDevice/OpenPropertyStorefor 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, asrefresh_micsdoes.@ -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) {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 usehos_options_eachwith 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.@ -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) {There's a loop here that ends in silence. Say the named endpoint opens, then takes no sound for 1.5 s.
output_reopencounts it inout_reopensand falls back to the default. 3 s later this branch reopens the named device, and that open resetsout_named_retry_waitto 3000 becauseout_named_activeis 1. It stalls again.out_reopensis 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 stalloutput_reopenreturns 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 butwaveOutOpenon 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 resetout_named_retry_waituntil 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.Pushed
aa4cf22bwith 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.aa4cf22b7496c91754b7Pushed 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 the1764fed2translation 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 main1764fed2, 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 to6fb13fe5while these fixes were tested, and the description records the exact tested base rather than claiming latest-main validation.WIP: feat(audio): select the playback output deviceto feat(audio): select the playback output deviceenum referenced this pull request2026-11-16 03:41:47 +00:00
TrashPanda referenced this pull request2026-11-16 03:47:24 +00:00