Home/Modules/codecs

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

No handler is advertised as fully implemented merely because its name appears in the registry.

Major Standards Covered

HandlerStandard / FormatTypical roleState
PCM/WAVPCM in RIFF/WAVEUncompressed audioNative audio path
AIFFAIFF/AIFF-CUncompressed/container audioRecognized
FLACFree Lossless Audio CodecLosslessBackend
ALACApple Lossless Audio CodecLosslessBackend
MP3MPEG-1/2 Layer IIILossyBackend
AACMPEG-2/4 AACLossyBackend
HE-AACMPEG-4 HE-AACLossy / low bitrateBackend
VorbisXiph.Org VorbisLossyBackend
OpusIETF Opus / RFC 6716Speech/musicBackend
SpeexXiph.Org SpeexSpeechBackend
WMAWindows Media AudioLossy/lossless familyBackend
AC-3Dolby DigitalMultichannelBackend
E-AC-3Dolby Digital PlusMultichannelBackend
AMR-NBAdaptive Multi-Rate NarrowbandSpeechBackend
AMR-WBAdaptive Multi-Rate WidebandSpeechBackend
μ-lawG.711 μ-lawTelephony PCM compandingBackend/interop
A-lawG.711 A-lawTelephony PCM compandingBackend/interop
MIDIMIDI StandardNote/event data, not sampled audioEvent format
WebM/Matroska audioMatroska/WebM containersContainerContainer

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

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)

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:

It provides:

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