cl theora


A decoder library for the OGG/Theora video format via the theorafile C library

About cl-theora

This is a decoder library for the OGG/Theora video format via the theorafile C library. It offers easy and fast decoding for Theora video files, primarily intended for video playback in games.

How To

Load the library and create a new file:

(org.shirakumo.fraf.theora:open "video.ogv")

From there you can read out the properties like the width, height, framerate, pixel-format, channels, samplerate, audio-track, and video-track.

With read-video and read-audio you can read out video and audio data respectively. Note that synchronising playback both streams is left up to you. Video is decoded as 8-bit YUV, and audio is decoded as floats.

Note that reading video and audio is not thread safe, so you must put a lock around both if you intend on decoding from multiple threads.

Once you are done with the file, you must free it.

Creating Theora Files

To convert a video file to an ogg/theora file suitable for this library, we recommend using an ffmpeg command similar to this:

ffmpeg -i my-file -codec:v libtheora -qscale:v 7 -codec:a libvorbis -qscale:a 5 output.ogv

qscale:v and qscale:a are the respective video and audio quality optimisation options, ranging from 0 to 10.

Decoding YUV Data

For reference, here's a very basic YUV decoding fragment shader:

in vec2 tex_coord;
uniform sampler2D Y, U, V;
void main() {
  vec3 yuv = vec3(texture(Y, tex_coord).r - 0.0625,
                  texture(U, tex_coord).r - 0.5,
                  texture(V, tex_coord).r - 0.5);
  vec3 rgb = vec3(dot(yuv, vec3(+1.164, +0.000, +1.793)),
                  dot(yuv, vec3(+1.164, -0.213, -0.533)),
                  dot(yuv, vec3(+1.164, +2.112, +0.000)));
  gl_FragColor = vec4(rgb, 1.0);

System Information

Yukari Hafner

Definition Index