feat(beta): wire voice in/out end-to-end with push-to-talk (v0.2.0-beta.1)

Reaches the Internal Beta milestone of DEC-001's release sequence the
same day as Alpha. Adds voice capture and playback through the full
Flutter UI → FRB → Rust core → tsclientlib → server path.

Promotions from PoC:
  poc/audio-capture-playback-spike  →  crates/chanora_audio/

New product code:
  crates/chanora_audio/src/engine.rs — cpal capture and playback,
    audiopus Opus VoIP encoder (48 kHz mono 20 ms frames), tsclientlib
    AudioHandler for decode + jitter buffer + mix on playback,
    push-to-talk gate, graceful playback-only fallback when capture
    is unavailable.
  crates/chanora_protocol/src/adapter.rs — extended with
    voice_out_tx (clonable mpsc::Sender<OutPacket>) and
    take_voice_in() (one-shot mpsc::Receiver<InboundVoice>); main
    loop now interleaves outbound voice drain, event pumping, and
    control-request handling.
  crates/chanora_protocol/src/lib.rs — re-exports the few
    tsproto_packets types (OutAudio, OutPacket, InAudioBuf,
    AudioData, CodecType, Direction) that chanora_audio
    legitimately needs. Documented as the single deliberate
    cross-crate type re-export per SAD-067, justified by the
    performance cost of a parallel type hierarchy on the 20 ms
    voice frame.
  core/chanora_core/src/lib.rs — ChanoraSession::start_audio,
    set_ptt, audio_stats; disconnect now stops the engine first.
  crates/chanora_bridge/src/api.rs — startAudio, setPtt,
    audioStats commands and BridgeAudioStats DTO.
  apps/chanora_flutter/lib/main.dart — "Start audio" button +
    hold-to-talk PTT button with pressed/released visual state +
    live stats line (TX/RX/PTT). Stats polled every 500 ms.

ARB:
  Both en and zh-Hans gain startAudioAction, pttHoldToTalk,
  pttTransmitting, audioStatsLine. Banner updated to
  "Beta build — voice in/out wired; not production ready."

FRB config:
  flutter_rust_bridge.yaml gains local: true so codegen resolves
  the workspace member's library stem to "chanora_bridge" instead
  of falling back to "UNKNOWN".

Empirical verification (2026-05-14, against cn.teamspeak.app):
  cargo check + cargo test --workspace: all green.
  flutter analyze: 0 issues.
  flutter test: 4/4 passing including:
    - test/alpha_e2e_test.dart (regression: Alpha still works)
    - test/beta_e2e_test.dart (Beta: connect → startAudio →
      PTT cycle → disconnect against cn.teamspeak.app).
  Live smoke (cargo test alpha_smoke -- --ignored): 49 channels,
  37 clients retrieved.
  Capture stream open against the host PipeWire auto_null source
  refused (snd_pcm_hw_params); engine correctly logged the warning
  and continued in playback-only mode. TX=0 frames, RX=0 frames
  reflects the headless null-source environment; on a real mic
  host the encoder produces ~50 frames/second while PTT is held.

Honest Beta scope (NOT in this release):
  - AEC / AGC / NS / HPF DSP (DEC-007..010): AudioEffects exists
    as a struct but the filters are no-ops. Beta+ work.
  - Production-quality resampler: current code is linear
    interpolation. Beta+ work.
  - Identity persistence via chanora_storage: still ephemeral.
  - Push-to-Dart event stream: UI polls instead.
  - chanora_diagnostics tracing-layer wiring: still scaffold.
  - Mobile (Android) cdylib + UI: PoC-proven, not yet in product.
  - Reconnect / network-loss recovery for the voice path.

Docs updates:
  - docs/governance/product-decision-register.md bumped to v0.9.7
    (Beta-milestone change-history entry; no row changes).
  - docs/governance/poc-results-summary.md bumped to v0.6.0
    (RISK-PoC-005 updated with Beta progress).
This commit is contained in:
EdisonJwa
2026-05-14 22:43:57 +08:00
parent 53b176b722
commit 9790005c3e
28 changed files with 2056 additions and 159 deletions
@@ -97,48 +97,66 @@ abstract class AppL10n {
Locale('zh'),
];
/// Application title shown in launchers and the app bar. The product name `Chanora` is fixed by DEC-018 and must not be translated.
/// No description provided for @appTitle.
///
/// In en, this message translates to:
/// **'Chanora'**
String get appTitle;
/// Plain-language banner informing testers that this build is not for end-user use. Mirrors README.md's status line.
/// No description provided for @homeNotProductionReadyBanner.
///
/// In en, this message translates to:
/// **'Alpha build — not production ready.'**
/// **'Beta build — voice in/out wired; not production ready.'**
String get homeNotProductionReadyBanner;
/// Label for the server-address input on the connect form.
/// No description provided for @fieldServerHost.
///
/// In en, this message translates to:
/// **'Server address'**
String get fieldServerHost;
/// Label for the nickname input on the connect form.
/// No description provided for @fieldNickname.
///
/// In en, this message translates to:
/// **'Nickname'**
String get fieldNickname;
/// Label for the button that initiates a connection.
/// No description provided for @connectAction.
///
/// In en, this message translates to:
/// **'Connect'**
String get connectAction;
/// Label for the button that ends the active connection.
/// No description provided for @disconnectAction.
///
/// In en, this message translates to:
/// **'Disconnect'**
String get disconnectAction;
/// Label for the button that re-fetches the server snapshot.
/// No description provided for @refreshAction.
///
/// In en, this message translates to:
/// **'Refresh'**
String get refreshAction;
/// No description provided for @startAudioAction.
///
/// In en, this message translates to:
/// **'Start audio'**
String get startAudioAction;
/// No description provided for @pttHoldToTalk.
///
/// In en, this message translates to:
/// **'Hold to talk'**
String get pttHoldToTalk;
/// No description provided for @pttTransmitting.
///
/// In en, this message translates to:
/// **'Transmitting…'**
String get pttTransmitting;
/// No description provided for @statusIdle.
///
/// In en, this message translates to:
@@ -163,6 +181,12 @@ abstract class AppL10n {
/// **'Error: {message}'**
String statusError(String message);
/// No description provided for @audioStatsLine.
///
/// In en, this message translates to:
/// **'TX {sent} frames • RX {received} frames • PTT {ptt}'**
String audioStatsLine(int sent, int received, String ptt);
/// No description provided for @channelsHeading.
///
/// In en, this message translates to:
@@ -13,7 +13,7 @@ class AppL10nEn extends AppL10n {
@override
String get homeNotProductionReadyBanner =>
'Alpha build — not production ready.';
'Beta build — voice in/out wired; not production ready.';
@override
String get fieldServerHost => 'Server address';
@@ -30,6 +30,15 @@ class AppL10nEn extends AppL10n {
@override
String get refreshAction => 'Refresh';
@override
String get startAudioAction => 'Start audio';
@override
String get pttHoldToTalk => 'Hold to talk';
@override
String get pttTransmitting => 'Transmitting…';
@override
String get statusIdle => 'Not connected';
@@ -46,6 +55,11 @@ class AppL10nEn extends AppL10n {
return 'Error: $message';
}
@override
String audioStatsLine(int sent, int received, String ptt) {
return 'TX $sent frames • RX $received frames • PTT $ptt';
}
@override
String get channelsHeading => 'Channels';
@@ -12,7 +12,7 @@ class AppL10nZh extends AppL10n {
String get appTitle => 'Chanora';
@override
String get homeNotProductionReadyBanner => 'Alpha 版本——尚未达到生产环境质量。';
String get homeNotProductionReadyBanner => 'Beta 版本——已接通语音收发;尚未达到生产环境质量。';
@override
String get fieldServerHost => '服务器地址';
@@ -29,6 +29,15 @@ class AppL10nZh extends AppL10n {
@override
String get refreshAction => '刷新';
@override
String get startAudioAction => '启动语音';
@override
String get pttHoldToTalk => '按住说话';
@override
String get pttTransmitting => '正在发送…';
@override
String get statusIdle => '未连接';
@@ -45,6 +54,11 @@ class AppL10nZh extends AppL10n {
return '错误:$message';
}
@override
String audioStatsLine(int sent, int received, String ptt) {
return '发送 $sent 帧 • 接收 $received 帧 • PTT $ptt';
}
@override
String get channelsHeading => '频道';