Hail is a portable capture, playback and full-duplex PCM transport written in C11. Bounded queues carry samples and timing metadata between native audio devices and application threads. Capture continues while playback is interrupted; generations keep delayed writes from reviving cancelled audio.
Transport, execution ownership and platform implementation stay separate:
application / optional Hull binding
speech · DSP · recording · sensing
|
timestamped PCM + status
|
+-------------+-------------+
| |
capture queue playback queue
drop newest silence on underrun
| |
| render reference
+-------------+-------------+
|
private backend contract
/ \
execution ownership platform resources
serialized external drive CoreAudio · WASAPI
concurrent gates/snapshots PipeWire · ALSA · virtual
Execution ownership is explicit rather than inferred from a platform name. Backend-specific clocks, fault controls and scratch stay inside their adapter. Structural checks enforce the portable boundary; source and failure-path audits are recorded in the axis audit and C audit.
One Hail allocation per context and stream. No steady-state Hail allocations.
Native SDK allocations are outside that budget. Public names use ha_ and HA_;
streams and contexts are opaque. The version 0.1 ABI remains provisional.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure
./build/hail_virtual_exampleThe deterministic example needs no audio hardware. It uses a caller-owned arena and exercises duplex PCM, interruption, stale writes and device loss. CoreAudio is enabled by default on macOS, WASAPI on Windows; the default tests do not open native audio streams.
# Linux native backends; requires ALSA and PipeWire development packages
cmake -S . -B build-linux -DHA_BACKEND_ALSA=ON -DHA_BACKEND_PIPEWIRE=ON
# Shared library
cmake -S . -B build-shared -DHA_BUILD_SHARED=ON
# Freestanding allocation: supply an allocator; native backends are excluded
cmake -S . -B build-arena -DHA_FREESTANDING=ON
# ASan + UBSan with a supported GCC/Clang toolchain
cmake -S . -B build-asan -DHA_SANITIZER=address -DCMAKE_BUILD_TYPE=Debug
# Native Windows: use ClangCL for C11 atomics
cmake -S . -B build-win -T ClangCL
cmake --build build-win --config Release --parallel
ctest --test-dir build-win -C Release --output-on-failureSee the build guide for dependencies, installation, CMake and pkg-config consumers, sanitizers and explicitly selected native tests.
An opened, running duplex stream exposes bounded copy operations. Each block carries its sample position, clock domain/epoch and available timing facts.
#include <hail.h>
/* Function-body excerpt. s is an opened, running mono S16 duplex stream.
* This example runs on its serialized control owner; dedicated PCM roles
* can run concurrently. */
ha_stream_status status = HA_INIT(ha_stream_status);
ha_block_info block = HA_INIT(ha_block_info);
int16_t input[256], output[256] = {0};
uint32_t captured = 0, accepted = 0;
ha_result result = ha_stream_get_status(s, &status);
if (result == HA_OK) {
result = ha_stream_write(s, output, 256,
status.playback_generation, &accepted);
/* Handle partial acceptance, WOULD_BLOCK, BUSY and terminal state. */
}
result = ha_stream_read(s, input, 256, &captured, &block);
/* Consume captured frames when result is HA_OK; an empty queue returns
* HA_WOULD_BLOCK. PCM format must match the negotiated stream format. */This illustrates the transfer API, not construction or teardown. The complete virtual example demonstrates those lifecycle steps; the native example enumerates real endpoints without opening a microphone. Start, stop, flush and close complete through control polling. Applications must quiesce their data roles before final destruction.
- Independent duplex legs. Capture/render rates, periods and clocks need not match.
- Bounded flow. Capture drops newest when full; playback fills missing frames with silence. Losses remain observable.
- Playback generations. Flush invalidates old writes. Native render-only reset preserves capture where supported.
- Honest time. Clock domains, epochs, validity and uncertainty accompany PCM. Unknown timing stays unknown.
- Render reference. Optional selected playback PCM supports external processing; it is not proof of audible DAC output.
- Safe retirement. Cancellation does not free storage. Native workers/callbacks must retire before reclamation, including failed opens.
- Exact application PCM. Native-endian S16/F32, interleaved mono/stereo, 8–192 kHz; device support and conversion facts are reported separately.
- Allocator control. Exact Hail memory plans and custom allocators support fixed arenas; the core has no mandatory OS, DSP or runtime dependency.
Implementation, execution and hardware qualification are distinct support levels.
| Target | Implementation and current evidence | Remaining qualification |
|---|---|---|
| macOS / CoreAudio | Native static/shared; scoped M1 Max physical duplex; arm64 macOS 15/26 strict BlackHole matrix and sanitizers | Broader devices/transports and calibrated physical latency; hosted profile uses a 2,048-frame native period |
| Windows / WASAPI | Shared-mode backend; native ClangCL static/shared CI, fault/ownership tests and installed consumers | Real capture/playback and sustained duplex; Windows handoff |
| Linux / PipeWire and ALSA | Native static/shared; isolated PipeWire loopback, ALSA null, fault tests and sanitizers | Real devices, including intended Raspberry Pi configurations |
| Freestanding / virtual | Fixed-arena example, deterministic conformance and backend-free compile | No FreeRTOS, UEFI or bare-metal audio adapter yet |
| Android / iOS | Future platform work | Dedicated native adapters and device qualification |
The audit-fix baseline passed all 11 general CI jobs, plus the complete CoreAudio workflows on macOS 15 and 26. These are specific configurations, not a blanket latency or production-readiness claim. See verification, CI evidence, and the retained CoreAudio timing failures.
Hail supplies device I/O and timestamped PCM. Resampling, AEC, VAD, codecs,
networking, inference and conversation policy belong in external components.
The duplex speech-service roadmap describes the client adapter,
gateway and herding-sparks boundary; these services are not bundled with Hail.
An optional Hull binding can mediate capabilities without moving native audio
servicing onto a language-runtime thread.
| Topic | Reference |
|---|---|
| API, threading and ownership | Public API |
| Design and independent responsibilities | Architecture · axis audit |
| Writing a backend | Private contract · native limitations |
| Qualification | Verification · macOS · Windows |
| Loopback fixtures | CoreAudio · Linux · WASAPI design |
| Audit workflows | C audit skill · axis audit skill |
| Ecosystem and future work | Repository audit · roadmap |
The landing page follows Keel's self-contained site pattern: static HTML/CSS, local SVG assets, no runtime CDN or build-time package dependency.
make -C site check
make -C site build
make -C site serveMIT. Copyright (c) 2026 Artalis. See LICENSE.