codecs
system module codecs
<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 Codec Handlers
Package: codecs/
Date: 2026-09-28
This package defines the SLeeLa audio-codec handler registry. It provides one place to identify major audio coding standards, describe their containers/signatures, and expose whether a handler is natively implemented, requires an external codec backend, or is only recognized.
The codec registry is deliberately separate from audio/: the Audio API performs PCM/WAV mixing, while codecs/ defines compressed-audio and container integration.
Handler Classes
- Native — SLeeLa contains the codec implementation.
- Backend — the handler contract exists, but an approved codec library/backend is required for actual encode/decode.
- Recognized — the format can be identified and described, but encode/decode is not claimed.
- Container — identifies a container/transport rather than a compression algorithm.
No handler is advertised as fully implemented merely because its name appears in the registry.
Major Standards Covered
| Handler | Standard / Format | Typical role | State |
|---|---|---|---|
| PCM/WAV | PCM in RIFF/WAVE | Uncompressed audio | Native audio path |
| AIFF | AIFF/AIFF-C | Uncompressed/container audio | Recognized |
| FLAC | Free Lossless Audio Codec | Lossless | Backend |
| ALAC | Apple Lossless Audio Codec | Lossless | Backend |
| MP3 | MPEG-1/2 Layer III | Lossy | Backend |
| AAC | MPEG-2/4 AAC | Lossy | Backend |
| HE-AAC | MPEG-4 HE-AAC | Lossy / low bitrate | Backend |
| Vorbis | Xiph.Org Vorbis | Lossy | Backend |
| Opus | IETF Opus / RFC 6716 | Speech/music | Backend |
| Speex | Xiph.Org Speex | Speech | Backend |
| WMA | Windows Media Audio | Lossy/lossless family | Backend |
| AC-3 | Dolby Digital | Multichannel | Backend |
| E-AC-3 | Dolby Digital Plus | Multichannel | Backend |
| AMR-NB | Adaptive Multi-Rate Narrowband | Speech | Backend |
| AMR-WB | Adaptive Multi-Rate Wideband | Speech | Backend |
| μ-law | G.711 μ-law | Telephony PCM companding | Backend/interop |
| A-law | G.711 A-law | Telephony PCM companding | Backend/interop |
| MIDI | MIDI Standard | Note/event data, not sampled audio | Event format |
| WebM/Matroska audio | Matroska/WebM containers | Container | Container |
Architecture: individual codecs + a Loader/Manager
Each codec is now a self-contained plugin in its own folder under
codecs/codecs/<name>/, implementing a small common vtable
(codecs/include/sleela_codec_plugin.h): describe, load, unload, probe,
decode, encode. Every codec ships C and C++ (the vtable/glue in .c, the
byte-level/format detail in .cpp) plus its own .md.
SLeeLa never links or calls an individual codec directly. It calls the Codec
Loader / Unloader / Management Controller (codecs/include/sleela_codec_manager.h),
which owns every plugin's lifecycle:
SLeeLa -> Codec Manager (loader/unloader/controller) -> individual codec plugin
load / unload / resolve / decode / encode
sleela_codec_manager_create()registers every known codec (none loaded).sleela_codec_manager_load(mgr, id)/..._unload(mgr, id)manage lifecycle...._resolve_extension/..._resolve_probepick a codec from a filename or content bytes...._decode/..._encodedispatch to the loaded plugin.- A backend-less codec reports its state and returns a clean
SLEELA_CODEC_ERR_UNSUPPORTEDinstead of faking success.
The SLeeLa-facing handle to the Loader is lib/codecs/SLCodecLoader.sleela
(runnable demo: lib/codecs/codecs.sleela).
Native codecs (fully implemented in-package, no external library)
- PCM/WAV (
codecs/codecs/pcm_wav/) — RIFF/WAVE 16-bit PCM read/write; the PCM boundary every other codec targets. - AIFF (
codecs/codecs/aiff/) —FORM/AIFFbig-endian 16-bit PCM read/write, including the 80-bit extended sample-rate field. - G.711 μ-law / A-law (
codecs/codecs/g711_mulaw/,.../g711_alaw/) — telephony companding, one byte ↔ one 16-bit PCM sample.
Backend codecs (contract + probe, pluggable implementation)
FLAC, ALAC, MP3, AAC, HE-AAC, Vorbis, Opus, Speex, WMA, AC-3, E-AC-3, AMR-NB, AMR-WB are Backend handlers: they identify the format (a C++ signature probe) and delegate encode/decode to a runtime-registered backend adapter.
/* A host wires an approved library (libFLAC, libopus, ...) at startup: */
static const sleela_codec_backend flac_adapter = { "libFLAC", flac_dec, flac_enc };
sleela_codec_backend_register(SLEELA_CODEC_FLAC, &flac_adapter);
With a backend registered, the plugin's decode/encode dispatch to it; with none
registered, they return SLEELA_CODEC_ERR_UNSUPPORTED — never a false success.
(No third-party libraries are bundled in-tree.) MIDI is an Event format and
Matroska/WebM are Container handlers (probe + identification).
C Handler Registry (metadata)
The static registry is in:
codecs/include/sleela_codecs.hcodecs/src/sleela_codecs.c
It provides:
- stable codec identifiers;
- human-readable names;
- MIME/type and extension metadata;
- handler state;
- encode/decode capability flags;
- lookup by identifier;
- lookup by common file extension;
- enumeration of the complete registry.
The registry is metadata and dispatch infrastructure. It does not silently substitute a system utility or third-party library for a codec implementation.
Integration Rule
The Audio API in audio/ should consume decoded PCM through an explicit boundary. Codec handlers should not bypass Audio validation or directly mutate mixer state.
The intended path is:
compressed/container input → codec handler → PCM boundary → Audio API → output
For encoding:
Audio PCM → codec handler → compressed/container output
Completion Policy
A handler becomes Native only when the codec implementation, validation, tests, and build integration are present.
A Backend handler may be wired to a supported codec library later. Until then, callers can inspect its state and fail cleanly instead of receiving a false success.
See CODECS.md for the detailed registry and implementation order.
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 95
- backends/flac_native/flac_native.c
- backends/flac_native/flac_native.h
- backends/flac_native/README.md
- CODECS.md
- codecs/aac/aac.c
- codecs/aac/AAC.md
- codecs/aac/aac_detail.cpp
- codecs/aac/aac_detail.h
- codecs/ac3/ac3.c
- codecs/ac3/AC3.md
- codecs/ac3/ac3_detail.cpp
- codecs/ac3/ac3_detail.h
- codecs/aiff/aiff.c
- codecs/aiff/AIFF.md
- codecs/aiff/aiff_detail.cpp
- codecs/aiff/aiff_detail.h
- codecs/alac/alac.c
- codecs/alac/ALAC.md
- codecs/alac/alac_detail.cpp
- codecs/alac/alac_detail.h
- codecs/amr_nb/amr_nb.c
- codecs/amr_nb/AMR_NB.md
- codecs/amr_nb/amr_nb_detail.cpp
- codecs/amr_nb/amr_nb_detail.h
- codecs/amr_wb/amr_wb.c
- codecs/amr_wb/AMR_WB.md
- codecs/amr_wb/amr_wb_detail.cpp
- codecs/amr_wb/amr_wb_detail.h
- codecs/eac3/eac3.c
- codecs/eac3/EAC3.md
- codecs/eac3/eac3_detail.cpp
- codecs/eac3/eac3_detail.h
- codecs/flac/flac.c
- codecs/flac/FLAC.md
- codecs/flac/flac_detail.cpp
- codecs/flac/flac_detail.h
- codecs/g711_alaw/g711_alaw.c
- codecs/g711_alaw/G711_ALAW.md
- codecs/g711_alaw/g711_alaw_detail.cpp
- codecs/g711_alaw/g711_alaw_detail.h
- codecs/g711_mulaw/g711_detail.cpp
- codecs/g711_mulaw/g711_detail.h
- codecs/g711_mulaw/g711_mulaw.c
- codecs/g711_mulaw/G711_MULAW.md
- codecs/he_aac/he_aac.c
- codecs/he_aac/HE_AAC.md
- codecs/he_aac/he_aac_detail.cpp
- codecs/he_aac/he_aac_detail.h
- codecs/matroska_audio/matroska_audio.c
- codecs/matroska_audio/MATROSKA_AUDIO.md
- codecs/matroska_audio/matroska_audio_detail.cpp
- codecs/matroska_audio/matroska_audio_detail.h
- codecs/midi/midi.c
- codecs/midi/MIDI.md
- codecs/midi/midi_detail.cpp
- codecs/midi/midi_detail.h
- codecs/mp3/mp3.c
- codecs/mp3/MP3.md
- codecs/mp3/mp3_detail.cpp
- codecs/mp3/mp3_detail.h
- codecs/opus/opus.c
- codecs/opus/OPUS.md
- codecs/opus/opus_detail.cpp
- codecs/opus/opus_detail.h
- codecs/pcm_wav/pcm_wav.c
- codecs/pcm_wav/pcm_wav.cpp
- codecs/pcm_wav/PCM_WAV.md
- codecs/pcm_wav/pcm_wav_detail.h
- codecs/speex/speex.c
- codecs/speex/SPEEX.md
- codecs/speex/speex_detail.cpp
- codecs/speex/speex_detail.h
- codecs/vorbis/vorbis.c
- codecs/vorbis/VORBIS.md
- codecs/vorbis/vorbis_detail.cpp
- codecs/vorbis/vorbis_detail.h
- codecs/webm_audio/webm_audio.c
- codecs/webm_audio/WEBM_AUDIO.md
- codecs/webm_audio/webm_audio_detail.cpp
- codecs/webm_audio/webm_audio_detail.h
- codecs/wma/wma.c
- codecs/wma/WMA.md
- codecs/wma/wma_detail.cpp
- codecs/wma/wma_detail.h
- include/sleela_codec_manager.h
- include/sleela_codec_plugin.h
- include/sleela_codecs.h
- Makefile
- README.md
- src/sleela_codec_backend.c
- src/sleela_codec_manager.c
- src/sleela_codecs.c
- tests/test_flac_native.c
- tests/test_manager.c
- tests/test_registry.c