README.md 3.66 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 13 14

# Features

* Intra frames
* 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 22

# Building
23

rzumer's avatar
rzumer committed
24
This repository uses a git submodule. To initialize it, run:
25 26 27 28 29

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

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

32
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:
33 34

```
35
sudo apt install perl yasm cmake clang pkg-config
36
```
Thomas Daede's avatar
Thomas Daede committed
37

38 39
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
40 41
# Compressing video

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

Thomas Daede's avatar
Thomas Daede committed
44
```
45
cargo run --release --bin rav1e -- input.y4m -o output.ivf
Thomas Daede's avatar
Thomas Daede committed
46 47 48 49
```
# Decompressing video

```
50 51
mkdir aom_test
cd aom_test
Thomas Daede's avatar
Thomas Daede committed
52
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
53 54 55
make -j8
./aomdec ../output.ivf -o output.y4m
```
Thomas Daede's avatar
Thomas Daede committed
56 57 58 59

# Design

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

# Contributing

74
## Coding style
Michael Bebenita's avatar
Michael Bebenita committed
75
Check code formatting with [rustfmt](https://github.com/rust-lang-nursery/rustfmt) before submitting a PR.
Michael Bebenita's avatar
Michael Bebenita committed
76 77 78 79 80 81 82 83 84 85 86 87
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
88 89

```
Michael Bebenita's avatar
Michael Bebenita committed
90
cd rav1e
Michael Bebenita's avatar
Michael Bebenita committed
91 92
cargo +nightly fmt -- --check
```
Michael Bebenita's avatar
Michael Bebenita committed
93 94 95 96 97

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

99 100 101 102 103 104 105 106 107 108 109
## 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
110 111 112 113 114 115 116 117 118 119
Run regular benchmarks with:
```
cargo bench
```

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

120 121 122 123
# 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).