Commit c1aa69b9 authored by Tom Finegan's avatar Tom Finegan

Add contributor guide info to

- Move encoder testing instructions to
- Migrate and rename support scripts.
- Migrate Get the code section.
- Migrate patch submission and Git/Gerrit login instructions.

Change-Id: I82d8f508839c6a15b35465f07ef72305af198a73
parent a92bd80b
......@@ -3,6 +3,7 @@
## Contents
1. [Building the lib and applications](#building-the-library-and-applications)
- [Prerequisites](#prerequisites)
- [Get the code](#get-the-code)
- [Basics](#basic-build)
- [Configuration options](#configuration-options)
- [Dylib builds](#dylib-builds)
......@@ -16,14 +17,25 @@
- [Basics](#testing-basics)
- [Unit tests](#1_unit-tests)
- [Example tests](#2_example-tests)
- [Encoder tests](#3_encoder-tests)
- [IDE hosted tests](#ide-hosted-tests)
- [Downloading test data](#downloading-the-test-data)
- [Additional test data](#additional-test-data)
- [Sharded testing](#sharded-testing)
- [Running tests directly](#1_running-test_libaom-directly)
- [Running tests via CMake](#2_running-the-tests-via-the-cmake-build)
3. [Coding style](#coding-style)
4. [Support](#support)
5. [Bug reports](#bug-reports)
4. [Submitting patches](#submitting-patches)
- [Login cookie](#login-cookie)
- [Contributor agreement](#contributor-agreement)
- [Testing your code](#testing-your-code)
- [Commit message hook](#commit-message-hook)
- [Upload your change](#upload-your-change)
- [Incorporating Reviewer Comments](#incorporating-reviewer-comments)
- [Submitting your change](#submitting-your-change)
- [Viewing change status](#viewing-the-status-of-uploaded-changes)
5. [Support](#support)
6. [Bug reports](#bug-reports)
## Building the library and applications
......@@ -39,6 +51,17 @@
7. Emscripten builds require the portable
### Get the code
The AV1 library source code is stored in the Alliance for Open Media Git
$ git clone
# By default, the above command stores the source in the aom directory:
$ cd aom
### Basic build
CMake replaces the configure step typical of many projects. Running CMake will
......@@ -46,8 +69,10 @@ produce configuration and build files for the currently selected CMake
generator. For most systems the default generator is Unix Makefiles. The basic
form of a makefile build is the following:
$ cmake path/to/aom
$ make
The above will generate a makefile build that produces the AV1 library and
applications for the current host system after the make step completes
......@@ -247,7 +272,9 @@ appropriately using the emsdk\_env script.
### Testing basics
Currently there are two types of tests in the AV1 codec repository.
There are several methods of testing the AV1 codec. All of these methods require
the presence of the AV1 source code and a working build of the AV1 library and
#### 1. Unit tests:
......@@ -278,6 +305,57 @@ The example tests require a bash shell and can be run in the following manner:
$ path/to/aom/test/ --bin-path examples
#### 3. Encoder tests:
When making a change to the encoder run encoder tests to confirm that your
change has a positive or negligible impact on encode quality. When running these
tests the build configuration should be changed to enable internal encoder
$ cmake path/to/aom -DCONFIG_INTERNAL_STATS=1
$ make
The repository contains scripts intended to make running these tests as simple
as possible. The following example demonstrates creating a set of baseline clips
for comparison to results produced after making your change to libaom:
# This will encode all Y4M files in the current directory using the
# settings specified to create the encoder baseline statistical data:
$ cd path/to/test/inputs
# This command line assumes that, its helper script
#, and the aomenc you intend to test are all within a
# directory in your PATH.
$ 200 500 50 baseline
After making your change and creating the baseline clips, you'll need to run
encodes that include your change(s) to confirm that things are working as
# This will encode all Y4M files in the current directory using the
# settings specified to create the statistical data for your change:
$ cd path/to/test/inputs
# This command line assumes that, its helper script
#, and the aomenc you intend to test are all within a
# directory in your PATH.
$ 200 500 50 mytweak
After creating both data sets you can use `test/` to generate a
report that can be viewed in a web browser:
$ metrics_template.html "*stt" baseline mytweak \
> mytweak.html
You can view the report by opening mytweak.html in a web browser.
### IDE hosted tests
By default the generated projects files created by CMake will not include the
......@@ -308,6 +386,13 @@ rule:
The above make command will only download and verify the test data.
### Additional test data
The test data mentioned above is strictly intended for unit testing.
Additional input data for testing the encoder can be obtained from:
### Sharded testing
The AV1 codec library unit tests are built upon gtest which supports sharding of
......@@ -347,8 +432,20 @@ is the default maximum value.
## Coding style
We are using the Google C Coding Style defined by the
[Google C++ Style Guide](
The coding style used by this project is enforced with clang-format using the
configuration contained in the .clang-format file in the root of the repository.
configuration contained in the
file in the root of the repository.
You can download clang-format using your system's package manager, or directly
from []( You can also view the
[documentation]( on
Output from clang-format varies by clang-format version, for best results your
version should match the one used on Jenkins. You can find the clang-format
version by reading the comment in the `.clang-format` file linked above.
Before pushing changes for review you can format your code with:
......@@ -361,7 +458,116 @@ Before pushing changes for review you can format your code with:
Check the .clang-format file for the version used to generate it if there is any
difference between your local formatting and the review system.
See also:
Some Git installations have clang-format integration. Here are some examples:
# Apply clang-format to all staged changes:
$ git clang-format
# Clang format all staged and unstaged changes:
$ git clang-format -f
# Clang format all staged and unstaged changes interactively:
$ git clang-format -f -p
## Submitting patches
We manage the submission of patches using the
[Gerrit]( code review tool. This tool
implements a workflow on top of the Git version control system to ensure that
all changes get peer reviewed and tested prior to their distribution.
### Login cookie
Browse to [AOMedia Git index]( and login with
your account (Gmail credentials, for example). Next, follow the
`Generate Password` Password link at the top of the page. You’ll be given
instructions for creating a cookie to use with our Git repos.
### Contributor agreement
You will be required to execute a
[contributor agreement]( to ensure that the AOMedia
Project has the right to distribute your changes.
### Testing your code
The testing basics are covered in the [testing section](#testing-the-av1-codec)
In addition to the local tests, many more (e.g. asan, tsan, valgrind) will run
through Jenkins instances upon upload to gerrit.
### Commit message hook
Gerrit requires that each submission include a unique Change-Id. You can assign
one manually using git commit --amend, but it’s easier to automate it with the
commit-msg hook provided by Gerrit.
Copy commit-msg to the `.git/hooks` directory of your local repo. Here's an
$ curl -Lo aom/.git/hooks/commit-msg
# Next, ensure that the downloaded commit-msg script is executable:
$ chmod u+x aom/.git/hooks/commit-msg
See the Gerrit
for more information.
### Upload your change
The command line to upload your patch looks like this:
$ git push HEAD:refs/for/master
### Incorporating reviewer comments
If you previously uploaded a change to Gerrit and the Approver has asked for
changes, follow these steps:
1. Edit the files to make the changes the reviewer has requested.
2. Recommit your edits using the --amend flag, for example:
$ git commit -a --amend
3. Use the same git push command as above to upload to Gerrit again for another
review cycle.
In general, you should not rebase your changes when doing updates in response to
review. Doing so can make it harder to follow the evolution of your change in
the diff view.
### Submitting your change
Once your change has been Approved and Verified, you can “submit” it through the
Gerrit UI. This will usually automatically rebase your change onto the branch
Sometimes this can’t be done automatically. If you run into this problem, you
must rebase your changes manually:
$ git fetch
$ git rebase origin/branchname
If there are any conflicts, resolve them as you normally would with Git. When
you’re done, reupload your change.
### Viewing the status of uploaded changes
To check the status of a change that you uploaded, open
[Gerrit](, sign in, and click My >
## Support
# Copyright (c) 2016, Alliance for Open Media. All rights reserved
# This source code is subject to the terms of the BSD 2 Clause License and
# the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
# was not distributed with this source code in the LICENSE file, you can
# obtain it at If the Alliance for Open
# Media Patent License 1.0 was not distributed with this source code in the
# PATENTS file, you can obtain it at
# Author: (Jim Bankoski)
if [[ $# -ne 2 ]]; then
echo "Encodes a file using best known settings (slow!)"
echo " Usage: be [FILE] [BITRATE]"
echo " Example: be akiyo_cif.y4m 200"
f=$1 # file is first parameter
b=$2 # bitrate is second parameter
if [[ -e $f.fpf ]]; then
# First-pass file found, do second pass only
aomenc \
$f \
-o $f-$b.av1.webm \
-p 2 \
--pass=2 \
--fpf=$f.fpf \
--best \
--cpu-used=0 \
--target-bitrate=$b \
--auto-alt-ref=1 \
-v \
--minsection-pct=0 \
--maxsection-pct=800 \
--lag-in-frames=25 \
--kf-min-dist=0 \
--kf-max-dist=99999 \
--static-thresh=0 \
--min-q=0 \
--max-q=63 \
--drop-frame=0 \
--bias-pct=50 \
--minsection-pct=0 \
--maxsection-pct=800 \
--psnr \
--arnr-maxframes=7 \
--arnr-strength=3 \
# No first-pass file found, do 2-pass encode
aomenc \
$f \
-o $f-$b.av1.webm \
-p 2 \
--pass=1 \
--fpf=$f.fpf \
--best \
--cpu-used=0 \
--target-bitrate=$b \
--auto-alt-ref=1 \
-v \
--minsection-pct=0 \
--maxsection-pct=800 \
--lag-in-frames=25 \
--kf-min-dist=0 \
--kf-max-dist=99999 \
--static-thresh=0 \
--min-q=0 \
--max-q=63 \
aomenc \
$f \
-o $f-$b.av1.webm \
-p 2 \
--pass=2 \
--fpf=$f.fpf \
--best \
--cpu-used=0 \
--target-bitrate=$b \
--auto-alt-ref=1 \
-v \
--minsection-pct=0 \
--maxsection-pct=800 \
--lag-in-frames=25 \
--kf-min-dist=0 \
--kf-max-dist=99999 \
--static-thresh=0 \
--min-q=0 \
--max-q=63 \
--drop-frame=0 \
--bias-pct=50 \
--minsection-pct=0 \
--maxsection-pct=800 \
--psnr \
--arnr-maxframes=7 \
--arnr-strength=3 \
This diff is collapsed.
<!DOCTYPE html>
<html lang="en">
<meta charset="utf-8">
<title>Video Codec Test Results</title>
<style type="text/css">
<!-- Begin 960 reset -->
<!-- End 960 reset -->
<!-- Begin 960 text -->
body{font:13px/1.5 'Helvetica Neue',Arial,'Liberation Sans',FreeSans,sans-serif}pre,code{font-family
:'DejaVu Sans Mono',Menlo,Consolas,monospace}hr{border:0 #ccc solid;border-top-width:1px;clear:both;
<!-- End 960 text -->
<!-- Begin 960 grid (fluid variant)
12 columns, 1152px total width | -->
rgin-left:1%;margin-right:1%}.alpha{margin-left:0}.omega{margin-right:0}.container_12 .grid_1{width:
6.333%}.container_12 .grid_2{width:14.667%}.container_12 .grid_3{width:23.0%}.container_12 .grid_4{w
idth:31.333%}.container_12 .grid_5{width:39.667%}.container_12 .grid_6{width:48.0%}.container_12 .gr
id_7{width:56.333%}.container_12 .grid_8{width:64.667%}.container_12 .grid_9{width:73.0%}.container_
12 .grid_10{width:81.333%}.container_12 .grid_11{width:89.667%}.container_12 .grid_12{width:98.0%}.c
ontainer_12 .prefix_1{padding-left:8.333%}.container_12 .prefix_2{padding-left:16.667%}.container_12
.prefix_3{padding-left:25.0%}.container_12 .prefix_4{padding-left:33.333%}.container_12 .prefix_5{p
adding-left:41.667%}.container_12 .prefix_6{padding-left:50.0%}.container_12 .prefix_7{padding-left:
58.333%}.container_12 .prefix_8{padding-left:66.667%}.container_12 .prefix_9{padding-left:75.0%}.con
tainer_12 .prefix_10{padding-left:83.333%}.container_12 .prefix_11{padding-left:91.667%}.container_1
2 .suffix_1{padding-right:8.333%}.container_12 .suffix_2{padding-right:16.667%}.container_12 .suffix
_3{padding-right:25.0%}.container_12 .suffix_4{padding-right:33.333%}.container_12 .suffix_5{padding
-right:41.667%}.container_12 .suffix_6{padding-right:50.0%}.container_12 .suffix_7{padding-right:58.
333%}.container_12 .suffix_8{padding-right:66.667%}.container_12 .suffix_9{padding-right:75.0%}.cont
ainer_12 .suffix_10{padding-right:83.333%}.container_12 .suffix_11{padding-right:91.667%}.container_
12 .push_1{left:8.333%}.container_12 .push_2{left:16.667%}.container_12 .push_3{left:25.0%}.containe
r_12 .push_4{left:33.333%}.container_12 .push_5{left:41.667%}.container_12 .push_6{left:50.0%}.conta
iner_12 .push_7{left:58.333%}.container_12 .push_8{left:66.667%}.container_12 .push_9{left:75.0%}.co
ntainer_12 .push_10{left:83.333%}.container_12 .push_11{left:91.667%}.container_12 .pull_1{left:-8.3
33%}.container_12 .pull_2{left:-16.667%}.container_12 .pull_3{left:-25.0%}.container_12 .pull_4{left
:-33.333%}.container_12 .pull_5{left:-41.667%}.container_12 .pull_6{left:-50.0%}.container_12 .pull_
7{left:-58.333%}.container_12 .pull_8{left:-66.667%}.container_12 .pull_9{left:-75.0%}.container_12
.pull_10{left:-83.333%}.container_12 .pull_11{left:-91.667%}.clear{clear:both;display:block;overflow
:hidden;visibility:hidden;width:0;height:0}.clearfix:after{clear:both;content:' ';display:block;font
-size:0;line-height:0;visibility:hidden;width:0;height:0}.clearfix{display:inline-block}* html .clea
<!-- End 960 grid -->
div.metricgraph {
body {
div.header {
font-family: Arial, sans-serif;
div.header h2 {
margin: .5em auto;
} {
font-family: Arial, sans-serif;
margin-bottom: 1em;
div.main {
div.cliplist {
font-family: Arial, sans-serif;
margin-top: 6px;
div.chartarea {
font-family: Arial, sans-serif;
div.indicators {
font-family: Arial, sans-serif;
font-size: 13px;
margin-top: 6px;
min-height: 600px;
background-color: #f7f7f7;
div.indicators div.content {
margin: 1em;
div.indicators div.content h5 {
font-size: 13px;
text-align: center;
margin: 0;
div.indicators div.content ul {
margin-left: 0;
padding-left: 0;
margin-top: 0;
div.indicators div.content ul li {
margin-left: 1.5em;
div.indicators div.content p:first-child {
margin-bottom: .5em;
} {
color: #000;
.header-style {
font-weight: bold;
border: 1px solid #fff;
background-color: #ccc;
td.header-style+td {
.orange-background {
background-color: orange;
.light-gray-background {
background-color: #f0f0f0;
<script type="text/javascript" src=""></script>
<script type="text/javascript">
var chart_left = 40;
var chart_top = 6;
var chart_height = document.documentElement.clientHeight-100;
var chart_width = "100%";
var snrs = [];
var filestable_dsnr = [];
var filestable_drate = [];
var filestable_avg = [];
// Python template code replaces the following 2 lines.
var selected = 0
var imagestr = '';
var bettertable=0;
var chart=0;
var better=0;
var metricdata=0;
var metricView=0;
var column=1;
var formatter=0;
function changeColumn(col) {
column = col;
function changeMetric(m) {
function setup_vis() {
chart = new google.visualization.ScatterChart(
bettertable = new google.visualization.Table(
function build_metrics_radio() {
for (metric=1; metric < metrics.length; metric++) {
var rb = document.createElement('input');
var l = document.createElement('label');
rb.setAttribute('onClick', "changeColumn('"+metric.toString()+"')");
l.innerHTML = metrics[metric];
function draw_files() {
var options = {'allowHtml': true, 'width': "100%", 'height': "50%"};
if (better != 0) delete better;
better = new google.visualization.DataTable(col)
// Python Template code replaces the following line with a list of
// formatters.
if (ftable == 'filestable_dsnr')
formatter = new google.visualization.NumberFormat(
{fractionDigits: 4, suffix:" db"});
formatter = new google.visualization.NumberFormat(
{fractionDigits: 4, suffix:"%"});
bettertable.draw(better,options);, 'select',
function query_file() {
imagestr = better.getFormattedValue(selected, 0)
var metricjson = eval('(' + snrs[column][selected] + ')');
metricdata = new google.visualization.DataTable(metricjson, 0.6);
if( metricView != 0 ) delete metricView;
metricView = new google.visualization.DataView(metricdata);
chart.draw(metricView, {curveType:'function',
explorer: {},
chartArea:{left:chart_left, top:chart_top, width:chart_width,
hAxis:{title:"Datarate in kbps"},
vAxis:{title:"Quality in decibels", format: '##.0', textPosition: 'in'},
legend:{position:"in"}, title:imagestr, pointSize:2, lineWidth:1,
width:chart_width, height:chart_height-50 });, 'select', chartSelect);, 'onmouseover', chartMouseOver);, 'onmouseout', chartMouseOut);
function chartMouseOut(e) {
statusbar = document.getElementById('status'); = 'none';