feat(audio): support Linux playback output selection #1205
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
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1205
Loading…
Reference in a new issue
No description provided.
Delete branch "Phishinabowl/Longshot:feat/linux-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: Windows 10 / RTX 3080, Ubuntu 26.04.1 / RTX 5090 Laptop (SDL2, PulseAudio through PipeWire) · Needs: current-main refresh, feature measurements, screenshots/guide review, Linux SDL3 and physical output hotplug coverage
Why
The output-device selector introduced in #1001 can select Windows playback endpoints, but Linux only offers the system default. Linux discovery returns an empty list, the POSIX playback shim ignores its device argument, and SDL always opens Default.
This completes named output selection on Linux using the SDL library already loaded by the game. Prior-work search for "Linux playback" found no matching pull request or issue; #1001 is the related merged selector implementation.
What changed
Linux can choose a named playback output, temporarily fall back to Default when it disappears, and return to the preferred output when it reappears. Existing pre-mix switching and channel-layout recovery remain in place.
host/hos_sdl.c,host/hos_sdl.h: enumerate SDL2/SDL3 playback devices, resolve backend-qualified names to process-local tokens, open the requested endpoint, query its channels and detect disappearance. Tokens are never persisted or reused for a different identity. Renamed devices are missing; ambiguous duplicate names are omitted rather than choosing the wrong output.host/audio_output_devices.c: supply Linux metadata and resolution through the existing locked preference mailbox and host callbacks. Discovery does not open a stream.host/posix/win32_posix.c: own the SDL playback handle, report a removed output to the existing recovery path, and stop callbacks before releasing queue/userdata/mutex state. A failed SDL3 resume destroys its stream.gpu/vk/vk_menu.cpp,gpu/vk/menu_i18n.h,README.md: replace the Windows-only Linux help text, translate the system-default explanation in all 13 menu languages, and document Linux identity/duplicate-name limits.translator_files.stamp(vk)implementation.Measurements
Verdict: the missing Linux enumeration is reproduced on main and corrected here; real Linux routing/fallback/return worked in the game. The required feature on/off FPS or frame-time comparison has not been measured, so this remains WIP. No zero-cost or performance claim is made.
Hardware: functional runtime checks used Windows 10 / RTX 3080 / NVIDIA 621.24 / Ryzen 9 5900XT / 64 GB and Ubuntu 26.04.1 / RTX 5090 Laptop / NVIDIA 595.99.02 / Core Ultra 9 275HX / 64 GB. The synthetic regression opens no hardware.
Scene: Audio overlay and actual playback during manual play-testing; no fixed scene/settings performance comparison has been run.
Method: production-source fixture return values on main versus this change, plus live audio-server link/state observations and owner-reported playback. These are functional results; no FPS/frame-time median is claimed.
How to reproduce: run the commands below, then select a named output in Audio; remove/reintroduce that endpoint while retaining the preferred selection and observe the fallback/return route.
1b2e7555fd9118d4Game-free reproduction:
python -I -B tests/test_linux_audio_output.py --cc clang; run its--metadata-only --source ../main-checkoutvariant against main checked out at1b2e7555for the failing control. No device or game is opened by this fixture. Clang/GCC fake-SDL checks passed on Linux; llvm-mingw Clang checks passed on Windows.Pending performance method: same PC, warmed save/scene/settings, at least two interleaved main/PR pairs with medians, including Default and named selection on the same real sink. Build and shader-preparation durations are not substituted for runtime measurements.
Flags and settings
No new environment switch or build flag. The existing output row and preference keys gain Linux behavior; the shipped choice remains Default.
audio_output_device_idsdl:backend:device-nameidentity, not an enumeration indexaudio_output_device_nameHOS_AUDIO_DEVICETesting
Tested:
fd9118d4, using existing native tools: Windows llvm-mingw Clang 23.1.5; Linux Clang 23.1.6. Static module/hash/architecture/protection/export/direct-provider inspection passed. Required normal-cache shader preparation completed on both with no tagged preparation issues and isolated settings.1b2e7555, again with all failures controlled on that main:639e0652plus the feature delta1b2e7555All selected audio, Mono, preference, recovery and localization checks passed. No topic-only failure was observed. These are not all-green suites; skips are not passes. Main controls reran each failing test name, not another full main suite. The tested authored delta was hash-verified on both PCs before committing it as
fd9118d4.Baseline failures common to both original full suites (all under
tests/):Windows-only baseline failures:
Linux-only baseline failures:
Updated-main affected failures are subsets of these sets: 14 Windows and 13 Linux, all reproduced on
1b2e7555. Diagnostic comparisons retain the originals: random control-session directory names and interleaved compiler warnings differ; Windows work-lock diagnostics were additionally qualified by a matching serial pair.test_bug_report.pyandtest_hardware_report.pyencountered missing shared-Tooling routing in both topic/control environments; they are failures, not inferred passes. Unrelated fixture/compiler mismatches were not repaired here.Not tested: real Linux SDL3 playback; physical USB/Bluetooth unplug/replug; Linux surround hardware, duplicate-name hardware and direct ALSA/other SDL audio drivers. Thread/callback synchronization is modeled by fixtures, not stress-tested. No controlled runtime performance comparison, before/after screenshots or canonical guide-image source review has been completed.
Must be tested:
0cab3548when this PR was prepared; the tested base remains1b2e7555. The four new merges have no file overlap with this feature. No rebase/build was silently substituted for the tested revision.Risks
What could break: stream/callback lifetime on close or failed resume, backend-specific enumeration/hotplug behavior, and routing when names change or collide. SDL2 cannot distinguish identically named devices; ambiguous names are omitted. A missing preferred output uses Default and retries without overwriting the preference. A legacy Linux debug counter may still log
(0 devices); it is not the new selector's SDL enumeration.Turning it off: choose Default to stop requesting a named route; revert the implementation commit to restore the prior Linux path. Default still uses the new stream-lifetime handling, so it is not an off-switch for every changed line.
Compatibility: saves and existing speaker-layout/Mono values are unchanged. Existing INI keys remain; Linux identities are backend-qualified names. A preference copied from another backend/platform may be unavailable and fall back to Default. No
MkwVkHost/MkwVkRendererchange or API-version bump, no shader source/translator-stamp change in this feature diff, and no new build tool/library dependency. Shader preparation during validation was required by unrelated upstream renderer changes relative to the older dev base, not by audio selection itself.Checklist
Everyone
type(scope): description) of the status line's type.main. Tested base1b2e7555; observed main0cab3548is four merges newer, with no feature-file overlap.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named). Full/affected results and baseline failures are named above; final refreshed-revision suite qualification remains pending.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). Public committed records pending; no private logs, host paths or game data will be committed.mainand passing here.tests/that reads changed source updated in this PR, not weakened.Tested in game:
fd9118d4: Audio overlay/playback tested on Windows 10, RTX 3080, NVIDIA 621.24 and Ubuntu 26.04.1 Wayland, RTX 5090 Laptop, NVIDIA 595.99.02, SDL2/PulseAudio/PipeWire. Owner passed Windows switching/Default, playback, Mono, mic and saves/settings, and Linux analog/headphone/Default playback and controls. Live Linux stream links verified separate virtual-sink selection, removal fallback with preference retained, automatic return after recreation, and final analog fallback. Temporary sinks removed; system default unchanged. A normal-close/restart restored the real named analog output. Physical USB/Bluetooth and real Linux SDL3 remain untested; controlled performance and screenshots/guide review remain pending as listed in the WIP description.WIP: feat(audio): support Linux playback output selectionto feat(audio): support Linux playback output selection