Skip to main content

loqui_audio/
lib.rs

1//! Audio in and out for loqui.
2//!
3//! Out: synthesized speech is encoded as WAV (16-bit PCM), FLAC, Ogg Opus
4//! or raw 16-bit PCM, the formats an OpenAI-compatible `/audio/speech` client asks
5//! for. In: uploaded audio in any common container (WAV, FLAC, MP3, Ogg
6//! Vorbis or Opus, WebM/Opus, MP4/AAC) is decoded, mixed to mono and
7//! resampled for Whisper. Everything here is pure Rust.
8
9mod decode;
10mod encode;
11#[cfg(feature = "mp3")]
12mod mp3;
13mod ogg;
14mod opus;
15
16pub use decode::{WHISPER_RATE, decode, decode_mono_16k, resample};
17pub use encode::encode;
18
19/// Mono audio: samples in `[-1, 1]` at `rate` Hz.
20#[derive(Clone, PartialEq)]
21pub struct Pcm {
22    pub samples: Vec<f32>,
23    pub rate: u32,
24}
25
26impl std::fmt::Debug for Pcm {
27    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
28        f.debug_struct("Pcm").field("samples", &self.samples.len()).field("rate", &self.rate).finish()
29    }
30}
31
32impl Pcm {
33    pub fn duration_secs(&self) -> f64 {
34        if self.rate == 0 { 0.0 } else { self.samples.len() as f64 / f64::from(self.rate) }
35    }
36}
37
38/// An output format, named as the OpenAI API names it in `response_format`.
39///
40/// Non-exhaustive because `Mp3` exists only with the `mp3` feature, and any
41/// crate in a build can turn that on.
42#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
43#[non_exhaustive]
44pub enum Format {
45    Wav,
46    Flac,
47    /// Opus in Ogg, as OpenAI serves `opus`.
48    Opus,
49    /// MP3 through LAME, with the `mp3` feature.
50    #[cfg(feature = "mp3")]
51    Mp3,
52    /// Headerless 16-bit little-endian PCM at the synthesis rate.
53    Pcm,
54}
55
56impl Format {
57    /// What a request that names no format gets: MP3, as OpenAI serves,
58    /// where this build can encode it; otherwise WAV.
59    #[cfg(feature = "mp3")]
60    pub const DEFAULT: Format = Format::Mp3;
61    #[cfg(not(feature = "mp3"))]
62    pub const DEFAULT: Format = Format::Wav;
63
64    /// Parses an OpenAI `response_format`. Formats this build cannot
65    /// produce (`aac`, and `mp3` without the feature) are errors that name
66    /// what can be.
67    pub fn parse(name: &str) -> Result<Self, Error> {
68        match name {
69            "wav" => Ok(Self::Wav),
70            "flac" => Ok(Self::Flac),
71            "opus" => Ok(Self::Opus),
72            #[cfg(feature = "mp3")]
73            "mp3" => Ok(Self::Mp3),
74            "pcm" => Ok(Self::Pcm),
75            other => Err(Error::UnsupportedFormat { name: other.to_owned(), available: Self::names() }),
76        }
77    }
78
79    pub fn content_type(self) -> &'static str {
80        match self {
81            Self::Wav => "audio/wav",
82            Self::Flac => "audio/flac",
83            Self::Opus => "audio/ogg",
84            #[cfg(feature = "mp3")]
85            Self::Mp3 => "audio/mpeg",
86            Self::Pcm => "audio/pcm",
87        }
88    }
89
90    pub const ALL: &[Format] = &[
91        Format::Wav,
92        Format::Flac,
93        Format::Opus,
94        #[cfg(feature = "mp3")]
95        Format::Mp3,
96        Format::Pcm,
97    ];
98
99    /// The OpenAI name, as `response_format` spells it.
100    pub fn name(self) -> &'static str {
101        match self {
102            Self::Wav => "wav",
103            Self::Flac => "flac",
104            Self::Opus => "opus",
105            #[cfg(feature = "mp3")]
106            Self::Mp3 => "mp3",
107            Self::Pcm => "pcm",
108        }
109    }
110
111    fn names() -> String {
112        Self::ALL.iter().map(|f| f.name()).collect::<Vec<_>>().join(", ")
113    }
114}
115
116#[derive(Debug, thiserror::Error)]
117pub enum Error {
118    #[error("unsupported output format {name:?}; this build produces {available}")]
119    UnsupportedFormat { name: String, available: String },
120    #[error("encoding failed: {0}")]
121    Encode(String),
122    #[error("could not decode audio: {0}")]
123    Decode(String),
124    #[error("audio is longer than the {max_secs} s limit")]
125    TooLong { max_secs: u64 },
126}
127
128#[cfg(test)]
129mod tests {
130    use super::*;
131
132    #[test]
133    fn formats_parse_by_openai_name() {
134        assert_eq!(Format::parse("wav").unwrap(), Format::Wav);
135        assert_eq!(Format::parse("flac").unwrap(), Format::Flac);
136        assert_eq!(Format::parse("opus").unwrap(), Format::Opus);
137        let err = Format::parse("aac").unwrap_err().to_string();
138        assert!(err.contains("aac") && err.contains("wav, flac, opus"), "{err}");
139        for format in Format::ALL {
140            assert_eq!(Format::parse(format.name()).unwrap(), *format);
141        }
142    }
143}