README.md 4.09 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 4 5 6 7 8
[![Build Status](https://travis-ci.org/xiph/rav1e.svg?branch=master)](https://travis-ci.org/xiph/rav1e)

# 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
9
rav1e temporarily uses libaom's transforms and CDF initialization tables, but is otherwise an independent implementation.
Thomas Daede's avatar
Thomas Daede committed
10 11 12

# Features

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

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

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

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

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

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

```
39
sudo apt install perl yasm cmake clang pkg-config
40
```
Thomas Daede's avatar
Thomas Daede committed
41

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

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

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

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

Gideon Mayhak's avatar
Gideon Mayhak committed
53
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
54

Thomas Daede's avatar
Thomas Daede committed
55
```
56 57
mkdir aom_test
cd aom_test
Thomas Daede's avatar
Thomas Daede committed
58
cmake ../aom_build/aom -DAOM_TARGET_CPU=generic -DCONFIG_AV1_ENCODER=0 -DCONFIG_UNIT_TESTS=0 -DENABLE_DOCS=0 -DCONFIG_LOWBITDEPTH=1
Thomas Daede's avatar
Thomas Daede committed
59 60 61
make -j8
./aomdec ../output.ivf -o output.y4m
```
Thomas Daede's avatar
Thomas Daede committed
62 63 64 65

# Design

* src/context.rs - High-level functions that write symbols to the bitstream, and maintain context.
Raphael Zumer's avatar
Raphael Zumer committed
66 67
* 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
68 69 70
* 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
71
* src/rdo.rs - RDO-related structures and distortion computation functions.
Thomas Daede's avatar
Thomas Daede committed
72
* src/transform.rs - Implementations of DCT and ADST transforms.
Michael Bebenita's avatar
Michael Bebenita committed
73
* src/util.rs - Misc utility code.
Thomas Daede's avatar
Thomas Daede committed
74 75 76
* 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
77 78 79

# Contributing

80
## Coding style
Michael Bebenita's avatar
Michael Bebenita committed
81
Check code formatting with [rustfmt](https://github.com/rust-lang-nursery/rustfmt) before submitting a PR.
Michael Bebenita's avatar
Michael Bebenita committed
82 83 84 85 86 87 88 89 90 91 92 93
rav1e currently uses a [forked version](https://github.com/mbebenita/rustfmt) of rustfmt.

To install rustfmt:

```
git clone https://github.com/mbebenita/rustfmt
cd rustfmt
cargo +nightly build // Depends on the Rust nightly toolchain. 
cargo +nightly install -f // Overwrite the installed rustfmt.
```

then
Michael Bebenita's avatar
Michael Bebenita committed
94 95

```
Michael Bebenita's avatar
Michael Bebenita committed
96
cd rav1e
Michael Bebenita's avatar
Michael Bebenita committed
97 98
cargo +nightly fmt -- --check
```
Michael Bebenita's avatar
Michael Bebenita committed
99 100 101 102 103

You should also try [clippy](https://github.com/rust-lang-nursery/rust-clippy).
```
cargo +nightly clippy
```
104

105 106 107 108 109 110 111 112 113 114 115
## 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
116 117 118 119 120 121 122 123 124 125
Run regular benchmarks with:
```
cargo bench
```

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

126 127 128 129
# 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).