Getting Started

This is a simple guide to getting the code and encoding a simple video.

Installation

Pre-requisites

Standard build tools (autoconf, automake v1.11 or later, libtool, and a C compiler)
git
libogg (v1.3 or later)
libpng
libjpeg
libcheck (v0.9.8 or later, can be skipped if you pass --disable-unit-tests to ./configure)
libsdl (can by skipped if you pass --disable-player to ./configure)

Instructions for installing these packages are OS-specific (feel free to contribute some here, especially if you tried installing these somewhere and ran into difficulties; you will likely save other people some pain). If you have a package manager that has separate -dev versions with the public headers, make sure you install those in addition to the actual libraries.

Installation Procedure

Just run these commands:

   git clone https://git.xiph.org/daala.git
   cd daala
   ./autogen.sh
   ./configure
   make

Note that the git clone can take several minutes to complete.

And optionally

   make tools

Make sure you run the git clone operation on the same machine where you intend to use the code. Checking out a copy on Windows and then trying to use it on Linux will not work, as executable permissions and line-endings will not be set properly.

Encoding a Video

If you do not have one, get a sample video or two in .y4m format from media.xiph.org. We also maintain a set of still-image collections in .y4m format:

Subset 1 (50 images, small training set)
Subset 2 (1000 images, large training set)
Subset 3 (50 images, small testing set)
Subset 4 (1000 images, large testing set)

Encode the video:

   ./examples/encoder_example -v 30 -k 256 video.y4m -o video.ogv

where

video.y4m is the input video you want to encode,
video.ogv is the name of the encoded video file to output,
-v specifies the quality (currently from 0 to 511, where 0 is lossless), and
-k specifies the maximum keyframe interval (this is currently 1 by default, which makes every frame a keyframe).

Decoding a Video

Play the video:

   ./examples/player_example -p video.ogv

The -p option starts the player paused. Run

   ./examples/player_example --help

for information on the controls available while playing.

If you want to use a different player, you can decode the video back to .y4m with

   ./examples/dump_video video.ogv -o decoded_video.y4m

Many other players can play back these .y4m files, and other tools can convert them to various other formats.

Using PNG Images

To encode a series of images:

   make tools
   ./tools/png2y4m video%05d.png -o video.y4m

where %05d means your input images are named video00000.png, video00001.png, etc. You can leave out the %05d tag if you only want to convert a single image (which does not need to be numbered).

To convert a y4m back to PNGs:

   ./tools/y4m2png video.y4m -o video%05d.png

If you are converting a .y4m file that only contains a single frame (e.g., from one of the still-image subsets linked above), you can leave out the %05d tag. Conversion from PNG to Y4M uses the Rec 709 matrix with video levels, a box filter for chroma subsampling, and a triangular dither. Conversion back from Y4M to PNG uses the same matrix, levels, and box filter, but does not dither.

Daala Quickstart

Contents