Edison Jwa
2f6d45fb04
* feat(audio): add Silero ONNX VAD with WebRTC fallback Introduce SileroOnnxVad and SileroOnnxVadWorker for desktop targets. The worker runs Silero v6 ONNX inference on a dedicated thread, accumulating 10 ms frames into the 512-sample 16 kHz input the model expects. Add VadOutput, VoiceActivityDetector trait, and WebRtcFallbackVad to provide a uniform VAD interface with graceful fallback when the ONNX model is unavailable. Wire the new VadBackend variants through AudioProcessingConfig and the snapshot stats so the bridge can report which detector is active. * feat(audio): integrate desktop VAD worker into capture engine Wire SileroOnnxVadWorker into the desktop capture path so voice activity can open the transmit gate before encoding. The capture callback now processes all audio through resample, downmix, and VAD unconditionally; transmit_active still gates Opus encoding. Add new_desktop_audio_processing_state() to construct the config/stats/worker triple, and apply_desktop_vad_backend() to synchronously load or clear the worker on config changes. Override processing_backend to Noop for desktop so bridge diagnostics report the correct backend rather than the iOS-oriented PlatformVoiceProcessing default. Includes review-driven cleanups: StreamConfig clone to deref per clippy, and a comment explaining why two try_lock calls on silero_vad_worker are structurally necessary (borrow checker requires the policy probe and the fallback path to not share a lock guard because mark_vad_fallback_active takes &mut self). * fix(audio): modernize Windows PTT to current windows-rs API Port the Raw Input plus low-level keyboard hook PTT backend to the newer windows-rs patterns: OptionalHandle, Result-returning CreateWindowExW, and None for CallNextHookEx. Replaces the old HHOOK(0) pointer casts. Add deterministic tests for mouse button 4 and 5 press and release driving the gate. * build(windows): force MSVC release CRT for audiopus cmake builds audiopus_sys calls cmake::build(opus_path), so downstream Cargo env cannot use cmake-rs Config::define() to override CMake's MSVC Debug CRT defaults. Point cmake-rs at a small wrapper that injects the policy and cache variables during configure while passing cmake --build, --version, and -E through unchanged. Keeps Opus Debug builds on Rust's release dynamic CRT (/MD) instead of CMake's default debug CRT (/MDd), which otherwise pulls in unresolved __imp__CrtDbgReportW symbols at test link. Document that the iOS deployment target is intentionally absent from this file. It is enforced by tools/build-ios.sh and the Xcode project; setting it globally here would make native macOS cargo check runs try to link iPhone objects against the macOS SDK. * build(flutter): update pubspec.lock after plugin additions Regenerated lockfile reflecting the local_notifications and connectivity_plus plugin additions from the poke-notifications feature. * fix(audio): address PR #37 review findings Six fixes from independent PR review: 1. BLOCKER: Replace Windows-only cmake .cmd wrapper with cross-platform CMake env vars. Setting CMAKE=tools/cmake-msvc-release-crt.cmd globally broke non-Windows hosts because cmake-rs would try to execute a .cmd file on macOS/Linux. Instead, set CMAKE_POLICY_DEFAULT_CMP0091=NEW and CMAKE_MSVC_RUNTIME_LIBRARY= MultiThreadedDLL as env vars that CMake reads natively. MSVC- specific vars are safely ignored by GCC/Clang toolchains. Delete the now-unnecessary wrapper script. 2. IMPORTANT: Join the Silero worker thread in Drop instead of detaching it. The old code dropped the JoinHandle which detaches the thread; the new code calls handle.join() after closing the channel, ensuring the ONNX session is cleaned up before the worker is replaced during config changes. 3. IMPORTANT: Single-try_lock refactor of the capture VAD callback. The double try_lock (policy probe + send) is replaced by a single scoped try_lock that both probes availability and sends the frame. The guard is dropped before the fallback path, which needs &mut self for mark_vad_fallback_active. This also eliminates the VadWorkerPolicy enum and callback_vad_worker_policy function, whose behavior is now inlined into the callback. 4. IMPORTANT: Remove tracing from the realtime capture callback. mark_vad_fallback_active and sync_vad_backend emitted info!/warn! from the audio thread. Replace with silent atomic state publishing via SharedAudioProcessingStats; the bridge stats stream already exposes vad_fallback_active for diagnostics. 5. IMPORTANT: Defer ONNX model load outside the worker mutex. apply_desktop_vad_backend_to_worker now constructs the new worker before taking the lock, then swaps it in under a short hold. This prevents the realtime callback from being blocked during model I/O + thread spawn. 6. MINOR: Remove unused VadBackend import from vad/mod.rs after deleting the policy code. * fix(audio): address PR #37 second-pass review findings 5-agent review found 5 blocking issues. All addressed: 1. BLOCKER: CMake env vars don't reach CMake cache. Restored .cmd wrapper but scoped to Windows MSVC targets only via [target.x86_64-pc-windows-msvc] and [target.aarch64-pc-windows-msvc] in .cargo/config.toml. Non-Windows hosts are unaffected. 2. BLOCKER: processing_backend normalized in set_audio_processing_config on desktop (cfg-gated override to Noop), mirroring startup default. 3. BLOCKER: Model-path reload was already wired via reload_audio_processing_config. Fixed misleading doc comment in core/lib.rs. 4. BLOCKER: DEC-030 updated to reflect desktop VoiceActivity enablement. Traceability docs (SRS, SysDes, SAD, SDD, implementation-status) updated. 5. Silero ONNX cfg narrowed to desktop-only (excludes macOS/Android). Cargo.toml ort dependency target cfg narrowed similarly. 6. Realtime callback debt documented as TODO at CaptureState::ingest. * fix(audio): exclude ort dep on Android target ort does not provide first-class Android prebuilts in our pin, mirror the iOS/macOS exclusion so cargo metadata succeeds for android targets. * test(audio): fix stale select_ptt_backend import in ptt_privacy The helper moved out of the ptt_backends submodule onto the crate root; update the integration test imports so the test compiles again. * build(windows): scope MSVC release CRT cmake wrapper via Cargo [env] Cargo's [target.<triple>] table only forwards a fixed allowlist (linker, runner, rustflags, rustdocflags, ar), so setting CMAKE there was silently dropped and audiopus_sys kept linking the debug CRT, producing LNK4098 'MSVCRTD conflicts' and __imp__CrtDbgReportW errors on x86_64-pc-windows-msvc test builds. Move the override to Cargo's [env] table using cc/cmake-rs's target-suffixed CMAKE_<triple> lookup (force=true, relative=true) so it applies to MSVC targets only and not to host tooling. Add stdout markers to the wrapper so its invocation is provable in cargo -vv logs. Verified: cargo test -p chanora_audio --target x86_64-pc-windows-msvc --lib --no-run now links cleanly; CMakeCache.txt records CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL and CMP0091=NEW. * fix(flutter): gate VoiceActivity transmit mode by platform support VoiceActivity relies on the native VAD worker, which is only wired up on Windows, Linux, and Android. Showing the option on iOS, macOS, or web let users select a mode that silently never transmitted. Add voiceActivityTransmitAvailable + transmitModeSegmentsFor() helpers in voice_settings_controls.dart, hide the VAD row in voice_compact.dart and drop the VAD segment from the settings dialog when unsupported. Keep the legacy const transmitModeSegments for the existing widget test and add two new tests covering the gated helper.
Chanora
Chanora is a cross-platform voice communication client for TeamSpeak-compatible servers.
It is built with a shared Flutter UI and a Rust core, with TeamSpeak-compatible protocol integration isolated behind tsclientlib.
Flutter UI + Rust Core + tsclientlib
Chanora is an independent project and is not affiliated with, endorsed by, sponsored by, or officially associated with TeamSpeak.
Status
Chanora is currently a baseline-candidate Flutter + Rust workspace. It is not production-ready and is not approved for public or store release.
Current documentation baseline: v0.9.x document set
Current status: Baseline Candidate
Implementation status: Not production-ready
The current engineering focus is:
- defining the system and software architecture;
- hardening the Flutter + Rust application structure;
- validating TeamSpeak-compatible protocol integration through
tsclientlib; - defining cross-platform audio behavior;
- preparing release, verification, security, privacy, and legal gates.
Target Platforms
Chanora is intended to support:
- Windows
- macOS
- Linux
- Android
- iOS / iPadOS
Current platform policy:
| Platform | Baseline |
|---|---|
| iOS / iPadOS runtime target | iOS 16+ while Apple CoreML Silero VAD is linked |
| macOS runtime target | macOS 13+ while Apple CoreML Silero VAD is linked |
| App Store Connect upload gate | Xcode 26+ with iOS 26 / iPadOS 26 SDK+ for upload on or after 2026-04-28 |
| Android runtime target | Android API 28+ per DEC-004, SysRS-288, SRS-187, and Gradle minSdk = 28 |
| Google Play target API | Target the Google Play-required API level on upload date |
The App Store / Play Store upload gates are release requirements. They are separate from local development and internal testing requirements.
Apple CoreML VAD development requires the private silero-coreml SwiftPM package checked out as a sibling of this repository, so the app checkout and package checkout share the same parent directory:
workspace/
chanora/
silero-coreml/
The iOS and macOS Xcode projects reference that package via ../../../../silero-coreml from their project files. GitHub CI skips the unsigned iOS build when the sibling package is unavailable, but local Apple builds need that checkout.
Architecture Overview
Chanora separates UI, protocol logic, state synchronization, audio processing, diagnostics, and platform services.
Flutter Application
├─ App Shell
├─ Material 3 / Chanora Design System
├─ Feature Modules
├─ View Models / State
└─ Typed Flutter/Rust Bridge
Rust Core
├─ Connection Manager
├─ State Synchronization
├─ Protocol Adapter
├─ Audio Subsystem
├─ Storage Services
└─ Diagnostics
Protocol Layer
└─ tsclientlib
└─ TeamSpeak-compatible server
Key architecture rules:
- Flutter does not call
tsclientlibdirectly. - Protocol-specific types do not leak into the Flutter UI layer.
- Rust Core owns protocol coordination, state synchronization, audio logic, storage services, diagnostics, and bridge-facing DTOs.
- Flutter owns presentation, navigation, Material 3 theming, accessibility, localization presentation, and platform UI behavior.
- Product localization and server-provided content are separated.
- UTF-8 is the internal cross-layer text representation.
- Non-UTF-8 conversion, if needed, occurs only at explicit protocol or platform boundaries.
MVP Direction
The current recommended MVP scope is:
| Area | MVP decision |
|---|---|
| Active server connections | One active server connection per client instance |
| UI baseline | Material 3 + Chanora Design System |
| Product language | English UI first, i18n-ready architecture |
| Server content | Preserve Unicode and do not translate server-provided content |
| Audio processing defaults | Echo Canceller, Automatic Gain Control, Noise Suppression, and High-Pass Filter enabled where supported and stable |
| Audio implementation path | Platform-native first; fallback isolated behind the audio subsystem |
| Local non-secret storage | SQLite or equivalent embedded database |
| Secret storage | Platform secure storage |
| Flutter/Rust bridge | Stable typed bridge with generated or schema-controlled DTOs |
| Diagnostics | Local, user-initiated export only |
| Telemetry | None in MVP |
| Crash reporting | Disabled unless explicitly approved later |
Desktop Push-to-Talk
Chanora's desktop Push-to-Talk (PTT) follows a capability-based design (see
docs/architecture/desktop-ptt-architecture.md).
Focused PTT — the user holds a bound key or mouse button inside the
focused Chanora window — is mandatory on Windows, macOS, and Linux.
Global PTT (recognised while the application is not focused) is
capability-dependent: it requires the operating system, the
user-granted permission set, the display server, and the available
input backend to all permit it.
The application reports a PttCapabilityLevel (L0Focused,
L1GlobalShortcut, L2GlobalHoldToTalk, L3GlobalWithMouseButtons)
that matches actual runtime behaviour, not the platform's theoretical
maximum. The UI capability badge shows the live value.
Per-platform strategy (resolved by owner rulings 2026-05-15, see
docs/governance/product-decision-register.md DEC-023 through
DEC-028):
- Windows — Raw Input first, low-level keyboard hook fallback, Focused PTT terminal fallback. Mouse side buttons supported. P0 / MVP.
- macOS — permission-aware Event Tap with Focused PTT fallback; Global PTT upgrades asynchronously when the user grants Input Monitoring / Accessibility. P0 / MVP.
- Linux — officially tested on GNOME on Wayland using the
org.freedesktop.portal.GlobalShortcutsinterface; every other Linux environment falls back to Focused PTT. Release notes do not claim Global PTT support outside the tested compositor. - Raw key codes, scan codes, virtual-key values, keysyms, and key-press timing sequences are never logged or included in the user-initiated diagnostic export. The diagnostic export carries only capability level, backend identifier, and bound input class.
A missed-key-up watchdog (default 30 s) clears transmit_active
when the OS suppresses a key-up event so a stuck-PTT bug class is
ruled out by construction.
Repository Layout
The repository documentation is expected to live under docs/.
docs/
requirements/
sysrs.md
srs.md
architecture/
sysdes.md
sad.md
sdd.md
verification/
verification-master-plan.md
swe4-unit-verification-plan.md
swe5-software-integration-verification-plan.md
swe6-software-verification-plan.md
sys4-system-integration-verification-plan.md
release/
release-readiness-go-nogo-record.md
platform-release-policy.md
security/
security-privacy-legal-guideline.md
threat-model.md
secure-storage-audit-report.md
diagnostic-redaction-audit-report.md
dependency-and-supply-chain-report.md
privacy/
privacy-policy.md
legal/
trademark-and-attribution-review.md
ui-ux/
material3-guideline.md
material3-design-tokens.md
material3-component-catalog.md
adaptive-layout-platform-guide.md
i18n/
localization-architecture.md
governance/
document-index.md
document-naming-convention.md
traceability-matrix.md
baseline-approval-record.md
baseline-candidate-validation-report.md
document-review-report.md
product-decision-register.md
decision-impact-assessment.md
git-commit-message-convention.md
repo-format-validation-report.md
path-migration-map.md
references/
external-references.md
aspice-swe2-swe3-integration-note.md
Implementation source folders are present in this workspace. The current high-level structure is:
apps/
chanora_flutter/
core/
chanora_core/
crates/
chanora_protocol/
chanora_audio/
chanora_state/
chanora_storage/
chanora_diagnostics/
chanora_bridge/
The exact implementation layout may continue to evolve as maintainability reviews split or merge Modules, but the repository scaffold exists.
Documentation Entry Points
Start here:
| Topic | Document |
|---|---|
| System requirements | docs/requirements/sysrs.md |
| Software requirements | docs/requirements/srs.md |
| System architecture | docs/architecture/sysdes.md |
| Software architecture | docs/architecture/sad.md |
| Software detailed design | docs/architecture/sdd.md |
| Verification strategy | docs/verification/verification-master-plan.md |
| Release readiness | docs/release/release-readiness-go-nogo-record.md |
| Platform release policy | docs/release/platform-release-policy.md |
| Product decisions | docs/governance/product-decision-register.md |
| Traceability | docs/governance/traceability-matrix.md |
| Security/privacy/legal gates | docs/security/security-privacy-legal-guideline.md |
Engineering Process
Chanora follows this documentation hierarchy:
SysRS -> SysDes -> SRS -> SAD -> SDD
Direct traceability rules:
| Document | Direct upstream source |
|---|---|
| SysDes | SysRS |
| SRS | SysDes only |
| SAD | SRS only |
| SDD | SAD only |
Verification mapping:
SDD -> SWE.4 Unit Verification
SAD + SDD -> SWE.5 Software Integration Verification
SRS -> SWE.6 Software Verification
SysDes -> SYS.4 System Integration Verification
Release readiness is tracked separately through the Go/No-Go record.
Release Readiness
A release is not approved by design documents alone.
Before an external or public release, the project must complete:
docs/release/release-readiness-go-nogo-record.md
The release decision must explicitly state:
Go
Conditional Go
No-Go
Release readiness must include:
- release scope;
- build number;
- commit SHA;
- Git tag;
- artifact hashes;
- satisfied P0/MVP requirements;
- deferred requirements;
- verification results;
- waivers;
- security review status;
- platform readiness;
- legal and OSS review status;
- privacy policy status;
- approval decision and approvers.
Security, Privacy, and Legal Gates
Security, privacy, and legal evidence are required before public or store release.
Required documents include:
docs/security/threat-model.md
docs/security/secure-storage-audit-report.md
docs/security/diagnostic-redaction-audit-report.md
docs/security/dependency-and-supply-chain-report.md
docs/privacy/privacy-policy.md
docs/legal/trademark-and-attribution-review.md
Important gates:
- identity secrets and server passwords must use platform secure storage;
- logs and diagnostic exports must redact secrets;
- diagnostic export must be user-initiated unless a later approved policy changes this;
- dependency licenses and vulnerabilities must be reviewed;
- OSS notices must be prepared where required;
- public wording must not imply official TeamSpeak affiliation;
- privacy policy must describe local storage, diagnostics, permissions, and data handling.
Git Commit Convention
Chanora uses a Conventional Commits style format:
<type>(<scope>): <summary>
Examples:
feat(voice): add push-to-talk state handling
fix(protocol): recover channel tree after reconnect snapshot
docs(sad): add interface catalog and performance view
i18n(ui): add fallback behavior for missing localization keys
sec(diagnostics): redact server password from export bundle
release(android): prepare internal alpha build metadata
See:
docs/governance/git-commit-message-convention.md
Development
Common local commands include:
flutter pub get
flutter test
cargo test
cargo clippy
cargo fmt
Android runtime success also requires an available Android NDK toolchain and an authorized device or emulator for build/install/smoke verification.
Contributing
Before making a change:
- Check the affected requirement/design document.
- Confirm the correct traceability layer.
- Use the Git commit convention.
- Update docs and verification plans when the change affects requirements, architecture, detailed design, release behavior, security, privacy, or legal gates.
License
Chanora is dual-licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option. This dual-license model was Accepted on 2026-05-14
as decision DEC-020 in
docs/governance/product-decision-register.md.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Chanora by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.
Third-party software bundled or linked by Chanora is listed in
NOTICE with its own licenses. The complete legal review of
the dependency tree (DEC-012) must complete before any public/store
release. See:
docs/governance/product-decision-register.md
docs/security/dependency-and-supply-chain-report.md
docs/legal/trademark-and-attribution-review.md