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
ffmpegsubprocess, only when the user asks for it, by--ffmpegon the command line orOKLM_FFMPEG=1in the environment, and only when anffmpegbinary is found onPATH(or named byOKLM_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.ogvbeforehand. - ffmpeg is never needed to build OKLM, and no test depends on it (the
tests use an
.ogvfixture, 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.