English | 日本語

tympan-aspl

A Rust framework for writing macOS AudioServerPlugins.

tympan-aspl provides Rust abstractions over the Core Audio HAL AudioServerPlugin interface, enabling Rust applications to implement custom virtual audio devices and audio drivers on macOS without writing C++ or Objective-C.

Status

Intended functionality complete. Every "In scope" item from docs/overview.md is implemented, and every non-Tier-4 entry in ADR 0001 is wired up on CI:

Framework

• Layer 1 — low-level AudioServerPlugin FFI (src/raw/): the extern "C" CFPlugIn factory and IUnknown vtable (raw::entry, raw::vtable), the C-ABI struct mirrors with compile-time static_assertions (raw::abi), property marshalling (raw::marshal), and the CoreFoundation glue (raw::cf, raw::clock).
• Layer 2 — realtime primitives (src/realtime/): the RealtimeContext type-level marker, a lock-free SPSC ring (realtime::ring), the atomic AudioServerPlugin lifecycle State, a wait-free CFPlugIn Refcount, and the off-thread log sink.
• Layer 3 — the object / property / dispatch surface (object, property, objects, dispatch) and the public API: Driver, Device, Stream, IoBuffer, and the plugin_entry! declarative macro that exports the CFPlugIn factory symbol.
• bundle — .driver bundle layout and Info.plist generation.

Examples

Three reference drivers under examples/, each a buildable .driver cdylib pinned alloc-free in CI:

• minimal-loopback/ — stateless stereo virtual loopback; the smallest viable driver.
• gain/ — fixed linear gain on the WriteMix direction; per-instance configuration template.
• lowpass/ — one-pole low-pass with per-channel filter memory; per-instance processing state, reset in start_io.

CI

Hosted CI cannot run a plug-in to completion: amfid rejects an ad-hoc-signed HAL bundle on macOS 15 before any plug-in code runs, and the runners produce no hardware audio I/O. Device-enumeration and audio-data-path checks therefore live in docs/testing.md Tier 4 as a pre-release manual / self-hosted checklist. The framework's raw_lifecycle in-process harness drives the actual AudioServerPlugInDriverInterface vtable end-to-end on every PR, so the FFI layer is exercised mechanically — just not by coreaudiod itself.

The framework is usable: write impl Driver for MyDriver and tympan_aspl::plugin_entry!(MyDriver) in a cdylib crate and the resulting .driver bundle loads in coreaudiod once Developer ID signed. See examples/minimal-loopback/ for the minimal recipe and docs/plugin-author-guide.md for the collected practical recipes (identity, packaging, realtime debugging, common pitfalls).

Future work

The path to full Tier 4 verification is documented in ADR 0001 § Trigger for revisiting. The next step is wiring a Developer ID signing identity (held as a GitHub secret) into Tier 3 — at which point device enumeration moves from Tier 4 back into hosted CI without a code change here. Audio-data-path I/O verification stays Tier 4 (the runners have no audio hardware) and requires a self-hosted runner or local machine.

A release.yml workflow that runs cargo publish --dry-run on tag push is planned; tracked separately.

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.

Quickstart for driver authors

Add a new cdylib crate that depends on this framework, implement Driver, and invoke plugin_entry!:

# Cargo.toml
[package]
name = "my-driver"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["rlib", "cdylib"]

[dependencies]
tympan-aspl = "0.1"

// src/lib.rs
use tympan_aspl::{
    plugin_entry, DeviceSpec, Driver, IoBuffer, RealtimeContext,
    StreamFormat, StreamSpec,
};

pub struct MyDriver;

impl Driver for MyDriver {
    const NAME: &'static str = "My Driver";
    const MANUFACTURER: &'static str = "your name";
    const VERSION: &'static str = "0.1.0";

    fn new() -> Self {
        Self
    }

    fn device(&self) -> DeviceSpec {
        let format = StreamFormat::float32(48_000.0, 2);
        DeviceSpec::new("com.example.mydriver", "My Driver", Self::MANUFACTURER)
            .with_sample_rate(48_000.0)
            .with_input(StreamSpec::input(format))
            .with_output(StreamSpec::output(format))
    }

    fn process_io(&mut self, _rt: &RealtimeContext, buffer: &mut IoBuffer<'_>) {
        // Allocation-free, lock-free path.
        let n = buffer.output.len().min(buffer.input.len());
        buffer.output[..n].copy_from_slice(&buffer.input[..n]);
        buffer.output[n..].fill(0.0);
    }
}

plugin_entry!(MyDriver);

Build with cargo build --release, assemble the .driver bundle — the committed Info.plist plus the built cdylib placed in Contents/MacOS/ — and install it under /Library/Audio/Plug-Ins/HAL/. For local development on a SIP-disabled developer machine, an ad-hoc signature is enough to get the bundle on disk; on production macOS 15 the coreaudiod helper requires the bundle to be Developer ID signed before it will load to completion. See docs/plugin-author-guide.md for the packaging recipe and examples/minimal-loopback/ for the same shape as a complete crate.

Development

The project's CI tiers (described above) are split across .github/workflows/tier1.yml, tier2.yml, tier3.yml, tier3-asan.yml, and tier3-tsan.yml; ADR 0001 records the tiered verification strategy.

To run the same fmt and clippy checks locally before every git push, opt into the repository's pre-push hook:

git config core.hooksPath .githooks

The hook lives in .githooks/pre-push. It is a no-op when no *.rs, Cargo.toml, or Cargo.lock files changed in the pushed range, so documentation-only pushes are not slowed down. Bypass it for a single push with git push --no-verify.

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

Examples