Home /Modules/audio/1-2-3-4.md

1-2-3-4.md

audio/1-2-3-4.md · 191 line(s) · markdown

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:

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:

Branches:

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/

C++17

audio/cpp/

Java 21

audio/java/

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:

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:

The current process invocation does not transmit all of those fields to the native executable.

Therefore:

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:

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:

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.