Add realtime audio device config (#12849)

## Summary
- add top-level realtime audio config for microphone and speaker
selection
- apply configured devices when starting realtime capture and playback
- keep missing-device behavior on the system default fallback path

## Validation
- just write-config-schema
- cargo test -p codex-core realtime_audio
- cargo test -p codex-tui
- just fix -p codex-core
- just fix -p codex-tui
- just fmt

---------

Co-authored-by: Codex <noreply@openai.com>

codex-rs/tui/src/audio_device.rs

@@ -0,0 +1,122 @@
+use codex_core::config::Config;
+use cpal::traits::DeviceTrait;
+use cpal::traits::HostTrait;
+use tracing::warn;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum AudioDeviceKind {
+    Input,
+    Output,
+}
+
+impl AudioDeviceKind {
+    fn noun(self) -> &'static str {
+        match self {
+            Self::Input => "input",
+            Self::Output => "output",
+        }
+    }
+
+    fn configured_name(self, config: &Config) -> Option<&str> {
+        match self {
+            Self::Input => config.realtime_audio.microphone.as_deref(),
+            Self::Output => config.realtime_audio.speaker.as_deref(),
+        }
+    }
+}
+
+pub(crate) fn select_configured_input_device_and_config(
+    config: &Config,
+) -> Result<(cpal::Device, cpal::SupportedStreamConfig), String> {
+    select_device_and_config(AudioDeviceKind::Input, config)
+}
+
+pub(crate) fn select_configured_output_device_and_config(
+    config: &Config,
+) -> Result<(cpal::Device, cpal::SupportedStreamConfig), String> {
+    select_device_and_config(AudioDeviceKind::Output, config)
+}
+
+fn select_device_and_config(
+    kind: AudioDeviceKind,
+    config: &Config,
+) -> Result<(cpal::Device, cpal::SupportedStreamConfig), String> {
+    let host = cpal::default_host();
+    let configured_name = kind.configured_name(config);
+    let selected = configured_name
+        .and_then(|name| find_device_by_name(&host, kind, name))
+        .or_else(|| {
+            let default_device = default_device(&host, kind);
+            if let Some(name) = configured_name
+                && default_device.is_some()
+            {
+                warn!(
+                    "configured {} audio device `{name}` was unavailable; falling back to system default",
+                    kind.noun()
+                );
+            }
+            default_device
+        })
+        .ok_or_else(|| missing_device_error(kind, configured_name))?;
+
+    let stream_config = default_config(&selected, kind)?;
+    Ok((selected, stream_config))
+}
+
+fn find_device_by_name(
+    host: &cpal::Host,
+    kind: AudioDeviceKind,
+    name: &str,
+) -> Option<cpal::Device> {
+    let devices = devices(host, kind).ok()?;
+    devices
+        .into_iter()
+        .find(|device| device.name().ok().as_deref() == Some(name))
+}
+
+fn devices(host: &cpal::Host, kind: AudioDeviceKind) -> Result<Vec<cpal::Device>, String> {
+    match kind {
+        AudioDeviceKind::Input => host
+            .input_devices()
+            .map(|devices| devices.collect())
+            .map_err(|err| format!("failed to enumerate input audio devices: {err}")),
+        AudioDeviceKind::Output => host
+            .output_devices()
+            .map(|devices| devices.collect())
+            .map_err(|err| format!("failed to enumerate output audio devices: {err}")),
+    }
+}
+
+fn default_device(host: &cpal::Host, kind: AudioDeviceKind) -> Option<cpal::Device> {
+    match kind {
+        AudioDeviceKind::Input => host.default_input_device(),
+        AudioDeviceKind::Output => host.default_output_device(),
+    }
+}
+
+fn default_config(
+    device: &cpal::Device,
+    kind: AudioDeviceKind,
+) -> Result<cpal::SupportedStreamConfig, String> {
+    match kind {
+        AudioDeviceKind::Input => device
+            .default_input_config()
+            .map_err(|err| format!("failed to get default input config: {err}")),
+        AudioDeviceKind::Output => device
+            .default_output_config()
+            .map_err(|err| format!("failed to get default output config: {err}")),
+    }
+}
+
+fn missing_device_error(kind: AudioDeviceKind, configured_name: Option<&str>) -> String {
+    match (kind, configured_name) {
+        (AudioDeviceKind::Input, Some(name)) => format!(
+            "configured input audio device `{name}` was unavailable and no default input audio device was found"
+        ),
+        (AudioDeviceKind::Output, Some(name)) => format!(
+            "configured output audio device `{name}` was unavailable and no default output audio device was found"
+        ),
+        (AudioDeviceKind::Input, None) => "no input audio device available".to_string(),
+        (AudioDeviceKind::Output, None) => "no output audio device available".to_string(),
+    }
+}

codex-rs/tui/src/chatwidget/realtime.rs

@@ -207,7 +207,7 @@ impl ChatWidget {
         {
             if self.realtime_conversation.audio_player.is_none() {
                 self.realtime_conversation.audio_player =
-                    crate::voice::RealtimeAudioPlayer::start().ok();
+                    crate::voice::RealtimeAudioPlayer::start(&self.config).ok();
             }
             if let Some(player) = &self.realtime_conversation.audio_player
                 && let Err(err) = player.enqueue_frame(frame)
@@ -231,7 +231,10 @@ impl ChatWidget {
         self.realtime_conversation.meter_placeholder_id = Some(placeholder_id.clone());
         self.request_redraw();
 
-        let capture = match crate::voice::VoiceCapture::start_realtime(self.app_event_tx.clone()) {
+        let capture = match crate::voice::VoiceCapture::start_realtime(
+            &self.config,
+            self.app_event_tx.clone(),
+        ) {
             Ok(capture) => capture,
             Err(err) => {
                 self.remove_transcription_placeholder(&placeholder_id);
@@ -250,7 +253,7 @@ impl ChatWidget {
         self.realtime_conversation.capture = Some(capture);
         if self.realtime_conversation.audio_player.is_none() {
             self.realtime_conversation.audio_player =
-                crate::voice::RealtimeAudioPlayer::start().ok();
+                crate::voice::RealtimeAudioPlayer::start(&self.config).ok();
         }
 
         std::thread::spawn(move || {

codex-rs/tui/src/lib.rs

@@ -63,6 +63,8 @@ mod app_backtrack;
 mod app_event;
 mod app_event_sender;
 mod ascii_animation;
+#[cfg(all(not(target_os = "linux"), feature = "voice-input"))]
+mod audio_device;
 mod bottom_pane;
 mod chatwidget;
 mod cli;
@@ -123,6 +125,7 @@ mod voice;
 mod voice {
     use crate::app_event::AppEvent;
     use crate::app_event_sender::AppEventSender;
+    use codex_core::config::Config;
     use codex_protocol::protocol::RealtimeAudioFrame;
     use std::sync::Arc;
     use std::sync::Mutex;
@@ -146,7 +149,7 @@ mod voice {
             Err("voice input is unavailable in this build".to_string())
         }
 
-        pub fn start_realtime(_tx: AppEventSender) -> Result<Self, String> {
+        pub fn start_realtime(_config: &Config, _tx: AppEventSender) -> Result<Self, String> {
             Err("voice input is unavailable in this build".to_string())
         }
 
@@ -186,7 +189,7 @@ mod voice {
     }
 
     impl RealtimeAudioPlayer {
-        pub(crate) fn start() -> Result<Self, String> {
+        pub(crate) fn start(_config: &Config) -> Result<Self, String> {
             Err("voice output is unavailable in this build".to_string())
         }
 

codex-rs/tui/src/voice.rs

@@ -51,7 +51,7 @@ pub struct VoiceCapture {
 
 impl VoiceCapture {
     pub fn start() -> Result<Self, String> {
-        let (device, config) = select_input_device_and_config()?;
+        let (device, config) = select_default_input_device_and_config()?;
 
         let sample_rate = config.sample_rate().0;
         let channels = config.channels();
@@ -74,8 +74,8 @@ impl VoiceCapture {
         })
     }
 
-    pub fn start_realtime(tx: AppEventSender) -> Result<Self, String> {
-        let (device, config) = select_input_device_and_config()?;
+    pub fn start_realtime(config: &Config, tx: AppEventSender) -> Result<Self, String> {
+        let (device, config) = select_realtime_input_device_and_config(config)?;
 
         let sample_rate = config.sample_rate().0;
         let channels = config.channels();
@@ -262,7 +262,8 @@ pub fn transcribe_async(
 // Voice input helpers
 // -------------------------
 
-fn select_input_device_and_config() -> Result<(cpal::Device, cpal::SupportedStreamConfig), String> {
+fn select_default_input_device_and_config()
+-> Result<(cpal::Device, cpal::SupportedStreamConfig), String> {
     let host = cpal::default_host();
     let device = host
         .default_input_device()
@@ -273,6 +274,12 @@ fn select_input_device_and_config() -> Result<(cpal::Device, cpal::SupportedStre
     Ok((device, config))
 }
 
+fn select_realtime_input_device_and_config(
+    config: &Config,
+) -> Result<(cpal::Device, cpal::SupportedStreamConfig), String> {
+    crate::audio_device::select_configured_input_device_and_config(config)
+}
+
 fn build_input_stream(
     device: &cpal::Device,
     config: &cpal::SupportedStreamConfig,
@@ -466,14 +473,9 @@ pub(crate) struct RealtimeAudioPlayer {
 }
 
 impl RealtimeAudioPlayer {
-    pub(crate) fn start() -> Result<Self, String> {
-        let host = cpal::default_host();
-        let device = host
-            .default_output_device()
-            .ok_or_else(|| "no output audio device available".to_string())?;
-        let config = device
-            .default_output_config()
-            .map_err(|e| format!("failed to get default output config: {e}"))?;
+    pub(crate) fn start(config: &Config) -> Result<Self, String> {
+        let (device, config) =
+            crate::audio_device::select_configured_output_device_and_config(config)?;
         let output_sample_rate = config.sample_rate().0;
         let output_channels = config.channels();
         let queue = Arc::new(Mutex::new(VecDeque::new()));