SLeeLa SLeeLa # SLeeLa Audio API **Package:** `audio/` **Updated:** 2026-09-28 **Status:** Native PCM16 WAV foundation implemented; SLVM-to-C/C++ Audio bridge added; Java/native CLI contract aligned; CI build coverage added; final cross-path behavioral/EQ conformance remains. The SLeeLa Audio API is a layered audio-processing package spanning C11, C++17, Java 21, native processing, and JavaFX presentation. ## Package Layout | Path | Responsibility | |---|---| | `audio/c/` | C11 ABI, validation, and PCM16 WAV mixing | | `audio/cpp/` | C++17 typed API and PCM16 WAV mixing | | `audio/java/` | Java 21 orchestration and native-process boundary | | `audio/native/` | Native command-line media-processing adapter | | `audio/gui/` | JavaFX audio/video presentation and integration | | `audio/sleela/` | SLeeLa language-layer Audio classes | | `audio/1-2-3-4.md` | Ordered implementation record, dates, completion state, and closure work | | `.github/workflows/audio-ci.yml` | Audio compile/build integration CI | ## Implemented Audio Capabilities The current native C/C++ mixer provides: - PCM16 WAV input; - mono and stereo input; - synchronized input offsets; - per-input gain; - master gain; - left/right gain; - pan; - stereo PCM16 WAV output; - sample-rate validation; - configuration validation; - malformed/truncated input rejection; - bounded input count of 128; - audio-length overflow protection; - output-size and RIFF-size protection. The C and C++ APIs provide corresponding audio-processing semantics. The C++ source also received a final source-integrity cleanup removing embedded newline artifacts from the implementation. ## Native Command-Line Adapter The native adapter now documents and parses the parameterized process contract: ``` sleela-audio-native --output OUTPUT --sample-rate RATE \ --input PATH START_SECONDS GAIN_DB ... \ --bass DB --mid DB --treble DB \ --master-gain DB --pan VALUE \ --left-gain VALUE --right-gain VALUE ``` The adapter: - accepts repeated `--input` entries; - carries per-input start offsets and gain; - carries master, pan, and channel gain controls; - carries bass, mid, and treble values at the process boundary; - rejects unknown or incomplete options; - invokes the same native C++ mixer implementation used by the C++ API. EQ values are carried by the process contract, but the native mixer does **not yet implement EQ filtering semantics**. They therefore remain an explicit implementation/conformance item. ## Java API The Java 21 layer provides: - `Audio` interface; - `Input`, `Controls`, and `Configuration` records; - `NativeAudio` process adapter; - executable validation; - configuration validation; - process exit handling; - interruption handling. The Java/native command contract is now aligned with the native adapter. `NativeAudio` emits: ``` --output OUTPUT --sample-rate SAMPLE_RATE --input PATH START_SECONDS GAIN_DB --bass BASS_DB --mid MID_DB --treble TREBLE_DB --master-gain MASTER_GAIN_DB --pan PAN --left-gain LEFT_GAIN --right-gain RIGHT_GAIN ``` This closes the earlier documentation gap in which the Java configuration represented more controls than the process invocation transmitted. The Java layer remains orchestration; native C/C++ remains responsible for the actual PCM processing. ## GUI The JavaFX layer provides the presentation and session boundary for the Audio/Video work. It is intentionally separated from the native processing implementation so that command-line, service, and GUI consumers can use the appropriate layer. ## EQ Status The public C, C++, and Java models and the native CLI contract expose: - bass; - mid; - treble. The native PCM16 mixer currently carries these values through the API/CLI boundary but does not apply EQ filtering. EQ is therefore **transported but not implemented as an audio effect**. ## Verification and Conformance The ordered completion record is maintained in `audio/1-2-3-4.md`. The required behavioral matrix includes: 1. mono → stereo; 2. stereo → stereo; 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. The remaining closure work is to execute and record the complete cross-language behavioral matrix and either implement or explicitly finalize the EQ semantics. ## Audio CI Audio-specific CI is now defined in `.github/workflows/audio-ci.yml`. The workflow is triggered by changes under `audio/**` or to the workflow itself and covers: - C audio: `make clean all test`; - C++ audio: `make clean all test`; - native audio adapter: `make clean all test`; - Java 21 Audio API compilation; - JavaFX audio GUI Maven packaging. The workflow provides compile/build integration coverage for the complete Audio package. A green CI result should be treated separately from the behavioral conformance matrix until those runtime cases are recorded. ## Build ### C11 ```bash cd audio/c make clean all test ``` ### C++17 ```bash cd audio/cpp make clean all test ``` ### Native adapter ```bash cd audio/native make clean all test ``` ### Java 21 ```bash cd audio/java javac -d build/classes src/module-info.java src/com/mearvk/audio/sleela/*.java ``` ### JavaFX GUI ```bash cd audio/gui mvn -B -DskipTests package ``` ## Engineering Record The Audio API work was developed in stages: - **2026-09-22:** initial JavaFX Audio/Video GUI and Java API work. - **2026-09-28:** GUI cleanup and native audio architecture. - **2026-09-28:** C ABI, native build/documentation, process adapter, and GUI/native boundary. - **2026-09-28:** C/C++/Java language-layer quality tightening. - **2026-09-28:** final C WAV buffer-bookkeeping correction and overflow protections. - **2026-09-28:** Java/native CLI contract aligned with the complete modeled control set. - **2026-09-28:** Audio API compile/integration CI added. - **2026-09-28:** C++ source newline artifacts corrected. - **2026-09-28:** `audio/1-2-3-4.md` maintained as the ordered completion record. ## Current Status **Implemented:** core native PCM16 WAV foundation, C/C++ APIs, parameterized native CLI boundary, aligned Java process adapter, JavaFX integration, validation, overflow protection, and Audio-specific CI build coverage. **Remaining closure:** run and record the full cross-language behavioral conformance matrix and implement or explicitly finalize native EQ semantics. The package is therefore **implemented at its core with its current process contract documented and aligned**, while the remaining behavioral and EQ closure items are kept explicit rather than being described as complete prematurely. ## SLeeLa language layer The Audio API now has a dedicated `audio/sleela/` contract layer with **9 standard .sleela classes**. All nine declare SLeeLa syntax 1.3 and contain executable method bodies compatible with the current compiler. The SLVM bridge is handle-based: `audioNew -> audioAdd -> audioControls -> audioValidate -> audioRender -> audioClose` The VM owns the bounded job state. `audioRender` crosses a stable C ABI callback into `impl/core/sleela_audio_bridge.cpp`, which invokes the existing C++ WAV renderer. Source-level SLeeLa never receives native pointers or OS handles. The existing `audio/c/` C ABI remains available, `impl/core/sleela_audio_mixer.c` remains the in-VM float mixer, and `audio/cpp/` remains the concrete WAV implementation. See `audio/sleela/README.md` and `audio/sleela/SLVM.md` for the complete boundary. --- # SLeeLa

SLeeLa — The Now. The Ingredient.

SLeeLa Marketing Logo