README.md 5.29 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 75 76 77 78 79 80 81 82 83 84
# 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
85 86 87
# Design

* src/context.rs - High-level functions that write symbols to the bitstream, and maintain context.
Raphael Zumer's avatar
Raphael Zumer committed
88
* src/ec.rs - Low-level implementation of the entropy coder, which directly writes the bitstream.
0xflotus's avatar
0xflotus committed
89
* 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
90 91 92
* 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
93
* src/rdo.rs - RDO-related structures and distortion computation functions.
94
* src/transform/*.rs - Implementations of DCT and ADST transforms.
95
* src/util.rs - Misc utility code.
Thomas Daede's avatar
Thomas Daede committed
96 97
* src/bin/rav1e.rs - rav1e command line tool.
* src/bin/rav1erepl.rs - Command line tool for debugging.
98 99 100

# Contributing

101 102
## Toolchain
rav1e uses the stable version of Rust (the stable toolchain).
103

104
To install the toolchain:
105
```
106
rustup install stable
107 108
```

109 110 111 112 113

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

To install the rustfmt:
114 115

```
116
rustup component add rustfmt
117 118 119
```

then
120 121

```
122
cargo fmt -- --check
123
```
Michael Bebenita's avatar
Michael Bebenita committed
124

125 126 127 128 129

## 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.
130 131 132 133

To install clippy:

```
134
rustup component add clippy
135 136
```

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

139

140 141 142 143 144 145 146 147
## Testing
Run unit tests with:
```
cargo test
```

Run encode-decode integration tests with:
```
Raphaël Zumer's avatar
Raphaël Zumer committed
148
cargo test --release --features=decode_test
149 150
```

151 152 153 154 155
Run the encode-decode tests against `dav1d` with:
```
cargo test --release --features=decode_test_dav1d
```

156 157 158 159 160
Run regular benchmarks with:
```
cargo bench
```

161 162 163 164
# 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).