asr-core 0.0.2

Unified streaming, offline, and cloud speech-to-text engine for Rust
Documentation
//! 多格式音频文件解码(`decode-symphonia` feature)。
//!
//! [`read_audio`] 用 symphonia 探测并解码本地音频文件;字节已在内存里
//! (网络响应、录音缓冲)时用 [`decode_audio`],语义相同。输出保持文件
//! 原生采样率的单声道 f32 [`AudioBuffer`]——与会话输入的约定一致,采样
//! 率对齐模型目标率由会话内既有的重采样器负责,解码侧不做重采样。
//!
//! 内存契约:整个解码结果驻留内存(单声道 f32,约每秒每 kHz 采样率
//! 4 KB——1 小时 44.1 kHz 约 635 MB,16 kHz 约 230 MB),解码发生在会话
//! 的 `max_duration` 等限制生效之前,超长录音的预算与分段由宿主负责;
//! 流式分块解码是后续方向的候选。
//!
//! 覆盖容器与编解码:WAV PCM(含 float 与 24/32-bit 整型)、FLAC、MP3、
//! AAC(m4a / ADTS)、Ogg Vorbis、MKV/WebM(内含已支持编解码时);AIFF
//! 等 symphonia 其余支持格式需宿主自行启用对应 feature。symphonia 没有
//! Opus 解码器,`.opus` 与 ogg-opus 不在覆盖范围内。声道折叠策略与
//! [`crate::audio::read_wav_pcm16`] 相同:逐帧取各声道平均。
//!
//! 失败哲学:解码器脚下的流变化(声道数、采样率、链式 Ogg 第二段、编解码
//! 中途重配置)一律响亮报错——定宽下混跨错位帧会无报错地损坏音频,静默的
//! 坏转写比明确的拒绝更糟。流变化的呈现形态因编解码而异,除异规格 buffer
//! 外还包括持续解码失败与持续零帧包(见解码循环内的守卫),同样报错。
//! 局部损坏(孤立坏包、截断尾部)则只损失受影响的包。

use std::fs::File;
use std::io::Cursor;
use std::path::Path;

use symphonia::core::codecs::audio::AudioDecoderOptions;
use symphonia::core::errors::Error as SymphoniaError;
use symphonia::core::formats::probe::Hint;
use symphonia::core::formats::FormatOptions;
use symphonia::core::formats::TrackType;
use symphonia::core::io::MediaSourceStream;
use symphonia::core::meta::MetadataOptions;

use crate::{AsrError, AudioBuffer, AudioSpec, ErrorKind};

const SUPPORTED: &str = "WAV/PCM incl. float, FLAC, MP3, M4A/AAC, Ogg Vorbis, MKV/WebM";

fn decode_error(message: impl Into<String>) -> AsrError {
    AsrError::new(ErrorKind::InvalidInput, "decode", message)
}

/// 读取并解码本地音频文件为单声道 f32 缓冲(`decode-symphonia`)。
///
/// 输入格式见[模块文档][self];采样率须落在引擎可接受的 8000..=192000 Hz。
/// 单个损坏数据包会被跳过而不是终止整个解码,与广播流录音头部残缺的
/// 现实相容;见模块文档的失败哲学。
pub fn read_audio(path: impl AsRef<Path>) -> Result<AudioBuffer, AsrError> {
    let file =
        File::open(path).map_err(|e| AsrError::new(ErrorKind::Io, "decode", e.to_string()))?;
    decode_stream(MediaSourceStream::new(Box::new(file), Default::default()))
}

/// 解码内存中的音频字节为单声道 f32 缓冲(`decode-symphonia`)。
///
/// [`read_audio`] 的字节入参形态:宿主手上的音频已经不在文件系统里
/// (网络响应、剪贴板、录音缓冲)时直接喂字节,省去落盘。格式同样由
/// 内容探测决定,语义与失败哲学见[模块文档][self]。
///
/// # 示例
///
/// ```rust,no_run
/// # use asr_core::audio::decode_audio;
/// # use asr_core::{AudioBuffer, utils::audio::encode_wav_pcm16};
/// # fn main() -> Result<(), asr_core::AsrError> {
/// let wav = encode_wav_pcm16(&AudioBuffer::mono(vec![0.0, 0.5, -0.5], 16000)?)?;
/// let decoded = decode_audio(&wav)?;
/// assert_eq!(decoded.spec.sample_rate, 16000);
/// assert_eq!(decoded.samples.len(), 3);
/// # Ok(())
/// # }
/// ```
pub fn decode_audio(bytes: &[u8]) -> Result<AudioBuffer, AsrError> {
    decode_stream(MediaSourceStream::new(
        Box::new(Cursor::new(bytes)),
        Default::default(),
    ))
}

fn decode_stream(mss: MediaSourceStream) -> Result<AudioBuffer, AsrError> {
    // 不传扩展名 hint:symphonia 0.6.1 的 Probe::next 收该参数但忽略
    // (源码签名 `_hint`),内容嗅探是唯一的格式信号。
    let mut format = symphonia::default::get_probe()
        .probe(
            &Hint::new(),
            mss,
            FormatOptions::default(),
            MetadataOptions::default(),
        )
        .map_err(|e| {
            decode_error(format!(
                "unsupported or corrupt audio: {e} (supported: {SUPPORTED})"
            ))
        })?;
    // DEFAULT 标记的音轨优先,回退首个已知编解码轨:多轨容器里字面上的
    // 第一轨可能是解说轨或备用配音。
    let track = format
        .default_track(TrackType::Audio)
        .ok_or_else(|| decode_error("no audio track"))?;
    let params = track
        .codec_params
        .as_ref()
        .and_then(|params| params.audio())
        .ok_or_else(|| decode_error("audio track has no codec parameters"))?;
    let sample_rate = params
        .sample_rate
        .ok_or_else(|| decode_error("audio track has no sample rate"))?;
    let channels = params
        .channels
        .as_ref()
        .map(|channels| channels.count())
        .filter(|count| *count > 0)
        .ok_or_else(|| decode_error("audio track has no channels"))?;
    let mut decoder = symphonia::default::get_codecs()
        .make_audio_decoder(params, &AudioDecoderOptions::default())
        .map_err(|e| {
            decode_error(format!(
                "unsupported audio codec: {e} (supported: {SUPPORTED}; \
                 Opus has no decoder in symphonia)"
            ))
        })?;
    let track_id = track.id;
    // 引擎侧采样率校验(8000..=192000)在 AudioSpec::mono 内完成。
    AudioSpec::mono(sample_rate)?;
    let mut samples = Vec::new();
    let mut interleaved = Vec::new();
    let mut saw_packet = false;
    // 孤立坏包跳过;但解码器对"流已变"的表达方式因编解码而异——mpa 在
    // 布局变化后对每个后续包报 DecodeError,拼接 MP3 的第二段在 gapless
    // 裁剪下每包解出 0 帧——都不是异规格 buffer,spec 守卫拦不住。连续
    // 多个无产出包说明流已重配置或接了第二段,继续走只产出静默截断的
    // "成功"结果,必须响亮报错。阈值给广播流的短暂干扰留出余量。
    const MAX_UNPRODUCTIVE_PACKETS: usize = 5;
    let mut unproductive = 0usize;
    loop {
        let packet = match format.next_packet() {
            Ok(Some(packet)) => packet,
            Ok(None) => break,
            // 容器在文件中途被截断:保留已解码前缀,按流结束处理。
            Err(SymphoniaError::IoError(e)) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
                break
            }
            // 链式 Ogg 物理流要求重新探测轨道(接在第一段后面的第二个
            // 流)。静默丢弃剩余段会把部分转写当完整结果交出,宁可报错。
            Err(SymphoniaError::ResetRequired) => {
                return Err(decode_error(
                    "audio stream reconfigures mid-file (e.g. a chained OGG); \
                     split the segments first",
                ))
            }
            Err(e) => return Err(decode_error(format!("failed to read packet: {e}"))),
        };
        if packet.track_id != track_id {
            continue;
        }
        saw_packet = true;
        let decoded = match decoder.decode(&packet) {
            Ok(decoded) => decoded,
            // 孤立坏包(损坏数据 / IO)跳过;持续失败按流已变处理。
            Err(SymphoniaError::DecodeError(_) | SymphoniaError::IoError(_)) => {
                unproductive += 1;
                if unproductive >= MAX_UNPRODUCTIVE_PACKETS {
                    return Err(decode_error(format!(
                        "audio stream broke mid-file: {MAX_UNPRODUCTIVE_PACKETS} consecutive \
                         packets failed to decode; chained or reconfigured streams must be \
                         split first"
                    )));
                }
                continue;
            }
            Err(SymphoniaError::ResetRequired) => {
                return Err(decode_error("audio codec reconfigured mid-file"))
            }
            Err(e) => return Err(decode_error(format!("audio decoding failed: {e}"))),
        };
        let spec = decoded.spec();
        if spec.rate() != sample_rate || spec.channels().count() != channels {
            return Err(decode_error(
                "audio stream changed sample rate or channels mid-file",
            ));
        }
        if decoded.frames() == 0 {
            unproductive += 1;
            if unproductive >= MAX_UNPRODUCTIVE_PACKETS {
                return Err(decode_error(format!(
                    "audio stream broke mid-file: {MAX_UNPRODUCTIVE_PACKETS} consecutive \
                     packets decoded to no audio; a concatenated second segment must be \
                     split first"
                )));
            }
            continue;
        }
        unproductive = 0;
        interleaved.clear();
        interleaved.resize(decoded.samples_interleaved(), 0.0);
        decoded.copy_to_slice_interleaved(&mut interleaved);
        samples.extend(
            interleaved
                .chunks_exact(channels)
                .map(|frame| frame.iter().sum::<f32>() / channels as f32),
        );
    }
    // 合法但空的文件(零包)返回空缓冲;有过包却一帧都没解出来说明整个
    // 输入都是损坏数据,返回空转写反而是误导。
    if samples.is_empty() && saw_packet {
        return Err(decode_error(
            "no audio could be decoded from the input (every packet failed)",
        ));
    }
    AudioBuffer::mono(samples, sample_rate)
}

#[cfg(test)]
mod tests;