2016-02-05 12:53:25 +00:00
Kvazaar
=======
2015-02-23 11:18:48 +00:00
An open-source HEVC encoder licensed under LGPLv2.1
2014-01-28 15:37:14 +00:00
2014-01-29 08:51:44 +00:00
Join channel #kvazaar_hevc in Freenode IRC network to contact us.
2014-01-28 15:37:14 +00:00
2017-02-13 16:25:15 +00:00
Kvazaar is still under development. Speed and RD-quality will continue to improve.
2014-01-29 08:51:44 +00:00
http://ultravideo.cs.tut.fi/#encoder for more information.
2017-02-13 16:25:15 +00:00
- Linux/Mac [](https://travis-ci.org/ultravideo/kvazaar)
- Windows [](https://ci.appveyor.com/project/Ultravideo/kvazaar)
2014-10-29 14:09:32 +00:00
2018-03-14 09:58:30 +00:00
## Table of Contents
- [Using Kvazaar ](#using-kvazaar )
- [Example: ](#example )
- [Parameters ](#parameters )
- [LP-GOP syntax ](#lp-gop-syntax )
- [Presets ](#presets )
- [Kvazaar library ](#kvazaar-library )
- [Compiling Kvazaar ](#compiling-kvazaar )
- [Required libraries ](#required-libraries )
- [Autotools ](#autotools )
- [OS X ](#os-x )
- [Visual Studio ](#visual-studio )
- [Docker ](#docker )
- [Visualization (Windows only) ](#visualization-windows-only )
- [Contributing to Kvazaar ](#contributing-to-kvazaar )
- [Code documentation ](#code-documentation )
- [For version control we try to follow these conventions: ](#for-version-control-we-try-to-follow-these-conventions )
- [Testing ](#testing )
- [Unit tests ](#unit-tests )
- [Code style ](#code-style )
2016-05-19 12:38:12 +00:00
## Using Kvazaar
2014-01-28 15:37:14 +00:00
2017-02-13 16:25:15 +00:00
### Example:
kvazaar --input BQMall_832x480_60.yuv --output out.hevc
The mandatory parameters are input and output. If the resolution of the input file is not in the filename, or when pipe is used, the input resolution must also be given: ```--input-res=1920x1080```.
The default input format is 8-bit yuv420p for 8-bit and yuv420p10le for 10-bit. Input format and bitdepth can be selected with ```--input-format``` and ```--input-bitdepth```.
Speed and compression quality can be selected with ```--preset```, or by setting the options manually.
### Parameters
2016-02-05 14:16:18 +00:00
[comment]: # (BEGIN KVAZAAR HELP MESSAGE)
```
Usage:
kvazaar -i < input > --input-res < width > x< height > -o < output >
2016-10-26 23:45:24 +00:00
Required:
2016-11-04 13:30:58 +00:00
-i, --input : Input file
--input-res < res > : Input resolution [auto]
auto: detect from file name
< int > x< int > : width times height
-o, --output : Output file
2016-10-26 23:45:24 +00:00
Presets:
2016-11-04 13:30:58 +00:00
--preset=< preset > : Set options to a preset [medium]
- ultrafast, superfast, veryfast, faster,
fast, medium, slow, slower, veryslow
2016-10-26 23:45:24 +00:00
placebo
Input:
2016-11-04 13:30:58 +00:00
-n, --frames < integer > : Number of frames to code [all]
--seek < integer > : First frame to code [0]
2017-11-09 14:53:31 +00:00
--input-fps < num > [/< denom > ] : Framerate of the input video [25.0]
2016-11-04 13:30:58 +00:00
--source-scan-type < string > : Set source scan type [progressive].
- progressive: progressive scan
- tff: top field first
- bff: bottom field first
--input-format : P420 or P400
--input-bitdepth : 8-16
--loop-input : Re-read input file forever
2016-10-26 23:45:24 +00:00
Options:
2016-11-04 13:30:58 +00:00
--help : Print this help message and exit
--version : Print version information and exit
--aud : Use access unit delimiters
--debug < string > : Output encoders reconstruction.
--cpuid < integer > : Disable runtime cpu optimizations with value 0.
--hash : Decoded picture hash [checksum]
- none: 0 bytes
- checksum: 18 bytes
- md5: 56 bytes
--no-psnr : Don't calculate PSNR for frames
--no-info : Don't add encoder info SEI.
2016-10-26 23:45:24 +00:00
Video structure:
2016-11-04 13:30:58 +00:00
-q, --qp < integer > : Quantization Parameter [32]
-p, --period < integer > : Period of intra pictures [0]
- 0: only first picture is intra
- 1: all pictures are intra
- 2-N: every Nth picture is intra
--vps-period < integer > : Specify how often the video parameter set is
re-sent. [0]
- 0: only send VPS with the first frame
- N: send VPS with every Nth intra frame
-r, --ref < integer > : Reference frames, range 1..15 [3]
--gop < string > : Definition of GOP structure [0]
- 0: disabled
- 8: B-frame pyramid of length 8
- lp-< string > : lp-gop definition
(e.g. lp-g8d4t2, see README)
--cqmfile < string > : Custom Quantization Matrices from a file
--bitrate < integer > : Target bitrate. [0]
- 0: disable rate-control
- N: target N bits per second
--lossless : Use lossless coding
--mv-constraint : Constrain movement vectors
- none: no constraint
- frametile: constrain within the tile
- frametilemargin: constrain even more
2017-01-31 14:30:40 +00:00
--roi < string > : Use a delta QP map for region of interest
Read an array of delta QP values from
a file, where the first two values are the
width and height, followed by width*height
delta QP values in raster order.
The delta QP map can be any size or aspect
ratio, and will be mapped to LCU's.
2017-04-19 12:47:47 +00:00
--(no-)erp-aqp : Use adaptive QP for 360 video with
equirectangular projection
2017-11-09 14:53:31 +00:00
--level < number > : Use the given HEVC level in the output and give
an error if the input doesn't fit to it's
2017-12-07 08:47:44 +00:00
limits [6.2]
2017-11-09 14:53:31 +00:00
Allowed values are 1, 2, 2.1, 3, 3.1, 4, 4.1
5, 5.1, 5.2, 6, 6.1 and 6.2. The dot is
optional.
--force-level < number > : Same as --level, except instead of errors you
2017-12-07 08:47:44 +00:00
get warnings
--high-tier : Used with --level. Tells the encoder to use
high-tier bitrate limits instead of the
main-tier limits during encoding.
2016-10-26 23:45:24 +00:00
Compression tools:
2016-11-04 13:30:58 +00:00
--deblock [< beta:tc > ] : Deblocking
- beta: between -6 and 6
- tc: between -6 and 6
--(no-)sao : Sample Adaptive Offset
--(no-)rdoq : Rate-Distortion Optimized Quantization
--(no-)signhide : Sign Hiding
--(no-)smp : Symmetric Motion Partition
--(no-)amp : Asymmetric Motion Partition
--rd < integer > : Intra mode search complexity
- 0: skip intra if inter is good enough
- 1: rough intra mode search with SATD
- 2: refine intra mode search with SSE
--(no-)mv-rdo : Rate-Distortion Optimized motion vector costs
--(no-)full-intra-search
: Try all intra modes during rough search.
--(no-)transform-skip : Transform skip
--me < string > : Integer motion estimation
- hexbs: Hexagon Based Search
- tz: Test Zone Search
- full: Full Search
- full8, full16, full32, full64
2017-12-12 12:45:01 +00:00
- dia: Diamond Search
2017-12-22 10:10:41 +00:00
--me-steps < integer > : How many search steps does the motion estimation
2018-01-10 13:16:52 +00:00
do before cutting off [-1]
2017-12-22 10:10:41 +00:00
Has effect only for 'hexbs' and 'dia'
2016-11-04 13:30:58 +00:00
--subme < integer > : Set fractional pixel motion estimation level
- 0: only integer motion estimation
- 1: + 1/2-pixel horizontal and vertical
- 2: + 1/2-pixel diagonal
- 3: + 1/4-pixel horizontal and vertical
- 4: + 1/4-pixel diagonal
--pu-depth-inter < int > -< int >
: Range for sizes for inter predictions
- 0, 1, 2, 3: from 64x64 to 8x8
--pu-depth-intra < int > -< int > : Range for sizes for intra predictions
- 0, 1, 2, 3, 4: from 64x64 to 4x4
--(no-)bipred : Bi-prediction
--(no-)cu-split-termination
: CU split search termination condition
- off: Never terminate cu-split search
- zero: Terminate with zero residual
--(no-)me-early-termination : ME early termination condition
- off: Don't terminate early
- on: Terminate early
- sensitive: Terminate even earlier
--(no-)implicit-rdpcm : Implicit residual DPCM
Currently only supported with lossless coding.
--(no-)tmvp : Temporal Motion Vector Prediction
--(no-)rdoq-skip : Skips RDOQ for 4x4 blocks
2016-02-05 14:16:18 +00:00
2016-10-26 23:45:24 +00:00
Parallel processing:
2016-11-04 13:30:58 +00:00
--threads < integer > : Number of threads to use [auto]
- 0: process everything with main thread
- N: use N threads for encoding
- auto: select based on number of cores
--owf < integer > : Frame parallelism [auto]
- N: Process N-1 frames at a time
- auto: Select automatically
--(no-)wpp : Wavefront parallel processing [enabled]
Enabling tiles automatically disables WPP.
To enable WPP with tiles, re-enable it after
enabling tiles.
--tiles < int > x< int > : Split picture into width x height uniform tiles.
--tiles-width-split < string > |u< int > :
Specifies a comma separated list of pixel
2017-12-07 08:47:44 +00:00
positions of tiles columns separation
coordinates.
Can also be u, followed by a single int n, in
which case it produces columns of uniform width.
2016-11-04 13:30:58 +00:00
--tiles-height-split < string > |u< int > :
Specifies a comma separated list of pixel
positions of tiles rows separation coordinates.
2017-12-07 08:47:44 +00:00
Can also be u followed by and a single int n, in
which case it produces rows of uniform height.
2017-01-31 14:30:40 +00:00
--slices < string > : Control how slices are used
- tiles: put tiles in independent slices
- wpp: put rows in dependent slices
- tiles+wpp: do both
2016-10-26 23:45:24 +00:00
Video Usability Information:
2016-11-04 13:30:58 +00:00
--sar < width:height > : Specify Sample Aspect Ratio
--overscan < string > : Specify crop overscan setting [undef]
- undef, show, crop
--videoformat < string > : Specify video format [undef]
- component, pal, ntsc, secam, mac, undef
--range < string > : Specify color range [tv]
- tv, pc
--colorprim < string > : Specify color primaries [undef]
- undef, bt709, bt470m, bt470bg,
smpte170m, smpte240m, film, bt2020
--transfer < string > : Specify transfer characteristics [undef]
- undef, bt709, bt470m, bt470bg,
smpte170m, smpte240m, linear, log100,
log316, iec61966-2-4, bt1361e,
iec61966-2-1, bt2020-10, bt2020-12
--colormatrix < string > : Specify color matrix setting [undef]
- undef, bt709, fcc, bt470bg, smpte170m,
smpte240m, GBR, YCgCo, bt2020nc, bt2020c
--chromaloc < integer > : Specify chroma sample location (0 to 5) [0]
2016-02-05 14:16:18 +00:00
2016-10-26 23:45:24 +00:00
Deprecated parameters: (might be removed at some point)
2016-11-04 13:30:58 +00:00
-w, --width : Use --input-res
-h, --height : Use --input-res
2016-02-05 14:16:18 +00:00
```
[comment]: # (END KVAZAAR HELP MESSAGE)
2015-11-13 16:19:13 +00:00
2015-11-03 13:26:34 +00:00
2015-11-13 16:19:13 +00:00
### LP-GOP syntax
2016-11-04 15:22:24 +00:00
The LP-GOP syntax is "lp-g(num)d(num)t(num)", where
2015-11-13 16:19:13 +00:00
- g = GOP length.
- d = Number of GOP layers.
- t = How many references to skip for temporal scaling, where 4 means only
every fourth picture needs to be decoded.
2016-11-04 15:22:24 +00:00
```
QP
+4 o o o o
+3 o o o o o o
+2 o o o o ooooooo
+1 o o o o o o ooooooooo
g8d4t1 g8d3t1 g8d2t1 g8d1t1
```
2015-11-13 22:05:13 +00:00
2016-05-19 12:38:12 +00:00
## Presets
2016-02-05 12:53:25 +00:00
The names of the presets are the same as with x264: ultrafast,
superfast, veryfast, faster, fast, medium, slow, slower, veryslow and
placebo. The effects of the presets are listed in the following table,
where the names have been abbreviated to fit the layout in GitHub.
2015-11-03 13:26:34 +00:00
2017-03-30 10:19:05 +00:00
| | 0-uf | 1-sf | 2-vf | 3-fr | 4-f | 5-m | 6-s | 7-sr | 8-vs | 9-p |
| -------------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |
| rd | 0 | 0 | 0 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
| pu-depth-intra | 2-3 | 2-3 | 2-3 | 2-3 | 2-3 | 1-3 | 1-3 | 1-3 | 1-4 | 1-4 |
| pu-depth-inter | 2-3 | 2-3 | 2-3 | 1-3 | 1-3 | 1-3 | 1-3 | 0-3 | 0-3 | 0-3 |
| me | hexbs | hexbs | hexbs | hexbs | hexbs | hexbs | hexbs | hexbs | hexbs | tz |
| ref | 1 | 1 | 1 | 1 | 1 | 1 | 2 | 2 | 3 | 4 |
| deblock | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
| signhide | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 1 | 1 |
| subme | 0 | 0 | 2 | 2 | 4 | 4 | 4 | 4 | 4 | 4 |
| sao | 0 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
| rdoq | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 1 | 1 | 1 |
| rdoq-skip | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 0 |
| transform-skip | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
| mv-rdo | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
| full-intra-search | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| smp | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
| amp | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
| cu-split-termination | zero | zero | zero | zero | zero | zero | zero | zero | zero | off |
| me-early-termination | sens. | sens. | sens. | sens. | on | on | on | on | on | off |
2015-11-03 13:26:34 +00:00
2016-05-19 12:38:12 +00:00
## Kvazaar library
2015-10-27 09:04:00 +00:00
See [kvazaar.h ](src/kvazaar.h ) for the library API and its
documentation.
When using the static Kvazaar library on Windows, macro `KVZ_STATIC_LIB`
must be defined. On other platforms it's not strictly required.
The needed linker and compiler flags can be obtained with pkg-config.
2014-01-28 15:37:14 +00:00
2017-02-13 16:25:15 +00:00
## Compiling Kvazaar
2015-10-27 09:16:31 +00:00
If you have trouble regarding compiling the source code, please make an
[issue ](https://github.com/ultravideo/kvazaar/issues ) about in Github.
Others might encounter the same problem and there is probably much to
improve in the build process. We want to make this as simple as
possible.
2014-01-29 08:51:44 +00:00
2017-02-13 16:25:15 +00:00
2016-05-19 12:38:12 +00:00
### Required libraries
2015-10-27 09:16:31 +00:00
- For Visual Studio, the pthreads-w32 library is required. Platforms
with native POSIX thread support don't need anything.
- The project file expects the library to be in ../pthreads.2/
relative to Kvazaar. You can just extract the pre-built library
there.
- The executable needs pthreadVC2.dll to be present. Either install it
somewhere or ship it with the executable.
2014-01-29 08:51:44 +00:00
2016-05-19 12:04:25 +00:00
2017-02-13 16:25:15 +00:00
### Autotools
2016-05-19 12:04:25 +00:00
Depending on the platform, some additional tools are required for compiling Kvazaar with autotools.
2017-02-13 16:25:15 +00:00
For Ubuntu, the required packages are `automake autoconf libtool m4 build-essential yasm` . Yasm is
optional, but some of the optimization will not be compiled in if it's missing.
2016-05-19 12:04:25 +00:00
2015-12-21 13:52:28 +00:00
Run the following commands to compile and install Kvazaar.
2014-06-12 07:57:32 +00:00
2015-12-21 13:52:28 +00:00
./autogen.sh
./configure
make
sudo make install
2014-01-29 08:51:44 +00:00
2015-12-21 13:52:28 +00:00
See `./configure --help` for more options.
2014-01-29 08:51:44 +00:00
2017-02-13 16:25:15 +00:00
2016-05-19 12:38:12 +00:00
### OS X
2017-02-03 16:34:28 +00:00
- Install Homebrew
2017-02-13 16:25:15 +00:00
- run ```brew install automake libtool yasm```
2017-02-03 16:34:28 +00:00
- Refer to Autotools instructions
2014-06-12 07:57:32 +00:00
2017-02-13 16:25:15 +00:00
2016-05-19 12:38:12 +00:00
### Visual Studio
2017-02-13 16:25:15 +00:00
- At least VisualStudio 2013 is required.
2015-10-27 09:04:00 +00:00
- Project files can be found under build/.
2015-10-27 09:16:31 +00:00
- Requires external [vsyasm.exe ](http://yasm.tortall.net/Download.html )
in %PATH%
2014-01-28 15:37:14 +00:00
2016-05-20 11:35:42 +00:00
2017-02-13 16:25:15 +00:00
### Docker
2016-05-20 11:35:42 +00:00
This project includes a [Dockerfile ](./Dockerfile ), which enables building for Docker. Kvazaar is also available in the Docker Hub [`ultravideo/kvazaar` ](https://hub.docker.com/r/ultravideo/kvazaar/ )
Build using Docker: `docker build -t kvazaar .`
Example usage: `docker run -i -a STDIN -a STDOUT kvazaar -i - --input-res=320x240 -o - < testfile_320x240.yuv > out.265`
For other examples, see [Dockerfile ](./Dockerfile )
2016-05-20 11:58:54 +00:00
2017-02-13 16:25:15 +00:00
### Visualization (Windows only)
2016-05-20 11:58:54 +00:00
Branch `visualizer` has a visual studio project, which can be compiled to enable visualization feature in Kvazaar.
Additional Requirements: [`SDL2` ](https://www.libsdl.org/download-2.0.php ), [`SDL2-ttf` ](https://www.libsdl.org/projects/SDL_ttf/ ).
Directory `visualizer_extras` is expected to be found from the same directory level as the kvazaar project directory. Inside should be directories `include` and `lib` found from the development library zip packages.
2016-05-20 13:14:59 +00:00
`SDL2.dll` , `SDL2_ttf.dll` , `libfreetype-6.dll` , `zlib1.dll` , and `pthreadVC2.dll` should be placed in the working directory (i.e. the folder the `kvazaar.exe` is in after compiling the `kvazaar_cli` project/solution) when running the visualizer. The required `.dll` can be found in the aforementioned `lib` -folder (`lib\x64`) and the dll folder inside the pthreads folder (see `Required libraries` ).
Note: The solution should be compiled on the x64 platform in visual studio.
2016-05-20 11:58:54 +00:00
Optional font file `arial.ttf` is to be placed in the working directory, if block info tool is used.
2014-01-28 15:37:14 +00:00
2017-02-13 16:25:15 +00:00
## Contributing to Kvazaar
We are happy to look at pull requests in Github. There is still lots of work to be done.
2015-12-17 11:56:32 +00:00
2016-05-19 12:38:12 +00:00
### Code documentation
2015-12-17 11:56:32 +00:00
You can generate Doxygen documentation pages by running the command
2016-02-05 12:53:25 +00:00
"doxygen docs.doxy". Here is a rough sketch of the module structure:
2015-12-17 11:56:32 +00:00
2015-10-27 09:04:00 +00:00
2014-01-28 15:37:14 +00:00
2017-02-13 16:25:15 +00:00
### For version control we try to follow these conventions:
2015-10-27 09:16:31 +00:00
- Master branch always produces a working bitstream (can be decoded with
HM).
- Commits for new features and major changes/fixes put to a sensibly
named feature branch first and later merged to the master branch.
- Always merge the feature branch to the master branch, not the other
2017-02-13 16:25:15 +00:00
way around, with fast-forwarding disabled if necessary.
- Every commit should at least compile.
2014-01-28 15:37:14 +00:00
2016-05-19 12:38:12 +00:00
### Testing
2017-02-13 16:25:15 +00:00
- Main automatic way of testing is with Travis CI. Commits, branches
and pull requests are tested automatically.
- Uninitialized variables and such are checked with Valgrind.
- Bitstream validity is checked with HM.
- Compilation is checked on GCC and Clang on Linux, and Clang on OSX.
- Windows msys2 build is checked automatically on Appveyor.
- If your changes change the bitstream, decode with HM to check that
it doesn't throw checksum errors or asserts.
- If your changes shouldn't alter the bitstream, check that they don't.
- Automatic compression quality testing is in the works.
2014-01-28 15:37:14 +00:00
2016-05-19 12:38:12 +00:00
### Unit tests
2015-10-27 09:16:31 +00:00
- There are some unit tests located in the tests directory. We would
like to have more.
- The Visual Studio project links the unit tests against the actual .lib
file used by the encoder. There is no Makefile as of yet.
- The unit tests use "greatest" unit testing framework. It is included
as a submodule, but getting it requires the following commands to be
run in the root directory of kvazaar:
2014-01-31 14:37:05 +00:00
git submodule init
git submodule update
2017-02-13 16:25:15 +00:00
- On Linux, run ```make test```.
2014-01-28 15:37:14 +00:00
2017-02-13 16:25:15 +00:00
### Code style
2014-01-28 15:37:14 +00:00
We try to follow the following conventions:
2014-06-12 07:57:32 +00:00
- C99 without features not supported by Visual Studio 2013 (VLAs).
2014-01-28 15:37:14 +00:00
- // comments allowed and encouraged.
- Follow overall conventions already established in the code.
- Indent by 2 spaces. (no tabs)
- { on the same line for control logic and on the next line for functions
- Reference and deference next to the variable name.
- Variable names in lowered characters with words divided by underscore.
- Maximum line length 79 characters when possible.
2015-10-27 09:16:31 +00:00
- Functions only used inside the module shouldn't be defined in the
module header. They can be defined in the beginning of the .c file if
necessary.
2017-02-13 16:25:15 +00:00
- Symbols defined in headers prefixed with kvz_ or KVZ_.
- Includes in alphabetic order.
