audio: host output device selection, enable/disable, and stereo controls

README.md

@@ -181,6 +181,23 @@ The full reference -- every key, machine profiles, Zorro boards, CD/HDD
 images, validation rules, and audio options -- is in the
 [configuration guide](docs/guide/configuration.md).
 
+## Audio output
+
+Real-time audio goes through [cpal](https://crates.io/crates/cpal), so the
+same code drives CoreAudio, WASAPI and ALSA. By default it uses the system
+default output; `--list-audio-devices` prints the alternatives and
+`--audio-device NAME` (or `[audio] output_device`) selects one by
+case-insensitive substring, falling back to the default if it disappears. The
+device is also selectable in the configuration screen and switchable live from
+the in-window menu, which additionally offers "Disabled" to turn sound off
+entirely (equivalent to `--noaudio`).
+
+Two host-side shaping options leave the emulated audio untouched:
+`--audio-channel-mode mono` averages the left/right output into both channels,
+and `--audio-stereo-separation 0-100` narrows the Amiga's hardware left/right
+panning (100 = full, 0 = mono). Both are also `[audio]` keys and configuration-
+screen fields.
+
 ## MIDI
 
 Copperline can bridge Paula's serial port to the host's MIDI system, so an

copperline.example.toml

@@ -245,6 +245,24 @@ floppy_sounds = true
 # Drive sound level, 0-100, relative to Paula's output.
 floppy_sounds_volume = 100
 
+# Host audio output device, matched by a case-insensitive substring against
+# the names `--list-audio-devices` prints (also set with `--audio-device`).
+# Commented out / omitted uses the system default output.
+# output_device = "External Headphones"
+
+# Whether live audio output is produced at all. Set false for no sound (the
+# runtime menu / launcher "Disabled" option); the CLI `--noaudio`/`--audio`
+# flags still override it. Omitted / true produces sound normally.
+# output_enabled = true
+
+# Output channel mode: "stereo" (default, the Amiga's hardware left/right
+# panning) or "mono" (both channels averaged together). Also `--audio-channel-mode`.
+# channel_mode = "stereo"
+
+# Stereo separation, 0-100. 100 (default) keeps the full hardware panning; lower
+# values narrow it and 0 collapses to mono. Also `--audio-stereo-separation`.
+# stereo_separation = 100
+
 
 # Host input preferences.
 # [input]

docs/guide/configuration.md

@@ -344,12 +344,33 @@ synchronous render path for comparison.
 [audio]
 floppy_sounds = true        # synthesized drive sounds (not sampled)
 floppy_sounds_volume = 100  # 0-100, relative to Paula's output
+# output_device = "..."     # host output device (substring); omit = system default
+# output_enabled = true     # false = no sound (GUI "Disabled"); --audio/--noaudio still win
+channel_mode = "stereo"     # "stereo" (default) or "mono"
+stereo_separation = 100     # 0-100; 100 = hardware panning, 0 = mono
 ```
 
 The drive sounds are generated from scratch: motor hum with spin-up/down,
 head-step clicks for seeks and the empty-drive poll, and faint read/write
 hiss during disk DMA.
 
+`output_device` picks the host output by a case-insensitive substring of the
+names `--list-audio-devices` prints (`--audio-device` overrides it); an omitted
+or unmatched name uses the system default. `channel_mode = "mono"` averages the
+left and right output into both channels, and `stereo_separation` narrows the
+Amiga's hardware left/right panning between full (100) and mono (0) -- so it is
+ignored when `channel_mode` is mono. `output_enabled = false` runs with no sound
+at all (the launcher and runtime-menu "Disabled" option); the `--audio` and
+`--noaudio` CLI flags still override it. These are host-output settings that do
+not change the emulated audio and are not stored in save states. The equivalent
+CLI flags are `--audio-device`, `--audio-channel-mode`, `--audio-stereo-separation`
+and `--list-audio-devices`.
+
+On Linux with PipeWire/PulseAudio, individual sinks are not ALSA devices, so
+only the `default`/`pipewire` route is offered; pick the output in the desktop
+sound settings (or route Copperline in `pavucontrol`) and it follows. macOS and
+Windows select each device directly.
+
 ## `[input]`
 
 ```toml