+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program. If not, see .
+
+Also add information on how to contact you by electronic and paper mail.
+
+ If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source. For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code. There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+ You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3843acd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,226 @@
+
+
+# rsLXST
+
+**Rust LXST telephony and media streaming for Reticulum.**
+
+[](LICENSE)
+[](https://www.rust-lang.org)
+[](https://github.com/markqvist/LXST)
+[](#feature-status)
+
+[rsLXMF](https://github.com/ratspeak/rsLXMF) |
+[Ratspeak](https://github.com/ratspeak/Ratspeak) |
+[rsReticulum](https://github.com/ratspeak/rsReticulum) |
+[Reticulum Manual](https://reticulum.network/manual/)
+
+
+
+---
+
+rsLXST is a Rust implementation of [LXST](https://github.com/markqvist/LXST), the Lightweight Extensible Signal
+Transport used for real-time voice calls and other media streams over Reticulum. This is not a
+fork of LXST; it is LXST written in a different language with interoperability
+as the primary focus. Python LXST remains the source-of-truth
+implementation, do not treat this repository as one.
+
+The current rsLXST is experimental and incomplete. It provides LXST wire codecs,
+Reticulum link media packet boundaries, a telephony runtime, and Opus stream
+integration for applications (such as Ratspeak).
+
+The first public target is interoperable Opus
+telephony, not complete feature parity with
+the reference implementation LXST.
+
+## Contents
+
+- [Release Scope](#release-scope)
+- [Build It](#build-it)
+- [Test It](#test-it)
+- [Crate Layout](#crate-layout)
+- [Using Telephony](#using-telephony)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Release Scope
+
+The experimental release is to cover basic voice calls, with several features still unsupported:
+
+- `rnphone` parity and `rnphone-rs` usage.
+- Full Codec2 support.
+- Deeper audio support: microphone/source backends, filters, AGC, etc.
+- Broadcast, stream, and non-telephony LXST primitives.
+
+Those are expected future work. They should not be implied by the first public
+Opus telephony release.
+
+## Build It
+
+The current development layout requires `rsReticulum` as a sibling checkout
+because rsLXST uses the Rust Reticulum crates directly:
+
+```text
+ratspeak-src/
+|-- rsReticulum/
+`-- rsLXST/
+```
+
+If you're starting fresh:
+
+```bash
+mkdir ratspeak-src
+cd ratspeak-src
+git clone https://github.com/ratspeak/rsReticulum
+git clone https://github.com/ratspeak/rsLXST
+cd rsLXST
+```
+
+### macOS
+
+Install Rust with `rustup`, then install Apple's command-line build tools:
+
+```bash
+xcode-select --install
+```
+
+Build the workspace:
+
+```bash
+cd rsLXST
+cargo build --release
+```
+
+### Linux / Raspberry Pi
+
+Install Rust with `rustup`, then install the usual build packages.
+
+Debian, Ubuntu, and Raspberry Pi OS:
+
+```bash
+sudo apt update
+sudo apt install -y build-essential pkg-config
+```
+
+Fedora:
+
+```bash
+sudo dnf install gcc make pkgconf-pkg-config
+```
+
+Arch:
+
+```bash
+sudo pacman -S --needed base-devel pkgconf
+```
+
+Build the workspace:
+
+```bash
+cd rsLXST
+cargo build --release
+```
+
+### Windows
+
+Install Rust with the MSVC toolchain. If Rust or Cargo asks for Visual Studio
+Build Tools, install the "Desktop development with C++" workload.
+
+Build from PowerShell:
+
+```powershell
+cd rsLXST
+cargo build --release
+```
+
+## Test It
+
+Run the Rust-only test gate:
+
+```bash
+SKIP_PYTHON_LXST_INTEROP=1 cargo test --workspace
+```
+
+Run the local CI gate:
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --workspace -- -D warnings
+SKIP_PYTHON_LXST_INTEROP=1 cargo test --workspace
+```
+
+The Rust-only gate covers wire codecs, telephony state, profile metadata,
+Opus stream boundaries, malformed-input handling, and the local service
+runtime.
+
+Python LXST interop tests against the pinned upstream reference live in the development tree and are not
+included in this published release but I am happy to provide them on request.
+
+## Crate Layout
+
+| Crate | Purpose |
+| --- | --- |
+| `lxst-core` | LXST constants, telephony profiles, signalling values, codec IDs, MessagePack packets, Raw audio frames, Opus encode/decode state, stream packetization, synthetic sources, and jitter buffers. This crate has no Reticulum runtime dependency. |
+| `lxst-rns` | The Reticulum link-packet boundary for no-receipt LXST signalling and media over active links. It packs outbound LXST packets and decodes inbound link plaintext into typed LXST packet/frame events. |
+| `lxst-telephony` | The telephony runtime and service layer. It owns call state, caller policy, Reticulum destination registration, announce discovery, outgoing link establishment, typed control/event channels, Opus transmit/receive stream boundaries, timeout handling, and shutdown teardown. |
+
+## Using Telephony
+
+Applications normally use `lxst-telephony` through `TelephonyService`, not by
+manually translating Reticulum events. The service registers the local
+`lxst.telephony` destination, emits startup/periodic announces, owns the call
+runtime, and exposes typed control and event channels.
+
+```rust
+use lxst_core::Profile;
+use lxst_telephony::{TelephonyControl, TelephonyService};
+use tokio::time::Duration;
+
+let parts = TelephonyService::registered(transport_tx, &identity)?;
+let control_tx = parts.control_tx.clone();
+let mut event_rx = parts.event_rx;
+
+tokio::spawn(parts.service.run());
+
+control_tx
+ .send(TelephonyControl::Call {
+ remote_identity,
+ profile: Some(Profile::QualityMedium),
+ discovery_timeout: Duration::from_secs(8),
+ })
+ .await?;
+```
+
+The service event stream is the app-facing state source. Use
+`TelephonyServiceEvent::Snapshot`, `IncomingCall`, `OutgoingCallStarted`,
+`CallTerminated`, stream lifecycle events, and media events instead of
+inferring call state from raw Reticulum traffic.
+
+For Opus calls, applications supply and receive `RawAudioFrame` values through
+`StartOpusStream` and `StartOpusReceiveStream`. rsLXST enforces the negotiated
+LXST profile and reports profile changes, source/sink closure, frame drops, and
+call-end stream shutdown explicitly.
+
+Applications still own platform integration:
+
+- contact or peer lookup
+- UI and call controls
+- microphone/camera/speaker permissions
+- device selection
+- audio session lifecycle
+- capture/playback and resampling into `RawAudioFrame`
+- settings persistence
+- mobile foreground/background behavior
+
+Ratspeak uses this boundary for its native voice-call feature.
+
+## Contributing
+
+If the issue or contribution belongs upstream as well, start there. Python LXST
+and Reticulum remain the reference implementations.
+
+PRs are closed for now until I have time to catch up on everything.
+
+## License
+
+Licensed under the GNU Affero General
+Public License v3.0 or later. See [LICENSE](LICENSE).
diff --git a/crates/lxst-core/Cargo.toml b/crates/lxst-core/Cargo.toml
new file mode 100644
index 0000000..3853dbe
--- /dev/null
+++ b/crates/lxst-core/Cargo.toml
@@ -0,0 +1,17 @@
+[package]
+name = "lxst-core"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+half.workspace = true
+opus-rs.workspace = true
+rmpv.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+hex.workspace = true
+proptest.workspace = true
+serde_json.workspace = true
diff --git a/crates/lxst-core/src/lib.rs b/crates/lxst-core/src/lib.rs
new file mode 100644
index 0000000..f548d06
--- /dev/null
+++ b/crates/lxst-core/src/lib.rs
@@ -0,0 +1,31 @@
+//! Core LXST wire types.
+//!
+//! This crate owns the byte-level contract with Python LXST. It deliberately
+//! avoids audio and Reticulum runtime dependencies so packet/profile parity can
+//! be tested in isolation.
+
+mod opus;
+mod profile;
+mod raw;
+mod stream;
+mod synthetic;
+mod telephony;
+mod wire;
+
+pub use opus::{OpusCodecError, OpusDecoderState, OpusEncoderState};
+pub use profile::{AudioCodec, OpusApplication, OpusProfile, Profile, SignallingStatus};
+pub use raw::RawAudioFrame;
+pub use stream::{
+ DropPolicy, FramePacketizer, FrameStreamEvent, FrameStreamState, JitterBuffer, JitterPush,
+ JitterStats, StreamError,
+};
+pub use synthetic::{RawFrameCollector, SyntheticError, SyntheticSource, SyntheticSourceKind};
+pub use telephony::{CallRole, TelephonyAction, TelephonyCall};
+pub use wire::{
+ Codec2Mode, CodecKind, Error, FIELD_FRAMES, FIELD_SIGNALLING, Frame, LxstPacket, RawBitDepth,
+ RawFrameHeader, Signal,
+};
+
+pub const APP_NAME: &str = "lxst";
+pub const TELEPHONY_PRIMITIVE_NAME: &str = "telephony";
+pub const TELEPHONY_DESTINATION_NAME: &str = "lxst.telephony";
diff --git a/crates/lxst-core/src/opus.rs b/crates/lxst-core/src/opus.rs
new file mode 100644
index 0000000..263c693
--- /dev/null
+++ b/crates/lxst-core/src/opus.rs
@@ -0,0 +1,649 @@
+use opus_rs::{Application, OpusDecoder, OpusEncoder};
+use thiserror::Error;
+
+use crate::{AudioCodec, CodecKind, Frame, OpusApplication, OpusProfile, Profile, RawAudioFrame};
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum OpusCodecError {
+ #[error("profile {0:?} does not use Opus")]
+ NonOpusProfile(Profile),
+ #[error("Opus frame channel count {actual} does not match profile channel count {expected}")]
+ ChannelMismatch { expected: u8, actual: u8 },
+ #[error("Opus frame sample count {actual} does not match profile sample count {expected}")]
+ SampleFrameMismatch { expected: usize, actual: usize },
+ #[error(
+ "Opus frame duration is not supported by the current encoder: {sample_rate_hz} Hz / {sample_frames} samples"
+ )]
+ UnsupportedFrameDuration {
+ sample_rate_hz: u32,
+ sample_frames: usize,
+ },
+ #[error("invalid Opus frame codec {0:?}")]
+ InvalidFrameCodec(CodecKind),
+ #[error("Opus subframe payload length {0} exceeds the supported packet length encoding")]
+ UnsupportedSubframePayloadLength(usize),
+ #[error("Opus encoder returned an unsupported subpacket layout")]
+ UnsupportedSubpacketLayout,
+ #[error("malformed Opus packet: {0}")]
+ MalformedPacket(&'static str),
+ #[error("Opus codec error: {0}")]
+ Codec(String),
+ #[error("LXST wire error: {0}")]
+ Wire(#[from] crate::Error),
+}
+
+pub struct OpusEncoderState {
+ profile: Profile,
+ channels: u8,
+ sample_frames: usize,
+ subframe_count: usize,
+ subframe_sample_frames: usize,
+ encode_sample_frames: usize,
+ encode_subframe_sample_frames: usize,
+ max_payload_bytes: usize,
+ encoder: OpusEncoder,
+}
+
+impl OpusEncoderState {
+ pub fn new(profile: Profile) -> Result {
+ let opus_profile = match profile.audio_codec() {
+ AudioCodec::Opus(profile) => profile,
+ AudioCodec::Codec2(_) => return Err(OpusCodecError::NonOpusProfile(profile)),
+ };
+ let channels = opus_profile.channels();
+ let sample_rate = opus_profile.sample_rate();
+ let encode_sample_rate = encode_sample_rate(opus_profile);
+ let sample_frames = profile.sample_frames_per_packet();
+ let encode_sample_frames =
+ scale_sample_frames(sample_frames, sample_rate, encode_sample_rate)?;
+ let packet_layout = PacketLayout::new(encode_sample_rate, encode_sample_frames)?;
+ let subframe_sample_frames = sample_frames
+ .checked_div(packet_layout.subframe_count)
+ .filter(|frames| frames * packet_layout.subframe_count == sample_frames)
+ .ok_or(OpusCodecError::UnsupportedFrameDuration {
+ sample_rate_hz: sample_rate,
+ sample_frames,
+ })?;
+ let mut encoder = OpusEncoder::new(
+ encode_sample_rate as i32,
+ usize::from(channels),
+ opus_application(opus_profile.application()),
+ )
+ .map_err(|err| OpusCodecError::Codec(err.to_string()))?;
+ encoder.bitrate_bps = opus_profile.bitrate_ceiling() as i32;
+ encoder.use_cbr = false;
+
+ Ok(Self {
+ profile,
+ channels,
+ sample_frames,
+ subframe_count: packet_layout.subframe_count,
+ subframe_sample_frames,
+ encode_sample_frames,
+ encode_subframe_sample_frames: packet_layout.subframe_sample_frames,
+ max_payload_bytes: opus_profile.max_bytes_per_frame_ms(profile.frame_time_ms()),
+ encoder,
+ })
+ }
+
+ pub const fn profile(&self) -> Profile {
+ self.profile
+ }
+
+ pub const fn channels(&self) -> u8 {
+ self.channels
+ }
+
+ pub const fn sample_frames(&self) -> usize {
+ self.sample_frames
+ }
+
+ pub const fn subframe_count(&self) -> usize {
+ self.subframe_count
+ }
+
+ pub const fn subframe_sample_frames(&self) -> usize {
+ self.subframe_sample_frames
+ }
+
+ pub const fn max_payload_bytes(&self) -> usize {
+ self.max_payload_bytes
+ }
+
+ pub fn encode_frame(&mut self, frame: &RawAudioFrame) -> Result {
+ self.validate_frame_shape(frame)?;
+ if self.subframe_count > 1 {
+ return self.encode_multi_subframe_packet(frame);
+ }
+
+ let resampled;
+ let input = if self.encode_sample_frames == self.sample_frames {
+ &frame.samples
+ } else {
+ resampled = resample_interleaved_linear(
+ &frame.samples,
+ self.sample_frames,
+ self.encode_sample_frames,
+ usize::from(self.channels),
+ );
+ &resampled
+ };
+ let mut encoded = vec![0u8; self.max_payload_bytes];
+ let written = self
+ .encoder
+ .encode(input, self.encode_sample_frames, &mut encoded)
+ .map_err(|err| OpusCodecError::Codec(err.to_string()))?;
+ encoded.truncate(written);
+ Ok(Frame::new(CodecKind::Opus, encoded))
+ }
+
+ fn encode_multi_subframe_packet(
+ &mut self,
+ frame: &RawAudioFrame,
+ ) -> Result {
+ let channels = usize::from(self.channels);
+ let budgets = self.subframe_payload_budgets()?;
+ let mut subpackets = Vec::with_capacity(self.subframe_count);
+
+ for (subframe_index, payload_budget) in budgets.into_iter().enumerate() {
+ let start = subframe_index * self.subframe_sample_frames * channels;
+ let end = start + self.subframe_sample_frames * channels;
+ let resampled;
+ let input = if self.encode_subframe_sample_frames == self.subframe_sample_frames {
+ &frame.samples[start..end]
+ } else {
+ resampled = resample_interleaved_linear(
+ &frame.samples[start..end],
+ self.subframe_sample_frames,
+ self.encode_subframe_sample_frames,
+ channels,
+ );
+ &resampled
+ };
+ let mut encoded = vec![0u8; payload_budget + 1];
+ let written = self
+ .encoder
+ .encode(input, self.encode_subframe_sample_frames, &mut encoded)
+ .map_err(|err| OpusCodecError::Codec(err.to_string()))?;
+ encoded.truncate(written);
+ if encoded.first().is_none_or(|toc| toc & 0x03 != 0) {
+ return Err(OpusCodecError::UnsupportedSubpacketLayout);
+ }
+ subpackets.push(encoded);
+ }
+
+ let toc = (subpackets[0][0] & !0x03) | 0x03;
+ let mut payload = Vec::with_capacity(self.max_payload_bytes);
+ payload.push(toc);
+ payload.push(0x80 | (self.subframe_count as u8));
+ for subpacket in subpackets.iter().take(self.subframe_count - 1) {
+ push_subframe_payload_len(&mut payload, subpacket.len() - 1)?;
+ }
+ for subpacket in subpackets {
+ payload.extend_from_slice(&subpacket[1..]);
+ }
+
+ debug_assert!(payload.len() <= self.max_payload_bytes);
+ Ok(Frame::new(CodecKind::Opus, payload))
+ }
+
+ fn subframe_payload_budgets(&self) -> Result, OpusCodecError> {
+ let header_bytes = 2 + self.subframe_count - 1;
+ let payload_budget = self
+ .max_payload_bytes
+ .checked_sub(header_bytes)
+ .ok_or(OpusCodecError::UnsupportedSubpacketLayout)?;
+ let base = payload_budget / self.subframe_count;
+ let extra = payload_budget % self.subframe_count;
+ Ok((0..self.subframe_count)
+ .map(|index| base + usize::from(index < extra))
+ .collect())
+ }
+
+ fn validate_frame_shape(&self, frame: &RawAudioFrame) -> Result<(), OpusCodecError> {
+ if frame.channels != self.channels {
+ return Err(OpusCodecError::ChannelMismatch {
+ expected: self.channels,
+ actual: frame.channels,
+ });
+ }
+ if frame.sample_frames() != self.sample_frames {
+ return Err(OpusCodecError::SampleFrameMismatch {
+ expected: self.sample_frames,
+ actual: frame.sample_frames(),
+ });
+ }
+ Ok(())
+ }
+}
+
+pub struct OpusDecoderState {
+ profile: Profile,
+ channels: u8,
+ sample_frames: usize,
+ subframe_count: usize,
+ subframe_sample_frames: usize,
+ decoder: OpusDecoder,
+}
+
+impl OpusDecoderState {
+ pub fn new(profile: Profile) -> Result {
+ let opus_profile = match profile.audio_codec() {
+ AudioCodec::Opus(profile) => profile,
+ AudioCodec::Codec2(_) => return Err(OpusCodecError::NonOpusProfile(profile)),
+ };
+ let channels = opus_profile.channels();
+ let sample_rate = opus_profile.sample_rate();
+ let sample_frames = profile.sample_frames_per_packet();
+ let packet_layout = PacketLayout::new(sample_rate, sample_frames)?;
+ let decoder = OpusDecoder::new(sample_rate as i32, usize::from(channels))
+ .map_err(|err| OpusCodecError::Codec(err.to_string()))?;
+
+ Ok(Self {
+ profile,
+ channels,
+ sample_frames,
+ subframe_count: packet_layout.subframe_count,
+ subframe_sample_frames: packet_layout.subframe_sample_frames,
+ decoder,
+ })
+ }
+
+ pub const fn profile(&self) -> Profile {
+ self.profile
+ }
+
+ pub const fn subframe_count(&self) -> usize {
+ self.subframe_count
+ }
+
+ pub const fn subframe_sample_frames(&self) -> usize {
+ self.subframe_sample_frames
+ }
+
+ pub fn decode_frame(&mut self, frame: &Frame) -> Result {
+ if frame.codec != CodecKind::Opus {
+ return Err(OpusCodecError::InvalidFrameCodec(frame.codec));
+ }
+ if self.subframe_count > 1 && frame.payload.first().is_some_and(|toc| toc & 0x03 == 0x03) {
+ return self.decode_multi_subframe_packet(frame);
+ }
+
+ self.decode_direct_packet(frame)
+ }
+
+ fn decode_direct_packet(&mut self, frame: &Frame) -> Result {
+ let mut samples = vec![0.0f32; self.sample_frames * usize::from(self.channels)];
+ let decoded = self
+ .decoder
+ .decode(&frame.payload, self.sample_frames, &mut samples)
+ .map_err(|err| OpusCodecError::Codec(err.to_string()))?;
+ samples.truncate(decoded * usize::from(self.channels));
+ Ok(RawAudioFrame::new(self.channels, samples)?)
+ }
+
+ fn decode_multi_subframe_packet(
+ &mut self,
+ frame: &Frame,
+ ) -> Result {
+ let subpayloads = parse_code3_subframe_payloads(&frame.payload, self.subframe_count)?;
+ let channels = usize::from(self.channels);
+ let mut samples = vec![0.0f32; self.sample_frames * channels];
+ let toc = frame.payload[0] & !0x03;
+
+ for (index, subpayload) in subpayloads.iter().enumerate() {
+ let start = index * self.subframe_sample_frames * channels;
+ let end = start + self.subframe_sample_frames * channels;
+ let mut subpacket = Vec::with_capacity(subpayload.len() + 1);
+ subpacket.push(toc);
+ subpacket.extend_from_slice(subpayload);
+ self.decoder
+ .decode(
+ &subpacket,
+ self.subframe_sample_frames,
+ &mut samples[start..end],
+ )
+ .map_err(|err| OpusCodecError::Codec(err.to_string()))?;
+ }
+
+ Ok(RawAudioFrame::new(self.channels, samples)?)
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct PacketLayout {
+ subframe_count: usize,
+ subframe_sample_frames: usize,
+}
+
+impl PacketLayout {
+ fn new(sample_rate_hz: u32, sample_frames: usize) -> Result {
+ if supports_direct_frame(sample_rate_hz, sample_frames) {
+ return Ok(Self {
+ subframe_count: 1,
+ subframe_sample_frames: sample_frames,
+ });
+ }
+
+ let subframe_sample_frames = (sample_rate_hz as usize) / 50;
+ if sample_frames != 0
+ && subframe_sample_frames != 0
+ && sample_frames % subframe_sample_frames == 0
+ && supports_direct_frame(sample_rate_hz, subframe_sample_frames)
+ {
+ return Ok(Self {
+ subframe_count: sample_frames / subframe_sample_frames,
+ subframe_sample_frames,
+ });
+ }
+
+ Err(OpusCodecError::UnsupportedFrameDuration {
+ sample_rate_hz,
+ sample_frames,
+ })
+ }
+}
+
+fn opus_application(application: OpusApplication) -> Application {
+ match application {
+ OpusApplication::Voip => Application::Voip,
+ OpusApplication::Audio => Application::Audio,
+ }
+}
+
+fn encode_sample_rate(profile: OpusProfile) -> u32 {
+ match profile {
+ // Python LXST uses libopus with an output byte ceiling but no fixed
+ // bitrate or bandwidth CTLs. At Medium's 8 kbps ceiling, libopus is
+ // free to pick lower voice bandwidth; opus-rs otherwise forces
+ // superwideband/hybrid from the 24 kHz API rate, which is poor for
+ // speech at this budget.
+ OpusProfile::VoiceMedium => 16_000,
+ _ => profile.sample_rate(),
+ }
+}
+
+fn scale_sample_frames(
+ sample_frames: usize,
+ source_sample_rate: u32,
+ encode_sample_rate: u32,
+) -> Result {
+ let numerator = sample_frames
+ .checked_mul(encode_sample_rate as usize)
+ .ok_or(OpusCodecError::UnsupportedFrameDuration {
+ sample_rate_hz: encode_sample_rate,
+ sample_frames,
+ })?;
+ let denominator = source_sample_rate as usize;
+ if numerator % denominator != 0 {
+ return Err(OpusCodecError::UnsupportedFrameDuration {
+ sample_rate_hz: encode_sample_rate,
+ sample_frames,
+ });
+ }
+ Ok(numerator / denominator)
+}
+
+fn supports_direct_frame(sample_rate_hz: u32, sample_frames: usize) -> bool {
+ sample_frames != 0 && (sample_rate_hz as usize) % sample_frames == 0
+}
+
+fn resample_interleaved_linear(
+ input: &[f32],
+ input_frames: usize,
+ output_frames: usize,
+ channels: usize,
+) -> Vec {
+ if input_frames == output_frames {
+ return input.to_vec();
+ }
+ let mut output = vec![0.0f32; output_frames * channels];
+ if input_frames == 0 || output_frames == 0 || channels == 0 {
+ return output;
+ }
+ if input_frames == 1 {
+ for frame in 0..output_frames {
+ let out = frame * channels;
+ output[out..out + channels].copy_from_slice(&input[..channels]);
+ }
+ return output;
+ }
+
+ let scale = input_frames as f64 / output_frames as f64;
+ let max_input_index = input_frames - 1;
+ for out_frame in 0..output_frames {
+ let src = ((out_frame as f64 + 0.5) * scale - 0.5).clamp(0.0, max_input_index as f64);
+ let left = src.floor() as usize;
+ let right = (left + 1).min(max_input_index);
+ let fraction = (src - left as f64) as f32;
+ let out = out_frame * channels;
+ let left_offset = left * channels;
+ let right_offset = right * channels;
+ for channel in 0..channels {
+ let a = input[left_offset + channel];
+ let b = input[right_offset + channel];
+ output[out + channel] = a + (b - a) * fraction;
+ }
+ }
+ output
+}
+
+fn push_subframe_payload_len(output: &mut Vec, len: usize) -> Result<(), OpusCodecError> {
+ if len < 252 {
+ output.push(len as u8);
+ Ok(())
+ } else if len <= 1275 {
+ let first = 252 + (len % 4);
+ output.push(first as u8);
+ output.push(((len - first) / 4) as u8);
+ Ok(())
+ } else {
+ Err(OpusCodecError::UnsupportedSubframePayloadLength(len))
+ }
+}
+
+fn parse_code3_subframe_payloads(
+ packet: &[u8],
+ expected_count: usize,
+) -> Result, OpusCodecError> {
+ if packet.len() < 2 {
+ return Err(OpusCodecError::MalformedPacket(
+ "code 3 packet is too short",
+ ));
+ }
+
+ let count_byte = packet[1];
+ let frame_count = usize::from(count_byte & 0x3F);
+ if frame_count != expected_count {
+ return Err(OpusCodecError::MalformedPacket(
+ "code 3 frame count does not match the active profile",
+ ));
+ }
+ if frame_count == 0 {
+ return Err(OpusCodecError::MalformedPacket(
+ "code 3 frame count is zero",
+ ));
+ }
+
+ let vbr = count_byte & 0x80 != 0;
+ let padding = count_byte & 0x40 != 0;
+ let mut cursor = 2;
+ let mut payload_end = packet.len();
+
+ if padding {
+ let mut pad_len = 0usize;
+ loop {
+ if cursor >= packet.len() {
+ return Err(OpusCodecError::MalformedPacket("padding exceeds packet"));
+ }
+ let byte = usize::from(packet[cursor]);
+ cursor += 1;
+ if byte == 255 {
+ pad_len += 254;
+ } else {
+ pad_len += byte;
+ break;
+ }
+ }
+ payload_end = packet
+ .len()
+ .checked_sub(pad_len)
+ .ok_or(OpusCodecError::MalformedPacket("padding exceeds packet"))?;
+ if cursor > payload_end {
+ return Err(OpusCodecError::MalformedPacket("padding exceeds payload"));
+ }
+ }
+
+ if vbr {
+ let mut lengths = Vec::with_capacity(frame_count);
+ for _ in 0..frame_count - 1 {
+ let (len, consumed) = read_subframe_payload_len(&packet[cursor..payload_end])?;
+ cursor += consumed;
+ lengths.push(len);
+ }
+
+ let declared_payload_bytes = lengths.iter().sum::();
+ let remaining = payload_end
+ .checked_sub(cursor)
+ .ok_or(OpusCodecError::MalformedPacket(
+ "payload cursor exceeds packet",
+ ))?;
+ if declared_payload_bytes > remaining {
+ return Err(OpusCodecError::MalformedPacket(
+ "declared frame lengths exceed packet payload",
+ ));
+ }
+ lengths.push(remaining - declared_payload_bytes);
+
+ let mut payloads = Vec::with_capacity(frame_count);
+ let mut payload_cursor = cursor;
+ for len in lengths {
+ let next = payload_cursor + len;
+ payloads.push(&packet[payload_cursor..next]);
+ payload_cursor = next;
+ }
+ Ok(payloads)
+ } else {
+ let compressed = &packet[cursor..payload_end];
+ if compressed.len() % frame_count != 0 {
+ return Err(OpusCodecError::MalformedPacket(
+ "CBR code 3 payload is not evenly divisible",
+ ));
+ }
+ let frame_len = compressed.len() / frame_count;
+ Ok(compressed.chunks(frame_len).collect())
+ }
+}
+
+fn read_subframe_payload_len(input: &[u8]) -> Result<(usize, usize), OpusCodecError> {
+ let first = *input
+ .first()
+ .ok_or(OpusCodecError::MalformedPacket("missing frame length"))?;
+ if first < 252 {
+ Ok((usize::from(first), 1))
+ } else {
+ let second = *input
+ .get(1)
+ .ok_or(OpusCodecError::MalformedPacket("truncated frame length"))?;
+ Ok((usize::from(first) + 4 * usize::from(second), 2))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::SyntheticSourceKind;
+
+ fn source_for(profile: Profile) -> crate::SyntheticSource {
+ crate::SyntheticSource::new(
+ profile.channels(),
+ profile.sample_rate_hz(),
+ profile.sample_frames_per_packet(),
+ SyntheticSourceKind::Sine {
+ frequency_hz: 440.0,
+ amplitude: 0.25,
+ },
+ )
+ .unwrap()
+ }
+
+ #[test]
+ fn opus_encoder_rejects_codec2_profiles() {
+ assert!(matches!(
+ OpusEncoderState::new(Profile::BandwidthLow),
+ Err(OpusCodecError::NonOpusProfile(Profile::BandwidthLow))
+ ));
+ }
+
+ #[test]
+ fn opus_profile_encoder_caps_payload_to_python_budget() {
+ let profile = Profile::LatencyLow;
+ let mut encoder = OpusEncoderState::new(profile).unwrap();
+ let frame = source_for(profile).next_raw_frame().unwrap();
+
+ let encoded = encoder.encode_frame(&frame).unwrap();
+ assert_eq!(encoded.codec, CodecKind::Opus);
+ assert!(encoded.payload.len() <= profile.opus_payload_ceiling_bytes().unwrap());
+ }
+
+ #[test]
+ fn opus_roundtrip_decodes_profile_shaped_pcm() {
+ let profile = Profile::LatencyLow;
+ let mut source = source_for(profile);
+ let frame = source.next_raw_frame().unwrap();
+ let mut encoder = OpusEncoderState::new(profile).unwrap();
+ let mut decoder = OpusDecoderState::new(profile).unwrap();
+
+ let encoded = encoder.encode_frame(&frame).unwrap();
+ let decoded = decoder.decode_frame(&encoded).unwrap();
+
+ assert_eq!(decoded.channels, profile.channels());
+ assert_eq!(decoded.sample_frames(), profile.sample_frames_per_packet());
+ assert_eq!(decoder.profile(), profile);
+ }
+
+ #[test]
+ fn opus_quality_profiles_encode_sixty_ms_as_three_subframes() {
+ for profile in [
+ Profile::QualityMedium,
+ Profile::QualityHigh,
+ Profile::QualityMax,
+ ] {
+ let mut source = source_for(profile);
+ let frame = source.next_raw_frame().unwrap();
+ let mut encoder = OpusEncoderState::new(profile).unwrap();
+ let mut decoder = OpusDecoderState::new(profile).unwrap();
+
+ assert_eq!(encoder.subframe_count(), 3);
+ assert_eq!(decoder.subframe_count(), 3);
+ assert_eq!(
+ encoder.subframe_sample_frames() * 3,
+ encoder.sample_frames()
+ );
+
+ let encoded = encoder.encode_frame(&frame).unwrap();
+ assert_eq!(encoded.codec, CodecKind::Opus);
+ assert_eq!(encoded.payload[0] & 0x03, 0x03);
+ assert_eq!(encoded.payload[1] & 0x3F, 3);
+ assert_ne!(encoded.payload[1] & 0x80, 0);
+ assert!(encoded.payload.len() <= profile.opus_payload_ceiling_bytes().unwrap());
+
+ let decoded = decoder.decode_frame(&encoded).unwrap();
+ assert_eq!(decoded.channels, profile.channels());
+ assert_eq!(decoded.sample_frames(), profile.sample_frames_per_packet());
+ }
+ }
+
+ #[test]
+ fn opus_medium_uses_wideband_silk_at_low_bitrate() {
+ let profile = Profile::QualityMedium;
+ let mut source = source_for(profile);
+ let frame = source.next_raw_frame().unwrap();
+ let mut encoder = OpusEncoderState::new(profile).unwrap();
+
+ let encoded = encoder.encode_frame(&frame).unwrap();
+
+ assert_eq!(encoded.payload[0] & !0x03, 0x48);
+ assert!(encoded.payload.len() <= profile.opus_payload_ceiling_bytes().unwrap());
+ }
+}
diff --git a/crates/lxst-core/src/profile.rs b/crates/lxst-core/src/profile.rs
new file mode 100644
index 0000000..2d48dde
--- /dev/null
+++ b/crates/lxst-core/src/profile.rs
@@ -0,0 +1,356 @@
+use crate::wire::{Codec2Mode, CodecKind};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u32)]
+pub enum SignallingStatus {
+ Busy = 0x00,
+ Rejected = 0x01,
+ Calling = 0x02,
+ Available = 0x03,
+ Ringing = 0x04,
+ Connecting = 0x05,
+ Established = 0x06,
+}
+
+impl SignallingStatus {
+ pub const AUTO_STATUS_CODES: [Self; 5] = [
+ Self::Calling,
+ Self::Available,
+ Self::Ringing,
+ Self::Connecting,
+ Self::Established,
+ ];
+
+ pub const fn wire_value(self) -> u32 {
+ self as u32
+ }
+
+ pub const fn from_wire(value: u32) -> Option {
+ match value {
+ 0x00 => Some(Self::Busy),
+ 0x01 => Some(Self::Rejected),
+ 0x02 => Some(Self::Calling),
+ 0x03 => Some(Self::Available),
+ 0x04 => Some(Self::Ringing),
+ 0x05 => Some(Self::Connecting),
+ 0x06 => Some(Self::Established),
+ _ => None,
+ }
+ }
+
+ pub fn is_auto_status(self) -> bool {
+ Self::AUTO_STATUS_CODES.contains(&self)
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u32)]
+pub enum Profile {
+ BandwidthUltraLow = 0x10,
+ BandwidthVeryLow = 0x20,
+ BandwidthLow = 0x30,
+ QualityMedium = 0x40,
+ QualityHigh = 0x50,
+ QualityMax = 0x60,
+ LatencyUltraLow = 0x70,
+ LatencyLow = 0x80,
+}
+
+impl Profile {
+ pub const DEFAULT: Self = Self::QualityMedium;
+
+ pub const ORDER: [Self; 8] = [
+ Self::BandwidthUltraLow,
+ Self::BandwidthVeryLow,
+ Self::BandwidthLow,
+ Self::QualityMedium,
+ Self::QualityHigh,
+ Self::QualityMax,
+ Self::LatencyLow,
+ Self::LatencyUltraLow,
+ ];
+
+ pub const fn wire_value(self) -> u32 {
+ self as u32
+ }
+
+ pub const fn from_wire(value: u32) -> Option {
+ match value {
+ 0x10 => Some(Self::BandwidthUltraLow),
+ 0x20 => Some(Self::BandwidthVeryLow),
+ 0x30 => Some(Self::BandwidthLow),
+ 0x40 => Some(Self::QualityMedium),
+ 0x50 => Some(Self::QualityHigh),
+ 0x60 => Some(Self::QualityMax),
+ 0x70 => Some(Self::LatencyUltraLow),
+ 0x80 => Some(Self::LatencyLow),
+ _ => None,
+ }
+ }
+
+ pub const fn name(self) -> &'static str {
+ match self {
+ Self::BandwidthUltraLow => "Ultra Low Bandwidth",
+ Self::BandwidthVeryLow => "Very Low Bandwidth",
+ Self::BandwidthLow => "Low Bandwidth",
+ Self::QualityMedium => "Medium Quality",
+ Self::QualityHigh => "High Quality",
+ Self::QualityMax => "Super High Quality",
+ Self::LatencyLow => "Low Latency",
+ Self::LatencyUltraLow => "Ultra Low Latency",
+ }
+ }
+
+ pub const fn abbreviation(self) -> &'static str {
+ match self {
+ Self::BandwidthUltraLow => "ULBW",
+ Self::BandwidthVeryLow => "VLBW",
+ Self::BandwidthLow => "LBW",
+ Self::QualityMedium => "MQ",
+ Self::QualityHigh => "HQ",
+ Self::QualityMax => "SHQ",
+ Self::LatencyLow => "LL",
+ Self::LatencyUltraLow => "ULL",
+ }
+ }
+
+ pub const fn frame_time_ms(self) -> u16 {
+ match self {
+ Self::BandwidthUltraLow => 400,
+ Self::BandwidthVeryLow => 320,
+ Self::BandwidthLow => 200,
+ Self::QualityMedium => 60,
+ Self::QualityHigh => 60,
+ Self::QualityMax => 60,
+ Self::LatencyLow => 20,
+ Self::LatencyUltraLow => 10,
+ }
+ }
+
+ pub const fn audio_codec(self) -> AudioCodec {
+ match self {
+ Self::BandwidthUltraLow => AudioCodec::Codec2(Codec2Mode::Mode700C),
+ Self::BandwidthVeryLow => AudioCodec::Codec2(Codec2Mode::Mode1600),
+ Self::BandwidthLow => AudioCodec::Codec2(Codec2Mode::Mode3200),
+ Self::QualityMedium => AudioCodec::Opus(OpusProfile::VoiceMedium),
+ Self::QualityHigh => AudioCodec::Opus(OpusProfile::VoiceHigh),
+ Self::QualityMax => AudioCodec::Opus(OpusProfile::VoiceMax),
+ Self::LatencyLow => AudioCodec::Opus(OpusProfile::VoiceMedium),
+ Self::LatencyUltraLow => AudioCodec::Opus(OpusProfile::VoiceMedium),
+ }
+ }
+
+ pub const fn channels(self) -> u8 {
+ self.audio_codec().channels()
+ }
+
+ pub const fn sample_rate_hz(self) -> u32 {
+ self.audio_codec().sample_rate_hz()
+ }
+
+ pub const fn sample_frames_per_packet(self) -> usize {
+ ((self.sample_rate_hz() as usize) * (self.frame_time_ms() as usize)) / 1000
+ }
+
+ pub const fn opus_payload_ceiling_bytes(self) -> Option {
+ match self.audio_codec() {
+ AudioCodec::Opus(profile) => Some(profile.max_bytes_per_frame_ms(self.frame_time_ms())),
+ AudioCodec::Codec2(_) => None,
+ }
+ }
+
+ pub fn next(self) -> Self {
+ let index = Self::ORDER
+ .iter()
+ .position(|candidate| *candidate == self)
+ .unwrap_or(0);
+ Self::ORDER[(index + 1) % Self::ORDER.len()]
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum AudioCodec {
+ Opus(OpusProfile),
+ Codec2(Codec2Mode),
+}
+
+impl AudioCodec {
+ pub const fn codec_kind(self) -> CodecKind {
+ match self {
+ Self::Opus(_) => CodecKind::Opus,
+ Self::Codec2(_) => CodecKind::Codec2,
+ }
+ }
+
+ pub const fn channels(self) -> u8 {
+ match self {
+ Self::Opus(profile) => profile.channels(),
+ Self::Codec2(_) => 1,
+ }
+ }
+
+ pub const fn sample_rate_hz(self) -> u32 {
+ match self {
+ Self::Opus(profile) => profile.sample_rate(),
+ Self::Codec2(_) => 8_000,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u8)]
+pub enum OpusProfile {
+ VoiceLow = 0x00,
+ VoiceMedium = 0x01,
+ VoiceHigh = 0x02,
+ VoiceMax = 0x03,
+ AudioMin = 0x04,
+ AudioLow = 0x05,
+ AudioMedium = 0x06,
+ AudioHigh = 0x07,
+ AudioMax = 0x08,
+}
+
+impl OpusProfile {
+ pub const VALID_FRAME_MS: [f32; 6] = [2.5, 5.0, 10.0, 20.0, 40.0, 60.0];
+ pub const FRAME_QUANTA_MS: f32 = 2.5;
+ pub const FRAME_MAX_MS: f32 = 60.0;
+
+ pub const fn channels(self) -> u8 {
+ match self {
+ Self::VoiceLow | Self::VoiceMedium | Self::VoiceHigh => 1,
+ Self::VoiceMax => 2,
+ Self::AudioMin | Self::AudioLow => 1,
+ Self::AudioMedium | Self::AudioHigh | Self::AudioMax => 2,
+ }
+ }
+
+ pub const fn sample_rate(self) -> u32 {
+ match self {
+ Self::VoiceLow => 8_000,
+ Self::VoiceMedium => 24_000,
+ Self::VoiceHigh | Self::VoiceMax => 48_000,
+ Self::AudioMin => 8_000,
+ Self::AudioLow => 12_000,
+ Self::AudioMedium => 24_000,
+ Self::AudioHigh | Self::AudioMax => 48_000,
+ }
+ }
+
+ pub const fn application(self) -> OpusApplication {
+ match self {
+ Self::VoiceLow | Self::VoiceMedium | Self::VoiceHigh | Self::VoiceMax => {
+ OpusApplication::Voip
+ }
+ Self::AudioMin
+ | Self::AudioLow
+ | Self::AudioMedium
+ | Self::AudioHigh
+ | Self::AudioMax => OpusApplication::Audio,
+ }
+ }
+
+ pub const fn bitrate_ceiling(self) -> u32 {
+ match self {
+ Self::VoiceLow => 6_000,
+ Self::VoiceMedium => 8_000,
+ Self::VoiceHigh => 16_000,
+ Self::VoiceMax => 32_000,
+ Self::AudioMin => 8_000,
+ Self::AudioLow => 14_000,
+ Self::AudioMedium => 28_000,
+ Self::AudioHigh => 56_000,
+ Self::AudioMax => 128_000,
+ }
+ }
+
+ pub const fn max_bytes_per_frame_ms(self, frame_duration_ms: u16) -> usize {
+ let numerator = (self.bitrate_ceiling() as usize) * (frame_duration_ms as usize);
+ numerator.div_ceil(8_000)
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum OpusApplication {
+ Voip,
+ Audio,
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn profile_order_matches_python_next_profile_order() {
+ assert_eq!(Profile::QualityMax.next(), Profile::LatencyLow);
+ assert_eq!(Profile::LatencyLow.next(), Profile::LatencyUltraLow);
+ assert_eq!(Profile::LatencyUltraLow.next(), Profile::BandwidthUltraLow);
+ }
+
+ #[test]
+ fn telephony_profile_mapping_matches_python_reference() {
+ assert_eq!(
+ Profile::BandwidthUltraLow.audio_codec(),
+ AudioCodec::Codec2(Codec2Mode::Mode700C)
+ );
+ assert_eq!(
+ Profile::BandwidthVeryLow.audio_codec(),
+ AudioCodec::Codec2(Codec2Mode::Mode1600)
+ );
+ assert_eq!(
+ Profile::BandwidthLow.audio_codec(),
+ AudioCodec::Codec2(Codec2Mode::Mode3200)
+ );
+ assert_eq!(
+ Profile::LatencyUltraLow.audio_codec(),
+ AudioCodec::Opus(OpusProfile::VoiceMedium)
+ );
+ assert_eq!(Profile::LatencyUltraLow.frame_time_ms(), 10);
+ assert_eq!(Profile::LatencyLow.frame_time_ms(), 20);
+ }
+
+ #[test]
+ fn telephony_profile_audio_budgets_match_python_tables() {
+ assert_eq!(Profile::BandwidthUltraLow.channels(), 1);
+ assert_eq!(Profile::BandwidthUltraLow.sample_rate_hz(), 8_000);
+ assert_eq!(Profile::BandwidthUltraLow.sample_frames_per_packet(), 3_200);
+ assert_eq!(
+ Profile::BandwidthUltraLow.opus_payload_ceiling_bytes(),
+ None
+ );
+
+ assert_eq!(Profile::QualityMedium.channels(), 1);
+ assert_eq!(Profile::QualityMedium.sample_rate_hz(), 24_000);
+ assert_eq!(Profile::QualityMedium.sample_frames_per_packet(), 1_440);
+ assert_eq!(
+ Profile::QualityMedium.opus_payload_ceiling_bytes(),
+ Some(60)
+ );
+
+ assert_eq!(Profile::QualityHigh.channels(), 1);
+ assert_eq!(Profile::QualityHigh.sample_rate_hz(), 48_000);
+ assert_eq!(Profile::QualityHigh.sample_frames_per_packet(), 2_880);
+ assert_eq!(Profile::QualityHigh.opus_payload_ceiling_bytes(), Some(120));
+
+ assert_eq!(Profile::QualityMax.channels(), 2);
+ assert_eq!(Profile::QualityMax.sample_rate_hz(), 48_000);
+ assert_eq!(Profile::QualityMax.sample_frames_per_packet(), 2_880);
+ assert_eq!(Profile::QualityMax.opus_payload_ceiling_bytes(), Some(240));
+
+ assert_eq!(Profile::LatencyLow.sample_frames_per_packet(), 480);
+ assert_eq!(Profile::LatencyLow.opus_payload_ceiling_bytes(), Some(20));
+ assert_eq!(Profile::LatencyUltraLow.sample_frames_per_packet(), 240);
+ assert_eq!(
+ Profile::LatencyUltraLow.opus_payload_ceiling_bytes(),
+ Some(10)
+ );
+ }
+
+ #[test]
+ fn opus_max_bytes_per_frame_matches_python_formula() {
+ assert_eq!(OpusProfile::VoiceMedium.max_bytes_per_frame_ms(60), 60);
+ assert_eq!(OpusProfile::VoiceHigh.max_bytes_per_frame_ms(60), 120);
+ assert_eq!(OpusProfile::VoiceMax.max_bytes_per_frame_ms(60), 240);
+ assert_eq!(OpusProfile::AudioMax.max_bytes_per_frame_ms(60), 960);
+ }
+}
diff --git a/crates/lxst-core/src/raw.rs b/crates/lxst-core/src/raw.rs
new file mode 100644
index 0000000..7395980
--- /dev/null
+++ b/crates/lxst-core/src/raw.rs
@@ -0,0 +1,204 @@
+use half::f16;
+
+use crate::{CodecKind, Error, Frame, RawBitDepth, RawFrameHeader};
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct RawAudioFrame {
+ pub channels: u8,
+ pub samples: Vec,
+}
+
+impl RawAudioFrame {
+ pub fn new(channels: u8, samples: impl Into>) -> Result {
+ let samples = samples.into();
+ validate_sample_count(channels, samples.len())?;
+ Ok(Self { channels, samples })
+ }
+
+ pub fn sample_frames(&self) -> usize {
+ self.samples.len() / usize::from(self.channels)
+ }
+
+ pub fn from_frame(frame: &Frame) -> Result {
+ if frame.codec != CodecKind::Raw {
+ return Err(Error::InvalidRawFrameCodec(frame.codec));
+ }
+
+ Self::from_payload(&frame.payload)
+ }
+
+ pub fn to_frame(&self, bit_depth: RawBitDepth) -> Result {
+ Ok(Frame::new(CodecKind::Raw, self.to_payload(bit_depth)?))
+ }
+
+ pub fn from_payload(payload: &[u8]) -> Result {
+ let Some((&header_byte, sample_bytes)) = payload.split_first() else {
+ return Err(Error::EmptyRawPayload);
+ };
+
+ let header = RawFrameHeader::parse(header_byte)?;
+ let samples = decode_samples(sample_bytes, header.bit_depth)?;
+ validate_sample_count(header.channels, samples.len())?;
+
+ Ok(Self {
+ channels: header.channels,
+ samples,
+ })
+ }
+
+ pub fn to_payload(&self, bit_depth: RawBitDepth) -> Result, Error> {
+ validate_sample_count(self.channels, self.samples.len())?;
+ let header = RawFrameHeader::new(self.channels, bit_depth)?;
+ let mut out = Vec::with_capacity(1 + self.samples.len() * bit_depth.bytes_per_sample());
+ out.push(header.encode());
+ encode_samples(&self.samples, bit_depth, &mut out);
+ Ok(out)
+ }
+}
+
+fn validate_sample_count(channels: u8, samples: usize) -> Result<(), Error> {
+ RawFrameHeader::new(channels, RawBitDepth::Float16)?;
+ if samples % usize::from(channels) != 0 {
+ Err(Error::InvalidRawSampleCount { samples, channels })
+ } else {
+ Ok(())
+ }
+}
+
+fn decode_samples(bytes: &[u8], bit_depth: RawBitDepth) -> Result, Error> {
+ let bytes_per_sample = bit_depth.bytes_per_sample();
+ if bytes.len() % bytes_per_sample != 0 {
+ return Err(Error::InvalidRawSampleBytes { bytes_per_sample });
+ }
+
+ let mut samples = Vec::with_capacity(bytes.len() / bytes_per_sample);
+ match bit_depth {
+ RawBitDepth::Float16 => {
+ for chunk in bytes.chunks_exact(2) {
+ samples.push(f16::from_le_bytes([chunk[0], chunk[1]]).to_f32());
+ }
+ }
+ RawBitDepth::Float32 => {
+ for chunk in bytes.chunks_exact(4) {
+ samples.push(f32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]));
+ }
+ }
+ RawBitDepth::Float64 => {
+ for chunk in bytes.chunks_exact(8) {
+ samples.push(f64::from_le_bytes([
+ chunk[0], chunk[1], chunk[2], chunk[3], chunk[4], chunk[5], chunk[6], chunk[7],
+ ]) as f32);
+ }
+ }
+ RawBitDepth::Float128 => {
+ for chunk in bytes.chunks_exact(16) {
+ samples.push(decode_float128_lossy(chunk));
+ }
+ }
+ }
+
+ Ok(samples)
+}
+
+fn encode_samples(samples: &[f32], bit_depth: RawBitDepth, out: &mut Vec) {
+ match bit_depth {
+ RawBitDepth::Float16 => {
+ for sample in samples {
+ out.extend_from_slice(&f16::from_f32(*sample).to_le_bytes());
+ }
+ }
+ RawBitDepth::Float32 => {
+ for sample in samples {
+ out.extend_from_slice(&sample.to_le_bytes());
+ }
+ }
+ RawBitDepth::Float64 => {
+ for sample in samples {
+ out.extend_from_slice(&f64::from(*sample).to_le_bytes());
+ }
+ }
+ RawBitDepth::Float128 => {
+ for sample in samples {
+ encode_float128_from_f32(*sample, out);
+ }
+ }
+ }
+}
+
+fn decode_float128_lossy(bytes: &[u8]) -> f32 {
+ // Python/Numpy names this dtype "float128", but on common little-endian
+ // platforms it may be backed by an 80-bit extended value padded to 16 bytes.
+ // We preserve finite zero exactly and otherwise use the leading f64 lane as
+ // a conservative lossy fallback until a platform-specific long-double codec
+ // is introduced.
+ if bytes.iter().all(|byte| *byte == 0) {
+ 0.0
+ } else {
+ f64::from_le_bytes([
+ bytes[0], bytes[1], bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7],
+ ]) as f32
+ }
+}
+
+fn encode_float128_from_f32(sample: f32, out: &mut Vec) {
+ out.extend_from_slice(&f64::from(sample).to_le_bytes());
+ out.extend_from_slice(&[0u8; 8]);
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn raw_audio_frame_encodes_python_default_float16_payload() {
+ let raw = RawAudioFrame::new(2, vec![0.0, 0.5, -0.25, 1.0]).unwrap();
+ let payload = raw.to_payload(RawBitDepth::Float16).unwrap();
+ assert_eq!(
+ payload,
+ vec![0x01, 0x00, 0x00, 0x00, 0x38, 0x00, 0xB4, 0x00, 0x3C]
+ );
+ assert_eq!(RawAudioFrame::from_payload(&payload).unwrap(), raw);
+ }
+
+ #[test]
+ fn raw_audio_frame_encodes_float32_and_float64() {
+ let raw = RawAudioFrame::new(1, vec![0.25, -1.5]).unwrap();
+
+ let f32_payload = raw.to_payload(RawBitDepth::Float32).unwrap();
+ assert_eq!(f32_payload[0], 0x40);
+ assert_eq!(RawAudioFrame::from_payload(&f32_payload).unwrap(), raw);
+
+ let f64_payload = raw.to_payload(RawBitDepth::Float64).unwrap();
+ assert_eq!(f64_payload[0], 0x80);
+ assert_eq!(RawAudioFrame::from_payload(&f64_payload).unwrap(), raw);
+ }
+
+ #[test]
+ fn raw_audio_frame_rejects_misaligned_payloads() {
+ assert_eq!(
+ RawAudioFrame::from_payload(&[]),
+ Err(Error::EmptyRawPayload)
+ );
+ assert_eq!(
+ RawAudioFrame::from_payload(&[0x40, 0x00]),
+ Err(Error::InvalidRawSampleBytes {
+ bytes_per_sample: 4,
+ })
+ );
+ assert_eq!(
+ RawAudioFrame::new(2, vec![0.0]),
+ Err(Error::InvalidRawSampleCount {
+ samples: 1,
+ channels: 2,
+ })
+ );
+ }
+
+ #[test]
+ fn raw_audio_frame_converts_to_and_from_lxst_frame() {
+ let raw = RawAudioFrame::new(1, vec![0.0, 1.0]).unwrap();
+ let frame = raw.to_frame(RawBitDepth::Float16).unwrap();
+ assert_eq!(frame.codec, CodecKind::Raw);
+ assert_eq!(RawAudioFrame::from_frame(&frame).unwrap(), raw);
+ }
+}
diff --git a/crates/lxst-core/src/stream.rs b/crates/lxst-core/src/stream.rs
new file mode 100644
index 0000000..7bb5039
--- /dev/null
+++ b/crates/lxst-core/src/stream.rs
@@ -0,0 +1,339 @@
+use std::collections::VecDeque;
+
+use thiserror::Error;
+
+use crate::{CodecKind, Frame, LxstPacket};
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum StreamError {
+ #[error("frame packetizer batch size must be greater than zero")]
+ InvalidBatchSize,
+ #[error("jitter buffer capacity must be greater than zero")]
+ InvalidJitterCapacity,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct FramePacketizer {
+ frames_per_packet: usize,
+}
+
+impl FramePacketizer {
+ pub const PYTHON_COMPATIBLE: Self = Self {
+ frames_per_packet: 1,
+ };
+
+ pub fn new(frames_per_packet: usize) -> Result {
+ if frames_per_packet == 0 {
+ Err(StreamError::InvalidBatchSize)
+ } else {
+ Ok(Self { frames_per_packet })
+ }
+ }
+
+ pub const fn frames_per_packet(self) -> usize {
+ self.frames_per_packet
+ }
+
+ pub fn packetize_one(self, frame: Frame) -> LxstPacket {
+ LxstPacket::frame(frame)
+ }
+
+ pub fn packetize(self, frames: impl IntoIterator- ) -> Vec {
+ let mut packets = Vec::new();
+ let mut batch = Vec::with_capacity(self.frames_per_packet);
+
+ for frame in frames {
+ batch.push(frame);
+ if batch.len() == self.frames_per_packet {
+ packets.push(packet_from_batch(&mut batch));
+ }
+ }
+
+ if !batch.is_empty() {
+ packets.push(packet_from_batch(&mut batch));
+ }
+
+ packets
+ }
+}
+
+fn packet_from_batch(batch: &mut Vec) -> LxstPacket {
+ if batch.len() == 1 {
+ LxstPacket::frame(batch.pop().expect("batch has one frame"))
+ } else {
+ LxstPacket {
+ signals: Vec::new(),
+ frames: std::mem::take(batch),
+ }
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum FrameStreamEvent {
+ CodecChanged {
+ from: Option,
+ to: CodecKind,
+ },
+ Frame(Frame),
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct FrameStreamState {
+ current_codec: Option,
+}
+
+impl FrameStreamState {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub const fn current_codec(&self) -> Option {
+ self.current_codec
+ }
+
+ pub fn accept_packet(&mut self, packet: LxstPacket) -> Vec {
+ let mut events = Vec::new();
+
+ for frame in packet.frames {
+ if self.current_codec != Some(frame.codec) {
+ let from = self.current_codec;
+ self.current_codec = Some(frame.codec);
+ events.push(FrameStreamEvent::CodecChanged {
+ from,
+ to: frame.codec,
+ });
+ }
+ events.push(FrameStreamEvent::Frame(frame));
+ }
+
+ events
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum DropPolicy {
+ DropNewest,
+ DropOldest,
+}
+
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
+pub struct JitterStats {
+ pub pushed: u64,
+ pub popped: u64,
+ pub dropped_oldest: u64,
+ pub dropped_newest: u64,
+ pub underruns: u64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum JitterPush {
+ Accepted,
+ DroppedIncoming(T),
+ DroppedOldest(T),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct JitterBuffer {
+ capacity: usize,
+ drop_policy: DropPolicy,
+ queue: VecDeque,
+ stats: JitterStats,
+}
+
+impl JitterBuffer {
+ pub fn new(capacity: usize, drop_policy: DropPolicy) -> Result {
+ if capacity == 0 {
+ Err(StreamError::InvalidJitterCapacity)
+ } else {
+ Ok(Self {
+ capacity,
+ drop_policy,
+ queue: VecDeque::with_capacity(capacity),
+ stats: JitterStats::default(),
+ })
+ }
+ }
+
+ pub const fn capacity(&self) -> usize {
+ self.capacity
+ }
+
+ pub const fn drop_policy(&self) -> DropPolicy {
+ self.drop_policy
+ }
+
+ pub fn len(&self) -> usize {
+ self.queue.len()
+ }
+
+ pub fn is_empty(&self) -> bool {
+ self.queue.is_empty()
+ }
+
+ pub const fn stats(&self) -> JitterStats {
+ self.stats
+ }
+
+ pub fn push(&mut self, item: T) -> JitterPush {
+ self.stats.pushed += 1;
+ if self.queue.len() < self.capacity {
+ self.queue.push_back(item);
+ return JitterPush::Accepted;
+ }
+
+ match self.drop_policy {
+ DropPolicy::DropNewest => {
+ self.stats.dropped_newest += 1;
+ JitterPush::DroppedIncoming(item)
+ }
+ DropPolicy::DropOldest => {
+ self.stats.dropped_oldest += 1;
+ let dropped = self
+ .queue
+ .pop_front()
+ .expect("full jitter buffer has oldest item");
+ self.queue.push_back(item);
+ JitterPush::DroppedOldest(dropped)
+ }
+ }
+ }
+
+ pub fn pop(&mut self) -> Option {
+ let item = self.queue.pop_front();
+ if item.is_some() {
+ self.stats.popped += 1;
+ } else {
+ self.stats.underruns += 1;
+ }
+ item
+ }
+
+ pub fn clear(&mut self) {
+ self.queue.clear();
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn raw_frame(byte: u8) -> Frame {
+ Frame::new(CodecKind::Raw, [0x00, byte])
+ }
+
+ #[test]
+ fn python_compatible_packetizer_sends_one_frame_per_packet() {
+ let frames = vec![raw_frame(1), raw_frame(2)];
+ let packets = FramePacketizer::PYTHON_COMPATIBLE.packetize(frames.clone());
+
+ assert_eq!(packets.len(), 2);
+ assert_eq!(packets[0].frames, vec![frames[0].clone()]);
+ assert_eq!(packets[1].frames, vec![frames[1].clone()]);
+ }
+
+ #[test]
+ fn batched_packetizer_groups_frames_without_reordering() {
+ let frames = vec![raw_frame(1), raw_frame(2), raw_frame(3)];
+ let packetizer = FramePacketizer::new(2).unwrap();
+ let packets = packetizer.packetize(frames.clone());
+
+ assert_eq!(packetizer.frames_per_packet(), 2);
+ assert_eq!(packets.len(), 2);
+ assert_eq!(
+ packets[0].frames,
+ vec![frames[0].clone(), frames[1].clone()]
+ );
+ assert_eq!(packets[1].frames, vec![frames[2].clone()]);
+ }
+
+ #[test]
+ fn frame_stream_state_emits_codec_changes_before_frames() {
+ let mut state = FrameStreamState::new();
+ let packet = LxstPacket {
+ signals: Vec::new(),
+ frames: vec![
+ Frame::new(CodecKind::Raw, [0x00]),
+ Frame::new(CodecKind::Raw, [0x01]),
+ Frame::new(CodecKind::Opus, [0xF8]),
+ ],
+ };
+
+ let events = state.accept_packet(packet);
+ assert_eq!(
+ events,
+ vec![
+ FrameStreamEvent::CodecChanged {
+ from: None,
+ to: CodecKind::Raw,
+ },
+ FrameStreamEvent::Frame(Frame::new(CodecKind::Raw, [0x00])),
+ FrameStreamEvent::Frame(Frame::new(CodecKind::Raw, [0x01])),
+ FrameStreamEvent::CodecChanged {
+ from: Some(CodecKind::Raw),
+ to: CodecKind::Opus,
+ },
+ FrameStreamEvent::Frame(Frame::new(CodecKind::Opus, [0xF8])),
+ ]
+ );
+ assert_eq!(state.current_codec(), Some(CodecKind::Opus));
+ }
+
+ #[test]
+ fn jitter_buffer_drop_newest_keeps_existing_latency_window() {
+ let mut buffer = JitterBuffer::new(2, DropPolicy::DropNewest).unwrap();
+ assert_eq!(buffer.push(1), JitterPush::Accepted);
+ assert_eq!(buffer.push(2), JitterPush::Accepted);
+ assert_eq!(buffer.push(3), JitterPush::DroppedIncoming(3));
+ assert_eq!(buffer.pop(), Some(1));
+ assert_eq!(buffer.pop(), Some(2));
+ assert_eq!(
+ buffer.stats(),
+ JitterStats {
+ pushed: 3,
+ popped: 2,
+ dropped_oldest: 0,
+ dropped_newest: 1,
+ underruns: 0,
+ }
+ );
+ }
+
+ #[test]
+ fn jitter_buffer_drop_oldest_preserves_latest_audio() {
+ let mut buffer = JitterBuffer::new(2, DropPolicy::DropOldest).unwrap();
+ assert_eq!(buffer.push(1), JitterPush::Accepted);
+ assert_eq!(buffer.push(2), JitterPush::Accepted);
+ assert_eq!(buffer.push(3), JitterPush::DroppedOldest(1));
+ assert_eq!(buffer.pop(), Some(2));
+ assert_eq!(buffer.pop(), Some(3));
+ assert_eq!(
+ buffer.stats(),
+ JitterStats {
+ pushed: 3,
+ popped: 2,
+ dropped_oldest: 1,
+ dropped_newest: 0,
+ underruns: 0,
+ }
+ );
+ }
+
+ #[test]
+ fn jitter_buffer_tracks_playback_underruns() {
+ let mut buffer = JitterBuffer::new(2, DropPolicy::DropOldest).unwrap();
+ assert_eq!(buffer.pop(), None);
+ assert_eq!(buffer.push(1), JitterPush::Accepted);
+ assert_eq!(buffer.pop(), Some(1));
+ assert_eq!(buffer.pop(), None);
+ assert_eq!(
+ buffer.stats(),
+ JitterStats {
+ pushed: 1,
+ popped: 1,
+ dropped_oldest: 0,
+ dropped_newest: 0,
+ underruns: 2,
+ }
+ );
+ }
+}
diff --git a/crates/lxst-core/src/synthetic.rs b/crates/lxst-core/src/synthetic.rs
new file mode 100644
index 0000000..03bb994
--- /dev/null
+++ b/crates/lxst-core/src/synthetic.rs
@@ -0,0 +1,249 @@
+use thiserror::Error;
+
+use crate::{Error as WireError, RawAudioFrame, RawFrameHeader};
+
+#[derive(Debug, Error, PartialEq)]
+pub enum SyntheticError {
+ #[error("synthetic source sample rate must be greater than zero")]
+ InvalidSampleRate,
+ #[error("synthetic source frame sample count must be greater than zero")]
+ InvalidFrameSamples,
+ #[error("synthetic source parameter must be finite")]
+ NonFiniteParameter,
+ #[error("raw frame error: {0}")]
+ Raw(#[from] WireError),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum SyntheticSourceKind {
+ Silence,
+ Ramp { start: f32, step: f32 },
+ Sine { frequency_hz: f32, amplitude: f32 },
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct SyntheticSource {
+ channels: u8,
+ sample_rate_hz: u32,
+ frame_samples: usize,
+ kind: SyntheticSourceKind,
+ cursor_samples: u64,
+}
+
+impl SyntheticSource {
+ pub fn new(
+ channels: u8,
+ sample_rate_hz: u32,
+ frame_samples: usize,
+ kind: SyntheticSourceKind,
+ ) -> Result {
+ RawFrameHeader::new(channels, crate::RawBitDepth::Float16)?;
+ if sample_rate_hz == 0 {
+ return Err(SyntheticError::InvalidSampleRate);
+ }
+ if frame_samples == 0 {
+ return Err(SyntheticError::InvalidFrameSamples);
+ }
+ validate_kind(kind)?;
+
+ Ok(Self {
+ channels,
+ sample_rate_hz,
+ frame_samples,
+ kind,
+ cursor_samples: 0,
+ })
+ }
+
+ pub const fn channels(&self) -> u8 {
+ self.channels
+ }
+
+ pub const fn sample_rate_hz(&self) -> u32 {
+ self.sample_rate_hz
+ }
+
+ pub const fn frame_samples(&self) -> usize {
+ self.frame_samples
+ }
+
+ pub const fn cursor_samples(&self) -> u64 {
+ self.cursor_samples
+ }
+
+ pub fn next_raw_frame(&mut self) -> Result {
+ let mut samples = Vec::with_capacity(self.frame_samples * usize::from(self.channels));
+
+ for frame_index in 0..self.frame_samples {
+ let absolute_sample = self.cursor_samples + frame_index as u64;
+ let base = self.sample_at(absolute_sample);
+ for channel in 0..self.channels {
+ samples.push(channel_sample(base, channel));
+ }
+ }
+
+ self.cursor_samples += self.frame_samples as u64;
+ Ok(RawAudioFrame::new(self.channels, samples)?)
+ }
+
+ fn sample_at(&self, absolute_sample: u64) -> f32 {
+ match self.kind {
+ SyntheticSourceKind::Silence => 0.0,
+ SyntheticSourceKind::Ramp { start, step } => start + step * absolute_sample as f32,
+ SyntheticSourceKind::Sine {
+ frequency_hz,
+ amplitude,
+ } => {
+ let t = absolute_sample as f32 / self.sample_rate_hz as f32;
+ amplitude * (std::f32::consts::TAU * frequency_hz * t).sin()
+ }
+ }
+ }
+}
+
+fn channel_sample(base: f32, channel: u8) -> f32 {
+ if channel == 0 {
+ base
+ } else {
+ // Deterministic but small channel separation for fixture validation.
+ base + f32::from(channel) * 0.001
+ }
+}
+
+fn validate_kind(kind: SyntheticSourceKind) -> Result<(), SyntheticError> {
+ match kind {
+ SyntheticSourceKind::Silence => Ok(()),
+ SyntheticSourceKind::Ramp { start, step } => {
+ if start.is_finite() && step.is_finite() {
+ Ok(())
+ } else {
+ Err(SyntheticError::NonFiniteParameter)
+ }
+ }
+ SyntheticSourceKind::Sine {
+ frequency_hz,
+ amplitude,
+ } => {
+ if frequency_hz.is_finite() && amplitude.is_finite() {
+ Ok(())
+ } else {
+ Err(SyntheticError::NonFiniteParameter)
+ }
+ }
+ }
+}
+
+#[derive(Debug, Clone, Default, PartialEq)]
+pub struct RawFrameCollector {
+ frames: Vec,
+ sample_frames: usize,
+}
+
+impl RawFrameCollector {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub fn push(&mut self, frame: RawAudioFrame) {
+ self.sample_frames += frame.sample_frames();
+ self.frames.push(frame);
+ }
+
+ pub fn frames(&self) -> &[RawAudioFrame] {
+ &self.frames
+ }
+
+ pub const fn sample_frames(&self) -> usize {
+ self.sample_frames
+ }
+
+ pub fn into_frames(self) -> Vec {
+ self.frames
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn ramp_source_generates_deterministic_interleaved_channels() {
+ let mut source = SyntheticSource::new(
+ 2,
+ 48_000,
+ 3,
+ SyntheticSourceKind::Ramp {
+ start: 0.0,
+ step: 0.5,
+ },
+ )
+ .unwrap();
+
+ let first = source.next_raw_frame().unwrap();
+ let second = source.next_raw_frame().unwrap();
+
+ assert_eq!(
+ first,
+ RawAudioFrame::new(2, vec![0.0, 0.001, 0.5, 0.501, 1.0, 1.001]).unwrap()
+ );
+ assert_eq!(
+ second,
+ RawAudioFrame::new(2, vec![1.5, 1.501, 2.0, 2.001, 2.5, 2.501]).unwrap()
+ );
+ assert_eq!(source.cursor_samples(), 6);
+ }
+
+ #[test]
+ fn sine_source_generates_expected_quarter_wave_samples() {
+ let mut source = SyntheticSource::new(
+ 1,
+ 4,
+ 5,
+ SyntheticSourceKind::Sine {
+ frequency_hz: 1.0,
+ amplitude: 1.0,
+ },
+ )
+ .unwrap();
+
+ let frame = source.next_raw_frame().unwrap();
+ let expected = [0.0, 1.0, 0.0, -1.0, 0.0];
+ for (sample, expected) in frame.samples.iter().zip(expected) {
+ assert!((sample - expected).abs() < 0.000_001);
+ }
+ }
+
+ #[test]
+ fn collector_tracks_frames_and_sample_count() {
+ let mut collector = RawFrameCollector::new();
+ collector.push(RawAudioFrame::new(1, vec![0.0, 1.0]).unwrap());
+ collector.push(RawAudioFrame::new(2, vec![0.0, 0.1, 0.2, 0.3]).unwrap());
+
+ assert_eq!(collector.frames().len(), 2);
+ assert_eq!(collector.sample_frames(), 4);
+ }
+
+ #[test]
+ fn invalid_source_parameters_fail_explicitly() {
+ assert_eq!(
+ SyntheticSource::new(1, 0, 1, SyntheticSourceKind::Silence),
+ Err(SyntheticError::InvalidSampleRate)
+ );
+ assert_eq!(
+ SyntheticSource::new(1, 48_000, 0, SyntheticSourceKind::Silence),
+ Err(SyntheticError::InvalidFrameSamples)
+ );
+ assert_eq!(
+ SyntheticSource::new(
+ 1,
+ 48_000,
+ 1,
+ SyntheticSourceKind::Ramp {
+ start: f32::NAN,
+ step: 1.0,
+ },
+ ),
+ Err(SyntheticError::NonFiniteParameter)
+ );
+ }
+}
diff --git a/crates/lxst-core/src/telephony.rs b/crates/lxst-core/src/telephony.rs
new file mode 100644
index 0000000..261c7a5
--- /dev/null
+++ b/crates/lxst-core/src/telephony.rs
@@ -0,0 +1,378 @@
+use crate::{Profile, Signal, SignallingStatus};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum CallRole {
+ Incoming,
+ Outgoing,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TelephonyAction {
+ SendSignal(Signal),
+ IdentifyLocalIdentity,
+ SelectProfile(Profile),
+ PrepareDialingPipelines,
+ ResetDialingPipelines,
+ OpenAudioPipelines,
+ StartAudioPipelines,
+ StartDialTone,
+ Terminate(Option),
+ TeardownLink,
+ RingIncomingCall,
+ SwitchProfile(Profile),
+ IgnoreSignal(Signal),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TelephonyCall {
+ role: CallRole,
+ status: SignallingStatus,
+ profile: Option,
+ answered: bool,
+}
+
+impl TelephonyCall {
+ pub fn outgoing(profile: Option) -> Self {
+ Self {
+ role: CallRole::Outgoing,
+ status: SignallingStatus::Calling,
+ profile,
+ answered: false,
+ }
+ }
+
+ pub fn incoming() -> Self {
+ Self {
+ role: CallRole::Incoming,
+ status: SignallingStatus::Available,
+ profile: None,
+ answered: false,
+ }
+ }
+
+ pub const fn role(&self) -> CallRole {
+ self.role
+ }
+
+ pub const fn status(&self) -> SignallingStatus {
+ self.status
+ }
+
+ pub const fn profile(&self) -> Option {
+ self.profile
+ }
+
+ pub const fn answered(&self) -> bool {
+ self.answered
+ }
+
+ pub fn incoming_link_established(line_busy: bool) -> Vec {
+ if line_busy {
+ vec![
+ TelephonyAction::SendSignal(Signal::from(SignallingStatus::Busy)),
+ TelephonyAction::TeardownLink,
+ ]
+ } else {
+ vec![TelephonyAction::SendSignal(Signal::from(
+ SignallingStatus::Available,
+ ))]
+ }
+ }
+
+ pub fn caller_identified(&mut self, line_busy: bool, allowed: bool) -> Vec {
+ if line_busy || !allowed {
+ return vec![
+ TelephonyAction::SendSignal(Signal::from(SignallingStatus::Busy)),
+ TelephonyAction::TeardownLink,
+ ];
+ }
+
+ let mut actions = Vec::new();
+ actions.push(TelephonyAction::ResetDialingPipelines);
+ self.push_status_signal(SignallingStatus::Ringing, &mut actions);
+ actions.push(TelephonyAction::RingIncomingCall);
+ actions
+ }
+
+ pub fn answer(&mut self) -> Vec {
+ if self.role != CallRole::Incoming || self.status != SignallingStatus::Ringing {
+ return Vec::new();
+ }
+
+ let mut actions = Vec::new();
+ self.answered = true;
+ self.ensure_profile(&mut actions);
+ self.push_status_signal(SignallingStatus::Connecting, &mut actions);
+ actions.push(TelephonyAction::OpenAudioPipelines);
+ self.push_status_signal(SignallingStatus::Established, &mut actions);
+ actions.push(TelephonyAction::StartAudioPipelines);
+ actions
+ }
+
+ pub fn receive_signal(&mut self, signal: Signal) -> Vec {
+ if self.role == CallRole::Incoming && !self.answered && matches!(signal, Signal::Status(_))
+ {
+ return vec![TelephonyAction::IgnoreSignal(signal)];
+ }
+
+ match signal {
+ Signal::Status(SignallingStatus::Busy) => {
+ vec![TelephonyAction::Terminate(Some(SignallingStatus::Busy))]
+ }
+ Signal::Status(SignallingStatus::Rejected) => {
+ vec![TelephonyAction::Terminate(Some(SignallingStatus::Rejected))]
+ }
+ Signal::Status(SignallingStatus::Calling) => {
+ vec![TelephonyAction::IgnoreSignal(signal)]
+ }
+ Signal::Status(SignallingStatus::Available) => {
+ self.status = SignallingStatus::Available;
+ vec![TelephonyAction::IdentifyLocalIdentity]
+ }
+ Signal::Status(SignallingStatus::Ringing) => {
+ let mut actions = Vec::new();
+ self.status = SignallingStatus::Ringing;
+ self.ensure_profile(&mut actions);
+ actions.push(TelephonyAction::PrepareDialingPipelines);
+ if let Some(profile) = self.profile {
+ actions.push(TelephonyAction::SendSignal(Signal::from(profile)));
+ }
+ actions.push(TelephonyAction::StartDialTone);
+ actions
+ }
+ Signal::Status(SignallingStatus::Connecting) => {
+ self.status = SignallingStatus::Connecting;
+ vec![
+ TelephonyAction::ResetDialingPipelines,
+ TelephonyAction::OpenAudioPipelines,
+ ]
+ }
+ Signal::Status(SignallingStatus::Established) => {
+ self.status = SignallingStatus::Established;
+ vec![TelephonyAction::StartAudioPipelines]
+ }
+ Signal::PreferredProfile(profile) => {
+ if self.profile == Some(profile) {
+ return Vec::new();
+ }
+
+ self.profile = Some(profile);
+ if self.status == SignallingStatus::Established {
+ vec![TelephonyAction::SwitchProfile(profile)]
+ } else {
+ vec![TelephonyAction::SelectProfile(profile)]
+ }
+ }
+ Signal::Raw(_) => vec![TelephonyAction::IgnoreSignal(signal)],
+ }
+ }
+
+ pub fn switch_profile(&mut self, profile: Profile) -> Vec {
+ if self.profile == Some(profile) {
+ return Vec::new();
+ }
+
+ self.profile = Some(profile);
+ if self.status == SignallingStatus::Established {
+ vec![
+ TelephonyAction::SendSignal(Signal::from(profile)),
+ TelephonyAction::SwitchProfile(profile),
+ ]
+ } else {
+ vec![TelephonyAction::SelectProfile(profile)]
+ }
+ }
+
+ pub fn hangup(&mut self, ring_timeout: bool) -> Vec {
+ let mut actions = Vec::new();
+
+ if self.role == CallRole::Incoming
+ && self.status == SignallingStatus::Ringing
+ && !ring_timeout
+ {
+ actions.push(TelephonyAction::SendSignal(Signal::from(
+ SignallingStatus::Rejected,
+ )));
+ }
+
+ actions.push(TelephonyAction::TeardownLink);
+ self.status = SignallingStatus::Available;
+ self.answered = false;
+ actions
+ }
+
+ fn ensure_profile(&mut self, actions: &mut Vec) {
+ let profile = self.profile.unwrap_or(Profile::DEFAULT);
+ self.profile = Some(profile);
+ actions.push(TelephonyAction::SelectProfile(profile));
+ }
+
+ fn push_status_signal(&mut self, status: SignallingStatus, actions: &mut Vec) {
+ if status.is_auto_status() {
+ self.status = status;
+ }
+ actions.push(TelephonyAction::SendSignal(Signal::from(status)));
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn incoming_link_establishment_matches_python_busy_branch() {
+ assert_eq!(
+ TelephonyCall::incoming_link_established(false),
+ vec![TelephonyAction::SendSignal(Signal::from(
+ SignallingStatus::Available
+ ))]
+ );
+ assert_eq!(
+ TelephonyCall::incoming_link_established(true),
+ vec![
+ TelephonyAction::SendSignal(Signal::from(SignallingStatus::Busy)),
+ TelephonyAction::TeardownLink,
+ ]
+ );
+ }
+
+ #[test]
+ fn incoming_identified_then_answered_sequence_matches_python() {
+ let mut call = TelephonyCall::incoming();
+ let ringing = call.caller_identified(false, true);
+ assert_eq!(call.status(), SignallingStatus::Ringing);
+ assert_eq!(
+ ringing,
+ vec![
+ TelephonyAction::ResetDialingPipelines,
+ TelephonyAction::SendSignal(Signal::from(SignallingStatus::Ringing)),
+ TelephonyAction::RingIncomingCall,
+ ]
+ );
+
+ let answer = call.answer();
+ assert_eq!(call.status(), SignallingStatus::Established);
+ assert!(call.answered());
+ assert_eq!(call.profile(), Some(Profile::DEFAULT));
+ assert_eq!(
+ answer,
+ vec![
+ TelephonyAction::SelectProfile(Profile::DEFAULT),
+ TelephonyAction::SendSignal(Signal::from(SignallingStatus::Connecting)),
+ TelephonyAction::OpenAudioPipelines,
+ TelephonyAction::SendSignal(Signal::from(SignallingStatus::Established)),
+ TelephonyAction::StartAudioPipelines,
+ ]
+ );
+ }
+
+ #[test]
+ fn outgoing_sequence_identifies_profiles_opens_and_starts_audio() {
+ let mut call = TelephonyCall::outgoing(None);
+
+ assert_eq!(
+ call.receive_signal(Signal::from(SignallingStatus::Available)),
+ vec![TelephonyAction::IdentifyLocalIdentity]
+ );
+
+ let ringing = call.receive_signal(Signal::from(SignallingStatus::Ringing));
+ assert_eq!(call.profile(), Some(Profile::DEFAULT));
+ assert_eq!(
+ ringing,
+ vec![
+ TelephonyAction::SelectProfile(Profile::DEFAULT),
+ TelephonyAction::PrepareDialingPipelines,
+ TelephonyAction::SendSignal(Signal::from(Profile::DEFAULT)),
+ TelephonyAction::StartDialTone,
+ ]
+ );
+
+ assert_eq!(
+ call.receive_signal(Signal::from(SignallingStatus::Connecting)),
+ vec![
+ TelephonyAction::ResetDialingPipelines,
+ TelephonyAction::OpenAudioPipelines,
+ ]
+ );
+ assert_eq!(
+ call.receive_signal(Signal::from(SignallingStatus::Established)),
+ vec![TelephonyAction::StartAudioPipelines]
+ );
+ assert_eq!(call.status(), SignallingStatus::Established);
+ }
+
+ #[test]
+ fn profile_signals_select_or_switch_profile_by_call_status() {
+ let mut call = TelephonyCall::outgoing(None);
+ assert_eq!(
+ call.receive_signal(Signal::from(Profile::LatencyLow)),
+ vec![TelephonyAction::SelectProfile(Profile::LatencyLow)]
+ );
+
+ call.receive_signal(Signal::from(SignallingStatus::Established));
+ assert_eq!(
+ call.receive_signal(Signal::from(Profile::LatencyUltraLow)),
+ vec![TelephonyAction::SwitchProfile(Profile::LatencyUltraLow)]
+ );
+ }
+
+ #[test]
+ fn duplicate_profile_signals_do_not_reconfigure_audio() {
+ let mut call = TelephonyCall::outgoing(Some(Profile::QualityHigh));
+ call.receive_signal(Signal::from(SignallingStatus::Established));
+
+ assert!(
+ call.receive_signal(Signal::from(Profile::QualityHigh))
+ .is_empty()
+ );
+ }
+
+ #[test]
+ fn local_profile_switch_signals_remote_and_reconfigures_established_call() {
+ let mut call = TelephonyCall::outgoing(Some(Profile::QualityMedium));
+ call.receive_signal(Signal::from(SignallingStatus::Established));
+
+ assert_eq!(
+ call.switch_profile(Profile::QualityHigh),
+ vec![
+ TelephonyAction::SendSignal(Signal::from(Profile::QualityHigh)),
+ TelephonyAction::SwitchProfile(Profile::QualityHigh),
+ ]
+ );
+ assert_eq!(call.profile(), Some(Profile::QualityHigh));
+ assert!(call.switch_profile(Profile::QualityHigh).is_empty());
+ }
+
+ #[test]
+ fn incoming_call_ignores_status_signals_before_answer() {
+ let mut call = TelephonyCall::incoming();
+ call.caller_identified(false, true);
+
+ assert_eq!(
+ call.receive_signal(Signal::from(SignallingStatus::Established)),
+ vec![TelephonyAction::IgnoreSignal(Signal::from(
+ SignallingStatus::Established
+ ))]
+ );
+ }
+
+ #[test]
+ fn incoming_hangup_sends_rejected_while_ringing_unless_timeout() {
+ let mut call = TelephonyCall::incoming();
+ call.caller_identified(false, true);
+ assert_eq!(
+ call.hangup(false),
+ vec![
+ TelephonyAction::SendSignal(Signal::from(SignallingStatus::Rejected)),
+ TelephonyAction::TeardownLink,
+ ]
+ );
+
+ let mut timeout_call = TelephonyCall::incoming();
+ timeout_call.caller_identified(false, true);
+ assert_eq!(
+ timeout_call.hangup(true),
+ vec![TelephonyAction::TeardownLink]
+ );
+ }
+}
diff --git a/crates/lxst-core/src/wire.rs b/crates/lxst-core/src/wire.rs
new file mode 100644
index 0000000..a1e0b01
--- /dev/null
+++ b/crates/lxst-core/src/wire.rs
@@ -0,0 +1,485 @@
+use rmpv::Value;
+use rmpv::decode::read_value;
+use rmpv::encode::write_value;
+use thiserror::Error;
+
+use crate::profile::{Profile, SignallingStatus};
+
+pub const FIELD_SIGNALLING: u8 = 0x00;
+pub const FIELD_FRAMES: u8 = 0x01;
+
+const PREFERRED_PROFILE_BASE: u32 = 0xFF;
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum Error {
+ #[error("msgpack decode error: {0}")]
+ Decode(String),
+ #[error("msgpack encode error: {0}")]
+ Encode(String),
+ #[error("LXST packet root must be a msgpack map")]
+ RootNotMap,
+ #[error("LXST field key must be a non-negative integer")]
+ InvalidFieldKey,
+ #[error("LXST field {field:#04x} has invalid value type")]
+ InvalidFieldType { field: u8 },
+ #[error("LXST signal value must be a non-negative integer")]
+ InvalidSignal,
+ #[error("LXST frame must contain a codec header byte")]
+ EmptyFrame,
+ #[error("unknown LXST codec id {0:#04x}")]
+ UnknownCodec(u8),
+ #[error("LXST codec {0:?} is not transmittable as a media frame")]
+ NonTransmittableCodec(CodecKind),
+ #[error("expected raw codec frame, got {0:?}")]
+ InvalidRawFrameCodec(CodecKind),
+ #[error("invalid raw channel count {0}; expected 1..=64")]
+ InvalidRawChannels(u8),
+ #[error("unknown raw bit-depth header {0}")]
+ UnknownRawBitDepth(u8),
+ #[error("raw payload is empty; expected one header byte plus sample data")]
+ EmptyRawPayload,
+ #[error("raw payload sample bytes are not aligned to {bytes_per_sample}-byte samples")]
+ InvalidRawSampleBytes { bytes_per_sample: usize },
+ #[error("raw sample count {samples} is not divisible by channel count {channels}")]
+ InvalidRawSampleCount { samples: usize, channels: u8 },
+ #[error("unknown Codec2 mode header {0:#04x}")]
+ UnknownCodec2Mode(u8),
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u8)]
+pub enum CodecKind {
+ Raw = 0x00,
+ Opus = 0x01,
+ Codec2 = 0x02,
+ Null = 0xFF,
+}
+
+impl CodecKind {
+ pub const fn wire_id(self) -> u8 {
+ self as u8
+ }
+
+ pub const fn from_wire(id: u8) -> Result {
+ match id {
+ 0x00 => Ok(Self::Raw),
+ 0x01 => Ok(Self::Opus),
+ 0x02 => Ok(Self::Codec2),
+ 0xFF => Ok(Self::Null),
+ other => Err(Error::UnknownCodec(other)),
+ }
+ }
+
+ pub const fn is_transmittable(self) -> bool {
+ !matches!(self, Self::Null)
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Signal {
+ Status(SignallingStatus),
+ PreferredProfile(Profile),
+ Raw(u32),
+}
+
+impl Signal {
+ pub const fn wire_value(self) -> u32 {
+ match self {
+ Self::Status(status) => status.wire_value(),
+ Self::PreferredProfile(profile) => PREFERRED_PROFILE_BASE + profile.wire_value(),
+ Self::Raw(value) => value,
+ }
+ }
+
+ pub const fn from_wire(value: u32) -> Self {
+ if let Some(status) = SignallingStatus::from_wire(value) {
+ Self::Status(status)
+ } else if value >= PREFERRED_PROFILE_BASE {
+ let profile_value = value - PREFERRED_PROFILE_BASE;
+ if let Some(profile) = Profile::from_wire(profile_value) {
+ Self::PreferredProfile(profile)
+ } else {
+ Self::Raw(value)
+ }
+ } else {
+ Self::Raw(value)
+ }
+ }
+}
+
+impl From for Signal {
+ fn from(value: SignallingStatus) -> Self {
+ Self::Status(value)
+ }
+}
+
+impl From for Signal {
+ fn from(value: Profile) -> Self {
+ Self::PreferredProfile(value)
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Frame {
+ pub codec: CodecKind,
+ pub payload: Vec,
+}
+
+impl Frame {
+ pub fn new(codec: CodecKind, payload: impl Into>) -> Self {
+ Self {
+ codec,
+ payload: payload.into(),
+ }
+ }
+
+ pub fn from_wire_bytes(bytes: &[u8]) -> Result {
+ let Some((&codec_id, payload)) = bytes.split_first() else {
+ return Err(Error::EmptyFrame);
+ };
+
+ let codec = CodecKind::from_wire(codec_id)?;
+ if !codec.is_transmittable() {
+ return Err(Error::NonTransmittableCodec(codec));
+ }
+
+ Ok(Self {
+ codec,
+ payload: payload.to_vec(),
+ })
+ }
+
+ pub fn to_wire_bytes(&self) -> Result, Error> {
+ if !self.codec.is_transmittable() {
+ return Err(Error::NonTransmittableCodec(self.codec));
+ }
+
+ let mut bytes = Vec::with_capacity(1 + self.payload.len());
+ bytes.push(self.codec.wire_id());
+ bytes.extend_from_slice(&self.payload);
+ Ok(bytes)
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct LxstPacket {
+ pub signals: Vec,
+ pub frames: Vec,
+}
+
+impl LxstPacket {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub fn signalling(signals: impl IntoIterator
- ) -> Self {
+ Self {
+ signals: signals.into_iter().collect(),
+ frames: Vec::new(),
+ }
+ }
+
+ pub fn frame(frame: Frame) -> Self {
+ Self {
+ signals: Vec::new(),
+ frames: vec![frame],
+ }
+ }
+
+ pub fn encode(&self) -> Result, Error> {
+ let mut map = Vec::with_capacity(2);
+
+ if !self.signals.is_empty() {
+ let signals = self
+ .signals
+ .iter()
+ .map(|signal| Value::from(signal.wire_value() as u64))
+ .collect();
+ map.push((Value::from(FIELD_SIGNALLING as u64), Value::Array(signals)));
+ }
+
+ if !self.frames.is_empty() {
+ let value = if self.frames.len() == 1 {
+ Value::Binary(self.frames[0].to_wire_bytes()?)
+ } else {
+ Value::Array(
+ self.frames
+ .iter()
+ .map(|frame| frame.to_wire_bytes().map(Value::Binary))
+ .collect::, _>>()?,
+ )
+ };
+ map.push((Value::from(FIELD_FRAMES as u64), value));
+ }
+
+ let mut out = Vec::new();
+ write_value(&mut out, &Value::Map(map)).map_err(|e| Error::Encode(e.to_string()))?;
+ Ok(out)
+ }
+
+ pub fn decode(bytes: &[u8]) -> Result {
+ let value = read_value(&mut &bytes[..]).map_err(|e| Error::Decode(e.to_string()))?;
+ Self::from_value(value)
+ }
+
+ fn from_value(value: Value) -> Result {
+ let Value::Map(entries) = value else {
+ return Err(Error::RootNotMap);
+ };
+
+ let mut packet = Self::new();
+ for (key, value) in entries {
+ let Some(field) = integer_value(&key).and_then(|v| u8::try_from(v).ok()) else {
+ return Err(Error::InvalidFieldKey);
+ };
+
+ match field {
+ FIELD_SIGNALLING => {
+ packet.signals.extend(parse_signals(value)?);
+ }
+ FIELD_FRAMES => {
+ packet.frames.extend(parse_frames(value)?);
+ }
+ _ => {}
+ }
+ }
+
+ Ok(packet)
+ }
+}
+
+fn parse_signals(value: Value) -> Result, Error> {
+ match value {
+ Value::Array(values) => values
+ .iter()
+ .map(parse_signal)
+ .collect::, _>>(),
+ other => Ok(vec![parse_signal(&other)?]),
+ }
+}
+
+fn parse_signal(value: &Value) -> Result {
+ let Some(raw) = integer_value(value).and_then(|v| u32::try_from(v).ok()) else {
+ return Err(Error::InvalidSignal);
+ };
+ Ok(Signal::from_wire(raw))
+}
+
+fn parse_frames(value: Value) -> Result, Error> {
+ match value {
+ Value::Binary(bytes) => Ok(vec![Frame::from_wire_bytes(&bytes)?]),
+ Value::Array(values) => values
+ .into_iter()
+ .map(|value| match value {
+ Value::Binary(bytes) => Frame::from_wire_bytes(&bytes),
+ _ => Err(Error::InvalidFieldType {
+ field: FIELD_FRAMES,
+ }),
+ })
+ .collect(),
+ _ => Err(Error::InvalidFieldType {
+ field: FIELD_FRAMES,
+ }),
+ }
+}
+
+fn integer_value(value: &Value) -> Option {
+ value
+ .as_u64()
+ .or_else(|| value.as_i64().and_then(|v| u64::try_from(v).ok()))
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u8)]
+pub enum RawBitDepth {
+ Float16 = 0x00,
+ Float32 = 0x01,
+ Float64 = 0x02,
+ Float128 = 0x03,
+}
+
+impl RawBitDepth {
+ pub const fn from_header_bits(bits: u8) -> Result {
+ match bits {
+ 0x00 => Ok(Self::Float16),
+ 0x01 => Ok(Self::Float32),
+ 0x02 => Ok(Self::Float64),
+ 0x03 => Ok(Self::Float128),
+ other => Err(Error::UnknownRawBitDepth(other)),
+ }
+ }
+
+ pub const fn bits(self) -> u16 {
+ match self {
+ Self::Float16 => 16,
+ Self::Float32 => 32,
+ Self::Float64 => 64,
+ Self::Float128 => 128,
+ }
+ }
+
+ pub const fn bytes_per_sample(self) -> usize {
+ (self.bits() as usize) / 8
+ }
+
+ pub const fn numpy_dtype(self) -> &'static str {
+ match self {
+ Self::Float16 => "float16",
+ Self::Float32 => "float32",
+ Self::Float64 => "float64",
+ Self::Float128 => "float128",
+ }
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct RawFrameHeader {
+ pub channels: u8,
+ pub bit_depth: RawBitDepth,
+}
+
+impl RawFrameHeader {
+ pub const fn new(channels: u8, bit_depth: RawBitDepth) -> Result {
+ if channels == 0 || channels > 64 {
+ Err(Error::InvalidRawChannels(channels))
+ } else {
+ Ok(Self {
+ channels,
+ bit_depth,
+ })
+ }
+ }
+
+ pub fn parse(byte: u8) -> Result {
+ let channels = (byte & 0b0011_1111) + 1;
+ let bit_depth = RawBitDepth::from_header_bits(byte >> 6)?;
+ Self::new(channels, bit_depth)
+ }
+
+ pub const fn encode(self) -> u8 {
+ ((self.bit_depth as u8) << 6) | (self.channels - 1)
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u8)]
+pub enum Codec2Mode {
+ Mode700C = 0x00,
+ Mode1200 = 0x01,
+ Mode1300 = 0x02,
+ Mode1400 = 0x03,
+ Mode1600 = 0x04,
+ Mode2400 = 0x05,
+ Mode3200 = 0x06,
+}
+
+impl Codec2Mode {
+ pub const fn from_header(byte: u8) -> Result {
+ match byte {
+ 0x00 => Ok(Self::Mode700C),
+ 0x01 => Ok(Self::Mode1200),
+ 0x02 => Ok(Self::Mode1300),
+ 0x03 => Ok(Self::Mode1400),
+ 0x04 => Ok(Self::Mode1600),
+ 0x05 => Ok(Self::Mode2400),
+ 0x06 => Ok(Self::Mode3200),
+ other => Err(Error::UnknownCodec2Mode(other)),
+ }
+ }
+
+ pub const fn header(self) -> u8 {
+ self as u8
+ }
+
+ pub const fn bitrate(self) -> u16 {
+ match self {
+ Self::Mode700C => 700,
+ Self::Mode1200 => 1200,
+ Self::Mode1300 => 1300,
+ Self::Mode1400 => 1400,
+ Self::Mode1600 => 1600,
+ Self::Mode2400 => 2400,
+ Self::Mode3200 => 3200,
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn codec_header_mapping_matches_python() {
+ assert_eq!(CodecKind::Raw.wire_id(), 0x00);
+ assert_eq!(CodecKind::Opus.wire_id(), 0x01);
+ assert_eq!(CodecKind::Codec2.wire_id(), 0x02);
+ assert_eq!(CodecKind::Null.wire_id(), 0xFF);
+ assert_eq!(CodecKind::from_wire(0x02), Ok(CodecKind::Codec2));
+ assert_eq!(CodecKind::from_wire(0x03), Err(Error::UnknownCodec(0x03)));
+ }
+
+ #[test]
+ fn raw_header_roundtrip() {
+ let header = RawFrameHeader::new(2, RawBitDepth::Float32).unwrap();
+ assert_eq!(header.encode(), 0x41);
+ assert_eq!(RawFrameHeader::parse(0x41), Ok(header));
+
+ let max = RawFrameHeader::new(64, RawBitDepth::Float128).unwrap();
+ assert_eq!(RawFrameHeader::parse(max.encode()), Ok(max));
+ assert_eq!(
+ RawFrameHeader::new(0, RawBitDepth::Float16),
+ Err(Error::InvalidRawChannels(0))
+ );
+ }
+
+ #[test]
+ fn codec2_mode_headers_match_python() {
+ assert_eq!(Codec2Mode::Mode700C.header(), 0x00);
+ assert_eq!(Codec2Mode::Mode1600.header(), 0x04);
+ assert_eq!(Codec2Mode::Mode3200.header(), 0x06);
+ assert_eq!(Codec2Mode::Mode700C.bitrate(), 700);
+ assert_eq!(
+ Codec2Mode::from_header(0x07),
+ Err(Error::UnknownCodec2Mode(0x07))
+ );
+ }
+
+ #[test]
+ fn frame_roundtrip() {
+ let frame = Frame::new(CodecKind::Raw, [0x41, 0xAA, 0xBB]);
+ let wire = frame.to_wire_bytes().unwrap();
+ assert_eq!(wire, vec![0x00, 0x41, 0xAA, 0xBB]);
+ assert_eq!(Frame::from_wire_bytes(&wire), Ok(frame));
+ }
+
+ #[test]
+ fn null_codec_is_known_but_not_transmittable() {
+ assert_eq!(CodecKind::from_wire(0xFF), Ok(CodecKind::Null));
+ assert_eq!(
+ Frame::from_wire_bytes(&[0xFF]),
+ Err(Error::NonTransmittableCodec(CodecKind::Null))
+ );
+ assert_eq!(
+ LxstPacket::frame(Frame::new(CodecKind::Null, [])).encode(),
+ Err(Error::NonTransmittableCodec(CodecKind::Null))
+ );
+ }
+
+ #[test]
+ fn signal_profile_base_matches_python() {
+ let signal = Signal::from(Profile::QualityMedium);
+ assert_eq!(signal.wire_value(), 0xFF + 0x40);
+ assert_eq!(
+ Signal::from_wire(0xFF + 0x70),
+ Signal::PreferredProfile(Profile::LatencyUltraLow)
+ );
+ }
+
+ #[test]
+ fn packet_encodes_single_frame_as_binary_field() {
+ let packet = LxstPacket::frame(Frame::new(CodecKind::Raw, [0x00]));
+ let encoded = packet.encode().unwrap();
+ assert_eq!(encoded, vec![0x81, 0x01, 0xC4, 0x02, 0x00, 0x00]);
+ assert_eq!(LxstPacket::decode(&encoded), Ok(packet));
+ }
+}
diff --git a/crates/lxst-core/tests/malformed_wire.rs b/crates/lxst-core/tests/malformed_wire.rs
new file mode 100644
index 0000000..f58c307
--- /dev/null
+++ b/crates/lxst-core/tests/malformed_wire.rs
@@ -0,0 +1,128 @@
+use lxst_core::{
+ CodecKind, Error, FIELD_FRAMES, FIELD_SIGNALLING, Frame, LxstPacket, RawAudioFrame, RawBitDepth,
+};
+use proptest::prelude::*;
+use rmpv::Value;
+
+fn encode_value(value: Value) -> Vec {
+ let mut out = Vec::new();
+ rmpv::encode::write_value(&mut out, &value).expect("encode msgpack value");
+ out
+}
+
+#[test]
+fn malformed_msgpack_shapes_fail_deterministically() {
+ let cases = [
+ (
+ Value::Array(vec![]),
+ Error::RootNotMap,
+ "root array is not an LXST packet",
+ ),
+ (
+ Value::Map(vec![(Value::from(-1), Value::from(0))]),
+ Error::InvalidFieldKey,
+ "negative field key",
+ ),
+ (
+ Value::Map(vec![(Value::from(999), Value::from(0))]),
+ Error::InvalidFieldKey,
+ "oversized field key",
+ ),
+ (
+ Value::Map(vec![(
+ Value::from(FIELD_SIGNALLING as u64),
+ Value::String("bad".into()),
+ )]),
+ Error::InvalidSignal,
+ "non-integer signal",
+ ),
+ (
+ Value::Map(vec![(
+ Value::from(FIELD_FRAMES as u64),
+ Value::Array(vec![Value::from(1)]),
+ )]),
+ Error::InvalidFieldType {
+ field: FIELD_FRAMES,
+ },
+ "non-bytes frame in list",
+ ),
+ (
+ Value::Map(vec![(
+ Value::from(FIELD_FRAMES as u64),
+ Value::Binary(vec![]),
+ )]),
+ Error::EmptyFrame,
+ "empty media frame",
+ ),
+ (
+ Value::Map(vec![(
+ Value::from(FIELD_FRAMES as u64),
+ Value::Binary(vec![0x03]),
+ )]),
+ Error::UnknownCodec(0x03),
+ "unknown media codec",
+ ),
+ (
+ Value::Map(vec![(
+ Value::from(FIELD_FRAMES as u64),
+ Value::Binary(vec![0xFF]),
+ )]),
+ Error::NonTransmittableCodec(CodecKind::Null),
+ "null media codec is not transmittable",
+ ),
+ ];
+
+ for (value, expected, name) in cases {
+ assert_eq!(
+ LxstPacket::decode(&encode_value(value)),
+ Err(expected),
+ "{name}"
+ );
+ }
+}
+
+#[test]
+fn decoder_tolerates_trailing_bytes_like_python_umsgpack() {
+ let mut encoded = LxstPacket::frame(Frame::new(CodecKind::Raw, [0x00, 0x00]))
+ .encode()
+ .unwrap();
+ encoded.extend_from_slice(b"trailing");
+
+ let decoded = LxstPacket::decode(&encoded).unwrap();
+ assert_eq!(decoded.frames.len(), 1);
+}
+
+#[test]
+fn raw_payload_errors_are_explicit() {
+ assert_eq!(
+ RawAudioFrame::from_payload(&[0x40, 0x00]),
+ Err(Error::InvalidRawSampleBytes {
+ bytes_per_sample: 4,
+ })
+ );
+ assert_eq!(
+ RawAudioFrame::new(2, vec![0.0]),
+ Err(Error::InvalidRawSampleCount {
+ samples: 1,
+ channels: 2,
+ })
+ );
+ assert_eq!(
+ RawAudioFrame::new(1, vec![0.0])
+ .unwrap()
+ .to_frame(RawBitDepth::Float16)
+ .unwrap()
+ .codec,
+ CodecKind::Raw
+ );
+}
+
+proptest! {
+ #[test]
+ fn arbitrary_bytes_never_panic(bytes in proptest::collection::vec(any::(), 0..1024)) {
+ let result = std::panic::catch_unwind(|| {
+ let _ = LxstPacket::decode(&bytes);
+ });
+ prop_assert!(result.is_ok());
+ }
+}
diff --git a/crates/lxst-core/tests/python_raw_parity.rs b/crates/lxst-core/tests/python_raw_parity.rs
new file mode 100644
index 0000000..b832f5e
--- /dev/null
+++ b/crates/lxst-core/tests/python_raw_parity.rs
@@ -0,0 +1,161 @@
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use lxst_core::{RawAudioFrame, RawBitDepth};
+use serde_json::Value;
+
+const SKIP_ENV: &str = "SKIP_PYTHON_LXST_INTEROP";
+
+fn repo_root() -> PathBuf {
+ Path::new(env!("CARGO_MANIFEST_DIR"))
+ .ancestors()
+ .nth(2)
+ .expect("crate is under rsLXST/crates/lxst-core")
+ .to_path_buf()
+}
+
+fn fixture_script() -> PathBuf {
+ repo_root().join("tools/fixtures/lxst_raw_fixtures.py")
+}
+
+fn should_skip() -> bool {
+ std::env::var(SKIP_ENV).map(|v| v == "1").unwrap_or(false)
+}
+
+fn python_fixtures() -> Vec {
+ if should_skip() {
+ eprintln!("{SKIP_ENV}=1 -> skipping Python LXST Raw parity");
+ return Vec::new();
+ }
+
+ let output = Command::new("python3")
+ .arg(fixture_script())
+ .output()
+ .expect("spawn Python Raw fixture generator");
+
+ assert!(
+ output.status.success(),
+ "Python Raw fixture generator failed\nstdout:\n{}\nstderr:\n{}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ serde_json::from_slice(&output.stdout).expect("fixture JSON")
+}
+
+fn decode_with_python(payload_hex: &str) -> Value {
+ let output = Command::new("python3")
+ .arg(fixture_script())
+ .arg("--decode-hex")
+ .arg(payload_hex)
+ .output()
+ .expect("spawn Python Raw fixture decoder");
+
+ assert!(
+ output.status.success(),
+ "Python Raw fixture decoder failed\nstdout:\n{}\nstderr:\n{}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ serde_json::from_slice(&output.stdout).expect("decode JSON")
+}
+
+fn bit_depth(value: &Value) -> RawBitDepth {
+ match value["bitdepth_header"].as_u64().expect("bitdepth header") {
+ 0 => RawBitDepth::Float16,
+ 1 => RawBitDepth::Float32,
+ 2 => RawBitDepth::Float64,
+ 3 => RawBitDepth::Float128,
+ other => panic!("unknown bitdepth header {other}"),
+ }
+}
+
+fn samples(value: &Value) -> Vec {
+ value["samples"]
+ .as_array()
+ .expect("samples")
+ .iter()
+ .map(|sample| sample.as_f64().expect("sample") as f32)
+ .collect()
+}
+
+fn assert_samples_close(actual: &[f32], expected: &[f32], name: &str) {
+ assert_eq!(actual.len(), expected.len(), "{name}");
+ for (index, (actual, expected)) in actual.iter().zip(expected).enumerate() {
+ let delta = (actual - expected).abs();
+ assert!(
+ delta <= 0.000_976_562_5,
+ "{name} sample {index}: actual {actual} expected {expected} delta {delta}",
+ );
+ }
+}
+
+#[test]
+fn rust_decodes_python_raw_payloads() {
+ for fixture in python_fixtures() {
+ let name = fixture["name"].as_str().expect("fixture name");
+ let payload_hex = fixture["payload_hex"].as_str().expect("payload hex");
+ let payload = hex::decode(payload_hex).expect("payload hex decodes");
+ let raw = RawAudioFrame::from_payload(&payload)
+ .unwrap_or_else(|e| panic!("failed to decode fixture {name}: {e}"));
+ let depth = bit_depth(&fixture);
+ let expected_samples = samples(&fixture);
+
+ assert_eq!(
+ raw.channels,
+ fixture["channels"].as_u64().expect("channels") as u8,
+ "{name}",
+ );
+ assert_eq!(
+ raw.sample_frames(),
+ fixture["sample_frames"].as_u64().expect("sample frames") as usize,
+ "{name}",
+ );
+ assert_samples_close(&raw.samples, &expected_samples, name);
+ assert_eq!(
+ hex::encode(raw.to_payload(depth).unwrap()),
+ payload_hex,
+ "{name}"
+ );
+ }
+}
+
+#[test]
+fn python_decodes_rust_raw_payloads() {
+ if should_skip() {
+ eprintln!("{SKIP_ENV}=1 -> skipping Python LXST Raw parity");
+ return;
+ }
+
+ let cases = [
+ (
+ RawAudioFrame::new(2, vec![0.0, 0.5, -0.25, 1.0]).unwrap(),
+ RawBitDepth::Float16,
+ ),
+ (
+ RawAudioFrame::new(1, vec![0.25, -1.5, 2.0]).unwrap(),
+ RawBitDepth::Float32,
+ ),
+ (
+ RawAudioFrame::new(3, vec![0.0, 0.125, -0.5, 1.0, -1.0, 0.25]).unwrap(),
+ RawBitDepth::Float64,
+ ),
+ ];
+
+ for (raw, depth) in cases {
+ let payload_hex = hex::encode(raw.to_payload(depth).expect("encode Raw payload"));
+ let decoded = decode_with_python(&payload_hex);
+
+ assert_eq!(
+ decoded["channels"].as_u64().expect("channels") as u8,
+ raw.channels
+ );
+ assert_eq!(
+ decoded["sample_frames"].as_u64().expect("sample frames") as usize,
+ raw.sample_frames(),
+ );
+ assert_eq!(bit_depth(&decoded), depth);
+ assert_samples_close(&samples(&decoded), &raw.samples, &payload_hex);
+ }
+}
diff --git a/crates/lxst-core/tests/python_wire_parity.rs b/crates/lxst-core/tests/python_wire_parity.rs
new file mode 100644
index 0000000..d777d8c
--- /dev/null
+++ b/crates/lxst-core/tests/python_wire_parity.rs
@@ -0,0 +1,150 @@
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use lxst_core::{CodecKind, Frame, LxstPacket, Profile, Signal, SignallingStatus};
+use serde_json::Value;
+
+const SKIP_ENV: &str = "SKIP_PYTHON_LXST_INTEROP";
+
+fn repo_root() -> PathBuf {
+ Path::new(env!("CARGO_MANIFEST_DIR"))
+ .ancestors()
+ .nth(2)
+ .expect("crate is under rsLXST/crates/lxst-core")
+ .to_path_buf()
+}
+
+fn fixture_script() -> PathBuf {
+ repo_root().join("tools/fixtures/lxst_wire_fixtures.py")
+}
+
+fn should_skip() -> bool {
+ std::env::var(SKIP_ENV).map(|v| v == "1").unwrap_or(false)
+}
+
+fn python_fixtures() -> Vec {
+ if should_skip() {
+ eprintln!("{SKIP_ENV}=1 -> skipping Python LXST wire parity");
+ return Vec::new();
+ }
+
+ let output = Command::new("python3")
+ .arg(fixture_script())
+ .output()
+ .expect("spawn Python fixture generator");
+
+ assert!(
+ output.status.success(),
+ "Python fixture generator failed\nstdout:\n{}\nstderr:\n{}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ serde_json::from_slice(&output.stdout).expect("fixture JSON")
+}
+
+fn decode_with_python(packet_hex: &str) -> Value {
+ let output = Command::new("python3")
+ .arg(fixture_script())
+ .arg("--decode-hex")
+ .arg(packet_hex)
+ .output()
+ .expect("spawn Python fixture decoder");
+
+ assert!(
+ output.status.success(),
+ "Python fixture decoder failed\nstdout:\n{}\nstderr:\n{}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ serde_json::from_slice(&output.stdout).expect("decode JSON")
+}
+
+fn signal_values(packet: &LxstPacket) -> Vec {
+ packet.signals.iter().map(|s| s.wire_value()).collect()
+}
+
+#[test]
+fn rust_decodes_python_lxst_packets() {
+ for fixture in python_fixtures() {
+ let name = fixture["name"].as_str().expect("fixture name");
+ let packet_hex = fixture["packet_hex"].as_str().expect("packet hex");
+ let packet_bytes = hex::decode(packet_hex).expect("packet hex decodes");
+ let packet = LxstPacket::decode(&packet_bytes)
+ .unwrap_or_else(|e| panic!("failed to decode fixture {name}: {e}"));
+
+ let expected_signals: Vec = fixture["signals"]
+ .as_array()
+ .expect("signals array")
+ .iter()
+ .map(|v| v.as_u64().expect("signal int") as u32)
+ .collect();
+ assert_eq!(signal_values(&packet), expected_signals, "{name}");
+
+ let expected_frames = fixture["frames"].as_array().expect("frames array");
+ assert_eq!(packet.frames.len(), expected_frames.len(), "{name}");
+
+ for (frame, expected) in packet.frames.iter().zip(expected_frames) {
+ let codec = expected["codec"].as_u64().expect("codec") as u8;
+ assert_eq!(frame.codec.wire_id(), codec, "{name}");
+ let payload = expected["payload_hex"].as_str().expect("payload hex");
+ assert_eq!(hex::encode(&frame.payload), payload, "{name}");
+ }
+
+ if fixture["canonical"].as_bool().unwrap_or(false) {
+ assert_eq!(hex::encode(packet.encode().unwrap()), packet_hex, "{name}");
+ }
+ }
+}
+
+#[test]
+fn python_decodes_rust_lxst_packets() {
+ if should_skip() {
+ eprintln!("{SKIP_ENV}=1 -> skipping Python LXST wire parity");
+ return;
+ }
+
+ let packets = [
+ LxstPacket::signalling([
+ Signal::from(SignallingStatus::Available),
+ Signal::from(Profile::QualityMedium),
+ ]),
+ LxstPacket::frame(Frame::new(CodecKind::Raw, [0x41, 0x01, 0x02, 0x03, 0x04])),
+ LxstPacket {
+ signals: vec![
+ Signal::from(SignallingStatus::Established),
+ Signal::from(Profile::LatencyUltraLow),
+ ],
+ frames: vec![
+ Frame::new(CodecKind::Raw, [0x41, 0x01, 0x02, 0x03, 0x04]),
+ Frame::new(CodecKind::Codec2, [0x04, 0xAA, 0xBB]),
+ ],
+ },
+ ];
+
+ for packet in packets {
+ let packet_hex = hex::encode(packet.encode().expect("encode packet"));
+ let decoded = decode_with_python(&packet_hex);
+ let signals: Vec = decoded["signals"]
+ .as_array()
+ .expect("signals")
+ .iter()
+ .map(|v| v.as_u64().expect("signal") as u32)
+ .collect();
+ assert_eq!(signals, signal_values(&packet));
+
+ let frames = decoded["frames"].as_array().expect("frames");
+ assert_eq!(frames.len(), packet.frames.len());
+ for (frame, expected) in packet.frames.iter().zip(frames) {
+ assert_eq!(
+ expected["codec"].as_u64().expect("codec") as u8,
+ frame.codec.wire_id()
+ );
+ assert_eq!(
+ expected["payload_hex"].as_str().expect("payload"),
+ hex::encode(&frame.payload)
+ );
+ }
+ }
+}
diff --git a/crates/lxst-core/tests/reference_snapshot.rs b/crates/lxst-core/tests/reference_snapshot.rs
new file mode 100644
index 0000000..5f915c4
--- /dev/null
+++ b/crates/lxst-core/tests/reference_snapshot.rs
@@ -0,0 +1,82 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use serde_json::Value;
+
+const SKIP_ENV: &str = "SKIP_PYTHON_LXST_INTEROP";
+
+fn repo_root() -> PathBuf {
+ Path::new(env!("CARGO_MANIFEST_DIR"))
+ .ancestors()
+ .nth(2)
+ .expect("crate is under rsLXST/crates/lxst-core")
+ .to_path_buf()
+}
+
+#[test]
+fn python_lxst_reference_snapshot_is_available() {
+ if std::env::var(SKIP_ENV).map(|v| v == "1").unwrap_or(false) {
+ eprintln!("{SKIP_ENV}=1 -> skipping Python LXST reference snapshot");
+ return;
+ }
+
+ let script = repo_root().join("tools/reference/lxst_reference_snapshot.py");
+ let output = Command::new("python3")
+ .arg(script)
+ .output()
+ .expect("spawn Python LXST reference snapshot");
+
+ assert!(
+ output.status.success(),
+ "Python LXST reference snapshot failed\nstdout:\n{}\nstderr:\n{}",
+ String::from_utf8_lossy(&output.stdout),
+ String::from_utf8_lossy(&output.stderr)
+ );
+
+ let snapshot: Value = serde_json::from_slice(&output.stdout).expect("snapshot JSON");
+ let lock_path = repo_root().join("tools/reference/lxst_reference_lock.json");
+ let locked: Value =
+ serde_json::from_slice(&fs::read(lock_path).expect("read LXST reference lock"))
+ .expect("reference lock JSON");
+
+ assert_eq!(
+ snapshot["remote"].as_str(),
+ Some("https://github.com/markqvist/LXST.git")
+ );
+ assert_eq!(snapshot["dirty"].as_bool(), Some(false));
+ assert_eq!(snapshot["missing_files"].as_array().unwrap().len(), 0);
+ assert_eq!(
+ snapshot["remote"], locked["remote"],
+ "LXST upstream remote changed"
+ );
+ assert_eq!(
+ snapshot["commit"], locked["commit"],
+ "LXST source-of-truth commit changed; review upstream diff and update tools/reference/lxst_reference_lock.json intentionally"
+ );
+ assert_eq!(
+ snapshot["package_version"], locked["package_version"],
+ "LXST package version changed"
+ );
+
+ let files = snapshot["files"].as_object().expect("files object");
+ let locked_files = locked["files"].as_object().expect("locked files object");
+ for rel in [
+ "LXST/_version.py",
+ "LXST/Network.py",
+ "LXST/Primitives/Telephony.py",
+ "LXST/Codecs/__init__.py",
+ "LXST/Codecs/Raw.py",
+ "LXST/Codecs/Opus.py",
+ "LXST/Codecs/Codec2.py",
+ ] {
+ let entry = files.get(rel).unwrap_or_else(|| panic!("missing {rel}"));
+ let locked_entry = locked_files
+ .get(rel)
+ .unwrap_or_else(|| panic!("missing locked {rel}"));
+ let sha = entry["sha256"].as_str().expect("sha256");
+ assert_eq!(sha.len(), 64, "{rel}");
+ assert!(entry["bytes"].as_u64().unwrap_or(0) > 0, "{rel}");
+ assert_eq!(entry, locked_entry, "LXST reference file changed: {rel}");
+ }
+}
diff --git a/crates/lxst-rns/Cargo.toml b/crates/lxst-rns/Cargo.toml
new file mode 100644
index 0000000..8b226e2
--- /dev/null
+++ b/crates/lxst-rns/Cargo.toml
@@ -0,0 +1,18 @@
+[package]
+name = "lxst-rns"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+bytes.workspace = true
+lxst-core.workspace = true
+rns-link.workspace = true
+rns-transport.workspace = true
+rns-wire.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+
+[dev-dependencies]
+rns-crypto.workspace = true
diff --git a/crates/lxst-rns/src/lib.rs b/crates/lxst-rns/src/lib.rs
new file mode 100644
index 0000000..c46a835
--- /dev/null
+++ b/crates/lxst-rns/src/lib.rs
@@ -0,0 +1,659 @@
+//! Reticulum transport boundary for LXST.
+//!
+//! This crate is intentionally small: it turns already-encoded LXST packets into
+//! Reticulum link data packets and leaves call state, audio, and codec work to
+//! higher layers.
+
+use bytes::Bytes;
+use lxst_core::{
+ DropPolicy, Frame, FramePacketizer, FrameStreamEvent, FrameStreamState, JitterBuffer,
+ JitterPush, JitterStats, LxstPacket, OpusDecoderState, RawAudioFrame, RawBitDepth,
+};
+use rns_link::link::{Link, LinkState};
+use rns_transport::messages::{OutboundRequest, TransportMessage};
+use thiserror::Error;
+use tokio::sync::mpsc;
+
+#[derive(Debug, Error)]
+pub enum Error {
+ #[error("LXST core error: {0}")]
+ Lxst(#[from] lxst_core::Error),
+ #[error("LXST stream error: {0}")]
+ Stream(#[from] lxst_core::StreamError),
+ #[error("LXST Opus codec error: {0}")]
+ Opus(#[from] lxst_core::OpusCodecError),
+ #[error("Reticulum link is not active: {0:?}")]
+ LinkNotActive(LinkState),
+ #[error("LXST payload length {payload_len} exceeds link MDU {mdu}")]
+ PayloadExceedsMdu { payload_len: usize, mdu: usize },
+ #[error("Reticulum link encryption failed: {0}")]
+ LinkEncrypt(String),
+ #[error("Reticulum outbound queue is closed")]
+ TransportClosed,
+ #[error("Reticulum outbound queue is full")]
+ TransportFull,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PackedLinkPacket {
+ pub raw: Bytes,
+ pub packet_hash: [u8; 32],
+ pub destination_hash: [u8; 16],
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InboundLxstPacket {
+ pub link_id: [u8; 16],
+ pub packet: LxstPacket,
+ pub frame_events: Vec,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MediaIngressResult {
+ pub inbound: InboundLxstPacket,
+ pub jitter_pushes: Vec>,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct LxstLinkIngress {
+ frame_stream: FrameStreamState,
+}
+
+impl LxstLinkIngress {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub const fn current_codec(&self) -> Option {
+ self.frame_stream.current_codec()
+ }
+
+ /// Decode decrypted plaintext from `LinkManager::set_link_packet_channel`.
+ pub fn accept_plaintext(
+ &mut self,
+ link_id: [u8; 16],
+ payload: &[u8],
+ ) -> Result {
+ let packet = LxstPacket::decode(payload)?;
+ let frame_events = self.frame_stream.accept_packet(packet.clone());
+
+ Ok(InboundLxstPacket {
+ link_id,
+ packet,
+ frame_events,
+ })
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct LxstMediaEgress {
+ packetizer: FramePacketizer,
+}
+
+impl LxstMediaEgress {
+ pub const PYTHON_COMPATIBLE: Self = Self {
+ packetizer: FramePacketizer::PYTHON_COMPATIBLE,
+ };
+
+ pub fn new(frames_per_packet: usize) -> Result {
+ Ok(Self {
+ packetizer: FramePacketizer::new(frames_per_packet)?,
+ })
+ }
+
+ pub const fn packetizer(&self) -> FramePacketizer {
+ self.packetizer
+ }
+
+ pub fn pack_frames(
+ self,
+ link: &Link,
+ frames: impl IntoIterator
- ,
+ ) -> Result, Error> {
+ self.packetizer
+ .packetize(frames)
+ .iter()
+ .map(|packet| pack_lxst_link_packet(link, packet))
+ .collect()
+ }
+
+ pub fn pack_raw_frames(
+ self,
+ link: &Link,
+ bit_depth: RawBitDepth,
+ frames: impl IntoIterator
- ,
+ ) -> Result, Error> {
+ let frames = frames
+ .into_iter()
+ .map(|frame| frame.to_frame(bit_depth))
+ .collect::, _>>()?;
+ self.pack_frames(link, frames)
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LxstMediaIngress {
+ link_ingress: LxstLinkIngress,
+ jitter: JitterBuffer,
+}
+
+impl LxstMediaIngress {
+ pub fn new(jitter_capacity: usize, drop_policy: DropPolicy) -> Result {
+ Ok(Self {
+ link_ingress: LxstLinkIngress::new(),
+ jitter: JitterBuffer::new(jitter_capacity, drop_policy)?,
+ })
+ }
+
+ pub const fn current_codec(&self) -> Option {
+ self.link_ingress.current_codec()
+ }
+
+ pub const fn jitter_stats(&self) -> JitterStats {
+ self.jitter.stats()
+ }
+
+ pub fn jitter_len(&self) -> usize {
+ self.jitter.len()
+ }
+
+ pub fn accept_plaintext(
+ &mut self,
+ link_id: [u8; 16],
+ payload: &[u8],
+ ) -> Result {
+ let inbound = self.link_ingress.accept_plaintext(link_id, payload)?;
+ let mut jitter_pushes = Vec::new();
+
+ for event in &inbound.frame_events {
+ if let FrameStreamEvent::Frame(frame) = event {
+ jitter_pushes.push(self.jitter.push(frame.clone()));
+ }
+ }
+
+ Ok(MediaIngressResult {
+ inbound,
+ jitter_pushes,
+ })
+ }
+
+ pub fn pop_frame(&mut self) -> Option {
+ self.jitter.pop()
+ }
+
+ pub fn pop_raw_frame(&mut self) -> Result, Error> {
+ self.pop_frame()
+ .map(|frame| RawAudioFrame::from_frame(&frame).map_err(Error::from))
+ .transpose()
+ }
+
+ pub fn pop_opus_frame(
+ &mut self,
+ decoder: &mut OpusDecoderState,
+ ) -> Result, Error> {
+ self.pop_frame()
+ .map(|frame| decoder.decode_frame(&frame).map_err(Error::from))
+ .transpose()
+ }
+}
+
+/// Encode and encrypt an LXST packet for transmission over an active Reticulum
+/// link as a no-receipt data packet.
+pub fn pack_lxst_link_packet(link: &Link, packet: &LxstPacket) -> Result {
+ let payload = packet.encode()?;
+ pack_link_payload(link, &payload)
+}
+
+/// Encrypt application payload bytes and wrap them in a Reticulum LINK/DATA
+/// packet with context NONE, matching Python `RNS.Packet(link, data,
+/// create_receipt=False)`.
+pub fn pack_link_payload(link: &Link, payload: &[u8]) -> Result {
+ if link.state != LinkState::Active {
+ return Err(Error::LinkNotActive(link.state));
+ }
+
+ if payload.len() > link.mdu {
+ return Err(Error::PayloadExceedsMdu {
+ payload_len: payload.len(),
+ mdu: link.mdu,
+ });
+ }
+
+ let encrypted = link
+ .encrypt(payload)
+ .map_err(|e| Error::LinkEncrypt(e.to_string()))?;
+ let header = rns_wire::header::PacketHeader {
+ flags: rns_wire::flags::PacketFlags {
+ header_type: rns_wire::flags::HeaderType::Header1,
+ context_flag: false,
+ transport_type: rns_wire::flags::TransportType::Broadcast,
+ destination_type: rns_wire::flags::DestinationType::Link,
+ packet_type: rns_wire::flags::PacketType::Data,
+ },
+ hops: 0,
+ transport_id: None,
+ destination_hash: link.link_id,
+ context: rns_wire::context::PacketContext::None,
+ };
+
+ let mut raw = header.pack();
+ raw.extend_from_slice(&encrypted);
+ let packet_hash = rns_wire::hash::packet_hash(&raw, rns_wire::flags::HeaderType::Header1);
+
+ Ok(PackedLinkPacket {
+ raw: Bytes::from(raw),
+ packet_hash,
+ destination_hash: link.link_id,
+ })
+}
+
+/// Pack and queue an already-encoded LXST payload for Reticulum transmission.
+pub fn queue_link_payload(
+ transport_tx: &mpsc::Sender,
+ link: &Link,
+ payload: &[u8],
+) -> Result {
+ let packet = pack_link_payload(link, payload)?;
+ queue_packed_link_packet(transport_tx, packet)
+}
+
+/// Pack and queue a structured LXST packet for Reticulum transmission.
+pub fn queue_lxst_link_packet(
+ transport_tx: &mpsc::Sender,
+ link: &Link,
+ packet: &LxstPacket,
+) -> Result {
+ let packet = pack_lxst_link_packet(link, packet)?;
+ queue_packed_link_packet(transport_tx, packet)
+}
+
+fn queue_packed_link_packet(
+ transport_tx: &mpsc::Sender,
+ packet: PackedLinkPacket,
+) -> Result {
+ transport_tx
+ .try_send(TransportMessage::Outbound(OutboundRequest {
+ raw: packet.raw.clone(),
+ destination_hash: packet.destination_hash,
+ }))
+ .map_err(|e| match e {
+ mpsc::error::TrySendError::Full(_) => Error::TransportFull,
+ mpsc::error::TrySendError::Closed(_) => Error::TransportClosed,
+ })?;
+
+ Ok(packet)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use lxst_core::{
+ CodecKind, DropPolicy, Frame, FrameStreamEvent, OpusDecoderState, OpusEncoderState,
+ Profile, Signal, SignallingStatus, SyntheticSource, SyntheticSourceKind,
+ };
+ use rns_crypto::ed25519::Ed25519PrivateKey;
+
+ fn active_link_pair() -> (Link, Link) {
+ let dest_hash = [0xAA; 16];
+ let identity_key = Ed25519PrivateKey::generate();
+ let identity_pub = identity_key.public_key();
+
+ let (mut initiator, request_data) = Link::new_initiator(dest_hash, 1);
+ let (mut responder, proof_data) =
+ Link::new_responder(&request_data, &identity_key, dest_hash, 1).unwrap();
+
+ let rtt_data = initiator
+ .validate_proof(&proof_data, &identity_pub, &identity_pub.to_bytes())
+ .unwrap();
+ responder.receive_rtt_packet(&rtt_data).unwrap();
+
+ (initiator, responder)
+ }
+
+ #[test]
+ fn packed_lxst_packet_decrypts_on_peer_link() {
+ let (initiator, responder) = active_link_pair();
+ let lxst = LxstPacket::signalling([
+ Signal::from(SignallingStatus::Available),
+ Signal::from(Profile::QualityMedium),
+ ]);
+
+ let packet = pack_lxst_link_packet(&initiator, &lxst).unwrap();
+ let (header, data_offset) = rns_wire::header::PacketHeader::unpack(&packet.raw).unwrap();
+
+ assert_eq!(
+ header.flags.destination_type,
+ rns_wire::flags::DestinationType::Link
+ );
+ assert_eq!(header.flags.packet_type, rns_wire::flags::PacketType::Data);
+ assert_eq!(header.context, rns_wire::context::PacketContext::None);
+ assert_eq!(header.destination_hash, initiator.link_id);
+
+ let decrypted = responder.decrypt(&packet.raw[data_offset..]).unwrap();
+ assert_eq!(LxstPacket::decode(&decrypted).unwrap(), lxst);
+ }
+
+ #[test]
+ fn queue_sends_outbound_transport_message() {
+ let (initiator, _responder) = active_link_pair();
+ let payload = LxstPacket::frame(Frame::new(CodecKind::Raw, [0x00, 0x11, 0x22]))
+ .encode()
+ .unwrap();
+ let (tx, mut rx) = mpsc::channel(1);
+
+ let packet = queue_link_payload(&tx, &initiator, &payload).unwrap();
+ let sent = rx.try_recv().unwrap();
+ let TransportMessage::Outbound(outbound) = sent else {
+ panic!("expected outbound transport message");
+ };
+
+ assert_eq!(outbound.raw, packet.raw);
+ assert_eq!(outbound.destination_hash, initiator.link_id);
+ }
+
+ #[test]
+ fn inactive_links_do_not_pack_media_packets() {
+ let (link, _request_data) = Link::new_initiator([0xBB; 16], 1);
+ let packet = LxstPacket::signalling([Signal::from(SignallingStatus::Calling)]);
+
+ assert!(matches!(
+ pack_lxst_link_packet(&link, &packet),
+ Err(Error::LinkNotActive(LinkState::Pending))
+ ));
+ }
+
+ #[test]
+ fn payloads_must_fit_link_mdu() {
+ let (initiator, _responder) = active_link_pair();
+ let payload = vec![0u8; initiator.mdu + 1];
+
+ assert!(matches!(
+ pack_link_payload(&initiator, &payload),
+ Err(Error::PayloadExceedsMdu { .. })
+ ));
+ }
+
+ #[test]
+ fn ingress_decodes_decrypted_link_payloads_and_tracks_codecs() {
+ let link_id = [0x44; 16];
+ let mut ingress = LxstLinkIngress::new();
+ let packet = LxstPacket {
+ signals: vec![Signal::from(SignallingStatus::Established)],
+ frames: vec![
+ Frame::new(CodecKind::Raw, [0x00, 0x11]),
+ Frame::new(CodecKind::Opus, [0xF8, 0xFF, 0xFE]),
+ ],
+ };
+
+ let inbound = ingress
+ .accept_plaintext(link_id, &packet.encode().unwrap())
+ .unwrap();
+
+ assert_eq!(inbound.link_id, link_id);
+ assert_eq!(inbound.packet.signals, packet.signals);
+ assert_eq!(
+ inbound.frame_events,
+ vec![
+ FrameStreamEvent::CodecChanged {
+ from: None,
+ to: CodecKind::Raw,
+ },
+ FrameStreamEvent::Frame(Frame::new(CodecKind::Raw, [0x00, 0x11])),
+ FrameStreamEvent::CodecChanged {
+ from: Some(CodecKind::Raw),
+ to: CodecKind::Opus,
+ },
+ FrameStreamEvent::Frame(Frame::new(CodecKind::Opus, [0xF8, 0xFF, 0xFE])),
+ ]
+ );
+ assert_eq!(ingress.current_codec(), Some(CodecKind::Opus));
+ }
+
+ #[test]
+ fn ingress_rejects_malformed_plaintext() {
+ let mut ingress = LxstLinkIngress::new();
+ assert!(matches!(
+ ingress.accept_plaintext([0x55; 16], b"not msgpack"),
+ Err(Error::Lxst(_))
+ ));
+ }
+
+ #[test]
+ fn media_egress_and_ingress_roundtrip_raw_frames_over_link_crypto() {
+ let (initiator, responder) = active_link_pair();
+ let raw_frames = vec![
+ RawAudioFrame::new(2, vec![0.0, 0.5, -0.25, 1.0]).unwrap(),
+ RawAudioFrame::new(2, vec![0.125, -0.125, 0.75, -0.75]).unwrap(),
+ ];
+
+ let packed = LxstMediaEgress::PYTHON_COMPATIBLE
+ .pack_raw_frames(&initiator, RawBitDepth::Float16, raw_frames.clone())
+ .unwrap();
+ assert_eq!(packed.len(), raw_frames.len());
+
+ let mut ingress = LxstMediaIngress::new(4, DropPolicy::DropOldest).unwrap();
+ for packet in packed {
+ let (_header, data_offset) = rns_wire::header::PacketHeader::unpack(&packet.raw)
+ .expect("packed Reticulum header");
+ let plaintext = responder.decrypt(&packet.raw[data_offset..]).unwrap();
+ let result = ingress
+ .accept_plaintext(responder.link_id, &plaintext)
+ .expect("accept LXST payload");
+ assert_eq!(result.jitter_pushes, vec![JitterPush::Accepted]);
+ }
+
+ assert_eq!(ingress.current_codec(), Some(CodecKind::Raw));
+ assert_eq!(ingress.jitter_len(), raw_frames.len());
+ assert_eq!(
+ ingress.pop_raw_frame().unwrap(),
+ Some(raw_frames[0].clone())
+ );
+ assert_eq!(
+ ingress.pop_raw_frame().unwrap(),
+ Some(raw_frames[1].clone())
+ );
+ assert_eq!(ingress.pop_raw_frame().unwrap(), None);
+ assert_eq!(
+ ingress.jitter_stats(),
+ JitterStats {
+ pushed: 2,
+ popped: 2,
+ dropped_oldest: 0,
+ dropped_newest: 0,
+ underruns: 1,
+ }
+ );
+ }
+
+ #[test]
+ fn media_egress_can_batch_frames_for_rust_peers() {
+ let (initiator, responder) = active_link_pair();
+ let raw_frames = vec![
+ RawAudioFrame::new(1, vec![0.0]).unwrap(),
+ RawAudioFrame::new(1, vec![0.5]).unwrap(),
+ RawAudioFrame::new(1, vec![1.0]).unwrap(),
+ ];
+
+ let packed = LxstMediaEgress::new(2)
+ .unwrap()
+ .pack_raw_frames(&initiator, RawBitDepth::Float32, raw_frames.clone())
+ .unwrap();
+ assert_eq!(packed.len(), 2);
+
+ let mut ingress = LxstMediaIngress::new(8, DropPolicy::DropNewest).unwrap();
+ for packet in packed {
+ let (_header, data_offset) = rns_wire::header::PacketHeader::unpack(&packet.raw)
+ .expect("packed Reticulum header");
+ let plaintext = responder.decrypt(&packet.raw[data_offset..]).unwrap();
+ ingress
+ .accept_plaintext(responder.link_id, &plaintext)
+ .expect("accept LXST payload");
+ }
+
+ assert_eq!(
+ ingress.pop_raw_frame().unwrap(),
+ Some(raw_frames[0].clone())
+ );
+ assert_eq!(
+ ingress.pop_raw_frame().unwrap(),
+ Some(raw_frames[1].clone())
+ );
+ assert_eq!(
+ ingress.pop_raw_frame().unwrap(),
+ Some(raw_frames[2].clone())
+ );
+ }
+
+ #[test]
+ fn media_ingress_jitter_policy_drops_oldest_under_pressure() {
+ let (initiator, responder) = active_link_pair();
+ let raw_frames = vec![
+ RawAudioFrame::new(1, vec![0.0]).unwrap(),
+ RawAudioFrame::new(1, vec![1.0]).unwrap(),
+ ];
+ let packed = LxstMediaEgress::PYTHON_COMPATIBLE
+ .pack_raw_frames(&initiator, RawBitDepth::Float16, raw_frames.clone())
+ .unwrap();
+ let mut ingress = LxstMediaIngress::new(1, DropPolicy::DropOldest).unwrap();
+
+ let mut push_results = Vec::new();
+ for packet in packed {
+ let (_header, data_offset) = rns_wire::header::PacketHeader::unpack(&packet.raw)
+ .expect("packed Reticulum header");
+ let plaintext = responder.decrypt(&packet.raw[data_offset..]).unwrap();
+ let result = ingress
+ .accept_plaintext(responder.link_id, &plaintext)
+ .unwrap();
+ push_results.extend(result.jitter_pushes);
+ }
+
+ assert!(matches!(push_results[0], JitterPush::Accepted));
+ assert!(matches!(push_results[1], JitterPush::DroppedOldest(_)));
+ assert_eq!(
+ ingress.pop_raw_frame().unwrap(),
+ Some(raw_frames[1].clone())
+ );
+ assert_eq!(
+ ingress.jitter_stats(),
+ JitterStats {
+ pushed: 2,
+ popped: 1,
+ dropped_oldest: 1,
+ dropped_newest: 0,
+ underruns: 0,
+ }
+ );
+ }
+
+ #[test]
+ fn synthetic_raw_source_survives_link_media_flow() {
+ let (initiator, responder) = active_link_pair();
+ let mut source = SyntheticSource::new(
+ 2,
+ 48_000,
+ 4,
+ SyntheticSourceKind::Ramp {
+ start: -0.5,
+ step: 0.125,
+ },
+ )
+ .unwrap();
+ let expected = (0..12)
+ .map(|_| source.next_raw_frame().unwrap())
+ .collect::>();
+
+ let packed = LxstMediaEgress::PYTHON_COMPATIBLE
+ .pack_raw_frames(&initiator, RawBitDepth::Float32, expected.clone())
+ .unwrap();
+ let mut ingress = LxstMediaIngress::new(16, DropPolicy::DropOldest).unwrap();
+
+ for packet in packed {
+ let (_header, data_offset) =
+ rns_wire::header::PacketHeader::unpack(&packet.raw).unwrap();
+ let plaintext = responder.decrypt(&packet.raw[data_offset..]).unwrap();
+ ingress
+ .accept_plaintext(responder.link_id, &plaintext)
+ .unwrap();
+ }
+
+ let mut actual = Vec::new();
+ while let Some(frame) = ingress.pop_raw_frame().unwrap() {
+ actual.push(frame);
+ }
+
+ assert_eq!(actual, expected);
+ assert_eq!(
+ ingress.jitter_stats(),
+ JitterStats {
+ pushed: 12,
+ popped: 12,
+ dropped_oldest: 0,
+ dropped_newest: 0,
+ underruns: 1,
+ }
+ );
+ }
+
+ #[test]
+ fn sustained_opus_source_survives_link_media_flow() {
+ let (initiator, responder) = active_link_pair();
+ let profile = Profile::QualityHigh;
+ let mut source = SyntheticSource::new(
+ profile.channels(),
+ profile.sample_rate_hz(),
+ profile.sample_frames_per_packet(),
+ SyntheticSourceKind::Sine {
+ frequency_hz: 440.0,
+ amplitude: 0.25,
+ },
+ )
+ .unwrap();
+ let raw_frames = (0..12)
+ .map(|_| source.next_raw_frame().unwrap())
+ .collect::>();
+ let mut encoder = OpusEncoderState::new(profile).unwrap();
+ let opus_frames = raw_frames
+ .iter()
+ .map(|frame| encoder.encode_frame(frame).unwrap())
+ .collect::>();
+
+ let packed = LxstMediaEgress::PYTHON_COMPATIBLE
+ .pack_frames(&initiator, opus_frames)
+ .unwrap();
+ assert_eq!(packed.len(), raw_frames.len());
+
+ let mut ingress = LxstMediaIngress::new(16, DropPolicy::DropOldest).unwrap();
+ for packet in packed {
+ let (_header, data_offset) =
+ rns_wire::header::PacketHeader::unpack(&packet.raw).unwrap();
+ let plaintext = responder.decrypt(&packet.raw[data_offset..]).unwrap();
+ let result = ingress
+ .accept_plaintext(responder.link_id, &plaintext)
+ .unwrap();
+ assert_eq!(result.jitter_pushes, vec![JitterPush::Accepted]);
+ }
+
+ let mut decoder = OpusDecoderState::new(profile).unwrap();
+ let mut decoded_frames = Vec::new();
+ while let Some(frame) = ingress.pop_opus_frame(&mut decoder).unwrap() {
+ decoded_frames.push(frame);
+ }
+
+ assert_eq!(decoded_frames.len(), raw_frames.len());
+ assert_eq!(ingress.current_codec(), Some(CodecKind::Opus));
+ for frame in decoded_frames {
+ assert_eq!(frame.channels, profile.channels());
+ assert_eq!(frame.sample_frames(), profile.sample_frames_per_packet());
+ }
+ assert_eq!(
+ ingress.jitter_stats(),
+ JitterStats {
+ pushed: 12,
+ popped: 12,
+ dropped_oldest: 0,
+ dropped_newest: 0,
+ underruns: 1,
+ }
+ );
+ }
+}
diff --git a/crates/lxst-telephony/Cargo.toml b/crates/lxst-telephony/Cargo.toml
new file mode 100644
index 0000000..01df927
--- /dev/null
+++ b/crates/lxst-telephony/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "lxst-telephony"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+
+[dependencies]
+bytes.workspace = true
+lxst-core.workspace = true
+lxst-rns.workspace = true
+rns-crypto.workspace = true
+rns-identity.workspace = true
+rns-link.workspace = true
+rns-runtime.workspace = true
+rns-transport.workspace = true
+rns-wire.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+
+[dev-dependencies]
+hex.workspace = true
+rns-interface.workspace = true
+serial_test.workspace = true
+serde_json.workspace = true
diff --git a/crates/lxst-telephony/src/lib.rs b/crates/lxst-telephony/src/lib.rs
new file mode 100644
index 0000000..2b04f8f
--- /dev/null
+++ b/crates/lxst-telephony/src/lib.rs
@@ -0,0 +1,2863 @@
+//! Telephony runtime core for LXST.
+//!
+//! This crate owns the deterministic call-control boundary between Reticulum
+//! link events and the pure LXST signalling planner. It deliberately avoids
+//! spawning tasks or touching audio devices so live runtime code can be a thin
+//! adapter around tested protocol behavior.
+
+use std::collections::{HashMap, HashSet};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use bytes::Bytes;
+use lxst_core::{
+ CallRole, CodecKind, Frame, FrameStreamEvent, LxstPacket, OpusCodecError, OpusDecoderState,
+ OpusEncoderState, Profile, RawAudioFrame, RawBitDepth, Signal, SignallingStatus,
+ TELEPHONY_DESTINATION_NAME, TelephonyAction, TelephonyCall,
+};
+use lxst_rns::{InboundLxstPacket, LxstLinkIngress, LxstMediaEgress, queue_lxst_link_packet};
+use rns_crypto::ed25519::{Ed25519PrivateKey, Ed25519PublicKey};
+use rns_identity::destination::{
+ DestType, Destination, DestinationError, Direction, ProofStrategy,
+};
+use rns_identity::identity::Identity;
+use rns_identity::name_hash::name_hash;
+use rns_link::link::{CloseReason, Link};
+use rns_runtime::link_manager::LinkManager;
+use rns_transport::link_messages::DestinationEvent;
+use rns_transport::messages::{
+ AnnounceHandlerEvent, AnnounceRpcEntry, OutboundRequest, TransportMessage, TransportQuery,
+ TransportQueryResponse,
+};
+use thiserror::Error;
+use tokio::sync::mpsc;
+use tokio::time::{Duration, Instant, timeout};
+
+pub type LinkId = [u8; 16];
+pub type IdentityHash = [u8; 16];
+
+pub const TELEPHONY_ANNOUNCE_INTERVAL: Duration = Duration::from_secs(60 * 60 * 3);
+pub const TELEPHONY_STARTUP_ANNOUNCE_RETRY_INTERVAL: Duration = Duration::from_secs(5);
+pub const TELEPHONY_STARTUP_ANNOUNCE_RETRIES: u8 = 6;
+
+#[derive(Debug, Error)]
+pub enum Error {
+ #[error("Reticulum destination error: {0}")]
+ Destination(#[from] DestinationError),
+ #[error("LXST Reticulum boundary error: {0}")]
+ Rns(#[from] lxst_rns::Error),
+ #[error("LXST Opus codec error: {0}")]
+ Opus(#[from] OpusCodecError),
+ #[error("unknown LXST link")]
+ UnknownLink,
+ #[error("line is busy")]
+ LineBusy,
+ #[error("no active call")]
+ NoActiveCall,
+ #[error("active call is not established")]
+ CallNotEstablished,
+ #[error("requested media profile {requested:?} does not match active call profile {active:?}")]
+ MediaProfileMismatch { active: Profile, requested: Profile },
+ #[error("active call is on a different link")]
+ WrongActiveLink,
+ #[error("local identity does not contain a signing key")]
+ NoSigningKey,
+ #[error("Reticulum transport queue is closed")]
+ TransportClosed,
+ #[error("Reticulum transport queue is full")]
+ TransportFull,
+ #[error("LXST telephony service event queue is closed")]
+ ServiceEventClosed,
+ #[error("LXST telephony service event queue is full")]
+ ServiceEventFull,
+ #[error("Reticulum transport query channel closed")]
+ TransportQueryClosed,
+ #[error("unexpected Reticulum transport query response")]
+ UnexpectedTransportQueryResponse,
+ #[error("Reticulum link operation failed: {0}")]
+ LinkOperation(String),
+ #[error("Reticulum link proof validation failed: {0}")]
+ LinkProofInvalid(String),
+ #[error("Reticulum link destination channel closed")]
+ LinkDestinationClosed,
+ #[error("unexpected Reticulum destination event for link")]
+ UnexpectedLinkEvent,
+ #[error("remote LXST telephony announce did not include a Reticulum public key")]
+ RemotePublicKeyMissing,
+ #[error("remote LXST telephony announce was not discovered before timeout")]
+ RemoteTelephonyPeerNotDiscovered,
+ #[error("remote LXST telephony Reticulum path was not discovered before timeout")]
+ RemotePathNotDiscovered,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RemoteTelephonyPeer {
+ pub identity_hash: IdentityHash,
+ pub destination_hash: [u8; 16],
+ pub public_key: [u8; 64],
+ pub hops: u8,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum CallerAllowPolicy {
+ All,
+ None,
+ List(Vec),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CallerAccessPolicy {
+ pub allowed: CallerAllowPolicy,
+ pub blocked: Vec,
+}
+
+impl Default for CallerAccessPolicy {
+ fn default() -> Self {
+ Self {
+ allowed: CallerAllowPolicy::All,
+ blocked: Vec::new(),
+ }
+ }
+}
+
+impl CallerAccessPolicy {
+ pub fn is_allowed(&self, identity_hash: &IdentityHash) -> bool {
+ if self.blocked.iter().any(|blocked| blocked == identity_hash) {
+ return false;
+ }
+
+ match &self.allowed {
+ CallerAllowPolicy::All => true,
+ CallerAllowPolicy::None => false,
+ CallerAllowPolicy::List(allowed) => {
+ allowed.iter().any(|allowed| allowed == identity_hash)
+ }
+ }
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TelephonyCommand {
+ SendSignal {
+ link_id: LinkId,
+ signal: Signal,
+ },
+ IdentifyLocalIdentity {
+ link_id: LinkId,
+ },
+ SelectProfile {
+ link_id: LinkId,
+ profile: Profile,
+ },
+ SwitchProfile {
+ link_id: LinkId,
+ profile: Profile,
+ },
+ PrepareDialingPipelines {
+ link_id: LinkId,
+ },
+ ResetDialingPipelines {
+ link_id: LinkId,
+ },
+ OpenAudioPipelines {
+ link_id: LinkId,
+ },
+ StartAudioPipelines {
+ link_id: LinkId,
+ },
+ StopAudioPipelines {
+ link_id: LinkId,
+ },
+ StartDialTone {
+ link_id: LinkId,
+ },
+ RingIncomingCall {
+ link_id: LinkId,
+ remote_identity: IdentityHash,
+ },
+ CallTerminated {
+ link_id: LinkId,
+ reason: Option,
+ },
+ TeardownLink {
+ link_id: LinkId,
+ },
+ IgnoredSignal {
+ link_id: LinkId,
+ signal: Signal,
+ },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TelephonyCommandEffect {
+ Noop,
+ QueuedLinkPacket {
+ link_id: LinkId,
+ kind: QueuedLinkPacketKind,
+ },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum QueuedLinkPacketKind {
+ LxstData,
+ LinkIdentify,
+ LinkClose,
+}
+
+impl TelephonyCommand {
+ pub const fn link_id(&self) -> LinkId {
+ match self {
+ Self::SendSignal { link_id, .. }
+ | Self::IdentifyLocalIdentity { link_id }
+ | Self::SelectProfile { link_id, .. }
+ | Self::SwitchProfile { link_id, .. }
+ | Self::PrepareDialingPipelines { link_id }
+ | Self::ResetDialingPipelines { link_id }
+ | Self::OpenAudioPipelines { link_id }
+ | Self::StartAudioPipelines { link_id }
+ | Self::StopAudioPipelines { link_id }
+ | Self::StartDialTone { link_id }
+ | Self::RingIncomingCall { link_id, .. }
+ | Self::CallTerminated { link_id, .. }
+ | Self::TeardownLink { link_id }
+ | Self::IgnoredSignal { link_id, .. } => *link_id,
+ }
+ }
+
+ pub const fn signal(&self) -> Option {
+ match self {
+ Self::SendSignal { signal, .. } => Some(*signal),
+ _ => None,
+ }
+ }
+
+ pub fn to_lxst_packet(&self) -> Option {
+ self.signal().map(signalling_packet)
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TelephonyStep {
+ pub inbound: Option,
+ pub commands: Vec,
+}
+
+impl TelephonyStep {
+ pub fn commands(commands: Vec) -> Self {
+ Self {
+ inbound: None,
+ commands,
+ }
+ }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TelephonyDriveStep {
+ pub step: TelephonyStep,
+ pub effects: Vec,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TelephonyLinkEvent {
+ LinkEstablished {
+ link_id: LinkId,
+ },
+ IncomingLinkEstablished {
+ link_id: LinkId,
+ },
+ OutgoingLinkEstablished {
+ link_id: LinkId,
+ },
+ RemoteIdentified {
+ link_id: LinkId,
+ remote_identity: IdentityHash,
+ },
+ LinkPacket {
+ link_id: LinkId,
+ plaintext: Vec,
+ },
+ LinkClosed {
+ link_id: LinkId,
+ },
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ActiveCall {
+ pub link_id: LinkId,
+ pub remote_identity: IdentityHash,
+ pub call: TelephonyCall,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ActiveCallSnapshot {
+ pub link_id: LinkId,
+ pub remote_identity: IdentityHash,
+ pub role: CallRole,
+ pub status: SignallingStatus,
+ pub profile: Option,
+ pub answered: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TelephonyRuntimeSnapshot {
+ pub external_busy: bool,
+ pub pending_link_count: usize,
+ pub active_call: Option,
+}
+
+#[derive(Debug, Default)]
+pub struct TelephonyRuntimeCore {
+ access: CallerAccessPolicy,
+ external_busy: bool,
+ pending_links: HashSet,
+ ingress: HashMap,
+ active_call: Option,
+}
+
+impl TelephonyRuntimeCore {
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ pub fn with_access_policy(access: CallerAccessPolicy) -> Self {
+ Self {
+ access,
+ ..Self::default()
+ }
+ }
+
+ pub const fn access_policy(&self) -> &CallerAccessPolicy {
+ &self.access
+ }
+
+ pub fn set_access_policy(&mut self, access: CallerAccessPolicy) {
+ self.access = access;
+ }
+
+ pub const fn external_busy(&self) -> bool {
+ self.external_busy
+ }
+
+ pub fn set_external_busy(&mut self, busy: bool) {
+ self.external_busy = busy;
+ }
+
+ pub fn line_busy(&self) -> bool {
+ self.external_busy || self.active_call.is_some()
+ }
+
+ pub fn active_call(&self) -> Option<&ActiveCall> {
+ self.active_call.as_ref()
+ }
+
+ pub fn pending_link_count(&self) -> usize {
+ self.pending_links.len()
+ }
+
+ pub fn snapshot(&self) -> TelephonyRuntimeSnapshot {
+ TelephonyRuntimeSnapshot {
+ external_busy: self.external_busy,
+ pending_link_count: self.pending_links.len(),
+ active_call: self.active_call.as_ref().map(|active| ActiveCallSnapshot {
+ link_id: active.link_id,
+ remote_identity: active.remote_identity,
+ role: active.call.role(),
+ status: active.call.status(),
+ profile: active.call.profile(),
+ answered: active.call.answered(),
+ }),
+ }
+ }
+
+ pub fn incoming_link_established(&mut self, link_id: LinkId) -> Vec {
+ let actions = TelephonyCall::incoming_link_established(self.line_busy());
+ if !self.line_busy() {
+ self.pending_links.insert(link_id);
+ self.ingress.entry(link_id).or_default();
+ }
+
+ self.commands_from_actions(link_id, None, actions)
+ }
+
+ pub fn caller_identified(
+ &mut self,
+ link_id: LinkId,
+ remote_identity: IdentityHash,
+ ) -> Result, Error> {
+ if !self.pending_links.contains(&link_id) && !self.ingress.contains_key(&link_id) {
+ return Err(Error::UnknownLink);
+ }
+
+ let allowed = self.access.is_allowed(&remote_identity);
+ let busy = self.line_busy();
+ let mut call = TelephonyCall::incoming();
+ let actions = call.caller_identified(busy, allowed);
+
+ if busy || !allowed {
+ self.pending_links.remove(&link_id);
+ self.ingress.remove(&link_id);
+ return Ok(self.commands_from_actions(link_id, Some(remote_identity), actions));
+ }
+
+ self.pending_links.remove(&link_id);
+ self.active_call = Some(ActiveCall {
+ link_id,
+ remote_identity,
+ call,
+ });
+
+ Ok(self.commands_from_actions(link_id, Some(remote_identity), actions))
+ }
+
+ pub fn start_outgoing_call(
+ &mut self,
+ link_id: LinkId,
+ remote_identity: IdentityHash,
+ profile: Option,
+ ) -> Result<(), Error> {
+ if self.line_busy() {
+ return Err(Error::LineBusy);
+ }
+
+ self.ingress.entry(link_id).or_default();
+ self.active_call = Some(ActiveCall {
+ link_id,
+ remote_identity,
+ call: TelephonyCall::outgoing(profile),
+ });
+ Ok(())
+ }
+
+ pub fn outgoing_link_established(&mut self, link_id: LinkId) -> Result<(), Error> {
+ let active = self.active_call.as_ref().ok_or(Error::NoActiveCall)?;
+ if active.link_id != link_id {
+ return Err(Error::WrongActiveLink);
+ }
+ self.ingress.entry(link_id).or_default();
+ Ok(())
+ }
+
+ pub fn answer_active(&mut self) -> Result, Error> {
+ let active = self.active_call.as_mut().ok_or(Error::NoActiveCall)?;
+ let link_id = active.link_id;
+ let remote_identity = active.remote_identity;
+ let actions = active.call.answer();
+ Ok(self.commands_from_actions(link_id, Some(remote_identity), actions))
+ }
+
+ pub fn switch_active_profile(
+ &mut self,
+ profile: Profile,
+ ) -> Result, Error> {
+ let active = self.active_call.as_mut().ok_or(Error::NoActiveCall)?;
+ if active.call.status() != SignallingStatus::Established {
+ return Err(Error::CallNotEstablished);
+ }
+
+ let link_id = active.link_id;
+ let remote_identity = active.remote_identity;
+ let actions = active.call.switch_profile(profile);
+ Ok(self.commands_from_actions(link_id, Some(remote_identity), actions))
+ }
+
+ pub fn hangup_active(&mut self, ring_timeout: bool) -> Result, Error> {
+ let Some(mut active) = self.active_call.take() else {
+ return Err(Error::NoActiveCall);
+ };
+ let link_id = active.link_id;
+ let remote_identity = active.remote_identity;
+ let mut commands = self.commands_from_actions(
+ link_id,
+ Some(remote_identity),
+ active.call.hangup(ring_timeout),
+ );
+ commands.push(TelephonyCommand::StopAudioPipelines { link_id });
+ commands.push(TelephonyCommand::CallTerminated {
+ link_id,
+ reason: None,
+ });
+ self.pending_links.remove(&link_id);
+ self.ingress.remove(&link_id);
+ Ok(commands)
+ }
+
+ pub fn shutdown(&mut self) -> Vec {
+ let mut commands = Vec::new();
+
+ if let Some(mut active) = self.active_call.take() {
+ let link_id = active.link_id;
+ let remote_identity = active.remote_identity;
+ commands.extend(self.commands_from_actions(
+ link_id,
+ Some(remote_identity),
+ active.call.hangup(false),
+ ));
+ commands.push(TelephonyCommand::StopAudioPipelines { link_id });
+ commands.push(TelephonyCommand::CallTerminated {
+ link_id,
+ reason: None,
+ });
+ self.pending_links.remove(&link_id);
+ self.ingress.remove(&link_id);
+ }
+
+ for link_id in self.pending_links.drain().collect::>() {
+ self.ingress.remove(&link_id);
+ commands.push(TelephonyCommand::TeardownLink { link_id });
+ }
+ self.ingress.clear();
+
+ commands
+ }
+
+ pub fn link_closed(&mut self, link_id: LinkId) -> Vec {
+ self.pending_links.remove(&link_id);
+ self.ingress.remove(&link_id);
+
+ if self
+ .active_call
+ .as_ref()
+ .is_some_and(|active| active.link_id == link_id)
+ {
+ self.active_call.take();
+ vec![
+ TelephonyCommand::StopAudioPipelines { link_id },
+ TelephonyCommand::CallTerminated {
+ link_id,
+ reason: None,
+ },
+ ]
+ } else {
+ Vec::new()
+ }
+ }
+
+ pub fn accept_lxst_plaintext(
+ &mut self,
+ link_id: LinkId,
+ payload: &[u8],
+ ) -> Result {
+ let ingress = self.ingress.get_mut(&link_id).ok_or(Error::UnknownLink)?;
+ let inbound = ingress.accept_plaintext(link_id, payload)?;
+ let mut commands = Vec::new();
+
+ for signal in inbound.packet.signals.clone() {
+ commands.extend(self.receive_signal(link_id, signal)?);
+ }
+
+ Ok(TelephonyStep {
+ inbound: Some(inbound),
+ commands,
+ })
+ }
+
+ pub fn accept_link_event(&mut self, event: TelephonyLinkEvent) -> Result {
+ match event {
+ TelephonyLinkEvent::LinkEstablished { link_id } => {
+ if self.active_call.as_ref().is_some_and(|active| {
+ active.link_id == link_id && active.call.role() == CallRole::Outgoing
+ }) {
+ self.outgoing_link_established(link_id)?;
+ Ok(TelephonyStep::commands(Vec::new()))
+ } else {
+ Ok(TelephonyStep::commands(
+ self.incoming_link_established(link_id),
+ ))
+ }
+ }
+ TelephonyLinkEvent::IncomingLinkEstablished { link_id } => Ok(TelephonyStep::commands(
+ self.incoming_link_established(link_id),
+ )),
+ TelephonyLinkEvent::OutgoingLinkEstablished { link_id } => {
+ self.outgoing_link_established(link_id)?;
+ Ok(TelephonyStep::commands(Vec::new()))
+ }
+ TelephonyLinkEvent::RemoteIdentified {
+ link_id,
+ remote_identity,
+ } => Ok(TelephonyStep::commands(
+ self.caller_identified(link_id, remote_identity)?,
+ )),
+ TelephonyLinkEvent::LinkPacket { link_id, plaintext } => {
+ self.accept_lxst_plaintext(link_id, &plaintext)
+ }
+ TelephonyLinkEvent::LinkClosed { link_id } => {
+ Ok(TelephonyStep::commands(self.link_closed(link_id)))
+ }
+ }
+ }
+
+ pub fn receive_signal(
+ &mut self,
+ link_id: LinkId,
+ signal: Signal,
+ ) -> Result, Error> {
+ let active = self.active_call.as_mut().ok_or(Error::NoActiveCall)?;
+ if active.link_id != link_id {
+ return Err(Error::WrongActiveLink);
+ }
+
+ let remote_identity = active.remote_identity;
+ let actions = active.call.receive_signal(signal);
+ let terminates = actions.iter().find_map(|action| match action {
+ TelephonyAction::Terminate(reason) => Some(*reason),
+ _ => None,
+ });
+ let mut commands = self.commands_from_actions(link_id, Some(remote_identity), actions);
+
+ if let Some(reason) = terminates {
+ commands.push(TelephonyCommand::StopAudioPipelines { link_id });
+ commands.push(TelephonyCommand::TeardownLink { link_id });
+ commands.push(TelephonyCommand::CallTerminated { link_id, reason });
+ self.active_call.take();
+ self.pending_links.remove(&link_id);
+ self.ingress.remove(&link_id);
+ }
+
+ Ok(commands)
+ }
+
+ fn commands_from_actions(
+ &self,
+ link_id: LinkId,
+ remote_identity: Option,
+ actions: Vec,
+ ) -> Vec {
+ actions
+ .into_iter()
+ .filter_map(|action| match action {
+ TelephonyAction::SendSignal(signal) => {
+ Some(TelephonyCommand::SendSignal { link_id, signal })
+ }
+ TelephonyAction::IdentifyLocalIdentity => {
+ Some(TelephonyCommand::IdentifyLocalIdentity { link_id })
+ }
+ TelephonyAction::SelectProfile(profile) => {
+ Some(TelephonyCommand::SelectProfile { link_id, profile })
+ }
+ TelephonyAction::PrepareDialingPipelines => {
+ Some(TelephonyCommand::PrepareDialingPipelines { link_id })
+ }
+ TelephonyAction::ResetDialingPipelines => {
+ Some(TelephonyCommand::ResetDialingPipelines { link_id })
+ }
+ TelephonyAction::OpenAudioPipelines => {
+ Some(TelephonyCommand::OpenAudioPipelines { link_id })
+ }
+ TelephonyAction::StartAudioPipelines => {
+ Some(TelephonyCommand::StartAudioPipelines { link_id })
+ }
+ TelephonyAction::StartDialTone => Some(TelephonyCommand::StartDialTone { link_id }),
+ TelephonyAction::TeardownLink => Some(TelephonyCommand::TeardownLink { link_id }),
+ TelephonyAction::RingIncomingCall => {
+ remote_identity.map(|remote_identity| TelephonyCommand::RingIncomingCall {
+ link_id,
+ remote_identity,
+ })
+ }
+ TelephonyAction::SwitchProfile(profile) => {
+ Some(TelephonyCommand::SwitchProfile { link_id, profile })
+ }
+ TelephonyAction::IgnoreSignal(signal) => {
+ Some(TelephonyCommand::IgnoredSignal { link_id, signal })
+ }
+ TelephonyAction::Terminate(_) => None,
+ })
+ .collect()
+ }
+}
+
+#[derive(Debug)]
+pub enum TelephonyControl {
+ Announce,
+ Call {
+ remote_identity: IdentityHash,
+ profile: Option,
+ discovery_timeout: Duration,
+ },
+ Answer,
+ Hangup {
+ ring_timeout: bool,
+ },
+ SendRawFrames {
+ bit_depth: RawBitDepth,
+ frames: Vec,
+ },
+ SendOpusFrames {
+ profile: Profile,
+ frames: Vec,
+ },
+ StartOpusStream {
+ profile: Profile,
+ frames: mpsc::Receiver,
+ },
+ StopOpusStream,
+ StartOpusReceiveStream {
+ frames: mpsc::Sender,
+ },
+ StopOpusReceiveStream,
+ SwitchProfile {
+ profile: Profile,
+ },
+ SetExternalBusy(bool),
+ SetAccessPolicy(CallerAccessPolicy),
+ Shutdown,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OpusTransmitStreamStopReason {
+ Requested,
+ Replaced,
+ SourceClosed,
+ CallEnded,
+ ProfileChanged,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum OpusReceiveStreamStopReason {
+ Requested,
+ Replaced,
+ SinkClosed,
+ CallEnded,
+ ProfileChanged,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum TelephonyServiceEvent {
+ OutgoingCallStarted {
+ link_id: LinkId,
+ remote_identity: IdentityHash,
+ },
+ IncomingCall {
+ link_id: LinkId,
+ remote_identity: IdentityHash,
+ },
+ CallTerminated {
+ link_id: LinkId,
+ reason: Option,
+ },
+ MediaSent {
+ link_id: LinkId,
+ frames: usize,
+ packets: usize,
+ },
+ MediaReceived {
+ link_id: LinkId,
+ frames: usize,
+ },
+ OpusFramesReceived {
+ link_id: LinkId,
+ profile: Profile,
+ frames: Vec,
+ },
+ OpusTransmitStreamStarted {
+ link_id: LinkId,
+ profile: Profile,
+ },
+ OpusTransmitStreamStopped {
+ link_id: LinkId,
+ profile: Profile,
+ reason: OpusTransmitStreamStopReason,
+ },
+ OpusReceiveStreamStarted {
+ link_id: LinkId,
+ profile: Profile,
+ },
+ OpusReceiveStreamStopped {
+ link_id: LinkId,
+ profile: Profile,
+ reason: OpusReceiveStreamStopReason,
+ },
+ OpusReceiveStreamFrames {
+ link_id: LinkId,
+ profile: Profile,
+ frames: usize,
+ dropped: usize,
+ },
+ Snapshot(TelephonyRuntimeSnapshot),
+ Drive(TelephonyDriveStep),
+ Error {
+ message: String,
+ },
+ Stopped,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TelephonyServiceConfig {
+ pub poll_interval: Duration,
+ pub incoming_ring_timeout: Option,
+ pub outgoing_call_timeout: Option,
+ pub media_frames_per_tick: usize,
+ pub announce_on_start: bool,
+ pub announce_interval: Option,
+ pub startup_announce_retry_interval: Option,
+ pub startup_announce_retries: u8,
+}
+
+impl Default for TelephonyServiceConfig {
+ fn default() -> Self {
+ Self {
+ poll_interval: Duration::from_millis(20),
+ incoming_ring_timeout: Some(Duration::from_secs(60)),
+ outgoing_call_timeout: Some(Duration::from_secs(70)),
+ media_frames_per_tick: 4,
+ announce_on_start: true,
+ announce_interval: Some(TELEPHONY_ANNOUNCE_INTERVAL),
+ startup_announce_retry_interval: Some(TELEPHONY_STARTUP_ANNOUNCE_RETRY_INTERVAL),
+ startup_announce_retries: TELEPHONY_STARTUP_ANNOUNCE_RETRIES,
+ }
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TelephonyServiceChannelConfig {
+ pub control_capacity: usize,
+ pub event_capacity: usize,
+}
+
+impl Default for TelephonyServiceChannelConfig {
+ fn default() -> Self {
+ Self {
+ control_capacity: 32,
+ event_capacity: 128,
+ }
+ }
+}
+
+pub struct TelephonyServiceParts {
+ pub service: TelephonyService,
+ pub control_tx: mpsc::Sender,
+ pub event_rx: mpsc::Receiver,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum TelephonyServiceTimeoutKind {
+ IncomingRing,
+ OutgoingCall,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+struct TelephonyServiceTimeout {
+ link_id: LinkId,
+ kind: TelephonyServiceTimeoutKind,
+ expires_at: Instant,
+}
+
+#[derive(Default)]
+struct TelephonyServiceMedia {
+ opus_encoder: Option,
+ opus_encoder_generation: u64,
+ opus_decoder: Option,
+ opus_decoder_generation: u64,
+ opus_transmit_stream: Option,
+ opus_receive_stream: Option,
+}
+
+struct ActiveOpusEncoder {
+ link_id: LinkId,
+ profile: Profile,
+ encoder: OpusEncoderState,
+}
+
+struct ActiveOpusDecoder {
+ link_id: LinkId,
+ profile: Profile,
+ decoder: OpusDecoderState,
+}
+
+struct ActiveOpusTransmitStream {
+ link_id: LinkId,
+ profile: Profile,
+ frames_rx: mpsc::Receiver,
+}
+
+struct ActiveOpusReceiveStream {
+ link_id: LinkId,
+ profile: Profile,
+ frames_tx: mpsc::Sender,
+}
+
+impl TelephonyServiceMedia {
+ fn clear_unless_established(
+ &mut self,
+ active: Option<&ActiveCallSnapshot>,
+ ) -> Vec {
+ let mut events = Vec::new();
+ let Some(active) = active.filter(|active| active.status == SignallingStatus::Established)
+ else {
+ self.opus_encoder = None;
+ self.opus_decoder = None;
+ if let Some(stream) = self.opus_transmit_stream.take() {
+ events.push(TelephonyServiceEvent::OpusTransmitStreamStopped {
+ link_id: stream.link_id,
+ profile: stream.profile,
+ reason: OpusTransmitStreamStopReason::CallEnded,
+ });
+ }
+ if let Some(stream) = self.opus_receive_stream.take() {
+ events.push(TelephonyServiceEvent::OpusReceiveStreamStopped {
+ link_id: stream.link_id,
+ profile: stream.profile,
+ reason: OpusReceiveStreamStopReason::CallEnded,
+ });
+ }
+ return events;
+ };
+
+ if self
+ .opus_encoder
+ .as_ref()
+ .is_some_and(|encoder| encoder.link_id != active.link_id)
+ {
+ self.opus_encoder = None;
+ }
+ if self
+ .opus_decoder
+ .as_ref()
+ .is_some_and(|decoder| decoder.link_id != active.link_id)
+ {
+ self.opus_decoder = None;
+ }
+ if self.opus_transmit_stream.as_ref().is_some_and(|stream| {
+ stream.link_id != active.link_id || Some(stream.profile) != active.profile
+ }) {
+ if let Some(stream) = self.opus_transmit_stream.take() {
+ let reason = if stream.link_id == active.link_id {
+ OpusTransmitStreamStopReason::ProfileChanged
+ } else {
+ OpusTransmitStreamStopReason::CallEnded
+ };
+ events.push(TelephonyServiceEvent::OpusTransmitStreamStopped {
+ link_id: stream.link_id,
+ profile: stream.profile,
+ reason,
+ });
+ }
+ }
+ if self.opus_receive_stream.as_ref().is_some_and(|stream| {
+ stream.link_id != active.link_id || Some(stream.profile) != active.profile
+ }) {
+ if let Some(stream) = self.opus_receive_stream.take() {
+ let reason = if stream.link_id == active.link_id {
+ OpusReceiveStreamStopReason::ProfileChanged
+ } else {
+ OpusReceiveStreamStopReason::CallEnded
+ };
+ events.push(TelephonyServiceEvent::OpusReceiveStreamStopped {
+ link_id: stream.link_id,
+ profile: stream.profile,
+ reason,
+ });
+ }
+ }
+ events
+ }
+
+ fn opus_encoder_for(
+ &mut self,
+ link_id: LinkId,
+ profile: Profile,
+ ) -> Result<&mut OpusEncoderState, OpusCodecError> {
+ let needs_new = self
+ .opus_encoder
+ .as_ref()
+ .is_none_or(|encoder| encoder.link_id != link_id || encoder.profile != profile);
+
+ if needs_new {
+ self.opus_encoder_generation += 1;
+ self.opus_encoder = Some(ActiveOpusEncoder {
+ link_id,
+ profile,
+ encoder: OpusEncoderState::new(profile)?,
+ });
+ }
+
+ Ok(&mut self
+ .opus_encoder
+ .as_mut()
+ .expect("Opus encoder exists after creation")
+ .encoder)
+ }
+
+ fn opus_decoder_for(
+ &mut self,
+ link_id: LinkId,
+ profile: Profile,
+ ) -> Result<&mut OpusDecoderState, OpusCodecError> {
+ let needs_new = self
+ .opus_decoder
+ .as_ref()
+ .is_none_or(|decoder| decoder.link_id != link_id || decoder.profile != profile);
+
+ if needs_new {
+ self.opus_decoder_generation += 1;
+ self.opus_decoder = Some(ActiveOpusDecoder {
+ link_id,
+ profile,
+ decoder: OpusDecoderState::new(profile)?,
+ });
+ }
+
+ Ok(&mut self
+ .opus_decoder
+ .as_mut()
+ .expect("Opus decoder exists after creation")
+ .decoder)
+ }
+}
+
+pub struct TelephonyService {
+ endpoint: TelephonyRnsEndpoint,
+ core: TelephonyRuntimeCore,
+ control_rx: mpsc::Receiver,
+ event_tx: mpsc::Sender,
+ config: TelephonyServiceConfig,
+ active_timeout: Option,
+ next_announce_at: Option,
+ startup_announce_retries_remaining: u8,
+ media: TelephonyServiceMedia,
+}
+
+impl TelephonyService {
+ pub fn registered(
+ transport_tx: mpsc::Sender,
+ identity: &Identity,
+ ) -> Result {
+ Self::registered_with_config(
+ transport_tx,
+ identity,
+ TelephonyServiceConfig::default(),
+ TelephonyServiceChannelConfig::default(),
+ )
+ }
+
+ pub fn registered_with_config(
+ transport_tx: mpsc::Sender,
+ identity: &Identity,
+ config: TelephonyServiceConfig,
+ channels: TelephonyServiceChannelConfig,
+ ) -> Result {
+ let endpoint = TelephonyRnsEndpoint::register(transport_tx, identity)?;
+ let (control_tx, control_rx) = mpsc::channel(channels.control_capacity.max(1));
+ let (event_tx, event_rx) = mpsc::channel(channels.event_capacity.max(1));
+ let service = Self::with_config(
+ endpoint,
+ TelephonyRuntimeCore::new(),
+ control_rx,
+ event_tx,
+ config,
+ );
+
+ Ok(TelephonyServiceParts {
+ service,
+ control_tx,
+ event_rx,
+ })
+ }
+
+ pub fn new(
+ endpoint: TelephonyRnsEndpoint,
+ core: TelephonyRuntimeCore,
+ control_rx: mpsc::Receiver,
+ event_tx: mpsc::Sender,
+ ) -> Self {
+ Self::with_config(
+ endpoint,
+ core,
+ control_rx,
+ event_tx,
+ TelephonyServiceConfig::default(),
+ )
+ }
+
+ pub fn with_config(
+ endpoint: TelephonyRnsEndpoint,
+ core: TelephonyRuntimeCore,
+ control_rx: mpsc::Receiver,
+ event_tx: mpsc::Sender,
+ config: TelephonyServiceConfig,
+ ) -> Self {
+ let next_announce_at = if config.announce_on_start {
+ Some(Instant::now())
+ } else {
+ config
+ .announce_interval
+ .map(|interval| Instant::now() + interval)
+ };
+ let startup_announce_retries_remaining =
+ if config.announce_on_start && config.startup_announce_retry_interval.is_some() {
+ config.startup_announce_retries
+ } else {
+ 0
+ };
+
+ Self {
+ endpoint,
+ core,
+ control_rx,
+ event_tx,
+ config,
+ active_timeout: None,
+ next_announce_at,
+ startup_announce_retries_remaining,
+ media: TelephonyServiceMedia::default(),
+ }
+ }
+
+ pub async fn run(mut self) {
+ let mut interval = tokio::time::interval(self.config.poll_interval);
+
+ loop {
+ tokio::select! {
+ control = self.control_rx.recv() => {
+ let Some(control) = control else {
+ break;
+ };
+ if !self.handle_control(control).await {
+ break;
+ }
+ }
+ _ = interval.tick() => {
+ if !self.handle_due_announce().await {
+ break;
+ }
+ if !self.drive_ready().await {
+ break;
+ }
+ if !self.handle_due_timeout().await {
+ break;
+ }
+ if !self.pump_opus_stream().await {
+ break;
+ }
+ }
+ }
+ }
+
+ self.shutdown().await;
+ self.deregister_destinations();
+ let _ = self.event_tx.send(TelephonyServiceEvent::Stopped).await;
+ }
+
+ async fn handle_due_announce(&mut self) -> bool {
+ let Some(next_announce_at) = self.next_announce_at else {
+ return true;
+ };
+ let now = Instant::now();
+ if now < next_announce_at {
+ return true;
+ }
+
+ match self.endpoint.announce() {
+ Ok(()) => {
+ self.next_announce_at = if self.startup_announce_retries_remaining > 0 {
+ self.startup_announce_retries_remaining -= 1;
+ self.config
+ .startup_announce_retry_interval
+ .map(|interval| Instant::now() + interval)
+ } else {
+ self.config
+ .announce_interval
+ .map(|interval| Instant::now() + interval)
+ };
+ true
+ }
+ Err(err) => {
+ let retry_interval = self.config.poll_interval.max(Duration::from_secs(1));
+ self.next_announce_at = Some(Instant::now() + retry_interval);
+ emit_service_error(self.event_tx.clone(), err).await
+ }
+ }
+ }
+
+ async fn shutdown(&mut self) {
+ let commands = self.core.shutdown();
+ if !commands.is_empty() {
+ let _ = self.control_commands(Ok(commands)).await;
+ }
+
+ let stream_events = self.media.clear_unless_established(None);
+ let _ = emit_service_events(self.event_tx.clone(), stream_events).await;
+ self.active_timeout = None;
+ }
+
+ fn deregister_destinations(&self) {
+ for link_id in self
+ .endpoint
+ .outgoing_attempts
+ .keys()
+ .chain(self.endpoint.outgoing_links.keys())
+ {
+ let _ = self.endpoint.deregister_link_destination(*link_id);
+ }
+ let _ = self.endpoint.deregister_destination();
+ }
+
+ async fn handle_control(&mut self, control: TelephonyControl) -> bool {
+ let result = match control {
+ TelephonyControl::Announce => {
+ let result = self.endpoint.announce();
+ if result.is_ok() {
+ self.startup_announce_retries_remaining = 0;
+ self.next_announce_at = self
+ .config
+ .announce_interval
+ .map(|interval| Instant::now() + interval);
+ }
+ result
+ }
+ TelephonyControl::Call {
+ remote_identity,
+ profile,
+ discovery_timeout,
+ } => match self
+ .endpoint
+ .begin_outgoing_link(&mut self.core, remote_identity, profile, discovery_timeout)
+ .await
+ {
+ Ok(link_id) => {
+ let stream_events = self.refresh_active_timeout();
+ if !emit_service_events(self.event_tx.clone(), stream_events).await {
+ return false;
+ }
+ if !emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::OutgoingCallStarted {
+ link_id,
+ remote_identity,
+ },
+ )
+ .await
+ {
+ return false;
+ }
+ return emit_snapshot(self.event_tx.clone(), self.core.snapshot()).await;
+ }
+ Err(err) => Err(err),
+ },
+ TelephonyControl::Answer => {
+ let commands = self.core.answer_active();
+ self.control_commands(commands).await
+ }
+ TelephonyControl::Hangup { ring_timeout } => {
+ let commands = self.core.hangup_active(ring_timeout);
+ self.control_commands(commands).await
+ }
+ TelephonyControl::SendRawFrames { bit_depth, frames } => {
+ return match self.send_raw_frames(bit_depth, frames).await {
+ Ok(()) => true,
+ Err(err) => emit_service_error(self.event_tx.clone(), err).await,
+ };
+ }
+ TelephonyControl::SendOpusFrames { profile, frames } => {
+ return match self.send_opus_frames(profile, frames).await {
+ Ok(()) => true,
+ Err(err) => emit_service_error(self.event_tx.clone(), err).await,
+ };
+ }
+ TelephonyControl::StartOpusStream { profile, frames } => {
+ return match self.start_opus_stream(profile, frames).await {
+ Ok(()) => true,
+ Err(err) => emit_service_error(self.event_tx.clone(), err).await,
+ };
+ }
+ TelephonyControl::StopOpusStream => {
+ return self
+ .stop_opus_stream(OpusTransmitStreamStopReason::Requested)
+ .await;
+ }
+ TelephonyControl::StartOpusReceiveStream { frames } => {
+ return match self.start_opus_receive_stream(frames).await {
+ Ok(()) => true,
+ Err(err) => emit_service_error(self.event_tx.clone(), err).await,
+ };
+ }
+ TelephonyControl::StopOpusReceiveStream => {
+ return self
+ .stop_opus_receive_stream(OpusReceiveStreamStopReason::Requested)
+ .await;
+ }
+ TelephonyControl::SwitchProfile { profile } => {
+ let commands = self.core.switch_active_profile(profile);
+ self.control_commands(commands).await
+ }
+ TelephonyControl::SetExternalBusy(busy) => {
+ self.core.set_external_busy(busy);
+ let stream_events = self.refresh_active_timeout();
+ if !emit_service_events(self.event_tx.clone(), stream_events).await {
+ return false;
+ }
+ return emit_snapshot(self.event_tx.clone(), self.core.snapshot()).await;
+ }
+ TelephonyControl::SetAccessPolicy(access) => {
+ self.core.set_access_policy(access);
+ Ok(())
+ }
+ TelephonyControl::Shutdown => return false,
+ };
+
+ match result {
+ Ok(()) => true,
+ Err(err) => emit_service_error(self.event_tx.clone(), err).await,
+ }
+ }
+
+ async fn start_opus_receive_stream(
+ &mut self,
+ frames_tx: mpsc::Sender,
+ ) -> Result<(), Error> {
+ let active = self.core.active_call().ok_or(Error::NoActiveCall)?;
+ if active.call.status() != SignallingStatus::Established {
+ return Err(Error::CallNotEstablished);
+ }
+
+ let link_id = active.link_id;
+ let profile = active.call.profile().unwrap_or(Profile::DEFAULT);
+ self.stop_opus_receive_stream(OpusReceiveStreamStopReason::Replaced)
+ .await;
+ self.media.opus_receive_stream = Some(ActiveOpusReceiveStream {
+ link_id,
+ profile,
+ frames_tx,
+ });
+
+ if emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::OpusReceiveStreamStarted { link_id, profile },
+ )
+ .await
+ {
+ Ok(())
+ } else {
+ Err(Error::ServiceEventClosed)
+ }
+ }
+
+ async fn stop_opus_receive_stream(&mut self, reason: OpusReceiveStreamStopReason) -> bool {
+ let Some(stream) = self.media.opus_receive_stream.take() else {
+ return true;
+ };
+ emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::OpusReceiveStreamStopped {
+ link_id: stream.link_id,
+ profile: stream.profile,
+ reason,
+ },
+ )
+ .await
+ }
+
+ async fn start_opus_stream(
+ &mut self,
+ profile: Profile,
+ frames_rx: mpsc::Receiver,
+ ) -> Result<(), Error> {
+ let active = self.core.active_call().ok_or(Error::NoActiveCall)?;
+ if active.call.status() != SignallingStatus::Established {
+ return Err(Error::CallNotEstablished);
+ }
+ let active_profile = active.call.profile().unwrap_or(Profile::DEFAULT);
+ if profile != active_profile {
+ return Err(Error::MediaProfileMismatch {
+ active: active_profile,
+ requested: profile,
+ });
+ }
+
+ let link_id = active.link_id;
+ self.stop_opus_stream(OpusTransmitStreamStopReason::Replaced)
+ .await;
+ self.media.opus_transmit_stream = Some(ActiveOpusTransmitStream {
+ link_id,
+ profile,
+ frames_rx,
+ });
+
+ if emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::OpusTransmitStreamStarted { link_id, profile },
+ )
+ .await
+ {
+ Ok(())
+ } else {
+ Err(Error::ServiceEventClosed)
+ }
+ }
+
+ async fn stop_opus_stream(&mut self, reason: OpusTransmitStreamStopReason) -> bool {
+ let Some(stream) = self.media.opus_transmit_stream.take() else {
+ return true;
+ };
+ emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::OpusTransmitStreamStopped {
+ link_id: stream.link_id,
+ profile: stream.profile,
+ reason,
+ },
+ )
+ .await
+ }
+
+ async fn pump_opus_stream(&mut self) -> bool {
+ let Some((profile, frames, source_closed)) = self.drain_opus_stream_frames() else {
+ return true;
+ };
+
+ if !frames.is_empty()
+ && let Err(err) = self.send_opus_frames(profile, frames).await
+ {
+ self.media.opus_transmit_stream = None;
+ return emit_service_error(self.event_tx.clone(), err).await;
+ }
+
+ if source_closed {
+ self.stop_opus_stream(OpusTransmitStreamStopReason::SourceClosed)
+ .await
+ } else {
+ true
+ }
+ }
+
+ fn drain_opus_stream_frames(&mut self) -> Option<(Profile, Vec, bool)> {
+ let stream = self.media.opus_transmit_stream.as_mut()?;
+ let mut frames = Vec::new();
+ let mut source_closed = false;
+ let max_frames = self.config.media_frames_per_tick.max(1);
+
+ for _ in 0..max_frames {
+ match stream.frames_rx.try_recv() {
+ Ok(frame) => frames.push(frame),
+ Err(mpsc::error::TryRecvError::Empty) => break,
+ Err(mpsc::error::TryRecvError::Disconnected) => {
+ source_closed = true;
+ break;
+ }
+ }
+ }
+
+ if frames.is_empty() && !source_closed {
+ None
+ } else {
+ Some((stream.profile, frames, source_closed))
+ }
+ }
+
+ async fn control_commands(
+ &mut self,
+ commands: Result, Error>,
+ ) -> Result<(), Error> {
+ let commands = commands?;
+ let effects = self.endpoint.execute_commands(&commands)?;
+ let service_events = service_events_from_commands(&commands);
+ let step = TelephonyStep::commands(commands);
+ let stream_events = self.refresh_active_timeout();
+ if !emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::Drive(TelephonyDriveStep { step, effects }),
+ )
+ .await
+ {
+ return Err(Error::ServiceEventClosed);
+ }
+
+ for event in service_events {
+ if !emit_service_event(self.event_tx.clone(), event).await {
+ return Err(Error::ServiceEventClosed);
+ }
+ }
+ for event in stream_events {
+ if !emit_service_event(self.event_tx.clone(), event).await {
+ return Err(Error::ServiceEventClosed);
+ }
+ }
+
+ if emit_snapshot(self.event_tx.clone(), self.core.snapshot()).await {
+ Ok(())
+ } else {
+ Err(Error::ServiceEventClosed)
+ }
+ }
+
+ async fn send_raw_frames(
+ &mut self,
+ bit_depth: RawBitDepth,
+ frames: Vec,
+ ) -> Result<(), Error> {
+ let active = self.core.active_call().ok_or(Error::NoActiveCall)?;
+ if active.call.status() != SignallingStatus::Established {
+ return Err(Error::CallNotEstablished);
+ }
+
+ let link_id = active.link_id;
+ let frame_count = frames.len();
+ let packet_count = self.endpoint.queue_raw_frames(link_id, bit_depth, frames)?;
+ if emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::MediaSent {
+ link_id,
+ frames: frame_count,
+ packets: packet_count,
+ },
+ )
+ .await
+ {
+ Ok(())
+ } else {
+ Err(Error::ServiceEventClosed)
+ }
+ }
+
+ async fn send_opus_frames(
+ &mut self,
+ profile: Profile,
+ frames: Vec,
+ ) -> Result<(), Error> {
+ let active = self.core.active_call().ok_or(Error::NoActiveCall)?;
+ if active.call.status() != SignallingStatus::Established {
+ return Err(Error::CallNotEstablished);
+ }
+ let active_profile = active.call.profile().unwrap_or(Profile::DEFAULT);
+ if profile != active_profile {
+ return Err(Error::MediaProfileMismatch {
+ active: active_profile,
+ requested: profile,
+ });
+ }
+
+ let link_id = active.link_id;
+ let frame_count = frames.len();
+ let encoded = {
+ let encoder = self.media.opus_encoder_for(link_id, profile)?;
+ frames
+ .iter()
+ .map(|frame| encoder.encode_frame(frame))
+ .collect::, _>>()?
+ };
+ let packet_count = self.endpoint.queue_frames(link_id, encoded)?;
+ if emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::MediaSent {
+ link_id,
+ frames: frame_count,
+ packets: packet_count,
+ },
+ )
+ .await
+ {
+ Ok(())
+ } else {
+ Err(Error::ServiceEventClosed)
+ }
+ }
+
+ async fn drive_ready(&mut self) -> bool {
+ match self.endpoint.try_drive_ready(&mut self.core) {
+ Ok(steps) => {
+ let emit_snapshot_after_steps = !steps.is_empty();
+ for step in steps {
+ let service_events = service_events_from_commands(&step.step.commands);
+ let media_received = media_received_event(&step.step);
+ let opus_received_events = match self.opus_received_events(&step.step) {
+ Ok(events) => events,
+ Err(err) => {
+ if !emit_service_error(self.event_tx.clone(), err).await {
+ return false;
+ }
+ Vec::new()
+ }
+ };
+ if !emit_service_event(
+ self.event_tx.clone(),
+ TelephonyServiceEvent::Drive(step),
+ )
+ .await
+ {
+ return false;
+ }
+ for event in service_events {
+ if !emit_service_event(self.event_tx.clone(), event).await {
+ return false;
+ }
+ }
+ if let Some(event) = media_received
+ && !emit_service_event(self.event_tx.clone(), event).await
+ {
+ return false;
+ }
+ for event in opus_received_events {
+ if !emit_service_event(self.event_tx.clone(), event).await {
+ return false;
+ }
+ }
+ }
+ if emit_snapshot_after_steps {
+ let stream_events = self.refresh_active_timeout();
+ for event in stream_events {
+ if !emit_service_event(self.event_tx.clone(), event).await {
+ return false;
+ }
+ }
+ }
+ if emit_snapshot_after_steps
+ && !emit_snapshot(self.event_tx.clone(), self.core.snapshot()).await
+ {
+ return false;
+ }
+ true
+ }
+ Err(err) => emit_service_error(self.event_tx.clone(), err).await,
+ }
+ }
+
+ fn opus_received_events(
+ &mut self,
+ step: &TelephonyStep,
+ ) -> Result, Error> {
+ let Some(inbound) = step.inbound.as_ref() else {
+ return Ok(Vec::new());
+ };
+ let opus_frames = inbound
+ .frame_events
+ .iter()
+ .filter_map(|event| match event {
+ FrameStreamEvent::Frame(frame) if frame.codec == CodecKind::Opus => Some(frame),
+ _ => None,
+ })
+ .collect::>();
+ if opus_frames.is_empty() {
+ return Ok(Vec::new());
+ }
+
+ let active = self.core.active_call().ok_or(Error::NoActiveCall)?;
+ if active.link_id != inbound.link_id {
+ return Err(Error::WrongActiveLink);
+ }
+ let link_id = active.link_id;
+ let profile = active.call.profile().unwrap_or(Profile::DEFAULT);
+ let decoded = {
+ let decoder = self.media.opus_decoder_for(active.link_id, profile)?;
+ opus_frames
+ .iter()
+ .map(|frame| decoder.decode_frame(frame))
+ .collect::, _>>()?
+ };
+
+ let receive_stream_events = self.deliver_opus_receive_stream(link_id, profile, &decoded);
+ let mut events = Vec::with_capacity(1 + receive_stream_events.len());
+ events.push(TelephonyServiceEvent::OpusFramesReceived {
+ link_id,
+ profile,
+ frames: decoded,
+ });
+ events.extend(receive_stream_events);
+ Ok(events)
+ }
+
+ fn deliver_opus_receive_stream(
+ &mut self,
+ link_id: LinkId,
+ profile: Profile,
+ frames: &[RawAudioFrame],
+ ) -> Vec {
+ let Some(stream) = self.media.opus_receive_stream.as_ref() else {
+ return Vec::new();
+ };
+ if stream.link_id != link_id || stream.profile != profile {
+ self.media.opus_receive_stream = None;
+ return Vec::new();
+ }
+
+ let mut delivered = 0;
+ let mut dropped = 0;
+ let mut sink_closed = false;
+ for frame in frames {
+ let Some(stream) = self.media.opus_receive_stream.as_ref() else {
+ break;
+ };
+ match stream.frames_tx.try_send(frame.clone()) {
+ Ok(()) => delivered += 1,
+ Err(mpsc::error::TrySendError::Full(_)) => dropped += 1,
+ Err(mpsc::error::TrySendError::Closed(_)) => {
+ sink_closed = true;
+ break;
+ }
+ }
+ }
+
+ let mut events = Vec::new();
+ if delivered > 0 || dropped > 0 {
+ events.push(TelephonyServiceEvent::OpusReceiveStreamFrames {
+ link_id,
+ profile,
+ frames: delivered,
+ dropped,
+ });
+ }
+ if sink_closed && let Some(stream) = self.media.opus_receive_stream.take() {
+ events.push(TelephonyServiceEvent::OpusReceiveStreamStopped {
+ link_id: stream.link_id,
+ profile: stream.profile,
+ reason: OpusReceiveStreamStopReason::SinkClosed,
+ });
+ }
+ events
+ }
+
+ fn refresh_active_timeout(&mut self) -> Vec {
+ let snapshot = self.core.snapshot();
+ let stream_events = self
+ .media
+ .clear_unless_established(snapshot.active_call.as_ref());
+ let Some(active) = snapshot.active_call else {
+ self.active_timeout = None;
+ return stream_events;
+ };
+
+ let desired = match (active.role, active.status) {
+ (CallRole::Incoming, SignallingStatus::Ringing) => self
+ .config
+ .incoming_ring_timeout
+ .map(|duration| (TelephonyServiceTimeoutKind::IncomingRing, duration)),
+ (CallRole::Outgoing, status) if status != SignallingStatus::Established => self
+ .config
+ .outgoing_call_timeout
+ .map(|duration| (TelephonyServiceTimeoutKind::OutgoingCall, duration)),
+ _ => None,
+ };
+
+ let Some((kind, duration)) = desired else {
+ self.active_timeout = None;
+ return stream_events;
+ };
+
+ if self
+ .active_timeout
+ .is_some_and(|timeout| timeout.link_id == active.link_id && timeout.kind == kind)
+ {
+ return stream_events;
+ }
+
+ self.active_timeout = Some(TelephonyServiceTimeout {
+ link_id: active.link_id,
+ kind,
+ expires_at: Instant::now() + duration,
+ });
+ stream_events
+ }
+
+ async fn handle_due_timeout(&mut self) -> bool {
+ let Some(timeout_state) = self.active_timeout else {
+ return true;
+ };
+ if Instant::now() < timeout_state.expires_at {
+ return true;
+ }
+
+ let Some(active) = self.core.snapshot().active_call else {
+ self.active_timeout = None;
+ return true;
+ };
+ if active.link_id != timeout_state.link_id {
+ let stream_events = self.refresh_active_timeout();
+ if !emit_service_events(self.event_tx.clone(), stream_events).await {
+ return false;
+ }
+ return true;
+ }
+
+ let should_timeout = match timeout_state.kind {
+ TelephonyServiceTimeoutKind::IncomingRing => {
+ active.role == CallRole::Incoming && active.status == SignallingStatus::Ringing
+ }
+ TelephonyServiceTimeoutKind::OutgoingCall => {
+ active.role == CallRole::Outgoing && active.status != SignallingStatus::Established
+ }
+ };
+ if !should_timeout {
+ let stream_events = self.refresh_active_timeout();
+ if !emit_service_events(self.event_tx.clone(), stream_events).await {
+ return false;
+ }
+ return true;
+ }
+
+ self.active_timeout = None;
+ let commands = self
+ .core
+ .hangup_active(timeout_state.kind == TelephonyServiceTimeoutKind::IncomingRing);
+ match self.control_commands(commands).await {
+ Ok(()) => true,
+ Err(err) => emit_service_error(self.event_tx.clone(), err).await,
+ }
+ }
+}
+
+fn service_events_from_commands(commands: &[TelephonyCommand]) -> Vec {
+ commands
+ .iter()
+ .filter_map(|command| match command {
+ TelephonyCommand::RingIncomingCall {
+ link_id,
+ remote_identity,
+ } => Some(TelephonyServiceEvent::IncomingCall {
+ link_id: *link_id,
+ remote_identity: *remote_identity,
+ }),
+ TelephonyCommand::CallTerminated { link_id, reason } => {
+ Some(TelephonyServiceEvent::CallTerminated {
+ link_id: *link_id,
+ reason: *reason,
+ })
+ }
+ _ => None,
+ })
+ .collect()
+}
+
+fn media_received_event(step: &TelephonyStep) -> Option {
+ let inbound = step.inbound.as_ref()?;
+ let frames = inbound
+ .frame_events
+ .iter()
+ .filter(|event| matches!(event, FrameStreamEvent::Frame(_)))
+ .count();
+ (frames > 0).then_some(TelephonyServiceEvent::MediaReceived {
+ link_id: inbound.link_id,
+ frames,
+ })
+}
+
+async fn emit_service_error(event_tx: mpsc::Sender, err: Error) -> bool {
+ emit_service_event(
+ event_tx,
+ TelephonyServiceEvent::Error {
+ message: err.to_string(),
+ },
+ )
+ .await
+}
+
+async fn emit_snapshot(
+ event_tx: mpsc::Sender,
+ snapshot: TelephonyRuntimeSnapshot,
+) -> bool {
+ emit_service_event(event_tx, TelephonyServiceEvent::Snapshot(snapshot)).await
+}
+
+async fn emit_service_events(
+ event_tx: mpsc::Sender,
+ events: Vec,
+) -> bool {
+ for event in events {
+ if !emit_service_event(event_tx.clone(), event).await {
+ return false;
+ }
+ }
+ true
+}
+
+async fn emit_service_event(
+ event_tx: mpsc::Sender,
+ event: TelephonyServiceEvent,
+) -> bool {
+ event_tx.send(event).await.is_ok()
+}
+
+pub struct TelephonyRnsEndpoint {
+ pub destination_hash: [u8; 16],
+ pub manager: LinkManager,
+ pub link_established_rx: mpsc::Receiver,
+ pub link_identified_rx: mpsc::Receiver<(LinkId, IdentityHash)>,
+ pub link_packet_rx: mpsc::Receiver<(Vec, LinkId)>,
+ pub link_closed_rx: mpsc::Receiver,
+ transport_tx: mpsc::Sender,
+ identity_pub_key: [u8; 64],
+ identity_signing_key: Ed25519PrivateKey,
+ outgoing_attempts: HashMap,
+ outgoing_links: HashMap,
+}
+
+struct OutgoingLinkAttempt {
+ link: Link,
+ remote_public_key: [u8; 64],
+ event_rx: mpsc::Receiver,
+}
+
+struct OutgoingLinkState {
+ link: Link,
+ event_rx: mpsc::Receiver,
+}
+
+impl TelephonyRnsEndpoint {
+ pub fn register(
+ transport_tx: mpsc::Sender,
+ identity: &Identity,
+ ) -> Result {
+ let manager_signing_key = identity.get_signing_key().ok_or(Error::NoSigningKey)?;
+ let identity_signing_key = identity.get_signing_key().ok_or(Error::NoSigningKey)?;
+ let identity_pub_key = identity.get_public_key();
+ let destination_hash = telephony_destination_hash(&identity.hash);
+ let (destination_tx, destination_rx) = mpsc::channel::(256);
+
+ try_send_transport(
+ &transport_tx,
+ TransportMessage::RegisterDestination {
+ hash: destination_hash,
+ app_name: TELEPHONY_DESTINATION_NAME.to_string(),
+ delivery_tx: Some(destination_tx),
+ },
+ )?;
+
+ let mut manager = LinkManager::with_destination(
+ transport_tx.clone(),
+ destination_rx,
+ identity,
+ TELEPHONY_DESTINATION_NAME,
+ manager_signing_key,
+ );
+ let (established_tx, link_established_rx) = mpsc::channel(64);
+ let (identified_tx, link_identified_rx) = mpsc::channel(64);
+ let (packet_tx, link_packet_rx) = mpsc::channel(256);
+ let (closed_tx, link_closed_rx) = mpsc::channel(64);
+ manager.set_link_established_channel(established_tx);
+ manager.set_link_identified_channel(identified_tx);
+ manager.set_link_packet_channel(packet_tx);
+ manager.set_link_closed_channel(closed_tx);
+
+ Ok(Self {
+ destination_hash,
+ manager,
+ link_established_rx,
+ link_identified_rx,
+ link_packet_rx,
+ link_closed_rx,
+ transport_tx,
+ identity_pub_key,
+ identity_signing_key,
+ outgoing_attempts: HashMap::new(),
+ outgoing_links: HashMap::new(),
+ })
+ }
+
+ pub fn request_path_to_identity(&self, identity_hash: &IdentityHash) -> Result<(), Error> {
+ try_send_transport(
+ &self.transport_tx,
+ TransportMessage::RequestPath {
+ destination_hash: telephony_destination_hash(identity_hash),
+ },
+ )
+ }
+
+ pub fn deregister_destination(&self) -> Result<(), Error> {
+ try_send_transport(
+ &self.transport_tx,
+ TransportMessage::DeregisterDestination {
+ hash: self.destination_hash,
+ },
+ )
+ }
+
+ pub fn announce(&self) -> Result<(), Error> {
+ let raw = self.announce_packet();
+ try_send_transport(
+ &self.transport_tx,
+ TransportMessage::Outbound(OutboundRequest {
+ raw: Bytes::from(raw),
+ destination_hash: self.destination_hash,
+ }),
+ )
+ }
+
+ fn announce_packet(&self) -> Vec {
+ let announce_name_hash = name_hash(TELEPHONY_DESTINATION_NAME);
+ let random_bytes = rns_crypto::random::random_bytes(5);
+ let timestamp = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap_or_default()
+ .as_secs();
+ let timestamp_bytes = timestamp.to_be_bytes();
+ let mut random_hash = [0u8; 10];
+ random_hash[..5].copy_from_slice(&random_bytes);
+ random_hash[5..].copy_from_slice(×tamp_bytes[3..8]);
+
+ let mut signed_data = Vec::with_capacity(16 + 64 + 10 + 10);
+ signed_data.extend_from_slice(&self.destination_hash);
+ signed_data.extend_from_slice(&self.identity_pub_key);
+ signed_data.extend_from_slice(&announce_name_hash);
+ signed_data.extend_from_slice(&random_hash);
+ let signature = self.identity_signing_key.sign(&signed_data);
+
+ let mut announce_data = Vec::with_capacity(64 + 10 + 10 + 64);
+ announce_data.extend_from_slice(&self.identity_pub_key);
+ announce_data.extend_from_slice(&announce_name_hash);
+ announce_data.extend_from_slice(&random_hash);
+ announce_data.extend_from_slice(&signature);
+
+ let flags = rns_wire::flags::PacketFlags {
+ header_type: rns_wire::flags::HeaderType::Header1,
+ context_flag: false,
+ transport_type: rns_wire::flags::TransportType::Broadcast,
+ destination_type: rns_wire::flags::DestinationType::Single,
+ packet_type: rns_wire::flags::PacketType::Announce,
+ };
+ let header = rns_wire::header::PacketHeader {
+ flags,
+ hops: 0,
+ transport_id: None,
+ destination_hash: self.destination_hash,
+ context: rns_wire::context::PacketContext::None,
+ };
+ let mut raw = header.pack();
+ raw.extend_from_slice(&announce_data);
+ raw
+ }
+
+ pub fn deregister_link_destination(&self, link_id: LinkId) -> Result<(), Error> {
+ try_send_transport(
+ &self.transport_tx,
+ TransportMessage::DeregisterDestination { hash: link_id },
+ )
+ }
+
+ pub fn discover_remote_telephony_peer(
+ &self,
+ remote_identity: IdentityHash,
+ discovery_timeout: Duration,
+ ) -> impl std::future::Future