EdisonJwa
7188a5a69d
Implementation of SDD-120 §1-§8: Bench harness (crates/chanora_audio/benches/): - common.rs: deterministic synthetic audio (440 Hz sine, no RNG). - realtime_capture.rs: bench_capture_alloc_count (dhat) + bench_capture_callback_wall_clock (criterion). - opus_codec.rs: bench_opus_encode_latency + bench_opus_decode_latency (direct audiopus, not AudioHandler — SDD-120 §3 item 4). - resampler.rs: bench_resampler_throughput across 44.1->48 / 16->48 / 48->48 passthrough. CI tooling (crates/chanora_audio/examples/): - emit_baseline.rs: aggregates criterion estimates.json outputs into the SRS-217 baseline schema. - compare_baseline.rs: applies SRS-219 tolerance, renders markdown table with 🟢/🟡/🔴 markers + yellow simpler-form realization per SDD-120 §8. Deviation from SDD-120 §2 / §5 / §7 placement: these tools live under examples/, not benches/ or src/bin/. Rationale: they must consume serde_json (a dev-only dep — production builds must not pull it). Cargo only resolves dev-dependencies for [[test]], [[bench]], and [[example]] targets; [[bin]] targets under src/bin/ see only regular [dependencies]. examples/ keeps the binaries out of the production dep tree while still giving them cargo run --example invocation. An SDD-120 amendment should reflect this. Workflows (.github/workflows/): - bench-advisory.yml: PR + push triggers; runs benches; posts a sticky PR comment via actions/github-script@v7; job status is always success (SRS-218 clause 4 — non-blocking). - bench-baseline-update.yml: workflow_dispatch only; runs benches; opens PR via peter-evans/create-pull-request@v6 (sole writer of the SAD-089 baseline JSON). Cargo.toml additions ([dev-dependencies] only — verified excluded from --release builds): criterion 0.5, dhat 0.3, serde_json 1. Source-code seam: minimal pub-but-#[doc(hidden)] bench_seam module in chanora_audio (engine.rs + lib.rs re-export) so the criterion bench harness can construct a CaptureState and drive CaptureState::ingest without re-implementing the engine (SDD-120 §3). Non-iOS targets only — CaptureState itself is iOS-gated. Initial baseline seed: crates/chanora_audio/benches/baselines/ x86_64-unknown-linux-gnu.json = {}. compare_baseline handles the missing-baseline case gracefully and emits a 'no red markers' report; the first manual dispatch of bench-baseline-update.yml after merge establishes the real values. Out of scope per SDD-120 §10: production telemetry export, build-failing hard CI gate, multi-host benchmarking, IDE integration, Dart-side bridge round-trip bench. Verification: - cargo check --workspace --all-targets: PASS. - cargo bench --bench realtime_capture --no-run: PASS. - cargo bench --bench opus_codec --no-run: PASS. - cargo bench --bench resampler --no-run: PASS. - cargo build --example emit_baseline --example compare_baseline -p chanora_audio: PASS. - cargo test --workspace: 106 passed, 0 failed, 3 ignored — no regression from prior count.
158 lines
7.3 KiB
TOML
158 lines
7.3 KiB
TOML
[package]
|
|
name = "chanora_audio"
|
|
description = "Chanora audio subsystem — cpal-based capture/playback, audiopus encode, tsclientlib AudioHandler for decode + jitter buffer + mix. DEC-011, DEC-011.1."
|
|
version.workspace = true
|
|
edition.workspace = true
|
|
rust-version.workspace = true
|
|
authors.workspace = true
|
|
license.workspace = true
|
|
repository.workspace = true
|
|
publish.workspace = true
|
|
|
|
[dependencies]
|
|
chanora_protocol = { path = "../chanora_protocol" }
|
|
thiserror.workspace = true
|
|
tracing.workspace = true
|
|
|
|
# Cross-platform audio I/O (DEC-011.1).
|
|
cpal = "0.17.3"
|
|
# Opus encoder. tsclientlib already pulls this; we depend explicitly so
|
|
# this crate can compile against it without going through tsclientlib.
|
|
audiopus = "0.3.0-rc.0"
|
|
|
|
# AudioHandler lives in the tsclientlib crate behind the `audio`
|
|
# feature. We import the crate just for the AudioHandler type; the
|
|
# Connection type stays inside chanora_protocol.
|
|
tsclientlib = { git = "https://github.com/ReSpeak/tsclientlib.git", rev = "04aa2491", default-features = false, features = ["audio"] }
|
|
tokio = { version = "1", features = ["sync", "rt", "macros", "time"] }
|
|
|
|
[target.'cfg(not(target_os = "android"))'.dependencies]
|
|
# Desktop/iOS: native TLS maps to the platform TLS backend (Security.framework
|
|
# on Apple, SChannel on Windows, system OpenSSL on Linux/BSD).
|
|
reqwest = { version = "0.13", default-features = false, features = ["charset", "http2", "native-tls"] }
|
|
|
|
[target.'cfg(target_os = "ios")'.dependencies]
|
|
# Direct CoreAudio AudioUnit access on iOS (DEC-011.x follow-up).
|
|
# cpal's iOS backend is unsuitable for VoIP: it opens
|
|
# kAudioUnitSubType_RemoteIO with a mono-only output element and no
|
|
# control over buffer size / sample rate, AND its AudioUnit stays
|
|
# bound to the route present at construction time so user-driven
|
|
# `overrideOutputAudioPort` flips do not actually move audio to the
|
|
# new transducer. Every production iOS VoIP client (Linphone, Mumble
|
|
# iOS, Signal, Jitsi, WebRTC reference) instead drives
|
|
# `kAudioUnitSubType_VoiceProcessingIO` (a.k.a. VPIO) directly. VPIO
|
|
# is Apple's recommended voice unit; it ships hardware AEC + AGC + NS
|
|
# and honours route changes natively because it IS the canonical
|
|
# voice unit on iOS. `coreaudio-rs` (RustAudio org, same maintainers
|
|
# as `cpal`, 8.6M downloads) gives us a safe wrapper around the
|
|
# AudioUnit C API. We use it on iOS only; cpal stays on macOS where
|
|
# its CoreAudio backend works well against HAL units.
|
|
#
|
|
# Default features keep `audio_toolbox` + `core_audio`, both required
|
|
# for AudioUnit construction + property access.
|
|
coreaudio-rs = "0.14"
|
|
|
|
[target.'cfg(target_os = "android")'.dependencies]
|
|
# Android cross-builds should not pull OpenSSL. Use rustls here while keeping
|
|
# native-tls for Apple targets where aws-lc/rustls is problematic for iOS.
|
|
reqwest = { version = "0.13", default-features = false, features = ["charset", "http2", "rustls"] }
|
|
# JNI bindings to flip Android's AudioManager into MODE_IN_COMMUNICATION
|
|
# when the voice-comm preset is requested. ndk_context is initialised
|
|
# by the bridge crate's android_init shim.
|
|
jni = { version = "0.21", default-features = false }
|
|
ndk-context = "0.1"
|
|
# Oboe-rs (Google Oboe wrapper) for low-latency voice capture + playback.
|
|
# Primary backend for SDD-111..SDD-115. The pre-compiled static library
|
|
# shipped with `oboe-sys` 0.6 covers armv7 / aarch64 / x86 / x86_64.
|
|
# Default features keep the precompiled library + pregenerated bindings
|
|
# so we avoid the clang-sys / libclang requirement on the build host.
|
|
oboe = "0.6"
|
|
|
|
[target.'cfg(target_os = "windows")'.dependencies]
|
|
# Real Windows global PTT (SDD-083 / SDD-084): RegisterRawInputDevices
|
|
# + WM_INPUT translation backed by a hidden message-only window, and
|
|
# SetWindowsHookExW(WH_KEYBOARD_LL / WH_MOUSE_LL) fallback. Both
|
|
# require a per-backend OS thread that owns a message pump.
|
|
windows = { version = "0.54", features = [
|
|
"Win32_Foundation",
|
|
"Win32_Graphics_Gdi",
|
|
"Win32_System_LibraryLoader",
|
|
"Win32_System_Threading",
|
|
"Win32_UI_Input",
|
|
"Win32_UI_Input_KeyboardAndMouse",
|
|
"Win32_UI_WindowsAndMessaging",
|
|
] }
|
|
|
|
[dev-dependencies]
|
|
# `test-util` enables `start_paused` / virtual-clock tests used by
|
|
# the missed-key-up watchdog unit tests.
|
|
tokio = { version = "1", features = ["sync", "rt", "macros", "time", "test-util"] }
|
|
# Cross-platform recording Layer for the SDD-090 / DEC-027 privacy
|
|
# invariant integration test (`tests/ptt_privacy.rs`).
|
|
tracing-subscriber = { version = "0.3", features = ["registry"] }
|
|
# SDD-120 §3 — criterion bench harness (realtime_capture / opus_codec /
|
|
# resampler). `harness = false` per bench entry below disables the
|
|
# default libtest harness so criterion can install its own.
|
|
criterion = "0.5"
|
|
# SDD-120 §3 item 1 — dhat is used as the global allocator inside
|
|
# `benches/realtime_capture.rs` to count post-warmup heap allocations
|
|
# on the realtime capture path. Dev-dep only — does NOT affect
|
|
# production builds.
|
|
dhat = "0.3"
|
|
# SDD-120 §5 / §8 — JSON serialization for `emit_baseline` /
|
|
# `compare_baseline` binaries that consume criterion's per-bench
|
|
# `estimates.json` outputs and emit the SRS-217 baseline schema.
|
|
serde_json = "1"
|
|
|
|
[[bench]]
|
|
name = "realtime_capture"
|
|
harness = false
|
|
path = "benches/realtime_capture.rs"
|
|
|
|
[[bench]]
|
|
name = "opus_codec"
|
|
harness = false
|
|
path = "benches/opus_codec.rs"
|
|
|
|
[[bench]]
|
|
name = "resampler"
|
|
harness = false
|
|
path = "benches/resampler.rs"
|
|
|
|
[target.'cfg(target_os = "linux")'.dependencies]
|
|
# GNOME-on-Wayland Global Push-to-Talk uses the freedesktop
|
|
# `org.freedesktop.portal.GlobalShortcuts` interface over D-Bus.
|
|
# `zbus` is the standard async D-Bus crate; the `tokio` runtime
|
|
# selector is mandatory in zbus 5; we share the tokio runtime
|
|
# the rest of the audio + core crates already depend on. The
|
|
# `blocking-api` feature is retained so the audio-engine
|
|
# probe path can do a synchronous portal-version read without
|
|
# starting an async runtime; the live session flow uses the
|
|
# async surface.
|
|
zbus = { version = "5", default-features = false, features = ["tokio", "blocking-api"] }
|
|
# Stream / sink utilities for consuming portal signals on the
|
|
# async path.
|
|
futures-util = { version = "0.3", default-features = false, features = ["std"] }
|
|
# Random token bytes for the portal handle_token / session_handle_token
|
|
# options. The portal recommends fresh tokens to scope its own
|
|
# object paths per call.
|
|
rand = "0.8"
|
|
# SDL2 audio for Linux. Replaces the cpal capture / playback paths
|
|
# on Linux only; cpal stays in use on Windows/macOS. Rationale: the
|
|
# cpal Linux backend opens raw ALSA `default`, which on most Arch
|
|
# / Fedora / Debian installs routes through `dmix` + `plug` with
|
|
# nearest-neighbour resampling and very small period sizes — the
|
|
# combination produces audible crackling/popping. SDL2 on the same
|
|
# systems routes through PipeWire's PulseAudio compat bridge (or
|
|
# real PulseAudio), both of which carry a high-quality resampler
|
|
# and a sensible default period. The upstream tsclientlib audio
|
|
# example (`tsclientlib/examples/audio_utils/ts_to_audio.rs`) and
|
|
# the official Qint client both use SDL2 in exactly this shape;
|
|
# this dep brings Chanora in line with that pattern.
|
|
#
|
|
# `bundled` is OFF deliberately — we link against the system
|
|
# libSDL2.so. Arch ships `sdl2-compat`; Debian/Ubuntu ship
|
|
# `libsdl2-2.0-0`; Fedora ships `SDL2`. The chanora-flutter Linux
|
|
# build documentation lists this as a runtime dependency.
|
|
sdl2 = { version = "0.37", default-features = false }
|