# 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:

:: common lisp
(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:

:: glsl
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);
}
::