# 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`: `2429819abdcdcc85a8c00799d0d058560d8a2835` - `main`: `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/` - `Audio` interface. - `Input`, `Controls`, and `Configuration` records. - `NativeAudio` adapter. - 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 `Configuration` until 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: 1. mono input to stereo output; 2. stereo input to stereo output; 3. multiple synchronized offsets; 4. per-input gain; 5. master gain; 6. left/right gain; 7. pan; 8. clipping and saturation; 9. malformed WAV; 10. truncated WAV chunks; 11. sample-rate mismatch; 12. zero/invalid configuration; 13. one-input boundary; 14. 128-input boundary; 15. output-size overflow protection; 16. 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.