Skip to main content

blip25_vocoder/
lib.rs

1//! # blip25-vocoder
2//!
3//! The P25 voice codec: four wire rates across two codecs — full rate
4//! (P25 Phase 1 FDMA, `FullRate7200x4400` on air and `FullRate4400x4400`
5//! info-only) and half rate (P25 Phase 2 TDMA, `HalfRate3600x2450` on air and
6//! `HalfRate2450x2450` info-only) — plus parametric conversion between them.
7//! Encode and decode route through a private codec core, bit-exact with the
8//! reference software vocoder, wrapped here in the P25 wire formats.
9//!
10//! ## The two layers
11//!
12//! ```text
13//!   PCM  <->  [ codec core ]  <->  payload bits  <->  [ wire layers ]  <->  wire bytes
14//!             analysis/synthesis   49 or 88           FEC, interleave,
15//!             (bit-exact)                             priority, packing
16//! ```
17//!
18//! The codec core is codec-only — it performs no error correction; the one
19//! channel-quality input it takes is the [`vocoder::FrameStatus`] the wire
20//! layers derive, which drives its concealment. Everything else between the
21//! payload bits and the air interface
22//! is the rest of the crate: framing, FEC, de-interleaving, bit prioritization,
23//! erasure marking, and parameter-domain rate conversion.
24//!
25//! The core is a private module: it is not published separately, is not a
26//! dependency, and is not part of the public API. The only thing it contributes
27//! to the public surface is the re-exported [`vocoder::FrameStatus`].
28//!
29//! The core is **patent-encumbered** and derived from the reference software
30//! vocoder by reverse engineering; the wire layers are spec-derived from
31//! TIA-102.BABA / BABA-A. See [`PATENT_NOTICE.md`] and [`ATTRIBUTION.md`]
32//! before use.
33//!
34//! ## Quick start
35//!
36//! Most consumers should use the [`vocoder::Vocoder`] façade:
37//!
38//! ```rust
39//! use blip25_vocoder::vocoder::{Rate, Vocoder};
40//!
41//! // Open a P25 Phase 1 full-rate channel.
42//! let mut tx = Vocoder::new(Rate::FullRate7200x4400);
43//! let pcm: [i16; 160] = [0; 160];
44//! let bits = tx.encode_pcm(&pcm).unwrap();
45//! assert_eq!(bits.len(), 18);
46//!
47//! let mut rx = Vocoder::new(Rate::FullRate7200x4400);
48//! let out = rx.decode_bits(&bits).unwrap();
49//! assert_eq!(out.len(), 160);
50//! ```
51//!
52//! Three conveniences around the per-frame primitive:
53//!
54//! - [`vocoder::Vocoder::encode_stream`] / [`vocoder::Vocoder::decode_stream`]
55//!   — slice → `Iterator<Item = Result<…>>`, drops trailing partial frames.
56//! - [`vocoder::LiveEncoder`] / [`vocoder::LiveDecoder`] — chunk-driven
57//!   with internal residue buffer for audio-callback / socket use.
58//! - [`vocoder::VocoderBuilder`] — fluent configuration of the optional
59//!   post-decode enhancement chain.
60//!
61//! See [`vocoder`] for the full API and [`INTEGRATION.md`] for the
62//! layer boundaries a consumer is expected to own.
63//!
64//! ## Module organization
65//!
66//! See [`DESIGN.md`] at the repository root for the architectural
67//! model. The public API is a façade over three orthogonal axes joined
68//! at a common parameter type:
69//!
70//! - [`vocoder`] — the per-channel façade. **Recommended entry point.**
71//! - [`mbe_params`] — the parameter model, the interchange type used by
72//!   the wire and rate-conversion layers.
73//! - **Wire formats**, one module per protocol-rate combination:
74//!   [`fullrate`] (P25 Phase 1, 144-bit) and [`halfrate`] (P25 Phase 2,
75//!   72-bit). Future protocols become sibling modules; DMR and NXDN already
76//!   carry the same half-rate codec frame under a different interleave and
77//!   enter through [`halfrate::frame`].
78//! - [`rate_conversion`] — parameter-domain bits-to-bits conversion,
79//!   a peer of the codec and wire layers, not a sub-concern of either.
80//!
81//! FEC primitives shared across the wire layers live in [`fec`], and the
82//! optional post-decode filter chain in [`enhancement`]. `src/generated/` is
83//! not a module: it holds the Annex tables (B–T), transcribed from the
84//! standard and `include!`d by the wire layers that index them.
85//!
86//! ## Cargo features
87//!
88//! - `encode` (on by default) — the encode public API:
89//!   [`vocoder::Vocoder::encode_pcm`], [`vocoder::LiveEncoder`], and the encode
90//!   streaming iterators.
91//! - `decode` (on by default) — the decode public API, the shared frame and
92//!   parameter types, and the wire and rate-conversion layers. It stands alone,
93//!   so `--no-default-features --features decode` builds a receive-only crate.
94//! - `serde` (off by default) — derive `Serialize` / `Deserialize` on
95//!   the diagnostic types in [`vocoder`] ([`vocoder::Rate`],
96//!   [`vocoder::FrameStats`], [`vocoder::AnalysisStats`],
97//!   [`vocoder::FrameDisposition`], [`vocoder::DecodeStats`]) plus
98//!   [`mbe_params::MbeParams`]. Useful for shipping stats / params over an
99//!   RPC layer (gRPC / protobuf / WS) without hand-rolled converters.
100//!
101//! `serde` is the only optional dependency and the only thing that pulls
102//! anything in; with it off, this crate has no runtime dependencies at all.
103//!
104//! [`DESIGN.md`]: https://github.com/openBLIP25/blip25-vocoder/blob/main/DESIGN.md
105//! [`INTEGRATION.md`]: https://github.com/openBLIP25/blip25-vocoder/blob/main/INTEGRATION.md
106//! [`PATENT_NOTICE.md`]: https://github.com/openBLIP25/blip25-vocoder/blob/main/PATENT_NOTICE.md
107//! [`ATTRIBUTION.md`]: https://github.com/openBLIP25/blip25-vocoder/blob/main/ATTRIBUTION.md
108
109#![forbid(unsafe_code)]
110#![warn(missing_docs)]
111#![warn(rust_2018_idioms)]
112// Doc comments cross-reference crate-internal (`pub(crate)`) helpers by name;
113// those links are intentional and resolve within the source. The valuable
114// `broken_intra_doc_links` lint stays on to catch genuinely dead links.
115#![allow(rustdoc::private_intra_doc_links)]
116// A decode-only build (`--no-default-features --features decode`) gates out the
117// encode public API; the encode-only helpers it leaves behind are then unused.
118// Silence that dead-code noise only in the decode-only configuration.
119#![cfg_attr(not(feature = "encode"), allow(dead_code))]
120
121// The codec core. Private: the supported entry point is [`vocoder::Vocoder`],
122// and the only thing from here that reaches the public API is the re-exported
123// `FrameStatus`. See `src/engine/mod.rs` for why it stays `no_std`-clean.
124mod engine;
125
126mod bits;
127pub mod fec;
128
129pub mod mbe_params;
130
131pub mod fullrate;
132pub mod halfrate;
133
134pub mod rate_conversion;
135
136pub mod enhancement;
137pub mod vocoder;