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
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
//! Encoded audio bytes in, `f32` samples out, with the sample rate and channel
//! count travelling with them and a stated and tested sample-count guarantee.
//!
//! That sentence is the crate. Codecs fill the contract in; they are not the
//! contract. The trait boundaries, the error type and the buffer types are
//! settled before any codec exists, because changing them afterwards is a
//! breaking change and changing them now is free.
//!
//! # The contract
//!
//! - **In:** encoded bytes, held whole in memory and handed to a reader, or
//! arriving in pieces via [`StreamSource`].
//! - **Out:** `f32` samples that always travel with the [`AudioSpec`] that
//! describes them, so no downstream stage ever infers or assumes a rate. That
//! is the whole reason [`AudioBuffer`] exists rather than a bare `Vec<f32>`:
//! decibri has been bitten repeatedly by rate and layout travelling
//! separately from the samples they describe, most expensively on the AEC
//! reference path, where a wrong-rate reference is accepted silently and
//! cancels nothing.
//! - **Guarantee:** the number of samples produced for a given input is stated
//! and tested, not incidental. Decoding a source of `n` frames yields exactly
//! `n * channels` samples, and there is no rate conversion here for that
//! count to be conditional on. A caller who goes on to resample gets the
//! count [`decibri_resampler`] states for that rate pair and input length,
//! which is that crate's guarantee rather than this one's. A codec that
//! cannot state its output count does not go behind [`Decoder`].
//! - **Failure:** every rejection is a [`DecodeError`] that names the specific
//! thing it rejected. "Unsupported" on its own tells a caller nothing they
//! can act on.
//!
//! # Choosing a reader
//!
//! [`decode`] takes bytes in any carried container and gives back an
//! [`AudioBuffer`], [`AudioStreamDecoder`] does the same for a stream that
//! arrives in pieces, and [`identify`] answers what an input is without
//! decoding it. All three read the same twelve leading bytes, so a caller
//! never writes a magic-byte check and there is one statement of what a WAV
//! looks like rather than one per call site.
//!
//! Twelve, not four, because `RIFF` names a container *family*: the form type
//! at offset eight is what separates a WAV from an AVI, and `FORM` from an
//! `8SVX`. A container whose form type is not one this crate reads is
//! [`DecodeError::UnsupportedContainer`] naming the form type found, never a
//! reader handed a file that was never its.
//!
//! Headerless linear PCM, headerless G.711 and bare FLAC frame streams have no
//! signature and are outside this. They stay explicit, because the alternative
//! is guessing: a FLAC frame's 14-bit sync code and 8-bit header CRC together
//! let about one position in 32,768 of random data parse as a frame header, so
//! sniffing for one in bytes of unknown provenance would misfire on input that
//! is not FLAC at all.
//!
//! # Determinism
//!
//! For every format this crate carries (PCM, G.711, WAV, AIFF and FLAC),
//! decoding is **bit-exact and cross-platform byte-identical**. The same input
//! produces the same bytes on every target: no floating-point reassociation, no
//! platform-specific fast paths, no reliance on FMA contraction.
//!
//! If MP3 is ever added, its decode is compliant within the ISO/IEC 11172-4
//! accuracy bound and is explicitly **not** claimed as byte-identical. MPEG
//! never specified bit-exact decoding, and two conforming decoders legitimately
//! differ. That exception will be stated on the MP3 decoder itself and does not
//! weaken the guarantee above for any other format.
//!
//! This is written now, while it is a true statement about an empty crate,
//! rather than retrofitted once somebody has assumed otherwise.
//!
//! **Determinism is not losslessness.** Determinism holds for everything here.
//! Losslessness, a value surviving the round trip through `f32` with its
//! bits intact, holds for every format at or below 24 significant bits, all of
//! them except `i32` and `f64`. An `f32` significand is 24 bits, so 31-bit and
//! 53-bit values land on the nearest representable `f32` instead of on
//! themselves. That is inherent to an `f32` internal representation and is the
//! right trade for a crate feeding decibri's `f32` chain, but it is stated here
//! rather than left to be discovered. The error is bounded by half an ulp at the
//! value's magnitude; nothing wraps and no sign flips.
//!
//! # Rate conversion
//!
//! There is none here, and there never will be. Rate conversion is
//! [`decibri_resampler`], the crate's only dependency, called and never
//! reimplemented. Its failures arrive as [`DecodeError::Resample`]. Additional
//! *instances* of a resampler are expected and fine; a second *implementation*
//! is a correctness hazard, because resampler choice was measured during the
//! echo-cancellation work as moving AECMOS by up to 1.03, larger than the
//! effect being measured.
//!
//! # Sample conversion
//!
//! [`SampleFormat`] carries every linear PCM format the crate reads: `u8`
//! and `i8` (WAV's 8-bit is unsigned and AIFF's is signed, and those are the
//! two specifications' rules rather than a choice here), and 16-, 24- and
//! 32-bit integer and 32- and 64-bit float in both byte orders. It converts
//! each to and from `f32`. The numerical conventions are not
//! this crate's to choose: the scale factor, the rounding and clamping rule and
//! the downmix formula were all read out of decibri so that the same input
//! decoded through either crate gives the same samples. They are recorded, with
//! the file and line each came from, on the [`sample`] module.
//!
//! There is no dither, no feature flag for one and no plan for one. It needs a
//! random source, which would either break the byte-identical claim above or
//! make a generator seed part of the public contract.
//!
//! # G.711
//!
//! [`G711Law`] carries both ITU-T companding laws, mu-law and A-law, in both
//! directions, and [`G711Decoder`] decodes a headerless stream in either. The
//! tables are derived from the recommendation's own segment geometry rather than
//! transcribed from a third-party implementation, because the crate is published
//! under Apache-2.0 and reference data with an unestablished licence is a real
//! constraint.
//!
//! G.711 is a *sample format, not a rate*. It is overwhelmingly carried at
//! 8 kHz in telephony and nothing in the recommendation says so, so the rate
//! comes from the [`AudioSpec`] the caller states and nothing here defaults to
//! 8000.
//!
//! Decoding is a code to `i16` through the table, then `i16` to `f32` through
//! [`sample`]; encoding is the reverse. There is no direct code-to-`f32` path,
//! so the crate has one scaling rule rather than two.
//!
//! # WAV
//!
//! [`WavReader`] reads a RIFF/WAVE or RF64 file held whole in memory and
//! [`WavStreamDecoder`] reads one that arrives in pieces; [`WavWriter`] writes
//! every encoding either of them reads. [`WavCodec`] is the set of encodings a
//! WAV file can carry and this crate can decode: four widths of linear PCM, two
//! of IEEE float, and both G.711 laws.
//!
//! Dispatch is on the **`(wFormatTag, wBitsPerSample)` pair**, never on the tag
//! alone. Tag 1 covers four widths, and a reader that picked one would decode
//! the others at the wrong stride and produce noise rather than an error. It is
//! never, at any point, on a file name. `WAVE_FORMAT_EXTENSIBLE` resolves
//! through its SubFormat GUID.
//!
//! Malformed input is a typed [`DecodeError`] rather than a panic, and no
//! allocation anywhere is proportional to a size the file declared: a `data`
//! chunk announcing four gigabytes inside a two-kilobyte file is rejected
//! before a byte is reserved for it. All chunk arithmetic is 64-bit and
//! checked, which is what makes that true on a 32-bit target as well.
//!
//! # AIFF and AIFF-C
//!
//! [`AiffReader`] reads an AIFF or AIFF-C file held whole in memory,
//! [`AiffStreamDecoder`] reads one that arrives in pieces, and [`AiffWriter`]
//! writes every encoding either of them reads: plain `AIFF` where big-endian
//! PCM makes that form legal, `AIFC` with its `FVER` chunk and compression
//! field where the encoding requires it. [`AiffCodec`] is the set of encodings
//! this crate carries in the container: linear PCM at four widths (big-endian
//! under `NONE`/`twos`, little-endian under `sowt`, and **signed** at 8 bits
//! where WAV is unsigned), unsigned 8-bit under AIFF-C's `raw `, IEEE float
//! under `fl32`/`fl64`, and both G.711 laws under `alaw`/`ulaw`. Every other
//! compression type is [`DecodeError::UnsupportedCodec`].
//!
//! Dispatch is on the **form type and the compression four-CC** (paired with
//! `sampleSize` for the linear widths), never on a file name. The 80-bit
//! extended-precision sample rate is parsed by hand, and `COMM`'s
//! `numSampleFrames` is required to agree exactly with the `SSND` chunk's
//! length. Disagreement is a typed error, never a silent preference for
//! either source.
//!
//! # FLAC
//!
//! `FlacReader` reads a FLAC stream held whole in memory and
//! `FlacStreamDecoder` reads one that arrives in pieces; `FlacStreamInfo` is
//! what the streaminfo metadata block declared. Both readers are always
//! built: this crate has no Cargo features, so a FLAC stream decodes in every
//! build of it.
//!
//! Decoding is written from RFC 9639 and covers the whole format this crate
//! claims: every bit depth from 4 to 32, every channel count from 1 to 8, the
//! three stereo decorrelations, constant, verbatim, fixed and linear
//! predictor subframes, both Rice parameter widths and the escaped
//! partitions, fixed and variable block size streams, and the uncommon block
//! sizes and sample rates that live outside the streamable subset.
//!
//! **The integrity check is a runtime feature, not a test.** Every FLAC file
//! carries an MD5 of its own unencoded audio, so unlike every other format
//! here the decoder can check its own output on *every file it ever sees*. It
//! does: a whole-file decode hashes as it goes, a streaming decode hashes
//! incrementally, and both verify at the end. A mismatch is a typed error
//! rather than audio. An all-zero checksum means "not known", which the
//! format permits and which is not a failure. The frame header CRC-8 and the
//! whole-frame CRC-16 are verified as well, before any sample from that frame
//! is delivered.
//!
//! **Properties may not change mid-stream.** A FLAC frame header restates the
//! sample rate, channel count and bit depth, and the format allows them to
//! differ between frames. This crate rejects that with a typed error, because
//! [`AudioBuffer`] carries one [`AudioSpec`] for the samples it holds and
//! there is no honest way to describe a buffer whose rate changed half way
//! through.
//!
//! [`FlacWriter`] writes native FLAC streams at compression levels 0
//! through 8, computing residuals through the same integer prediction
//! functions the decoder reconstructs with, so the two cannot disagree about
//! the arithmetic. The Ogg and Matroska mappings are not here.
//!
//! ## Bare frames, out-of-band streaminfo, and recovery
//!
//! A FLAC frame is self-describing, so a run of frames with no `fLaC`
//! signature and no metadata in front of it is still decodable.
//! `FlacFrameReader` reads one held whole in memory and
//! `FlacStreamDecoder::frames` reads one that arrives in pieces, the third
//! headerless decoder in the crate, beside [`PcmDecoder`] and
//! [`G711Decoder`]. The two frame header codes that mean "take this field
//! from streaminfo", sample rate `0b0000` and bit depth `0b000`, have nothing
//! to be taken from on that path and are a typed error naming which field was
//! unresolved, never a default.
//!
//! Both readers accept a streaminfo block from **out of band**, which is what
//! Ogg and Matroska do: the block travels in the container's codec-private
//! header and the packets carry bare frames. The block's 34-byte body parses
//! through `FlacStreamInfo::from_block`, and supplying the result resolves
//! those two codes and restores the MD5 check to a path that otherwise has
//! none.
//! Whether that check actually ran is reported, as `Md5Check`, because a
//! caller cannot tell from the samples and a decode that quietly verified
//! nothing is how a guarantee gets claimed that was never provided.
//!
//! `FlacRecovery` finds frame boundaries in a byte run that may begin
//! mid-frame, hold garbage or be damaged. It is a separate type rather than a
//! flag, because everywhere else here a damaged frame is an error rather than
//! quietly shortened audio: recovery has to be asked for, and every decode
//! through it reports the byte ranges that produced nothing and the sample
//! positions lost. A sync point is accepted only when the frame at it passes
//! its CRC-16 *and* another frame header parses where that frame ends. The
//! 14-bit sync code and 8-bit header CRC together let about one position in
//! 32,768 of random data look like a frame, so a single validating header is
//! not evidence.
//!
//! **Recovery is whole-buffer only.** `FlacRecovery` takes a slice, and there
//! is no streaming form of it: a live stream that meets corruption part-way
//! through is a typed error from `FlacStreamDecoder`, not a resync. Accepting
//! a sync point requires the bytes *after* the candidate frame, so a
//! streaming resync would have to buffer forward without a bound or accept
//! weaker evidence than the standard above. Recovering a damaged live stream
//! means collecting its bytes and handing them to `FlacRecovery`.
//!
//! # Layout
//!
//! - [`decode`], [`AudioStreamDecoder`] and [`identify`] are the front door:
//! the reader comes from the content, not from the caller.
//! - [`Decoder`] is the boundary: frames in, samples out. It is object safe, so
//! platform decoders (AudioToolbox, MediaCodec) can sit behind it alongside
//! the crate's own.
//! - [`PcmDecoder`] is the implementation of it for headerless PCM, and
//! [`G711Decoder`] for headerless G.711.
//! - [`StreamSource`] is how bytes arrive when they arrive in pieces.
//! - [`WavReader`], [`WavStreamDecoder`] and [`WavWriter`] are the RIFF/WAVE
//! and RF64 container.
//! - [`AiffReader`], [`AiffStreamDecoder`] and [`AiffWriter`] are the AIFF
//! and AIFF-C container.
//! - `FlacReader`, `FlacStreamDecoder` and [`FlacWriter`] are FLAC;
//! `FlacFrameReader` is a bare frame stream and `FlacRecovery` is a
//! damaged one.
//! - [`AudioSpec`] and [`AudioBuffer`] keep rate and layout attached to
//! samples.
//! - [`SampleFormat`] and the functions beside it convert samples;
//! [`downmix_to_mono`], [`interleave`] and [`deinterleave`] rearrange them.
//! - [`G711Law`] is the mu-law and A-law table, in both directions.
//! - [`CodecId`] and [`FourCc`] let [`DecodeError`] name what it saw, and
//! [`Container`] is what [`identify`] answers with.
//!
//! # Status
//!
//! Linear PCM, G.711, the RIFF/WAVE and RF64 container, the AIFF and AIFF-C
//! container, and FLAC. [`PcmDecoder`] decodes headerless streams in any
//! [`SampleFormat`] and [`G711Decoder`] decodes headerless mu-law and A-law;
//! [`WavReader`] and [`WavStreamDecoder`] read WAV whole or in pieces and
//! [`WavWriter`] writes it; [`AiffReader`], [`AiffStreamDecoder`] and
//! [`AiffWriter`] do the same three things for AIFF; `FlacReader` and
//! `FlacStreamDecoder` read FLAC whole or in pieces, [`FlacWriter`] writes
//! it at compression levels 0 through 8, `FlacFrameReader` reads a bare
//! frame stream and `FlacRecovery` recovers what a damaged byte run holds.
//! The Ogg and Matroska mappings of FLAC are not here; the codec they would
//! build on is. [`decode`] and [`AudioStreamDecoder`] pick between the three
//! containers by content. [`WavStreamDecoder`], [`AiffStreamDecoder`],
//! `FlacStreamDecoder` and [`AudioStreamDecoder`] are the [`StreamSource`]s.
pub use ;
pub use ;
pub use ;
pub use Decoder;
pub use DecodeError;
pub use ;
pub use ;
pub use PcmDecoder;
pub use ;
pub use ;
pub use StreamSource;
pub use ;
/// The resampler this crate defers all rate conversion to.
///
/// Re-exported so a consumer can name [`ResamplerError`](decibri_resampler::ResamplerError)
/// when matching [`DecodeError::Resample`] without taking its own dependency,
/// and, more to the point, without taking a *different version* of it.
pub use decibri_resampler;
/// The README's Rust blocks, compiled and run as doctests so the examples on
/// the crate's front page cannot rot.
///
/// `cfg(doctest)` is set only while rustdoc collects doctests, so this item
/// exists to `cargo test` and to nothing else: it is not part of the public
/// API, does not appear in the built documentation, and the crate-level
/// documentation above stays the curated text rather than the README.
///
;