Home/Modules/codecs

codecs

library module lib/codecs

<img align="right" src="https://github.com/mearvk/SLeeLa/blob/master/images/debian/debian-logo.png" width="75" height="75" alt="SLeeLa">

SLeeLa Audio Codecs

Status: SLeeLa-side management surface + per-codec contracts. This directory is the language-facing codec layer: a Loader, Verifier, Processor, and Controller that a GUI or application drives, plus one metadata/capability class per codec, mirroring the native manager in codecs/ (the C/C++ core at codecs/include/sleela_codec_manager.h). SLeeLa never calls an individual codec directly — it asks the Controller/Loader, and the manager calls the plugin.

The actual byte-level encode/decode lives in the native plugins (and, for backend codecs, in a host-registered backend adapter). These .sleela classes own lifecycle, classification, verification, and honest capability reporting — they never fake a successful decode.

The four management roles

The management surface mirrors the native manager's split. A GUI drives the Controller; the Controller cooperates with the other three.

RoleFileResponsibility
ControllerSLCodecController.sleelaThe single surface an app drives. Owns the per-codec loaded + backend tables; load/unload/unloadAll/isLoaded/loadedCount; decode/encode/canProcess; delegates resolution/text to the Verifier.
LoaderSLCodecLoader.sleelaThe plugin load/unload contract and classification (nameOf, isNative) over the 20-codec registry.
VerifierSLCodecVerifier.sleelaresolveExtension (filename → id), probeMagic (content signature → id, mirroring each plugin's probe()), headerless, and resultText for the result codes.
ProcessorSLCodecProcessor.sleelaPure decode/encode dispatch over the facts (loaded, native, backendReady); never a false success.

Supporting files:

FileRole
SLPackage.sleelaPackage facade (configure/name/available).
codecs.sleelaA compact runnable Loader demo (class Codecs with main).
codec-pipeline.sleelaThe runnable Controller/Verifier/Processor pipeline with main — the executable reference for the four roles.
SLCodec<Name>.sleelaOne metadata/capability class per codec (20 files, see below).

The flow

file / bytes
     │
     ▼
Verifier.resolveExtension(".flac")  or  Verifier.probeMagic("fLaC")   → codec id
     │
     ▼
Controller.load(id)                 → mark the codec usable (lifecycle)
     │
     ▼
Controller.canProcess(id)           → true iff loaded AND (native OR backend wired)
     │
     ▼
Controller.decode(id) / encode(id)  → Processor dispatches; honest result code
     │
     ▼
Controller.resultText(code)         → human-readable status for the GUI
     │
     ▼
Controller.unload(id) / unloadAll()

Using it from a GUI (syntax 1.11)

As of #sleela 1.11, method calls resolve on class-typed fields, so the Controller holds its Verifier/Processor as fields and a GUI drives one object:

Controller ctrl = new Controller();
ctrl.create();                             // registers all codecs, none loaded

int id = ctrl.resolveExtension(".flac");   // → 2 (FLAC)
ctrl.load(id);                             // make it usable
if (ctrl.canProcess(id)) {                 // false until a FLAC backend is wired
    int r = ctrl.decode(id);
    print(ctrl.resultText(r));             // "ok" or an honest error
}
ctrl.unloadAll();

Run the executable reference:

# from the repository root
./impl/build/sleela run lib/codecs/codec-pipeline.sleela

Result codes

Mirror sleela_codec_result from the native plugin interface:

CodeMeaning
0ok
-1unsupported (backend not present)
-2invalid arguments (e.g. bad id)
-3input is not this codec's format
-4I/O or allocation failure
-5codec not loaded

A native codec (PCM/WAV, AIFF, G.711 μ-law/A-law) decodes/encodes in-package and returns 0 once loaded. A backend codec returns -1 until an approved backend adapter is registered via registerBackend(id) — never a false 0.

Codec registry

Ids and handler states mirror codecs/include/sleela_codecs.h (0 native · 1 backend · 2 recognized · 3 container · 4 event).

idClassCodecState
0SLCodecPcmWavPCM/WAVnative
1SLCodecAiffAIFFnative
2SLCodecFlacFLACbackend
3SLCodecAlacALACbackend
4SLCodecMp3MPEG Layer IIIbackend
5SLCodecAacAACbackend
6SLCodecHeAacHE-AACbackend
7SLCodecVorbisOgg Vorbisbackend
8SLCodecOpusOpusbackend
9SLCodecSpeexSpeexbackend
10SLCodecWmaWindows Media Audiobackend
11SLCodecAc3Dolby Digital AC-3backend
12SLCodecEac3Dolby Digital Plusbackend
13SLCodecAmrNbAMR-NBbackend
14SLCodecAmrWbAMR-WBbackend
15SLCodecG711MulawG.711 μ-lawnative
16SLCodecG711AlawG.711 A-lawnative
17SLCodecMidiMIDIevent
18SLCodecMatroskaAudioMatroska Audiocontainer
19SLCodecWebmAudioWebM Audiocontainer

Per-codec classes

Each SLCodec<Name>.sleela carries the registry identity + capability contract (id, name, mime, extensions, state/stateName, canDecode/canEncode, isNative/needsBackend) and an 11-attribute descriptive record with getter/setter pairs so a GUI, loader, or catalog can read and override each codec's metadata:

version, id, author, date, copyright, trademark, corporation, origin, birth date, science rating (1..10 maturity), national schedule (the standards-body designation).

SLCodecMp3 c = new SLCodecMp3();
print(c.getCorporation());        // Fraunhofer-Gesellschaft
print(c.getOrigin());             // Germany
print(c.getNationalSchedule());   // ISO/IEC 11172-3 (MPEG-1 Layer III)
c.setScienceRating(9);            // override where appropriate

Metadata values are faithful to each codec's real origin where publicly known.

Relationship to the native tree and to video

Implementation boundary

These classes manage, classify, verify, and report. Real transcoding requires the native plugin (native codecs) or a registered backend adapter (backend codecs). A backend codec with no adapter reports -1 (unsupported) rather than a false success — the deliberate "never fake a decode" contract carried from the native design.

Files 28