edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1813bbaa0c02ed79f1f933a86b9a4eb369141bc7
chanora/README.md
T

13 KiB
Raw Blame History

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 in early planning and baseline-candidate design.

Current documentation baseline: v0.9.2
Current status: Baseline Candidate
Implementation status: Not production-ready

The current engineering focus is:

  • defining the system and software architecture;
  • preparing 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 24+ unless Flutter, plugin, audio, or product constraints require raising it
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 tsclientlib directly.
  • 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.GlobalShortcuts interface; 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 may be added later. A likely 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 should be finalized when the repository scaffold is created.

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

Implementation commands will be added after the repository scaffold is finalized.

Expected future commands may include:

flutter pub get
flutter test
cargo test
cargo clippy
cargo fmt

Do not treat these as authoritative until the actual Flutter/Rust workspace has been created.

Contributing

Before making a change:

  1. Check the affected requirement/design document.
  2. Confirm the correct traceability layer.
  3. Use the Git commit convention.
  4. 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:

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
Reference in New Issue View Git Blame Copy Permalink