tympan-apo

Read this in other languages: 日本語.

A Rust framework for writing Windows Audio Processing Objects (APOs).

tympan-apo provides Rust abstractions over the Windows Audio Processing Object COM interfaces, enabling Rust applications to implement custom system-effect audio processors (SFX, MFX) that run inside the Windows Audio Engine without writing C++.

Special support is included for the Windows 11 AEC APO API, allowing Rust code to participate in the official acoustic-echo-cancellation processing slot in the microphone capture pipeline.

Status

Intended functionality complete. Every "In scope" item from docs/overview.md is implemented:

COM object infrastructure — IUnknown, IClassFactory, registration, and the four Dll* exports (src/raw/).
The required interface set — IAudioProcessingObject family plus IAudioSystemEffects v1/v2/v3 — and the SFX, MFX, and EFX categories.
AEC APO support (src/aec/): the AecProcessingObject foundation, the COM bridge (AecApoInstanceCom + register_aec_apo!), and the aec_scaffold example, gated behind the aec feature.
Format negotiation for both WAVEFORMATEX and WAVEFORMATEXTENSIBLE (src/format.rs).
Realtime-safe primitives (src/realtime/): a lock-free ring buffer, atomic state helpers, and an atomic refcount.
Registration helpers (src/clsid.rs, src/raw/register.rs, src/inf.rs, src/fx_properties.rs): CLSID assignment, registry writes, an INF generator, and FxProperties endpoint binding.
Example APOs under examples/: passthrough, gain, and aec_scaffold.

CI runs Tier 1 (fmt, clippy, build/test), Tier 2 (multi-DLL export, dependency, and signing verification), and Tier 3 (the COM lifecycle harness, including the AEC variant, plus an AddressSanitizer nightly). See docs/architecture.md for the API design and docs/testing.md for the CI strategy.

Naming

Tympan — the tympanal organ of moths, a membrane-based ultrasound sensor on the abdomen of pyralid and noctuid moths. Evolved to detect the echolocation calls of bats. The name reflects the library's role: a thin membrane between the OS audio engine and user-space Rust code.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Documentation