feat(audio,bridge,flutter): v1 audio + PTT lifecycle implementation (SDD-094..097)
Implement the SDD-094 / SDD-095 / SDD-096 / SDD-097 detailed designs
committed in dfa84ee.
Rust side
- chanora_audio::TransmitMode enum (Ptt/Continuous/VoiceActivity) with
serde-friendly u8 repr (SDD-095).
- chanora_audio::TransmitModeSelector: lock-free Atomic-backed selector
that is the sole writer of transmit_active (per SAD-083), applying
hard_mute as a final clamp. VoiceActivity falls through to Continuous
for v1 (DEC-030 placeholder).
- chanora_audio::ReleaseTailTimer: tokio-task-owning struct driving the
selector's ptt_held input; default 200 ms tail, configurable 0–500 ms
with AtomicU32 hot read; pending JoinHandle held in a std::sync::Mutex
touched only on PTT edge transitions (SDD-096).
- chanora_storage: AudioMeta persisted as audio_meta.json next to
identity.dek; get/set_transmit_mode + get/set_release_tail_ms with
0..=500 clamp on write.
- chanora_core::ChanoraSession: voice_join(channel, password) and
voice_leave() are the new lifecycle entry points; ensure_audio_running
and shutdown_audio_if_idle are private helpers around the existing
Option<AudioEngine> field. SessionEvent::VoiceState carries the
in_channel / transmit_mode / mute / release_tail_ms tuple. Selector
state survives reconnect; supervisor rewires it to each fresh engine
gate.
- chanora_bridge: drop start_audio; add voice_join, voice_leave,
set/get_transmit_mode, set/get_release_tail_ms, set_hard_mute.
BridgeEvent::VoiceState mirrors the core event. AudioStarted/Stopped
kept for backwards compat but Flutter ignores them in the new UI.
Flutter side
- New apps/chanora_flutter/lib/widgets/voice_bar.dart replaces the
legacy _AudioControls widget. Renders channel pill, mode badge,
mute toggle, level meter, PttCapabilityBadge, leave button. No
manual Start affordance anywhere.
- New apps/chanora_flutter/lib/widgets/voice_settings.dart dialog with
TransmitMode radio group (VoiceActivity disabled with 'Coming soon'
trailing label per DEC-030), bind-key button, release-tail slider
0–500 ms step 25.
- main.dart: state fields _inChannel, _transmitMode, _hardMute,
_releaseTailMs driven by BridgeEvent_VoiceState. Channel-tap now
calls voiceJoin instead of moveToChannel. Removed _onStartAudio,
_audioStarted-gated branch, and the FilledButton.
- l10n: 11 new strings in app_en.arb + app_zh.arb.
Verification
- cargo check --workspace: clean.
- cargo test --workspace --lib: 72 passed / 0 failed / 1 ignored
(chanora_audio: +12 new tests for TransmitMode/Selector/ReleaseTail;
chanora_storage: +2 new tests for audio_meta round-trip).
- flutter analyze: 0 errors, 0 warnings; 6 infos are the Flutter 3.32
Radio.groupValue deprecation (pre-existing API usage).
- FRB Dart/Rust bindings regenerated via flutter_rust_bridge_codegen.
Follow-up (intentionally deferred)
- PttController and per-platform PTT backends still drive AudioTransmitGate
directly via the legacy set_ptt path; routing those key edges through
ChanoraSession::release_tail_timer().{key_down,key_up} so the tail
applies to native PTT input is a contained wiring change in a follow-up.
- Real audio-level RMS in BridgeAudioStats (current meter is binary).
- VoiceActivity backend (DEC-030).
This commit is contained in:
@@ -0,0 +1,181 @@
|
||||
//! Release-tail timer (SDD-096).
|
||||
//!
|
||||
//! When a PTT key is released we don't immediately cut transmission
|
||||
//! — we keep the gate open for a short configurable tail (0–500 ms,
|
||||
//! default 200 ms) so room reverb and the trailing edge of words
|
||||
//! aren't clipped. A subsequent `key_down` within the tail window
|
||||
//! cancels the pending release so transmission stays continuous.
|
||||
//!
|
||||
//! The timer drives the `ptt_held` input of a
|
||||
//! [`crate::transmit_selector::TransmitModeSelector`] rather than
|
||||
//! the [`crate::AudioTransmitGate`] directly — the selector then
|
||||
//! decides whether the desired gate state is `true` or `false`
|
||||
//! based on the current [`crate::TransmitMode`]. This keeps a
|
||||
//! single owner of `transmit_active` (SAD-083).
|
||||
//!
|
||||
//! Threading model:
|
||||
//!
|
||||
//! * `tail_ms` is an [`AtomicU32`] so config changes are visible
|
||||
//! immediately to any in-flight release task.
|
||||
//! * The pending [`JoinHandle`] is held in a [`std::sync::Mutex`].
|
||||
//! The mutex is only ever touched on PTT *edge* transitions
|
||||
//! (`key_down` / `key_up`) — never on the audio frame hot path
|
||||
//! — so the brief acquisition is acceptable.
|
||||
|
||||
use std::sync::atomic::{AtomicU32, Ordering};
|
||||
use std::sync::{Arc, Mutex};
|
||||
use std::time::Duration;
|
||||
|
||||
use tokio::task::JoinHandle;
|
||||
|
||||
use crate::transmit_selector::TransmitModeSelector;
|
||||
|
||||
/// Maximum configurable release-tail, in milliseconds.
|
||||
pub const MAX_TAIL_MS: u32 = 500;
|
||||
|
||||
/// Default release-tail (SDD-096).
|
||||
pub const DEFAULT_TAIL_MS: u32 = 200;
|
||||
|
||||
/// Coalesces a PTT key release into a deferred selector update.
|
||||
///
|
||||
/// Cheap to clone via `Arc`.
|
||||
pub struct ReleaseTailTimer {
|
||||
selector: Arc<TransmitModeSelector>,
|
||||
pending: Arc<Mutex<Option<JoinHandle<()>>>>,
|
||||
tail_ms: AtomicU32,
|
||||
}
|
||||
|
||||
impl ReleaseTailTimer {
|
||||
/// Construct a new timer wired to `selector`. `tail_ms` is
|
||||
/// clamped to `0..=MAX_TAIL_MS` (SDD-096).
|
||||
pub fn new(selector: Arc<TransmitModeSelector>, tail_ms: u32) -> Self {
|
||||
Self {
|
||||
selector,
|
||||
pending: Arc::new(Mutex::new(None)),
|
||||
tail_ms: AtomicU32::new(tail_ms.min(MAX_TAIL_MS)),
|
||||
}
|
||||
}
|
||||
|
||||
/// Update the configured tail, clamped to `0..=MAX_TAIL_MS`.
|
||||
pub fn set_tail_ms(&self, ms: u32) {
|
||||
self.tail_ms.store(ms.min(MAX_TAIL_MS), Ordering::Relaxed);
|
||||
}
|
||||
|
||||
/// Current configured tail (post-clamp).
|
||||
pub fn tail_ms(&self) -> u32 {
|
||||
self.tail_ms.load(Ordering::Relaxed)
|
||||
}
|
||||
|
||||
/// Notify the timer that the PTT key went down. Cancels any
|
||||
/// pending release and immediately marks the selector's
|
||||
/// `ptt_held` input as `true`.
|
||||
pub fn key_down(&self) {
|
||||
self.cancel_pending();
|
||||
self.selector.set_ptt_held(true);
|
||||
}
|
||||
|
||||
/// Notify the timer that the PTT key went up. Spawns a task
|
||||
/// that sleeps for `tail_ms` and then clears the selector's
|
||||
/// `ptt_held` input. A subsequent [`Self::key_down`] within
|
||||
/// the window cancels this task.
|
||||
pub fn key_up(&self) {
|
||||
let tail = self.tail_ms();
|
||||
let selector = self.selector.clone();
|
||||
let new_handle = tokio::spawn(async move {
|
||||
if tail > 0 {
|
||||
tokio::time::sleep(Duration::from_millis(tail as u64)).await;
|
||||
}
|
||||
selector.set_ptt_held(false);
|
||||
});
|
||||
if let Ok(mut g) = self.pending.lock() {
|
||||
if let Some(prev) = g.replace(new_handle) {
|
||||
prev.abort();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Cancel any pending release task and leave the selector's
|
||||
/// `ptt_held` flag at whatever value it currently holds.
|
||||
pub fn cancel(&self) {
|
||||
self.cancel_pending();
|
||||
}
|
||||
|
||||
fn cancel_pending(&self) {
|
||||
if let Ok(mut g) = self.pending.lock() {
|
||||
if let Some(h) = g.take() {
|
||||
h.abort();
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for ReleaseTailTimer {
|
||||
fn drop(&mut self) {
|
||||
self.cancel_pending();
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::ptt::AudioTransmitGate;
|
||||
use crate::transmit_mode::TransmitMode;
|
||||
|
||||
fn setup(tail_ms: u32) -> (AudioTransmitGate, Arc<TransmitModeSelector>, ReleaseTailTimer) {
|
||||
let gate = AudioTransmitGate::new(false);
|
||||
let sel = Arc::new(TransmitModeSelector::new(gate.clone()));
|
||||
sel.set_mode(TransmitMode::Ptt);
|
||||
sel.set_in_channel(true);
|
||||
let timer = ReleaseTailTimer::new(sel.clone(), tail_ms);
|
||||
(gate, sel, timer)
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||||
async fn release_clears_after_tail() {
|
||||
let (gate, _sel, timer) = setup(80);
|
||||
timer.key_down();
|
||||
assert!(gate.load());
|
||||
timer.key_up();
|
||||
// Still transmitting during the tail.
|
||||
tokio::time::sleep(Duration::from_millis(20)).await;
|
||||
assert!(gate.load(), "should still be true during tail");
|
||||
// After the tail elapses, gate clears.
|
||||
tokio::time::sleep(Duration::from_millis(120)).await;
|
||||
assert!(!gate.load(), "gate should clear after tail");
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||||
async fn redown_within_tail_cancels_release() {
|
||||
let (gate, _sel, timer) = setup(200);
|
||||
timer.key_down();
|
||||
timer.key_up();
|
||||
tokio::time::sleep(Duration::from_millis(20)).await;
|
||||
timer.key_down();
|
||||
// Wait past the original tail; gate must still be true.
|
||||
tokio::time::sleep(Duration::from_millis(250)).await;
|
||||
assert!(gate.load(), "subsequent key_down should cancel pending release");
|
||||
}
|
||||
|
||||
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
|
||||
async fn zero_tail_clears_immediately() {
|
||||
let (gate, _sel, timer) = setup(0);
|
||||
timer.key_down();
|
||||
assert!(gate.load());
|
||||
timer.key_up();
|
||||
tokio::time::sleep(Duration::from_millis(30)).await;
|
||||
assert!(!gate.load());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn set_tail_ms_clamps_to_max() {
|
||||
let gate = AudioTransmitGate::new(false);
|
||||
let sel = Arc::new(TransmitModeSelector::new(gate));
|
||||
let timer = ReleaseTailTimer::new(sel, 100);
|
||||
timer.set_tail_ms(99999);
|
||||
assert_eq!(timer.tail_ms(), MAX_TAIL_MS);
|
||||
timer.set_tail_ms(0);
|
||||
assert_eq!(timer.tail_ms(), 0);
|
||||
timer.set_tail_ms(MAX_TAIL_MS);
|
||||
assert_eq!(timer.tail_ms(), MAX_TAIL_MS);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user