Commit 448ca408 authored by Tom Finegan's avatar Tom Finegan

Revert "Add contributor guide info to README.md."

This reverts commit c1aa69b9.

Reason for revert: Need to filter the contributor guide scripts from the example tests run before this can actually land.

Change-Id: If184314da71e45617b53fc59f41209fe40e1e36b
parent c1aa69b9
......@@ -3,7 +3,6 @@
## 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)
......@@ -17,25 +16,14 @@
- [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. [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)
4. [Support](#support)
5. [Bug reports](#bug-reports)
## Building the library and applications
......@@ -51,17 +39,6 @@
7. Emscripten builds require the portable
[EMSDK](https://kripken.github.io/emscripten-site/index.html).
### Get the code
The AV1 library source code is stored in the Alliance for Open Media Git
repository:
~~~
$ git clone https://aomedia.googlesource.com/aom
# 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
......@@ -69,10 +46,8 @@ 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
......@@ -272,9 +247,7 @@ appropriately using the emsdk\_env script.
### Testing basics
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
applications.
Currently there are two types of tests in the AV1 codec repository.
#### 1. Unit tests:
......@@ -305,57 +278,6 @@ The example tests require a bash shell and can be run in the following manner:
$ path/to/aom/test/examples.sh --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
statistics:
~~~
$ 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 run_encodes.sh, its helper script
# best_encode.sh, and the aomenc you intend to test are all within a
# directory in your PATH.
$ run_encodes.sh 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
intended:
~~~
# 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 run_encodes.sh, its helper script
# best_encode.sh, and the aomenc you intend to test are all within a
# directory in your PATH.
$ run_encodes.sh 200 500 50 mytweak
~~~
After creating both data sets you can use `test/visual_metrics.py` to generate a
report that can be viewed in a web browser:
~~~
$ visual_metrics.py 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
......@@ -386,13 +308,6 @@ 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:
https://media.xiph.org/video/derf/
### Sharded testing
The AV1 codec library unit tests are built upon gtest which supports sharding of
......@@ -432,20 +347,8 @@ is the default maximum value.
## Coding style
We are using the Google C Coding Style defined by the
[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
The coding style used by this project is enforced with clang-format using the
configuration contained in the
[.clang-format](https://chromium.googlesource.com/webm/aom/+/master/.clang-format)
file in the root of the repository.
You can download clang-format using your system's package manager, or directly
from [llvm.org](http://llvm.org/releases/download.html). You can also view the
[documentation](https://clang.llvm.org/docs/ClangFormat.html) on llvm.org.
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.
configuration contained in the .clang-format file in the root of the repository.
Before pushing changes for review you can format your code with:
......@@ -458,116 +361,7 @@ 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.
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](https://www.gerritcodereview.com/) 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](https://aomedia.googlesource.com/) 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](http://aomedia.org/license) 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)
above.
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
example:
~~~
$ curl -Lo aom/.git/hooks/commit-msg https://chromium-review.googlesource.com/tools/hooks/commit-msg
# Next, ensure that the downloaded commit-msg script is executable:
$ chmod u+x aom/.git/hooks/commit-msg
~~~
See the Gerrit
[documentation](https://gerrit-review.googlesource.com/Documentation/user-changeid.html)
for more information.
### Upload your change
The command line to upload your patch looks like this:
~~~
$ git push https://aomedia-review.googlesource.com/aom 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
specified.
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](https://aomedia-review.googlesource.com/), sign in, and click My >
Changes.
See also: http://clang.llvm.org/docs/ClangFormat.html
## Support
......
#!/bin/bash
#
# 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 www.aomedia.org/license/software. 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 www.aomedia.org/license/patent.
#
# Author: jimbankoski@google.com (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"
exit
fi
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 \
--arnr-type=3
else
# 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 \
--drop-frame=0
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 \
--arnr-type=3
fi
This diff is collapsed.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Video Codec Test Results</title>
<style type="text/css">
<!-- Begin 960 reset -->
a,abbr,acronym,address,applet,article,aside,audio,b,big,blockquote,body,canvas,caption,center,cite,c
ode,dd,del,details,dfn,dialog,div,dl,dt,em,embed,fieldset,figcaption,figure,font,footer,form,h1,h2,h
3,h4,h5,h6,header,hgroup,hr,html,i,iframe,img,ins,kbd,label,legend,li,mark,menu,meter,nav,object,ol,
output,p,pre,progress,q,rp,rt,ruby,s,samp,section,small,span,strike,strong,sub,summary,sup,table,tbo
dy,td,tfoot,th,thead,time,tr,tt,u,ul,var,video,xmp{border:0;margin:0;padding:0;font-size:100%}html,b
ody{height:100%}article,aside,details,figcaption,figure,footer,header,hgroup,menu,nav,section{displa
y:block}b,strong{font-weight:bold}img{color:transparent;font-size:0;vertical-align:middle;-ms-interp
olation-mode:bicubic}ol,ul{list-style:none}li{display:list-item}table{border-collapse:collapse;borde
r-spacing:0}th,td,caption{font-weight:normal;vertical-align:top;text-align:left}q{quotes:none}q:befo
re,q:after{content:'';content:none}sub,sup,small{font-size:75%}sub,sup{line-height:0;position:relati
ve;vertical-align:baseline}sub{bottom:-0.25em}sup{top:-0.5em}svg{overflow:hidden}
<!-- 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;
height:0}h1{font-size:25px}h2{font-size:23px}h3{font-size:21px}h4{font-size:19px}h5{font-size:17px}h
6{font-size:15px}ol{list-style:decimal}ul{list-style:disc}li{margin-left:30px}p,dl,hr,h1,h2,h3,h4,h5
,h6,ol,ul,pre,table,address,fieldset,figure{margin-bottom:20px}
<!-- End 960 text -->
<!-- Begin 960 grid (fluid variant)
12 columns, 1152px total width
http://960.gs/ | http://grids.heroku.com/ -->
.container_12{width:92%;margin-left:4%;margin-right:4%}.grid_1,.grid_2,.grid_3,.grid_4,.grid_5,.grid
_6,.grid_7,.grid_8,.grid_9,.grid_10,.grid_11,.grid_12{display:inline;float:left;position:relative;ma
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
rfix{height:1%}.clearfix{display:block}
<!-- End 960 grid -->
div.metricgraph {
}
body {
}
div.header {
font-family: Arial, sans-serif;
}
div.header h2 {
margin: .5em auto;
}
div.radio {
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;
}
span.google-visualization-table-sortind {
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;
}
</style>
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
var chart_left = 40;
var chart_top = 6;
var chart_height = document.documentElement.clientHeight-100;
var chart_width = "100%";
ftable='filestable_avg'
var snrs = [];
var filestable_dsnr = [];
var filestable_drate = [];
var filestable_avg = [];
// Python template code replaces the following 2 lines.
//%%metrics_js%%//
//%%filestable_dpsnr%%//
//%%filestable_avg%%//
//%%filestable_drate%%//
//%%snrs%%//
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;
console.log(col)
draw_files();
}
function changeMetric(m) {
ftable=m
draw_files()
}
function setup_vis() {
chart = new google.visualization.ScatterChart(
document.getElementById("metricgraph"));
bettertable = new google.visualization.Table(
document.getElementById("bettertable"));
draw_files();
build_metrics_radio();
}
function build_metrics_radio() {
for (metric=1; metric < metrics.length; metric++) {
var rb = document.createElement('input');
var l = document.createElement('label');
rb.setAttribute('type','radio');
rb.setAttribute('name','metric');
rb.setAttribute('onClick', "changeColumn('"+metric.toString()+"')");
l.innerHTML = metrics[metric];
document.getElementById('metrics').appendChild(rb);
document.getElementById('metrics').appendChild(l);
}
}
function draw_files() {
var options = {'allowHtml': true, 'width': "100%", 'height': "50%"};
if (better != 0) delete better;
col=eval(ftable+'[column]')
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"});
else
formatter = new google.visualization.NumberFormat(
{fractionDigits: 4, suffix:"%"});
//%%formatters%%//
bettertable.draw(better,options);
google.visualization.events.addListener(bettertable, 'select',
selectBetterHandler);
query_file()
}
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,
height:chart_height-90},
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 });
google.visualization.events.addListener(chart, 'select', chartSelect);
google.visualization.events.addListener(chart, 'onmouseover', chartMouseOver);
google.visualization.events.addListener(chart, 'onmouseout', chartMouseOut);
}
function chartMouseOut(e) {
statusbar = document.getElementById('status');