README.md 4.85 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

Thomas Daede's avatar
Thomas Daede committed
3
[![Build Status](https://travis-ci.org/xiph/rav1e.svg?branch=master)](https://travis-ci.org/xiph/rav1e)
Luca Barbato's avatar
Luca Barbato committed
4
[![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
5 6 7 8 9

# 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.

Thomas Daede's avatar
Thomas Daede committed
10
rav1e temporarily uses libaom's transforms and CDF initialization tables, but is otherwise an independent implementation.
Thomas Daede's avatar
Thomas Daede committed
11 12 13

# Features

Gideon Mayhak's avatar
Gideon Mayhak committed
14
* Intra and inter frames
Thomas Daede's avatar
Thomas Daede committed
15
* 64x64 superblocks
Raphael Zumer's avatar
Raphael Zumer committed
16 17
* 4x4 to 32x32 RDO-selected square blocks
* DC, H, V, Paeth, and smooth prediction modes
Thomas Daede's avatar
Thomas Daede committed
18
* 4x4 DCT and ADST transforms
19
* 8-, 10- and 12-bit depth color
20
* Variable speed settings
21
* ~10 fps encoding @ 480p
Thomas Daede's avatar
Thomas Daede committed
22

Gideon Mayhak's avatar
Gideon Mayhak committed
23 24 25 26
# 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
27
# Building
28

rzumer's avatar
rzumer committed
29
This repository uses a git submodule. To initialize it, run:
30 31 32 33 34

```
git submodule update --init
```

rzumer's avatar
rzumer committed
35
This is also required every time you switch branches or pull a submodule change.
36

Raphaël Zumer's avatar
Raphaël Zumer committed
37
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:
38 39

```
Raphaël Zumer's avatar
Raphaël Zumer committed
40
sudo apt install perl nasm cmake clang pkg-config
41
```
Thomas Daede's avatar
Thomas Daede committed
42

Raphaël Zumer's avatar
Raphaël Zumer committed
43
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.
44

Thomas Daede's avatar
Thomas Daede committed
45 46
# Compressing video

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

Thomas Daede's avatar
Thomas Daede committed
49
```
50
cargo run --release --bin rav1e -- input.y4m -o output.ivf
Thomas Daede's avatar
Thomas Daede committed
51 52 53
```
# Decompressing video

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

Thomas Daede's avatar
Thomas Daede committed
56
```
57 58
mkdir aom_test
cd aom_test
59
cmake ../aom_build/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
60 61 62
make -j8
./aomdec ../output.ivf -o output.y4m
```
Thomas Daede's avatar
Thomas Daede committed
63

64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
# 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
80 81 82
# Design

* src/context.rs - High-level functions that write symbols to the bitstream, and maintain context.
Raphael Zumer's avatar
Raphael Zumer committed
83 84
* src/ec.rs - Low-level implementation of the entropy coder, which directly writes the bitstream.
* src/lib.rs - The top level library, contains code to write headers, manage buffers, and iterate throught each superblock.
Thomas Daede's avatar
Thomas Daede committed
85 86 87
* 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
88
* src/rdo.rs - RDO-related structures and distortion computation functions.
89
* src/transform/*.rs - Implementations of DCT and ADST transforms.
Michael Bebenita's avatar
Michael Bebenita committed
90
* src/util.rs - Misc utility code.
Thomas Daede's avatar
Thomas Daede committed
91 92 93
* src/bin/rav1e.rs - rav1e command line tool.
* src/bin/rav1erepl.rs - Command line tool for debugging.
* aom_build/ - Local submodule of libaom. Some C functions and constants are used directly. Also used for benchmarking and testing.
Michael Bebenita's avatar
Michael Bebenita committed
94 95 96

# Contributing

97
## Coding style
Michael Bebenita's avatar
Michael Bebenita committed
98
Check code formatting with [rustfmt](https://github.com/rust-lang-nursery/rustfmt) before submitting a PR.
99
rav1e currently uses the nightly version of rustfmt.
Michael Bebenita's avatar
Michael Bebenita committed
100

101
To install nightly:
Michael Bebenita's avatar
Michael Bebenita committed
102 103

```
104 105 106 107 108 109 110
rustup install nightly
```

To install the nightly version of rustfmt:

```
rustup component add rustfmt-preview --toolchain nightly
Michael Bebenita's avatar
Michael Bebenita committed
111 112 113
```

then
Michael Bebenita's avatar
Michael Bebenita committed
114 115 116 117

```
cargo +nightly fmt -- --check
```
Michael Bebenita's avatar
Michael Bebenita committed
118 119

You should also try [clippy](https://github.com/rust-lang-nursery/rust-clippy).
120 121 122 123 124 125 126 127 128 129
Rust also uses nightly for clippy.

To install clippy:

```
rustup component add clippy-preview --toolchain nightly
```

then

Michael Bebenita's avatar
Michael Bebenita committed
130 131 132
```
cargo +nightly clippy
```
133

134 135 136 137 138 139 140 141 142 143 144
## Testing
Run unit tests with:
```
cargo test
```

Run encode-decode integration tests with:
```
cargo test --release --features=decode_test -- --ignored
```

rzumer's avatar
rzumer committed
145 146 147 148 149 150 151 152 153 154
Run regular benchmarks with:
```
cargo bench
```

Run comparative benchmarks with:
```
cargo bench --features=comparative_bench
```

155 156 157 158
# 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).