blip25_mbe/lib.rs
1//! # blip25-mbe
2//!
3//! A clean-room implementation of the MBE vocoder family.
4//!
5//! ## Quick start
6//!
7//! Most consumers should use the chip-shaped [`vocoder::Vocoder`]
8//! façade:
9//!
10//! ```rust
11//! use blip25_mbe::vocoder::{Rate, Vocoder};
12//!
13//! // Open a P25 Phase 1 (full-rate IMBE) channel.
14//! let mut tx = Vocoder::new(Rate::Imbe7200x4400);
15//! let pcm: [i16; 160] = [0; 160];
16//! let bits = tx.encode_pcm(&pcm).unwrap();
17//! assert_eq!(bits.len(), 18);
18//!
19//! let mut rx = Vocoder::new(Rate::Imbe7200x4400);
20//! let out = rx.decode_bits(&bits).unwrap();
21//! assert_eq!(out.len(), 160);
22//! ```
23//!
24//! Three streaming variants on top of the per-frame primitive:
25//!
26//! - [`vocoder::Vocoder::encode_stream`] / [`vocoder::Vocoder::decode_stream`]
27//! — slice → `Iterator<Item = Result<…>>`, drops trailing partial frames.
28//! - [`vocoder::LiveEncoder`] / [`vocoder::LiveDecoder`] — chunk-driven
29//! with internal residue buffer for audio-callback / socket use.
30//! - [`vocoder::VocoderBuilder`] — fluent configuration of optional
31//! knobs (tone detection, beyond-spec repeat reset).
32//!
33//! See [`vocoder`] for the full API and `INTEGRATION.md` for the
34//! AMBE-3000R protocol → Vocoder operation correspondence.
35//!
36//! ## Module organization
37//!
38//! See [`DESIGN.md`](https://github.com/) at the repository root for
39//! the architectural model. The public API is organized around four
40//! orthogonal axes joined at a common parameter type:
41//!
42//! - [`vocoder`] — chip-shaped façade. **Recommended entry point.**
43//! - [`mbe_params`] — the parameter model. The interchange type and
44//! the center of gravity of the crate.
45//! - [`codecs`] — analysis and synthesis algorithms, one submodule
46//! per codec generation (`mbe_baseline`, `ambe`, `ambe_plus`,
47//! `ambe_plus2`).
48//! - **Wire formats**, one module per protocol-rate combination:
49//! [`imbe_wire`] (P25 Phase 1 IMBE, 144-bit), [`ambe_plus2_wire`]
50//! (P25 Phase 2 AMBE+2, 72-bit), and [`dvsi_3000`] (DVSI chip
51//! protocol, r0..r63). Future protocols (DMR, D-STAR, NXDN, …)
52//! become sibling modules.
53//! - [`rate_conversion`] — parameter-domain bits-to-bits conversion,
54//! a peer of the codec and wire layers, not a sub-concern of either.
55//!
56//! Primitives shared across layers live in [`fec`] and [`bits`].
57//!
58//! ## Cargo features
59//!
60//! - `serde` (off by default) — derive `Serialize` / `Deserialize` on
61//! the diagnostic types in [`vocoder`] (`Rate`, `FrameStats`,
62//! `AnalysisStats`, `AnalysisOutputKind`, `DecodeStats`) plus
63//! [`mbe_params::MbeParams`] and
64//! [`codecs::mbe_baseline::FrameDisposition`]. Useful for shipping
65//! stats / params over a future RPC layer (gRPC / protobuf / WS)
66//! without hand-rolled converters.
67
68#![forbid(unsafe_code)]
69#![warn(missing_docs)]
70#![warn(rust_2018_idioms)]
71
72pub mod bits;
73pub mod fec;
74
75pub mod mbe_params;
76
77pub mod codecs;
78
79pub mod imbe_wire;
80pub mod ambe_plus2_wire;
81pub mod dvsi_3000;
82
83pub mod rate_conversion;
84
85pub mod enhancement;
86pub mod vocoder;