audio
system module audio
<img align="right" src="https://github.com/mearvk/SLeeLa/blob/master/images/debian/debian-logo.png" width="75" height="75" alt="SLeeLa">
<img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela/sleela-logo-004.jpg" alt="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
--inputentries; - 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:
Audiointerface;Input,Controls, andConfigurationrecords;NativeAudioprocess 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:
- mono โ stereo;
- stereo โ stereo;
- 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.
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
cd audio/c
make clean all test
C++17
cd audio/cpp
make clean all test
Native adapter
cd audio/native
make clean all test
Java 21
cd audio/java
javac -d build/classes src/module-info.java src/com/mearvk/audio/sleela/*.java
JavaFX GUI
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.mdmaintained 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
<p align="center"><img src="images/sleela/sleela-wordmark.svg" alt="SLeeLa โ The Now. The Ingredient." width="560"></p> <p align="center"><img src="https://github.com/mearvk/SLeeLa/blob/master/images/sleela-programming-language-002.jpg" alt="SLeeLa Marketing Logo" width="560"></p>
Files 35
- 1-2-3-4.md
- c/Audio.c
- c/Audio.h
- c/include/sleela_audio.h
- c/Makefile
- c/README.md
- c/src/sleela_audio.c
- cpp/Audio.cpp
- cpp/Audio.hpp
- cpp/include/sleela_audio.hpp
- cpp/Makefile
- cpp/README.md
- cpp/src/sleela_audio.cpp
- gui/pom.xml
- gui/README.md
- gui/src/main/java/module-info.java
- java/README.build.md
- java/README.md
- java/src/module-info.java
- native/include/README.md
- native/Makefile
- native/README.md
- native/src/sleela_audio_native.cpp
- README.md
- sleela/Audio.sleela
- sleela/AudioConfiguration.sleela
- sleela/AudioControls.sleela
- sleela/AudioDevice.sleela
- sleela/AudioInput.sleela
- sleela/AudioMixer.sleela
- sleela/AudioNative.sleela
- sleela/AudioStream.sleela
- sleela/AudioSystem.sleela
- sleela/README.md
- sleela/SLVM.md