Debian Codegraph @

.cargo/vendor/rav1e/README.md

raw
1 # rav1e [![Actions Status][actions badge]][actions] [![CodeCov][codecov badge]][codecov]
2
3 The fastest and safest AV1 encoder.
4
5 <details>
6 <summary><b>Table of Content</b></summary>
7
8 - [Overview](#overview)
9 - [Features](#features)
10 - [Documentation](#documentation)
11 - [Releases](#releases)
12 - [Building](#building)
13 - [Dependency: NASM](#dependency-nasm)
14 - [Release binary](#release-binary)
15 - [Unstable features](#unstable-features)
16 - [Target-specific builds](#target-specific-builds)
17 - [Building the C-API](#building-the-c-api)
18 - [Usage](#usage)
19 - [Compressing video](#compressing-video)
20 - [Decompressing video](#decompressing-video)
21 - [Configuring](#configuring)
22 - [Features](#features-1)
23 - [Contributing](#contributing)
24 - [Getting in Touch](#getting-in-touch)
25 </details>
26
27 ## Overview
28 rav1e is an 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.
29
30 ## Features
31 * Intra, inter, and switch frames
32 * 64x64 superblocks
33 * 4x4 to 64x64 RDO-selected square and rectangular blocks
34 * DC, H, V, Paeth, smooth, and all directional prediction modes
35 * DCT, (FLIP-)ADST and identity transforms (up to 64x64, 16x16 and 32x32 respectively)
36 * 8-, 10- and 12-bit depth color
37 * 4:2:0, 4:2:2 and 4:4:4 chroma sampling
38 * 11 speed settings (0-10, exhaustive to near real-time)
39 * Constant quantizer and target bitrate (single- and multi-pass) encoding modes
40 * Still picture mode
41
42 ## Documentation
43 Find the documentation in [`doc/`](doc/README.md)
44
45 ## Releases
46 For the foreseeable future, a weekly pre-release of rav1e will be [published](https://github.com/xiph/rav1e/releases) every Tuesday.
47
48 ## Building
49
50 ### Toolchain: Rust
51
52 rav1e currently requires Rust 1.74.0 or later to build.
53
54 ### Dependency: NASM
55 Some `x86_64`-specific optimizations require [NASM](https://nasm.us/) `2.14.02` or newer and are enabled by default.
56 `strip` will be used if available to remove the local symbols from the asm objects.
57
58 The CI is testing against `nasm 2.15.05`, so bugs for other versions might happen. If you find one please open an issue!
59
60 <details>
61 <summary>
62 Install nasm
63 </summary>
64
65 **ubuntu 20.04** (`nasm 2.14.02`)
66 ```sh
67 sudo apt install nasm
68 ```
69 **ubuntu 18.04** (`nasm 2.14.02`)
70 ```sh
71 sudo apt install nasm-mozilla
72 # link nasm into $PATH
73 sudo ln /usr/lib/nasm-mozilla/bin/nasm /usr/local/bin/
74 ```
75 **fedora 31, 32** (`nasm 2.14.02`)
76 ```sh
77 sudo dnf install nasm
78 ```
79 **windows** (`nasm 2.15.05`) <br/>
80 Have a [NASM binary](https://www.nasm.us/pub/nasm/releasebuilds/) in your system PATH.
81 ```sh
82 $NASM_VERSION="2.15.05" # or newer
83 $LINK="https://www.nasm.us/pub/nasm/releasebuilds/$NASM_VERSION/win64"
84 curl --ssl-no-revoke -LO "$LINK/nasm-$NASM_VERSION-win64.zip"
85 7z e -y "nasm-$NASM_VERSION-win64.zip" -o "C:\nasm"
86 # set path for the current sessions
87 set PATH="%PATH%;C:\nasm"
88 ```
89 **macOS** (`nasm 2.15.05`)
90 ```sh
91 brew install nasm
92 ```
93
94 </details>
95
96 ### Release binary
97 To build release binary in `target/release/rav1e` run:
98
99 ```sh
100 cargo build --release
101 ```
102
103 ### Unstable features
104 Experimental API and Features can be enabled by using the `unstable` feature.
105
106 ```sh
107 cargo build --features <feature>,unstable
108 ```
109
110 #### Current unstable features
111 - Channel API:
112 ```sh
113 cargo build --features channel-api,unstable
114 ```
115
116
117 Those Features and API are bound to change and evolve, do not rely on them staying the same over releases.
118
119 ### Target-specific builds
120 The rust compiler can produce a binary that is about 11%-13% faster if it can use `avx2`, `bmi1`, `bmi2`, `fma`, `lzcnt` and `popcnt` in the general code, you may allow it by issuing:
121
122 ```sh
123 RUSTFLAGS="-C target-cpu=native" cargo build --release
124 # or
125 RUSTFLAGS="-C target-cpu=x86-64-v3" cargo build --release
126 ```
127
128 The resulting binary will not work on cpus that do not sport the same set of extensions enabled.
129
130 > **NOTE** : You may use `rustc --print target-cpus` to check if the cpu is supported, if not `-C target-cpu=native` would be a no-op.
131
132 ### Building the C-API
133 **rav1e** provides a C-compatible set of library, header and pkg-config file.
134
135 To build and install it you can use [cargo-c](https://crates.io/crates/cargo-c):
136
137 ```sh
138 cargo install cargo-c
139 cargo cinstall --release
140 ```
141
142 Please refer to the cargo-c [installation](https://github.com/lu-zero/cargo-c#installation) instructions.
143
144 ## Usage
145 ### Compressing video
146 Input videos must be in [y4m format](https://wiki.multimedia.cx/index.php/YUV4MPEG2). The monochrome color format is not supported.
147
148 ```sh
149 cargo run --release --bin rav1e -- input.y4m -o output.ivf
150 ```
151
152 _(Find a y4m-file for testing at [`tests/small_input.y4m`](tests/small_input.y4m) or at http://ultravideo.cs.tut.fi/#testsequences)_
153
154 ### Decompressing video
155 Encoder output should be compatible with any AV1 decoder compliant with the v1.0.0 specification. You can decode using [dav1d](https://code.videolan.org/videolan/dav1d), which is now packaged [![in over 40 repositories](https://repology.org/badge/tiny-repos/dav1d.svg)](https://repology.org/project/dav1d/versions).
156
157 ```sh
158 dav1d -i output.ivf -o output.y4m
159 ```
160
161 ### Configuring
162 rav1e has several optional features that can be enabled by passing `--features` to cargo. Passing `--all-features` is discouraged.
163
164 #### Features
165 Find a full list in feature-table in [`Cargo.toml`](Cargo.toml)
166
167 * `asm` - enabled by default. When enabled, assembly is built for the platforms supporting it.
168 * `x86_64`: Requires [`nasm`](#dependency-nasm).
169 * `aarch64`
170 * Requires `gas`
171 * Alternative: Use `clang` assembler by setting `CC=clang`
172
173 **NOTE**: `SSE2` is always enabled on `x86_64`, `neon` is always enabled for aarch64, you may set the environment variable `RAV1E_CPU_TARGET` to `rust` to disable all the assembly-optimized routines at the runtime.
174
175 ## Contributing
176 Please read our guide to [contributing to rav1e](CONTRIBUTING.md).
177
178 ## Getting in Touch
179 Come chat with us on the IRC channel #daala on [Libera.Chat](https://libera.chat/)! You can also use a [web client](https://web.libera.chat/?channel=#daala) to join with a web browser.
180
181
182 <!-- Links -->
183 [actions]: https://github.com/xiph/rav1e/actions
184 [codecov]: https://codecov.io/gh/xiph/rav1e
185
186 <!-- Badges -->
187 [actions badge]: https://github.com/xiph/rav1e/workflows/rav1e/badge.svg
188 [codecov badge]: https://codecov.io/gh/xiph/rav1e/branch/master/graph/badge.svg