README.md 5.52 KB
Newer Older
Thomas Daede's avatar
Thomas Daede committed
1
The fastest and safest AV1 encoder.
Thomas Daede's avatar
Thomas Daede committed
2

3
[![Travis Build Status](https://travis-ci.org/xiph/rav1e.svg?branch=master)](https://travis-ci.org/xiph/rav1e)
Ewout ter Hoeven's avatar
Ewout ter Hoeven committed
4
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/xiph/rav1e?branch=master&svg=true)](https://ci.appveyor.com/project/tdaede/rav1e/history)
Luca Barbato's avatar
Luca Barbato committed
5
[![Coverage Status](https://coveralls.io/repos/github/xiph/rav1e/badge.svg?branch=master)](https://coveralls.io/github/xiph/rav1e?branch=master)
Thomas Daede's avatar
Thomas Daede committed
6
7
8
9
10
11
12

# Overview

rav1e is an experimental AV1 video encoder. It is designed to eventually cover all use cases, though in its current form it is most suitable for cases where libaom (the reference encoder) is too slow.

# Features

Gideon Mayhak's avatar
Gideon Mayhak committed
13
* Intra and inter frames
Thomas Daede's avatar
Thomas Daede committed
14
* 64x64 superblocks
Raphaël Zumer's avatar
Raphaël Zumer committed
15
16
* 4x4 to 64x64 RDO-selected square and 2:1/1:2 rectangular blocks
* DC, H, V, Paeth, smooth, and a subset of directional prediction modes
Raphaël Zumer's avatar
Raphaël Zumer committed
17
* DCT, ADST and identity transforms (up to 64x64, 16x16 and 32x32 respectively)
18
* 8-, 10- and 12-bit depth color
19
* 4:2:0 (full support), 4:2:2 and 4:4:4 (limited) chroma sampling
20
* Variable speed settings
Raphaël Zumer's avatar
Raphaël Zumer committed
21
* Near real-time encoding at high speed levels
Thomas Daede's avatar
Thomas Daede committed
22

23
24
25
26
# Releases

For the foreseeable future, a weekly pre-release of rav1e will be [published](https://github.com/xiph/rav1e/releases) every Tuesday.

Gideon Mayhak's avatar
Gideon Mayhak committed
27
28
29
30
# Windows builds

Automated AppVeyor builds can be found [here](https://ci.appveyor.com/project/tdaede/rav1e/history). Click on a build (it is recommended you select a build based on "master"), then click ARTIFACTS to reveal the rav1e.exe download link.

Thomas Daede's avatar
Thomas Daede committed
31
# Building
32

33
**rav1e** can optionally use either `libaom` (default) or a `dav1d` installation to run some extended tests.
34
Some `x86_64`-specific optimizations require a recent version of NASM.
35

36
In order to build, test and link to the codec on UNIX, you need Perl, NASM, CMake, Clang and pkg-config. To install this on Ubuntu or Linux Mint, run:
37
38

```
39
sudo apt install perl nasm cmake clang pkg-config
40
41
```

42
On Windows, pkg-config is not required. A Perl distribution such as Strawberry Perl, CMake, and a NASM binary in your system PATH are required.
43

44
To build release binary in `target/release/rav1e` run:
45
46

```
47
cargo build --release
48
```
Thomas Daede's avatar
Thomas Daede committed
49
50
51

# Compressing video

52
Input videos must be in y4m format and have 4:2:0 chroma subsampling.
53

Thomas Daede's avatar
Thomas Daede committed
54
```
55
cargo run --release --bin rav1e -- input.y4m -o output.ivf
Thomas Daede's avatar
Thomas Daede committed
56
57
58
```
# Decompressing video

59
Encoder output should be compatible with any AV1 decoder compliant with the v1.0.0 specification. You can build compatible aomdec using the following:
Gideon Mayhak's avatar
Gideon Mayhak committed
60

Thomas Daede's avatar
Thomas Daede committed
61
```
62
63
mkdir aom_test
cd aom_test
64
cmake /path/to/aom -DAOM_TARGET_CPU=generic -DCONFIG_AV1_ENCODER=0 -DENABLE_TESTS=0 -DENABLE_DOCS=0 -DCONFIG_LOWBITDEPTH=1
Thomas Daede's avatar
Thomas Daede committed
65
66
67
make -j8
./aomdec ../output.ivf -o output.y4m
```
Thomas Daede's avatar
Thomas Daede committed
68

69
70
71
72
73
74
# Configuring

rav1e has several optional features that can be enabled by passing --features to cargo test. Passing --all-features is discouraged.

* nasm - enabled by default. When enabled, assembly is built for x86_64.

75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
# Using the AOMAnalyzer

## Local Analyzer

1. Download the [AOM Analyzer](http://aomanalyzer.org).
2. Download [inspect.js](https://people.xiph.org/~mbebenita/analyzer/inspect.js) and [inspect.wasm](https://people.xiph.org/~mbebenita/analyzer/inspect.wasm) and save them in the same directory.
3. Run the analyzer: `AOMAnalyzer path_to_inspect.js output.ivf`

## Online Analyzer

If your `.ivf` file is hosted somewhere (and CORS is enabled on your web server) you can use:

```
https://arewecompressedyet.com/analyzer/?d=https://people.xiph.org/~mbebenita/analyzer/inspect.js&f=path_to_output.ivf
```

Thomas Daede's avatar
Thomas Daede committed
91
92
93
# Design

* src/context.rs - High-level functions that write symbols to the bitstream, and maintain context.
Raphael Zumer's avatar
Raphael Zumer committed
94
* src/ec.rs - Low-level implementation of the entropy coder, which directly writes the bitstream.
0xflotus's avatar
0xflotus committed
95
* src/lib.rs - The top level library, contains code to write headers, manage buffers, and iterate through each superblock.
Thomas Daede's avatar
Thomas Daede committed
96
97
98
* src/partition.rs - Functions and enums to manage partitions (subdivisions of a superblock).
* src/predict.rs - Intra prediction implementations.
* src/quantize.rs - Quantization and dequantization functions for coefficients.
Raphael Zumer's avatar
Raphael Zumer committed
99
* src/rdo.rs - RDO-related structures and distortion computation functions.
100
* src/transform/*.rs - Implementations of DCT and ADST transforms.
Michael Bebenita's avatar
Michael Bebenita committed
101
* src/util.rs - Misc utility code.
Thomas Daede's avatar
Thomas Daede committed
102
103
* src/bin/rav1e.rs - rav1e command line tool.
* src/bin/rav1erepl.rs - Command line tool for debugging.
Michael Bebenita's avatar
Michael Bebenita committed
104
105
106

# Contributing

107
108
## Toolchain
rav1e uses the stable version of Rust (the stable toolchain).
Michael Bebenita's avatar
Michael Bebenita committed
109

110
To install the toolchain:
Michael Bebenita's avatar
Michael Bebenita committed
111
```
112
rustup install stable
113
114
```

115
116
117
118
119

## Coding style
Check code formatting with [rustfmt](https://github.com/rust-lang-nursery/rustfmt) before submitting a PR.

To install the rustfmt:
120
121

```
122
rustup component add rustfmt
Michael Bebenita's avatar
Michael Bebenita committed
123
124
125
```

then
Michael Bebenita's avatar
Michael Bebenita committed
126
127

```
128
cargo fmt -- --check
Michael Bebenita's avatar
Michael Bebenita committed
129
```
Michael Bebenita's avatar
Michael Bebenita committed
130

131
132
133
134
135

## Code Analysis
The [clippy](https://github.com/rust-lang-nursery/rust-clippy) will help catch common mistakes and improve your Rust code.

We recommend you use it before submitting a PR.
136
137
138
139

To install clippy:

```
140
rustup component add clippy
141
142
```

143
then you can search "cargo clippy" in [.travis.yml](https://github.com/xiph/rav1e/blob/master/.travis.yml) for detailed command and run it.
144

145

146
147
148
149
150
151
152
153
## Testing
Run unit tests with:
```
cargo test
```

Run encode-decode integration tests with:
```
Raphaël Zumer's avatar
Raphaël Zumer committed
154
cargo test --release --features=decode_test
155
156
```

157
158
159
160
161
Run the encode-decode tests against `dav1d` with:
```
cargo test --release --features=decode_test_dav1d
```

rzumer's avatar
rzumer committed
162
163
Run regular benchmarks with:
```
164
cargo bench --features=bench
rzumer's avatar
rzumer committed
165
166
```

167
168
169
170
# Getting in Touch

Come chat with us on the IRC channel #daala on Freenode! If you don't have IRC set
up you can easily connect from your [web browser](http://webchat.freenode.net/?channels=%23daala).