OKLMdocumentation v1.0.3
On this page

ADR-0007: Video in containers other than Ogg

Records how OKLM reads video it cannot decode itself, and what it runs to do so.

Status: accepted (2026-11-01).

Context

OKLM decodes media through Allegro 5's addons (ADR-0001): images (PNG, JPEG, BMP, ...), audio (WAV, FLAC, Ogg Vorbis, Opus, MP3) and video. The video addon only reads Ogg Theora (.ogv). Most video people have is MP4, MKV or WebM (H.264, H.265, VP9, AV1), and writing decoders for those codecs is out of the question. A video question needs frames for the vision encoder and, optionally, the sound track for the audio encoder; it does not need the codecs themselves. ffmpeg decodes everything, but it is a large program with its own licences and its own attack surface, and OKLM does not depend on it.

Decision

  • Ogg Theora is decoded natively: frames at the requested rate, and the Vorbis sound track. It is done with libtheora, libvorbis and libogg, the libraries Allegro's video addon plays Ogg with (in its dependency pack on Windows), rather than through the addon: the addon plays in real time against a clock and sends the sound to an audio device, where OKLM wants frames as fast as they decode and the samples themselves, on machines without sound hardware.
  • Any other container goes through an ffmpeg subprocess, only when the user asks for it, by --ffmpeg on the command line or OKLM_FFMPEG=1 in the environment, and only when an ffmpeg binary is found on PATH (or named by OKLM_FFMPEG=/path/to/ffmpeg).
    • It runs with an argument vector, no shell, and reads the file the user named.
    • Frames come back as PPM images on a pipe, at the requested rate and size.
    • The sound comes back as 16 kHz mono 16-bit PCM on another run.
    • It is media conversion: no model data passes through ffmpeg.
  • Without that permission, or without ffmpeg, a non-Ogg video is refused with a message naming both ways out: --ffmpeg, or converting the file to .ogv beforehand.
  • ffmpeg is never needed to build OKLM, and no test depends on it (the tests use an .ogv fixture, and check the ffmpeg path only when ffmpeg is present).

Amendment (2026-11-01)

Implemented as above, with the Theora decoding moved from the video addon to its codec libraries (see Decision). Frames are taken every 1 / fps seconds; past the number wanted the interval doubles and every other frame is dropped, so memory stays bounded and the frames kept cover the whole video. The ffmpeg path reads ffmpeg -i file:PATH -vf fps=F -f image2pipe -c:v ppm - and -ac 1 -ar 16000 -f s16le -.

Consequences

Any video works for a user who has ffmpeg and says so, with no build dependency and nothing run behind their back. Without ffmpeg, OKLM reads Ogg Theora only. The ffmpeg path depends on the user's ffmpeg version for which formats it reads; OKLM only relies on its PPM and raw PCM outputs, stable for decades.