opus_codec/
types.rs

1//! Common types and constants used by the Opus codec
2
3use crate::bindings::{
4    OPUS_APPLICATION_AUDIO, OPUS_APPLICATION_RESTRICTED_LOWDELAY, OPUS_APPLICATION_VOIP, OPUS_AUTO,
5    OPUS_BANDWIDTH_FULLBAND, OPUS_BANDWIDTH_MEDIUMBAND, OPUS_BANDWIDTH_NARROWBAND,
6    OPUS_BANDWIDTH_SUPERWIDEBAND, OPUS_BANDWIDTH_WIDEBAND, OPUS_BITRATE_MAX, OPUS_FRAMESIZE_2_5_MS,
7    OPUS_FRAMESIZE_5_MS, OPUS_FRAMESIZE_10_MS, OPUS_FRAMESIZE_20_MS, OPUS_FRAMESIZE_40_MS,
8    OPUS_FRAMESIZE_60_MS, OPUS_FRAMESIZE_80_MS, OPUS_FRAMESIZE_100_MS, OPUS_FRAMESIZE_120_MS,
9    OPUS_FRAMESIZE_ARG, OPUS_SIGNAL_MUSIC, OPUS_SIGNAL_VOICE,
10};
11
12/// Encoder application mode.
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
14pub enum Application {
15    /// Optimize for conversational speech.
16    #[default]
17    Voip = OPUS_APPLICATION_VOIP as isize,
18    /// Optimize for general audio/music.
19    Audio = OPUS_APPLICATION_AUDIO as isize,
20    /// Low-delay mode, reduced algorithmic delay.
21    RestrictedLowDelay = OPUS_APPLICATION_RESTRICTED_LOWDELAY as isize,
22}
23
24/// Audio channel layout.
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum Channels {
27    /// Single-channel audio.
28    Mono = 1,
29    /// Two-channel interleaved audio.
30    Stereo = 2,
31}
32
33impl Channels {
34    /// As `usize`.
35    #[must_use]
36    pub const fn as_usize(self) -> usize {
37        self as usize
38    }
39
40    /// As `i32`.
41    #[must_use]
42    pub const fn as_i32(self) -> i32 {
43        self as i32
44    }
45}
46
47/// Supported input/output sample rates.
48#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
49pub enum SampleRate {
50    /// 8 kHz.
51    Hz8000 = 8000,
52    /// 12 kHz.
53    Hz12000 = 12000,
54    /// 16 kHz.
55    Hz16000 = 16000,
56    /// 24 kHz.
57    Hz24000 = 24000,
58    /// 48 kHz.
59    #[default]
60    Hz48000 = 48000,
61}
62
63impl SampleRate {
64    /// As `i32`.
65    #[must_use]
66    pub const fn as_i32(self) -> i32 {
67        self as i32
68    }
69
70    /// Return true if the sample rate is valid for Opus.
71    #[must_use]
72    pub const fn is_valid(self) -> bool {
73        matches!(
74            self,
75            Self::Hz8000 | Self::Hz12000 | Self::Hz16000 | Self::Hz24000 | Self::Hz48000
76        )
77    }
78}
79
80/// Coded bandwidth classifications in packets.
81#[derive(Debug, Clone, Copy, PartialEq, Eq)]
82pub enum Bandwidth {
83    /// 4 kHz bandpass.
84    Narrowband = OPUS_BANDWIDTH_NARROWBAND as isize,
85    /// 6 kHz bandpass.
86    Mediumband = OPUS_BANDWIDTH_MEDIUMBAND as isize,
87    /// 8 kHz bandpass.
88    Wideband = OPUS_BANDWIDTH_WIDEBAND as isize,
89    /// 12 kHz bandpass.
90    SuperWideband = OPUS_BANDWIDTH_SUPERWIDEBAND as isize,
91    /// 20 kHz bandpass.
92    Fullband = OPUS_BANDWIDTH_FULLBAND as isize,
93}
94
95/// Convenience frame sizes in milliseconds.
96#[derive(Debug, Clone, Copy, PartialEq, Eq)]
97pub enum FrameSize {
98    /// 2.5 ms.
99    Ms2_5 = 25,
100    /// 5 ms.
101    Ms5 = 50,
102    /// 10 ms.
103    Ms10 = 100,
104    /// 20 ms.
105    Ms20 = 200,
106    /// 40 ms.
107    Ms40 = 400,
108    /// 60 ms.
109    Ms60 = 600,
110}
111
112impl FrameSize {
113    /// Number of samples for this duration at `sample_rate`.
114    #[must_use]
115    pub const fn samples(self, sample_rate: SampleRate) -> usize {
116        // FrameSize discriminants count 0.1 ms units, so divide by 10_000 to convert to seconds
117        (self as usize * (sample_rate as usize)) / 10_000
118    }
119}
120
121/// Hint the encoder about the type of content.
122#[derive(Debug, Clone, Copy, PartialEq, Eq)]
123pub enum Signal {
124    /// Automatic selection (default).
125    Auto = OPUS_AUTO as isize,
126    /// Voice-optimized mode.
127    Voice = OPUS_SIGNAL_VOICE as isize,
128    /// Music/general audio optimized mode.
129    Music = OPUS_SIGNAL_MUSIC as isize,
130}
131
132/// Expert frame duration settings for the encoder.
133#[derive(Debug, Clone, Copy, PartialEq, Eq)]
134pub enum ExpertFrameDuration {
135    /// Select frame size from the argument (default).
136    Auto = OPUS_FRAMESIZE_ARG as isize,
137    /// 2.5 ms.
138    Ms2_5 = OPUS_FRAMESIZE_2_5_MS as isize,
139    /// 5 ms.
140    Ms5 = OPUS_FRAMESIZE_5_MS as isize,
141    /// 10 ms.
142    Ms10 = OPUS_FRAMESIZE_10_MS as isize,
143    /// 20 ms.
144    Ms20 = OPUS_FRAMESIZE_20_MS as isize,
145    /// 40 ms.
146    Ms40 = OPUS_FRAMESIZE_40_MS as isize,
147    /// 60 ms.
148    Ms60 = OPUS_FRAMESIZE_60_MS as isize,
149    /// 80 ms.
150    Ms80 = OPUS_FRAMESIZE_80_MS as isize,
151    /// 100 ms.
152    Ms100 = OPUS_FRAMESIZE_100_MS as isize,
153    /// 120 ms.
154    Ms120 = OPUS_FRAMESIZE_120_MS as isize,
155}
156
157/// Encoder complexity wrapper in the range 0..=10.
158#[derive(Debug, Clone, Copy, PartialEq, Eq)]
159pub struct Complexity(u32);
160
161impl Complexity {
162    /// Create a new complexity value in range 0..=10.
163    ///
164    /// # Panics
165    /// Panics when `complexity` is greater than 10.
166    #[must_use]
167    pub const fn new(complexity: u32) -> Self {
168        assert!(complexity <= 10, "Complexity must be between 0 and 10");
169        Self(complexity)
170    }
171
172    /// Raw complexity value.
173    #[must_use]
174    pub const fn value(self) -> u32 {
175        self.0
176    }
177}
178
179impl Default for Complexity {
180    fn default() -> Self {
181        Self::new(10)
182    }
183}
184
185/// Bitrate control options.
186#[derive(Debug, Clone, Copy, PartialEq, Eq)]
187pub enum Bitrate {
188    /// Let the encoder choose.
189    Auto,
190    /// Maximum allowed.
191    Max,
192    /// Explicit bits-per-second.
193    Custom(i32),
194}
195
196impl Bitrate {
197    /// Convert to libopus `i32` value.
198    #[must_use]
199    pub const fn value(self) -> i32 {
200        match self {
201            Self::Auto => OPUS_AUTO,
202            Self::Max => OPUS_BITRATE_MAX,
203            Self::Custom(bps) => bps,
204        }
205    }
206}
207
208#[cfg(test)]
209mod tests {
210    use super::*;
211
212    #[test]
213    fn frame_size_samples_are_correct() {
214        assert_eq!(FrameSize::Ms20.samples(SampleRate::Hz48000), 960);
215        assert_eq!(FrameSize::Ms5.samples(SampleRate::Hz16000), 80);
216        assert_eq!(FrameSize::Ms2_5.samples(SampleRate::Hz8000), 20);
217    }
218}
opus_codec/types.rs

opus_codec/
types.rs
