-
Notifications
You must be signed in to change notification settings - Fork 0
/
webm-contributor-guide.txt
200 lines (141 loc) · 6.72 KB
/
webm-contributor-guide.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
Contributing Source Code to libvpx
==================================
_Revised 2011-01-05_
This document will help guide you through contributing code to the WebM
Project and libvpx.
* * *
**Contents**
* TOC placeholder
{:toc}
* * *
In general, most of the on-going work on libvpx concerns speed and
quality improvement. A developer typically follows this workflow:
1. Work on the source code.
2. Recompile the `vpxenc` encoder binary.
3. Perform a video encode job with the new binary.
4. Evaluate the results, comparing to an identical encode done with a
prior version of `vpxenc`.
Once meaningful improvement is achieved, the developer submits his code
revisions to `libvpx`.
Below we describe in more detail how the core libvpx developers
evaluate their own work, so that new contributors can replicate the
process and have their code contributions approved and merged more
easily.
Required Packages
-----------------
* A Bash shell
* Python
* A modern web browser (like Google Chrome)
Become a Contributor
--------------------
All contributors are welcome. The WebM Project website has details on
configuring your machine and creating an account in our code review
system, so review the information at
**<http://www.webmproject.org/code/>** to get started.
Subscribe to codec-devel
------------------------
**_codec-devel_** is the mailing list (and Google Group) for developers
working on the libvpx library or researching next generation codecs.
While anyone may post to codec-devel, subscribing gives you unmoderated
access.
* Archive: <https://groups.google.com/a/webmproject.org/group/codec-devel>
* Subscribe: <[email protected]>
* Post: <[email protected]>
Though _codec-devel_ offers a web interface, many subscribers treat it
as a simple mailing list and interact solely through their mail clients.
Download Test Clips
-------------------
1. Create a directory to hold the clips (e.g., `~/derf_cif` on Linux
or `c:/derf_cif` on Windows).
2. Visit <http://media.xiph.org/video/derf/> with your web browser.
3. Download each of the the CIF clips found there, in YUV4MPEG (y4m)
format, to the directory you created.
<div class="admon tip" markdown="1">
Encoding Only a Few Test Clips
Normally, you won't want to encode the entire set of test clips, which
can be very time-consuming. Instead, consider symlinking only the clips
you want to use from their storage directory (e.g. `~/derf_cif`) to a
working directory (e.g. `~/derf_working`), and running your tests there.
</div>
Download Test Scripts
---------------------
Test scripts (and this document) are available in the
`contributor-guide` Git project:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ git clone http://git.chromium.org/webm/contributor-guide.git
$ cd contributor-guide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Symlink or physically copy the following scripts to somewhere in your
$PATH:
* `be`
* `run_tests`
* `visual_metrics.py`
Download, Build and Test libvpx
-------------------------------
1. To get started, ensure that your system satisfies the **[build
prerequisites](http://www.webmproject.org/code/build-prerequisites/)**.
2. Next, **clone the libvpx repository**. After cloning, you'll be
working in the master branch by default.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ git clone http://git.chromium.org/webm/libvpx.git
$ cd libvpx
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<div class="admon important" markdown="1">
**Important:** Although its not the common case, if your idea
would necessitate a change to the VP8 format itself, you'll want
to work in the libvpx experimental branch instead:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ git clone http://git.chromium.org/webm/libvpx.git
$ cd libvpx
$ git checkout -b experimental origin/experimental
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
</div>
3. **Configure and build libvpx.** Be sure to run the configure
script with `--enable-internal-stats`, which causes the encoder
(`vpxenc`) to output statistical data as well as a video file. For
example:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ ./configure --disable-codecs --enable-vp8 --enable-internal-stats --enable-debug --disable-install-docs --log=yes
$ make
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To learn more about configuration options, do:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ ./configure --help
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are several ways to "install" (`make install`, etc.), so
we'll leave that up to you. Just ensure that the VP8 encoder
(`vpxenc`) is executable and in your $PATH.
4. **Run some encodes** using the provided scripts. Example:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ cd <test clip directory>
$ run_tests 200 500 50 baseline
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In this example, `run_tests` will encode each `y4m` file in the
current directory at bitrates of 200, 250, 300, 350, 400, 450 and
500 kbps (start at 200, end at 500, 50 kbps increments). It will
create a directory `baseline` and write its output there.
Output consists of `webm` video files and `stt` files containing
statistics for each encode. If the test encodes are 2-pass
(default), an `fpf` file (first-pass data file) is also written
for each input file, and will be reused on subsequent 2-pass
encodes if not deleted.
5. **Make your changes to libvpx**, rebuild, and re-run the tests
using a different output directory name. Example:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ run_tests 200 500 50 mytweak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternatively, change the parameters in the batch encoder script
(`be`) that's called by `run_tests`. `be` in turn calls `vpxenc`.
6. When the tests are finished, run `visual_metrics.py` to generate
an **HTML-format report** that compares `mytweak` with `baseline`.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ visual_metrics.py "*stt" baseline mytweak > mytweak.html
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7. **View the report** by opening `mytweak.html` in a web browser.
Submit Your Patches
-------------------
See the detailed information at **<http://www.webmproject.org/code/contribute/submitting-patches/>**.
<!--
Icon artwork courtesy of the Tango Desktop Project,
http://tango.freedesktop.org/
-->