Audio API 1-2-3-4
Project: SLeeLa Audio API Document date: 2026-09-28 Scope: C, C++17, Java 21, native audio boundary, and JavaFX audio GUI.
This document records the implementation order, the work completed, and the remaining closure work identified during the final Audio API review.
1. Native Audio Foundation
Date: 2026-09-28
The native audio foundation establishes the PCM16 WAV processing boundary.
Completed:
- C audio ABI under
audio/c/. - C++17 typed API under
audio/cpp/. - PCM16 mono/stereo WAV input.
- Sample-rate validation.
- Per-input start offsets.
- Per-input gain.
- Master gain.
- Left/right gain.
- Pan.
- Stereo PCM16 WAV output.
- Input-count limit of 128.
- Configuration validation.
- Fail-closed handling for malformed or unsupported input.
- C++ truncated-WAV validation.
- C/C++ build targets and basic test/syntax targets.
Final C correction
On 2026-09-28, the final review found that the C implementation did not retain the loaded WAV byte count in its bytes[i] bookkeeping before its second parsing pass. That could cause the second pass to treat the buffer as empty.
The correction:
- records the actual input size;
- preserves the second-pass data-chunk scan;
- adds audio-length overflow protection;
- adds output-buffer size protection.
Branches:
master:2429819abdcdcc85a8c00799d0d058560d8a2835main:10661b8ac7904a0547e3c1f22d2cc9e7aadd0c6f
2. Language API and GUI Boundary
Date: 2026-09-28
The language-specific API layers are established in parallel with the native foundation.
C
audio/c/
- C11 public header.
- C ABI.
- Native validation and WAV mixing.
- Static-library build.
- Syntax/test target.
C++17
audio/cpp/
- Typed C++17 structures.
- Validation API.
- WAV mixing API.
- Static-library build.
- PCM16 and synchronization semantics corresponding to the C layer.
Java 21
audio/java/
Audiointerface.Input,Controls, andConfigurationrecords.NativeAudioadapter.- Java-side configuration validation.
- Executable validation.
- Process interruption and non-zero exit handling.
- Java 21 build documentation.
JavaFX GUI
audio/gui/
The GUI layer provides the user-facing audio/video session and mixer structures while keeping native media processing below the Java API boundary.
Earlier completed GUI work includes:
- Audio mixer application/model.
- Audio/video session API.
- GUI tests.
- JavaFX styling.
- Native-process integration boundary.
- Audio GUI workflow documentation and build support.
3. Native/Java Contract Review
Date: 2026-09-28
The final review identified one contract item that must remain explicit.
The current Java adapter invokes the native executable as:
executable OUTPUT SAMPLE_RATE INPUT...
The Java Configuration model also contains:
- input start time;
- input gain;
- bass;
- mid;
- treble;
- master gain;
- pan;
- left gain;
- right gain.
The current process invocation does not transmit all of those fields to the native executable.
Therefore:
- the native C/C++ APIs remain the authoritative parameterized mixer interfaces;
- the Java process adapter must not be described as transmitting the complete
Configurationuntil its process protocol is expanded; - future protocol work should define an unambiguous argument/configuration representation for offsets, gains, EQ, and channel controls.
This distinction is intentional. It prevents the Java API from claiming a capability that the current process wire/argument contract does not actually carry.
4. Conformance and Closure
Date: 2026-09-28
The final closure stage is defined as cross-language behavioral verification.
Required conformance cases:
- mono input to stereo output;
- stereo input to stereo output;
- multiple synchronized offsets;
- per-input gain;
- master gain;
- left/right gain;
- pan;
- clipping and saturation;
- malformed WAV;
- truncated WAV chunks;
- sample-rate mismatch;
- zero/invalid configuration;
- one-input boundary;
- 128-input boundary;
- output-size overflow protection;
- C/C++ equivalent PCM output for identical fixtures.
EQ status
The public C, C++, and Java models expose:
- bass;
- mid;
- treble.
The current native mixer does not yet implement those EQ controls.
Accordingly, EQ is recorded as an explicit closure item rather than silently treated as complete.
The implementation order for the final Audio API is therefore:
1. Native foundation → 2. Language and GUI boundary → 3. Contract definition → 4. Cross-language conformance and capability closure.
Historical implementation record
The repository history records the principal Audio API milestones:
- 2026-09-22: JavaFX Audio/Video GUI and initial Java API work.
- 2026-09-28 02:26–02:33 EDT: GUI cleanup, native audio ABI, native build/documentation, process adapter, GUI/native boundary documentation, and native/GUI testing work.
- 2026-09-28 13:47 EDT: C, C++17, and Java language-layer quality tightening.
- 2026-09-28: final C WAV bookkeeping and overflow correction recorded above.
Verification note
The GitHub commit-status endpoint currently reports no attached status checks for the two latest C correction commits. This document therefore records implementation state and identified work without claiming a CI result that has not been reported.
Status: Audio API foundation implemented; C defect corrected; Java/native contract and EQ semantics remain explicit closure items; cross-language conformance is the final verification stage.