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).

crates/chanora_audio/src/engine.rs

@@ -137,9 +137,23 @@ impl AudioEngine {
     /// Start the engine: open capture + playback streams, spawn the
     /// inbound-voice forwarder, return a handle.
     pub fn start(
+        cfg: AudioEngineConfig,
+        voice_out_tx: mpsc::Sender<OutPacket>,
+        voice_in_rx: mpsc::Receiver<InboundVoice>,
+    ) -> Result<Self, AudioError> {
+        let gate = crate::ptt::AudioTransmitGate::new(cfg.ptt_initial);
+        Self::start_with_gate(cfg, voice_out_tx, voice_in_rx, gate)
+    }
+
+    /// Start the engine using an externally-owned
+    /// [`AudioTransmitGate`]. The gate is shared with whatever
+    /// upstream (typically [`crate::TransmitModeSelector`]) is the
+    /// authoritative writer of `transmit_active`. See SAD-083.
+    pub fn start_with_gate(
         cfg: AudioEngineConfig,
         voice_out_tx: mpsc::Sender<OutPacket>,
         mut voice_in_rx: mpsc::Receiver<InboundVoice>,
+        transmit_gate: crate::ptt::AudioTransmitGate,
     ) -> Result<Self, AudioError> {
         let host = cpal::default_host();
         info!(
@@ -237,7 +251,6 @@ impl AudioEngine {
             }
         }
 
-        let transmit_gate = crate::ptt::AudioTransmitGate::new(cfg.ptt_initial);
         let transmit_flag_for_capture = transmit_gate.flag_arc();
         let frames_sent = Arc::new(AtomicU32::new(0));
         let frames_received = Arc::new(AtomicU32::new(0));

crates/chanora_audio/src/lib.rs

@@ -31,6 +31,9 @@
 mod engine;
 pub mod ptt;
 pub mod ptt_backends;
+pub mod release_tail;
+pub mod transmit_mode;
+pub mod transmit_selector;
 
 pub use engine::{AudioEngine, AudioEngineConfig};
 pub use ptt::{
@@ -40,6 +43,9 @@ pub use ptt_backends::{
     select as select_ptt_backend, DesktopPttBackend, FocusedPttBackend, PttBackendError,
     PttBinding, PttInputClass,
 };
+pub use release_tail::{ReleaseTailTimer, DEFAULT_TAIL_MS, MAX_TAIL_MS};
+pub use transmit_mode::TransmitMode;
+pub use transmit_selector::TransmitModeSelector;
 
 use thiserror::Error;
 

crates/chanora_audio/src/release_tail.rs

@@ -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);
+    }
+}

crates/chanora_audio/src/transmit_mode.rs

@@ -0,0 +1,90 @@
+//! Voice transmit mode (SDD-095).
+//!
+//! Selects how `transmit_active` is driven from the user's input
+//! signals. Persisted per-identity in
+//! [`chanora_storage::IdentityFileStore`] under the `transmit_mode`
+//! metadata key (default [`TransmitMode::Ptt`]).
+//!
+//! `VoiceActivity` is reserved per DEC-030 — for v1 the
+//! [`crate::transmit_selector::TransmitModeSelector`] treats it
+//! exactly like [`TransmitMode::Continuous`] until a real VAD
+//! implementation lands.
+
+/// User-visible voice transmit mode.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u8)]
+pub enum TransmitMode {
+    /// Push-to-talk: transmit only while the bound key is held
+    /// (with release-tail per SDD-096).
+    Ptt = 0,
+    /// Continuous: transmit whenever the user is in a voice
+    /// channel and not hard-muted.
+    Continuous = 1,
+    /// Voice activity detection. Reserved per DEC-030; v1 behaves
+    /// as [`TransmitMode::Continuous`] until a VAD implementation
+    /// is allocated.
+    VoiceActivity = 2,
+}
+
+impl Default for TransmitMode {
+    fn default() -> Self {
+        Self::Ptt
+    }
+}
+
+impl TransmitMode {
+    /// Encode as the persisted single-byte value.
+    pub fn as_u8(self) -> u8 {
+        self as u8
+    }
+
+    /// Decode from the persisted single-byte value. Returns
+    /// `None` for unknown encodings (the storage layer should
+    /// fall back to [`TransmitMode::default`] in that case).
+    pub fn from_u8(v: u8) -> Option<Self> {
+        match v {
+            0 => Some(Self::Ptt),
+            1 => Some(Self::Continuous),
+            2 => Some(Self::VoiceActivity),
+            _ => None,
+        }
+    }
+
+    /// Stable diagnostic identifier (never localised).
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Ptt => "ptt",
+            Self::Continuous => "continuous",
+            Self::VoiceActivity => "voice-activity",
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_is_ptt() {
+        assert_eq!(TransmitMode::default(), TransmitMode::Ptt);
+    }
+
+    #[test]
+    fn round_trip_u8() {
+        for m in [
+            TransmitMode::Ptt,
+            TransmitMode::Continuous,
+            TransmitMode::VoiceActivity,
+        ] {
+            assert_eq!(TransmitMode::from_u8(m.as_u8()), Some(m));
+        }
+        assert_eq!(TransmitMode::from_u8(99), None);
+    }
+
+    #[test]
+    fn as_str_is_stable() {
+        assert_eq!(TransmitMode::Ptt.as_str(), "ptt");
+        assert_eq!(TransmitMode::Continuous.as_str(), "continuous");
+        assert_eq!(TransmitMode::VoiceActivity.as_str(), "voice-activity");
+    }
+}

crates/chanora_audio/src/transmit_selector.rs

@@ -0,0 +1,206 @@
+//! Cross-platform transmit-mode selector (SAD-083).
+//!
+//! Single writer of `transmit_active` other than the missed-key-up
+//! watchdog (SAD-079). Computes the desired gate state from four
+//! lock-free inputs:
+//!
+//! * `mode` — current [`TransmitMode`]
+//! * `in_channel` — true when the session is in a voice channel
+//! * `hard_mute` — final clamp; forces `false` regardless of mode
+//! * `ptt_held` — raw key state (via [`crate::ReleaseTailTimer`]
+//!   on PTT mode)
+//!
+//! Hard-mute is a final clamp; leaving the channel forces the gate
+//! to `false`. `VoiceActivity` is treated identically to
+//! `Continuous` per DEC-030 until a VAD implementation lands.
+//!
+//! All four inputs are stored as atomics so any thread can update
+//! them without taking a lock. After each update we call
+//! [`TransmitModeSelector::recompute`] which writes the resolved
+//! desired value through the [`AudioTransmitGate`].
+
+use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
+
+use crate::ptt::AudioTransmitGate;
+use crate::transmit_mode::TransmitMode;
+
+/// Selector that maps user/session state to the `transmit_active`
+/// gate (SAD-083).
+pub struct TransmitModeSelector {
+    gate: std::sync::RwLock<AudioTransmitGate>,
+    mode: AtomicU8,
+    in_channel: AtomicBool,
+    hard_mute: AtomicBool,
+    ptt_held: AtomicBool,
+}
+
+impl TransmitModeSelector {
+    /// Construct a selector wired to `gate`. Defaults:
+    /// [`TransmitMode::Ptt`], not in channel, not muted, key
+    /// released. The gate's initial value is left untouched until
+    /// the first mutating call (which then writes the resolved
+    /// value).
+    pub fn new(gate: AudioTransmitGate) -> Self {
+        Self {
+            gate: std::sync::RwLock::new(gate),
+            mode: AtomicU8::new(TransmitMode::default().as_u8()),
+            in_channel: AtomicBool::new(false),
+            hard_mute: AtomicBool::new(false),
+            ptt_held: AtomicBool::new(false),
+        }
+    }
+
+    /// Rewire the selector to a fresh [`AudioTransmitGate`]
+    /// (typically the gate exposed by a newly-started
+    /// [`crate::AudioEngine`]). Cached mode / channel / mute /
+    /// ptt_held are preserved; the new gate is immediately
+    /// updated to the resolved value.
+    pub fn replace_gate(&self, gate: AudioTransmitGate) {
+        if let Ok(mut g) = self.gate.write() {
+            *g = gate;
+        }
+        self.recompute();
+    }
+
+    /// Update the selected mode and re-evaluate the gate.
+    pub fn set_mode(&self, m: TransmitMode) {
+        self.mode.store(m.as_u8(), Ordering::Relaxed);
+        self.recompute();
+    }
+
+    /// Current selected mode.
+    pub fn mode(&self) -> TransmitMode {
+        TransmitMode::from_u8(self.mode.load(Ordering::Relaxed)).unwrap_or_default()
+    }
+
+    /// Update channel membership and re-evaluate.
+    pub fn set_in_channel(&self, v: bool) {
+        self.in_channel.store(v, Ordering::Relaxed);
+        self.recompute();
+    }
+
+    /// Current channel-membership flag.
+    pub fn in_channel(&self) -> bool {
+        self.in_channel.load(Ordering::Relaxed)
+    }
+
+    /// Final-clamp hard mute. When `true` the gate is forced to
+    /// `false` regardless of mode.
+    pub fn set_hard_mute(&self, v: bool) {
+        self.hard_mute.store(v, Ordering::Relaxed);
+        self.recompute();
+    }
+
+    /// Current hard-mute flag.
+    pub fn hard_mute(&self) -> bool {
+        self.hard_mute.load(Ordering::Relaxed)
+    }
+
+    /// PTT key state (set by the platform input backend through
+    /// [`crate::ReleaseTailTimer`]).
+    pub fn set_ptt_held(&self, v: bool) {
+        self.ptt_held.store(v, Ordering::Relaxed);
+        self.recompute();
+    }
+
+    /// Current PTT-held flag.
+    pub fn ptt_held(&self) -> bool {
+        self.ptt_held.load(Ordering::Relaxed)
+    }
+
+    /// Shared snapshot of the underlying gate. Provided for the
+    /// audio engine's hot read path. Returns a clone so callers
+    /// don't hold the internal lock.
+    pub fn gate(&self) -> AudioTransmitGate {
+        self.gate.read().expect("selector gate lock poisoned").clone()
+    }
+
+    fn compute(&self) -> bool {
+        if self.hard_mute.load(Ordering::Relaxed) {
+            return false;
+        }
+        if !self.in_channel.load(Ordering::Relaxed) {
+            return false;
+        }
+        match self.mode() {
+            TransmitMode::Ptt => self.ptt_held.load(Ordering::Relaxed),
+            // DEC-030: VoiceActivity behaves as Continuous in v1.
+            TransmitMode::Continuous | TransmitMode::VoiceActivity => true,
+        }
+    }
+
+    /// Recompute the desired gate state and publish it. Exposed
+    /// for tests; callers normally trigger this implicitly through
+    /// the setter methods.
+    pub fn recompute(&self) {
+        let desired = self.compute();
+        if let Ok(g) = self.gate.read() {
+            g.set(desired);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fresh() -> (AudioTransmitGate, TransmitModeSelector) {
+        let g = AudioTransmitGate::new(false);
+        let s = TransmitModeSelector::new(g.clone());
+        (g, s)
+    }
+
+    #[test]
+    fn ptt_requires_channel_and_key() {
+        let (g, s) = fresh();
+        s.set_mode(TransmitMode::Ptt);
+        s.set_ptt_held(true);
+        assert!(!g.load(), "no channel -> false");
+        s.set_in_channel(true);
+        assert!(g.load(), "channel + key -> true");
+        s.set_ptt_held(false);
+        assert!(!g.load(), "key released -> false");
+    }
+
+    #[test]
+    fn continuous_ignores_ptt_held() {
+        let (g, s) = fresh();
+        s.set_mode(TransmitMode::Continuous);
+        s.set_in_channel(true);
+        assert!(g.load(), "channel + continuous -> true");
+        s.set_ptt_held(true);
+        assert!(g.load());
+        s.set_ptt_held(false);
+        assert!(g.load(), "continuous independent of key state");
+    }
+
+    #[test]
+    fn voice_activity_matches_continuous_v1() {
+        let (g, s) = fresh();
+        s.set_mode(TransmitMode::VoiceActivity);
+        s.set_in_channel(true);
+        assert!(g.load());
+    }
+
+    #[test]
+    fn hard_mute_clamps() {
+        let (g, s) = fresh();
+        s.set_mode(TransmitMode::Continuous);
+        s.set_in_channel(true);
+        assert!(g.load());
+        s.set_hard_mute(true);
+        assert!(!g.load(), "hard mute clamps to false");
+        s.set_hard_mute(false);
+        assert!(g.load());
+    }
+
+    #[test]
+    fn leaving_channel_forces_false() {
+        let (g, s) = fresh();
+        s.set_mode(TransmitMode::Continuous);
+        s.set_in_channel(true);
+        assert!(g.load());
+        s.set_in_channel(false);
+        assert!(!g.load());
+    }
+}