babycat 0.0.14

An audio decoding and manipulation library, with bindings for C, Python, and WebAssembly.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208

use serde::{Deserialize, Serialize};
use std::fmt;

#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[allow(clippy::enum_variant_names)]
pub enum Error {
    /// Raised when you are trying to use a feature at runtime that was not included at compile-time.
    ///
    /// For example, you may receive this error if you are trying to resample
    /// audio using a method that was not compiled for your target or binding.
    FeatureNotCompiled(&'static str),
    //
    // Input validation errors
    /// Raised when [`WaveformArgs.start_time_milliseconds`][crate::WaveformArgs#structfield.start_time_milliseconds] or [`WaveformArgs.end_time_milliseconds`][crate::WaveformArgs#structfield.end_time_milliseconds] is invalid.
    ///
    /// For example, this error is raised if you set the end timestamp to be before
    /// the start timestamp.
    WrongTimeOffset(usize, usize),
    /// Raised when you wanted to decode more channels than the audio actually had.
    WrongNumChannels(u16, u16),
    /// Raised if you specified [`WaveformArgs.convert_to_mono`][crate::WaveformArgs#structfield.convert_to_mono] as `true` and [`WaveformArgs.num_channels`][crate::WaveformArgs#structfield.num_channels] as 1.
    ///
    /// Setting both parameters is redundant and contradictory. You should either use
    /// [`WaveformArgs.convert_to_mono`][crate::WaveformArgs#structfield.convert_to_mono]
    /// to flatten all channels or [`WaveformArgs.num_channels`][crate::WaveformArgs#structfield.num_channels] = 1 to select the first channel and discard the rest.
    /// You can set [`WaveformArgs.num_channels`][crate::WaveformArgs#structfield.num_channels]
    /// `n > 1` and use  [`WaveformArgs.convert_to_mono`][crate::WaveformArgs#structfield.convert_to_mono] to only flatten those `n` channels.
    /// If you need to select channels in some other way, then do not provide either
    /// [`WaveformArgs.convert_to_mono`][crate::WaveformArgs#structfield.convert_to_mono]
    /// or [`WaveformArgs.num_channels`][crate::WaveformArgs#structfield.num_channels].
    /// All channels will be decoded and you can decide what to do with them.
    WrongNumChannelsAndMono,
    /// Raised if you set [`WaveformArgs.zero_pad_ending`][crate::WaveformArgs#structfield.zero_pad_ending] as `true` without also specifying [`WaveformArgs.end_time_milliseconds`][crate::WaveformArgs#structfield.end_time_milliseconds].
    CannotZeroPadWithoutSpecifiedLength,
    /// Raised if you set [`WaveformArgs.repeat_pad_ending`][crate::WaveformArgs#structfield.repeat_pad_ending] as `true` without also specifying [`WaveformArgs.end_time_milliseconds`][crate::WaveformArgs#structfield.end_time_milliseconds].
    CannotRepeatPadWithoutSpecifiedLength,
    /// Raised if you set both
    /// [`WaveformArgs.zero_pad_ending`][crate::WaveformArgs#structfield.zero_pad_ending]
    /// and
    /// [`WaveformArgs.repeat_pad_ending`][crate::WaveformArgs#structfield.repeat_pad_ending]
    /// as `true`.
    CannotSetZeroPadEndingAndRepeatPadEnding,
    //
    // Decoding errors
    /// Raised when we could not decode any of the audio streams.
    NoSuitableAudioStreams(usize),
    /// Raised when we do not recognize the decoding backend.
    UnknownDecodingBackend(u32),
    /// Raised when we were not able to detect the encoded input as decodable audio.
    UnknownInputEncoding,
    /// Raised when we were not able to decode the given (encoded) audio.
    UnknownDecodeError,
    /// Raised when we were not able to decode the given (encoded) audio.
    UnknownDecodeErrorWithMessage(&'static str),
    //
    // Encoding errors
    /// Raised when we encountered an unknown error when encoding a waveform into a particular format.
    UnknownEncodeError,
    //
    // Resampling errors
    /// Raised when we were not able to resample the audio.
    ResamplingError,
    // Also raised when we were not able to resample the audio.
    ResamplingErrorWithMessage(&'static str),
    /// Raised when we cannot resample from the input frame rate to the output frame rate.
    WrongFrameRate(u32, u32),
    /// Raised if you are trying upsample or downsample audio by a factor greater than 256.
    WrongFrameRateRatio(u32, u32),
    //
    // IO errors
    /// Raised if you asked Babycat to read a file but gave it a path to a directory.
    FilenameIsADirectory(&'static str),
    /// Raised if you asked Babycat to read a file that does not exist.
    FileNotFound(&'static str),
    /// Raised when something else went wrong while doing I/O.
    UnknownIOError,
    //
    // Source errors
    // Raised when we try to append one audio source to another, but they don't have
    // the same number of channels.
    CannotAppendSourcesWithDifferentNumChannels(u16, u16),
    // Raised when we try to append one audio source to another, but they don't have
    // the same frame rate.
    CannotAppendSourcesWithDifferentFrameRates(u32, u32),
}

impl std::error::Error for Error {}

impl Error {
    #[allow(dead_code)]
    pub fn error_type(&self) -> String {
        match *self {
            Error::FeatureNotCompiled(name) => format!("FeatureNotCompiledError({})", name),

            Error::WrongTimeOffset(t1, t2) => format!("WrongTimeOffset({},{})", t1, t2),

            Error::WrongNumChannels(c1, c2) => format!("WrongNumChannels({},{})", c1, c2),
            Error::WrongNumChannelsAndMono => "WrongNumChannelsAndMono".to_string(),

            Error::CannotZeroPadWithoutSpecifiedLength => {
                "CannotZeroPadWithoutSpecifiedLength".to_string()
            }
            Error::CannotRepeatPadWithoutSpecifiedLength => {
                "CannotRepeatPadWithoutSpecifiedLength".to_string()
            }
            Error::CannotSetZeroPadEndingAndRepeatPadEnding => {
                "CannotSetZeroPadEndingAndRepeatPadEnding".to_string()
            }

            Error::NoSuitableAudioStreams(num_streams) => {
                format!("NoSuitableAudioStreams({})", num_streams)
            }

            Error::UnknownDecodingBackend(b) => format!("UnknownDecodingBackend({})", b),

            Error::UnknownInputEncoding => "UnknownInputEncoding".to_string(),

            Error::UnknownDecodeError => "UnknownDecodeError".to_string(),

            Error::UnknownDecodeErrorWithMessage(msg) => {
                format!("UnknownDecodeErrorWithMessage: {}", msg)
            }

            Error::UnknownEncodeError => "UnknownEncodeError".to_string(),

            Error::ResamplingError => "ResamplingError".to_string(),

            Error::ResamplingErrorWithMessage(msg) => {
                format!("ResamplingErrorWithMessage({})", msg)
            }

            Error::WrongFrameRate(f1, f2) => format!("WrongFrameRate({},{})", f1, f2),

            Error::WrongFrameRateRatio(f1, f2) => format!("WrongFrameRateRatio({},{})", f1, f2),

            Error::FilenameIsADirectory(dir) => format!("FilenameIsADirectory({})", dir),

            Error::FileNotFound(filename) => format!("FileNotFound({})", filename),

            Error::UnknownIOError => "UnknownIOError".to_string(),

            Error::CannotAppendSourcesWithDifferentNumChannels(c1, c2) => format!(
                "CannotAppendSourcesWithDifferentNumChannels({}, {})",
                c1, c2
            ),

            Error::CannotAppendSourcesWithDifferentFrameRates(f1, f2) => format!(
                "CannotAppendSourcesWithDifferentNumChannels({}, {})",
                f1, f2
            ),
        }
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            Error::FeatureNotCompiled(name) => write!(f, "You are requesting a feature that was not included in the library at compile time. Feature name: {}", name),

            Error::WrongTimeOffset(t1, t2) => write!(f, "You provided invalid millisecond time offsets for trimming audio. You specified a `start_time_milliseconds` of {} ms and an `end_time_milliseconds` of {} ms. The start time needs to be a smaller number than the end time.", t1, t2),

            Error::WrongNumChannels(c1, c2) => write!(f, "Cannot change the number of audio channels. You asked to return the first {} channels, but the audio stream only has {} channels.", c1, c2),

            Error::WrongNumChannelsAndMono => write!(f, "You cannot set `convert_to_mono` as `true` and also set `num_channels` = 1. Pick one or the other. You either want `convert_to_mono` to average all channels as one channel... or you want to select the first channel with `num_channels`."),

            Error::CannotZeroPadWithoutSpecifiedLength => write!(f, "You cannot set `zero_pad_ending` without also specifying *where* the ending should be. Either set `zero_pad_ending` = `false` or specify `end_time_milliseconds` to a value above 0."),

            Error::CannotRepeatPadWithoutSpecifiedLength => write!(f, "You cannot set `repeat_pad_ending` without also specifying *where* the ending should be. Either set `repeat_pad_ending` = `false` or specify `end_time_milliseconds` to a value above 0."),

            Error::CannotSetZeroPadEndingAndRepeatPadEnding => write!(f, "You cannot set both `zero_pad_ending` and `repeat_pad_ending` as `true`. Pick one or the other."),

            Error::NoSuitableAudioStreams(num_streams) => write!(f, "We probed {} audio streams but could not decode any of them.", num_streams),

            Error::UnknownDecodingBackend(b) => write!(f, "Could not recognize the audio decoding backend `{}`.", b),

            Error::UnknownInputEncoding => write!(f, "Unknown input encoding for audio."),

            Error::UnknownDecodeError => write!(f, "Unknown decoding error."),

            Error::UnknownDecodeErrorWithMessage(msg) => write!(f, "Unknown decoding error: {}", msg),

            Error::UnknownEncodeError => write!(f, "Unknown encoding error."),

            Error::ResamplingError => write!(f, "Unknown error when resampling to a different frame rate."),

            Error::ResamplingErrorWithMessage(msg) => write!(f, "Unknown error when resampling to a different frame rate: {}", msg),

            Error::WrongFrameRate(f1, f2) => write!(f, "Cannot resample the audio to the given frame rate. You asked to resample the audio to a frame rate of {} hz when the audio's original frame rate is {} hz.", f2,f1),
            Error::WrongFrameRateRatio(f1, f2) => write!(f, "We currently only support resampling when the ratio between input and output frame rates is 256 or less (whether upsampling or downsampling). We were given input and output frame rates of {} and {}", f1, f2),

            Error::FilenameIsADirectory(dir) => write!(
                f,
                "The filename {} is a directory. Pass an individual audo file instead.",
                dir
            ),

            Error::FileNotFound(filename) => {
                write!(f, "Cannot find the given filename {}.", filename)
            }

            Error::UnknownIOError => write!(f, "Unknown I/O error."),

            Error::CannotAppendSourcesWithDifferentNumChannels(c1, c2) => write!(f, "We cannot append two sources because they have a different number of channels ({} channels and {} channels).", c1, c2),

            Error::CannotAppendSourcesWithDifferentFrameRates(f1, f2) => write!(f, "We cannot append two sources because they have a different frame rates ({} hz and {} hz).", f1, f2)
        }
    }
}