//! cpal 输出流:把缓冲里的交错 f32 样本按设备格式喂给声卡。 //! //! # 采样率策略(关系到音质) //! //! cpal 的 WASAPI **共享模式**输出带 `AUDCLNT_STREAMFLAGS_AUTOCONVERTPCM | //! AUDCLNT_STREAMFLAGS_SRC_DEFAULT_QUALITY`,因此**可以用源采样率直接建流**, //! 由 Windows 自己转换到设备混音格式。这样做的两个好处: //! //! 1. 不必自己引入重采样器,也就不会临时用一版质量不明的 SRC 把音质拉低; //! 2. 与现状(WebView2 内部同样把音频交给共享模式输出)**同级**,不构成退步。 //! //! 后续要做 bit-perfect(独占模式)时,只需把这里换成独占模式的 `IAudioClient` //! 初始化:源采样率直出、绕过 Windows 混音器,届时**必须**要求源采样率与设备一致, //! 否则要自己做高质量重采样。 //! //! # 线程归属 //! //! `cpal::Stream` 在 Windows 上不是 `Send`,**必须**在创建它的线程上持有与丢弃。 //! 因此本模块只提供 [`build`],由播放线程调用并把返回的流保存在自己内部。 use std::sync::atomic::Ordering; use std::sync::Arc; use cpal::traits::{DeviceTrait, HostTrait, StreamTrait}; use super::engine::Shared; /// 建立输出流并立即启动。**必须在播放线程上调用**(见模块注释的线程归属说明)。 pub fn build(shared: &Arc) -> Result { let host = cpal::default_host(); let device = host .default_output_device() .ok_or_else(|| "没有可用的默认音频输出设备".to_string())?; let supported = device .default_output_config() .map_err(|e| format!("读取默认输出配置失败: {e}"))?; let sample_format = supported.sample_format(); let out_channels = supported.channels(); let rate = shared.rate.load(Ordering::Relaxed); shared.out_channels.store(out_channels, Ordering::Relaxed); // 声道数用**设备**的(AUTOCONVERTPCM 只保证采样率可任意,声道布局仍按设备来), // 采样率用**源**的。解码出来的样本在 fill() 里做声道映射。 let config = cpal::StreamConfig { channels: out_channels, sample_rate: rate.into(), buffer_size: cpal::BufferSize::Default, }; let stream = match sample_format { cpal::SampleFormat::F32 => build_typed::(&device, config, shared.clone()), cpal::SampleFormat::I16 => build_typed::(&device, config, shared.clone()), cpal::SampleFormat::I32 => build_typed::(&device, config, shared.clone()), cpal::SampleFormat::U16 => build_typed::(&device, config, shared.clone()), other => Err(format!("不支持的输出采样格式: {other:?}")), }?; stream .play() .map_err(|e| format!("启动音频输出失败: {e}"))?; Ok(stream) } /// 按设备默认采样格式建流,回调里统一用 f32 计算、再转成设备格式输出。 fn build_typed( device: &cpal::Device, config: cpal::StreamConfig, shared: Arc, ) -> Result where T: cpal::SizedSample + cpal::FromSample, { let err_shared = shared.clone(); device .build_output_stream( config, move |data: &mut [T], _| fill(data, &shared), move |e| { // 设备被拔掉 / 被独占 / 驱动异常:只记日志并把会话标记为失败, // 由引擎把错误转成前端提示。这里**不能** panic —— 它在音频线程上。 crate::logger::log_error("music-audio", &format!("音频输出流错误: {e}")); err_shared.failed.store(true, Ordering::Relaxed); }, None, ) .map_err(|e| format!("创建音频输出流失败: {e}")) } /// 音频回调:把队列里的交错样本搬进设备缓冲。 /// /// 全程只做「出队 + 乘增益 + 转格式」,不加锁以外的任何分配/系统调用, /// 以免在实时线程上引入不可控的延迟(会直接表现为爆音)。 fn fill(data: &mut [T], shared: &Shared) where T: cpal::SizedSample + cpal::FromSample, { let out_ch = shared.out_channels.load(Ordering::Relaxed) as usize; let src_ch = shared.src_channels.load(Ordering::Relaxed) as usize; // 尚未确定声道数(刚起会话)或异常值:先输出静音,不能除零 if out_ch == 0 || src_ch == 0 { for s in data.iter_mut() { *s = T::from_sample(0.0); } return; } // 暂停:输出静音但**不消费队列**,恢复播放时数据不丢 if !shared.playing.load(Ordering::Relaxed) { for s in data.iter_mut() { *s = T::from_sample(0.0); } return; } let target = if shared.muted.load(Ordering::Relaxed) { 0.0 } else { f32::from_bits(shared.volume.load(Ordering::Relaxed)) }; let mut gain = f32::from_bits(shared.gain.load(Ordering::Relaxed)); let frames = data.len() / out_ch; // 音量在本块内线性走到目标值:拖动音量滑块/切静音时不会有台阶式的爆音。 let step = if frames > 0 { (target - gain) / frames as f32 } else { 0.0 }; let mut consumed: u64 = 0; { let mut queue = shared.buf.lock().unwrap_or_else(|e| e.into_inner()); for f in 0..frames { gain += step; let base = f * out_ch; // 一帧源数据 = src_ch 个样本;不足一帧(解码没跟上)就整帧输出静音 let mut src = [0f32; 8]; let has_frame = queue.len() >= src_ch; if has_frame { for slot in src.iter_mut().take(src_ch.min(8)) { *slot = queue.pop_front().unwrap_or(0.0); } consumed += 1; } for c in 0..out_ch { let v = if !has_frame { 0.0 } else if out_ch == 1 && src_ch > 1 { // 多声道 → 单声道:取平均,避免只留左声道 let n = src_ch.min(8); src[..n].iter().sum::() / n as f32 } else if src_ch == 1 { // 单声道 → 任意声道数:复制 src[0] } else if c < src_ch.min(8) { src[c] } else { // 源声道数少于设备声道数:多出来的声道填静音 0.0 }; data[base + c] = T::from_sample(v * gain); } } } if consumed > 0 { shared.frames_played.fetch_add(consumed, Ordering::Relaxed); } shared.gain.store(gain.to_bits(), Ordering::Relaxed); }