2014-01-28 15:37:14 +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
2014-01-29 08:51:44 +00:00
Kvazaar is not yet finished and does not implement all the features of HEVC. Compression performance will increase as we add more coding tools.
http://ultravideo.cs.tut.fi/#encoder for more information.
2014-02-17 13:14:42 +00:00
http://github.com/ultravideo/kvazaar/wiki/List-of-suggested-topics for a list of topics you might want to examine if you would like to do something bigger than a bug fix but don't know what yet.
2014-10-29 14:09:32 +00:00
[](https://travis-ci.org/ultravideo/kvazaar)
2014-01-29 08:51:44 +00:00
##Using Kvazaar
2014-01-28 15:37:14 +00:00
2014-02-11 14:33:50 +00:00
Usage:
2014-03-12 13:18:50 +00:00
kvazaar -i < input > --input-res < width > x< height > -o < output >
2014-02-11 14:33:50 +00:00
Optional parameters:
2014-03-10 12:58:57 +00:00
-n, --frames < integer > : Number of frames to code [all]
2014-06-04 12:23:27 +00:00
--seek < integer > : First frame to code [0]
--input-res < int > x< int > : Input resolution (width x height)
2014-02-11 14:33:50 +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
2015-02-18 11:41:03 +00:00
--vps-period < integer > : Specify how often the video parameter set is
re-sent. [0]
0: only send VPS with the first frame
1: send VPS with every intra frame
N: send VPS with every Nth intra frame
2014-02-20 09:02:51 +00:00
-r, --ref < integer > : Reference frames, range 1..15 [3]
2014-02-11 14:33:50 +00:00
--no-deblock : Disable deblocking filter
--deblock < beta:tc > : Deblocking filter parameters
beta and tc range is -6..6 [0:0]
--no-sao : Disable sample adaptive offset
2014-04-02 11:41:40 +00:00
--no-rdoq : Disable RDO quantization
2015-01-24 18:10:21 +00:00
--no-signhide : Disable sign hiding in quantization
2014-06-04 12:23:27 +00:00
--rd < integer > : Rate-Distortion Optimization level [1]
0: no RDO
1: estimated RDO
2: full RDO
2014-06-17 12:32:05 +00:00
--full-intra-search : Try all intra modes.
2014-04-02 11:41:40 +00:00
--no-transform-skip : Disable transform skip
2014-02-11 14:33:50 +00:00
--aud : Use access unit delimiters
config: Add --cqmfile to use custom quantization matrices from a file.
The coefficients in a matrix are stored in up-right diagonal order.
The following indicates the default matrices specified in the spec.
INTRA4X4_LUMA
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16
INTRA4X4_CHROMAU
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16
INTRA4X4_CHROMAV
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16
INTER4X4_LUMA
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16
INTER4X4_CHROMAU
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16
INTER4X4_CHROMAV
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16,
16, 16, 16, 16
INTRA8X8_LUMA
16, 16, 16, 16, 17, 18, 21, 24,
16, 16, 16, 16, 17, 19, 22, 25,
16, 16, 17, 18, 20, 22, 25, 29,
16, 16, 18, 21, 24, 27, 31, 36,
17, 17, 20, 24, 30, 35, 41, 47,
18, 19, 22, 27, 35, 44, 54, 65,
21, 22, 25, 31, 41, 54, 70, 88,
24, 25, 29, 36, 47, 65, 88, 115
INTRA8X8_CHROMAU
16, 16, 16, 16, 17, 18, 21, 24,
16, 16, 16, 16, 17, 19, 22, 25,
16, 16, 17, 18, 20, 22, 25, 29,
16, 16, 18, 21, 24, 27, 31, 36,
17, 17, 20, 24, 30, 35, 41, 47,
18, 19, 22, 27, 35, 44, 54, 65,
21, 22, 25, 31, 41, 54, 70, 88,
24, 25, 29, 36, 47, 65, 88, 115
INTRA8X8_CHROMAV
16, 16, 16, 16, 17, 18, 21, 24,
16, 16, 16, 16, 17, 19, 22, 25,
16, 16, 17, 18, 20, 22, 25, 29,
16, 16, 18, 21, 24, 27, 31, 36,
17, 17, 20, 24, 30, 35, 41, 47,
18, 19, 22, 27, 35, 44, 54, 65,
21, 22, 25, 31, 41, 54, 70, 88,
24, 25, 29, 36, 47, 65, 88, 115
INTER8X8_LUMA
16, 16, 16, 16, 17, 18, 20, 24,
16, 16, 16, 17, 18, 20, 24, 25,
16, 16, 17, 18, 20, 24, 25, 28,
16, 17, 18, 20, 24, 25, 28, 33,
17, 18, 20, 24, 25, 28, 33, 41,
18, 20, 24, 25, 28, 33, 41, 54,
20, 24, 25, 28, 33, 41, 54, 71,
24, 25, 28, 33, 41, 54, 71, 91
INTER8X8_CHROMAU
16, 16, 16, 16, 17, 18, 20, 24,
16, 16, 16, 17, 18, 20, 24, 25,
16, 16, 17, 18, 20, 24, 25, 28,
16, 17, 18, 20, 24, 25, 28, 33,
17, 18, 20, 24, 25, 28, 33, 41,
18, 20, 24, 25, 28, 33, 41, 54,
20, 24, 25, 28, 33, 41, 54, 71,
24, 25, 28, 33, 41, 54, 71, 91
INTER8X8_CHROMAV
16, 16, 16, 16, 17, 18, 20, 24,
16, 16, 16, 17, 18, 20, 24, 25,
16, 16, 17, 18, 20, 24, 25, 28,
16, 17, 18, 20, 24, 25, 28, 33,
17, 18, 20, 24, 25, 28, 33, 41,
18, 20, 24, 25, 28, 33, 41, 54,
20, 24, 25, 28, 33, 41, 54, 71,
24, 25, 28, 33, 41, 54, 71, 91
INTRA16X16_LUMA
16, 16, 16, 16, 17, 18, 21, 24,
16, 16, 16, 16, 17, 19, 22, 25,
16, 16, 17, 18, 20, 22, 25, 29,
16, 16, 18, 21, 24, 27, 31, 36,
17, 17, 20, 24, 30, 35, 41, 47,
18, 19, 22, 27, 35, 44, 54, 65,
21, 22, 25, 31, 41, 54, 70, 88,
24, 25, 29, 36, 47, 65, 88, 115
INTRA16X16_CHROMAU
16, 16, 16, 16, 17, 18, 21, 24,
16, 16, 16, 16, 17, 19, 22, 25,
16, 16, 17, 18, 20, 22, 25, 29,
16, 16, 18, 21, 24, 27, 31, 36,
17, 17, 20, 24, 30, 35, 41, 47,
18, 19, 22, 27, 35, 44, 54, 65,
21, 22, 25, 31, 41, 54, 70, 88,
24, 25, 29, 36, 47, 65, 88, 115
INTRA16X16_CHROMAV
16, 16, 16, 16, 17, 18, 21, 24,
16, 16, 16, 16, 17, 19, 22, 25,
16, 16, 17, 18, 20, 22, 25, 29,
16, 16, 18, 21, 24, 27, 31, 36,
17, 17, 20, 24, 30, 35, 41, 47,
18, 19, 22, 27, 35, 44, 54, 65,
21, 22, 25, 31, 41, 54, 70, 88,
24, 25, 29, 36, 47, 65, 88, 115
INTER16X16_LUMA
16, 16, 16, 16, 17, 18, 20, 24,
16, 16, 16, 17, 18, 20, 24, 25,
16, 16, 17, 18, 20, 24, 25, 28,
16, 17, 18, 20, 24, 25, 28, 33,
17, 18, 20, 24, 25, 28, 33, 41,
18, 20, 24, 25, 28, 33, 41, 54,
20, 24, 25, 28, 33, 41, 54, 71,
24, 25, 28, 33, 41, 54, 71, 91
INTER16X16_CHROMAU
16, 16, 16, 16, 17, 18, 20, 24,
16, 16, 16, 17, 18, 20, 24, 25,
16, 16, 17, 18, 20, 24, 25, 28,
16, 17, 18, 20, 24, 25, 28, 33,
17, 18, 20, 24, 25, 28, 33, 41,
18, 20, 24, 25, 28, 33, 41, 54,
20, 24, 25, 28, 33, 41, 54, 71,
24, 25, 28, 33, 41, 54, 71, 91
INTER16X16_CHROMAV
16, 16, 16, 16, 17, 18, 20, 24,
16, 16, 16, 17, 18, 20, 24, 25,
16, 16, 17, 18, 20, 24, 25, 28,
16, 17, 18, 20, 24, 25, 28, 33,
17, 18, 20, 24, 25, 28, 33, 41,
18, 20, 24, 25, 28, 33, 41, 54,
20, 24, 25, 28, 33, 41, 54, 71,
24, 25, 28, 33, 41, 54, 71, 91
INTRA32X32_LUMA
16, 16, 16, 16, 17, 18, 21, 24,
16, 16, 16, 16, 17, 19, 22, 25,
16, 16, 17, 18, 20, 22, 25, 29,
16, 16, 18, 21, 24, 27, 31, 36,
17, 17, 20, 24, 30, 35, 41, 47,
18, 19, 22, 27, 35, 44, 54, 65,
21, 22, 25, 31, 41, 54, 70, 88,
24, 25, 29, 36, 47, 65, 88, 115
INTER32X32_LUMA
16, 16, 16, 16, 17, 18, 20, 24,
16, 16, 16, 17, 18, 20, 24, 25,
16, 16, 17, 18, 20, 24, 25, 28,
16, 17, 18, 20, 24, 25, 28, 33,
17, 18, 20, 24, 25, 28, 33, 41,
18, 20, 24, 25, 28, 33, 41, 54,
20, 24, 25, 28, 33, 41, 54, 71,
24, 25, 28, 33, 41, 54, 71, 91
INTRA16X16_LUMA_DC
16
INTRA16X16_CHROMAU_DC
16
INTRA16X16_CHROMAV_DC
16
INTER16X16_LUMA_DC
16
INTER16X16_CHROMAU_DC
16
INTER16X16_CHROMAV_DC
16
INTRA32X32_LUMA_DC
16
INTER32X32_LUMA_DC
16
2014-02-11 10:55:21 +00:00
--cqmfile < string > : Custom Quantization Matrices from a file
2014-03-12 15:58:43 +00:00
--debug < string > : Output encoders reconstruction.
2014-12-03 09:52:42 +00:00
--cpuid < integer > : Disable runtime cpu optimizations with value 0.
2015-03-19 16:48:10 +00:00
--me < string > : Set integer motion estimation algorithm ["hexbs"]
"hexbs": Hexagon Based Search (faster)
"tz": Test Zone Search (better quality)
2014-12-03 09:52:42 +00:00
--subme < integer > : Set fractional pixel motion estimation level [1].
0: only integer motion estimation
1: fractional pixel motion estimation enabled
2015-01-12 08:59:28 +00:00
--pu-depth-inter < int > -< int > : Range for sizes of inter prediction units to try.
0: 64x64, 1: 32x32, 2: 16x16, 3: 8x8
--pu-depth-intra < int > -< int > : Range for sizes of intra prediction units to try.
0: 64x64, 1: 32x32, 2: 16x16, 3: 8x8, 4: 4x4
2015-03-30 06:54:22 +00:00
--gop < int > : Length of Group of Pictures, must be 8 or 0 [0]
2014-02-11 14:33:50 +00:00
Video Usability Information:
--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]
2015-01-12 08:59:28 +00:00
2014-06-04 12:23:27 +00:00
Parallel processing:
--threads < integer > : Maximum number of threads to use.
Disable threads if set to 0.
2015-01-12 08:59:28 +00:00
2014-06-04 12:23:27 +00:00
Tiles:
2015-01-12 08:59:28 +00:00
--tiles-width-split < string > |u< int > :
2014-06-04 12:23:27 +00:00
Specifies a comma separated list of pixel
positions of tiles columns separation coordinates.
Can also be u followed by and a single int n,
in which case it produces columns of uniform width.
2015-01-12 08:59:28 +00:00
--tiles-height-split < string > |u< int > :
2014-06-04 12:23:27 +00:00
Specifies a comma separated list of pixel
positions of tiles rows separation coordinates.
Can also be u followed by and a single int n,
in which case it produces rows of uniform height.
Wpp:
2015-01-12 08:59:28 +00:00
--wpp : Enable wavefront parallel processing
2014-12-03 09:52:42 +00:00
--owf < integer > |auto : Number of parallel frames to process. 0 to disable.
2014-06-04 12:23:27 +00:00
Slices:
--slice-addresses < string > |u< int > :
Specifies a comma separated list of LCU
positions in tile scan order of tile separations.
Can also be u followed by and a single int n,
in which case it produces uniform slice length.
Deprecated parameters: (might be removed at some point)
Use --input-res:
-w, --width : Width of input in pixels
-h, --height : Height of input in pixels
2014-02-05 17:16:44 +00:00
Example:
2014-03-12 13:18:50 +00:00
kvazaar -i < INPUT_YUV > --input-res < WIDTH > x< HEIGHT > -o < OUTPUT.BIN > -n < NUMBER_OF_FRAMES > -q < QP >
2014-01-28 15:37:14 +00:00
2014-03-12 13:18:50 +00:00
eg. `kvazaar -i BQMall_832x480_60.yuv --input-res 832x480 -o out.bin -n 600 -q 32`
2014-01-28 15:37:14 +00:00
2014-01-29 08:51:44 +00:00
The only accepted input format so far is 8-bit YUV 4:2:0.
2014-01-28 15:37:14 +00:00
##Compiling Kvazaar
2014-01-29 08:51:44 +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-06-12 07:57:32 +00:00
###Required libraries
- For Visual Studio 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
###Visual Studio 2010
2014-06-12 07:57:32 +00:00
- VS2010 and older does not have support for some of the c99 features that we use. Please use VS2013 or newer or GCC (MinGW) to compile on windows.
###Visual Studio 2013
2014-01-29 08:51:44 +00:00
- project files included
- requires external [vsyasm.exe ](http://yasm.tortall.net/Download.html ) in %PATH%
- run `rundll32 sysdm.cpl,EditEnvironmentVariables` and add PATH to user variables
2014-06-12 07:57:32 +00:00
###GCC
2014-01-29 08:51:44 +00:00
- Simple Makefile included in src/
- Yasm is expected to be in PATH
2014-06-12 07:57:32 +00:00
###OS X
- The program should compile and work on OS X but you might need a newer version of GCC than what comes with the platform.
2014-01-29 08:51:44 +00:00
###Other
2014-06-12 07:57:32 +00:00
- There is a scons SConstruct file that should work on both Windows and Linux.
2014-01-29 08:51:44 +00:00
- Contact us for support or write an [issue in Github ](https://github.com/ultravideo/kvazaar/issues )
2014-01-28 15:37:14 +00:00
##Contributing to Kvazaar
2014-02-21 10:37:09 +00:00
###For version control we try to follow these conventions:
2014-01-28 15:37:14 +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 way around, with fast-forwarding disabled if necessary. We have found that this differentiates between working and unfinished versions nicely.
- Every commit should at least compile. Producing a working bitstream is nice as well, but not always possible. Features may be temporarily disabled to produce a working bitstream, but remember to re-enbable them before merging to master.
###Testing:
- We do not have a proper testing framework yet. We test mainly by decoding the bitstream with HM and checking that the result matches the encoders own reconstruction.
2014-06-12 07:57:32 +00:00
- You should at least test that HM decodes a bitstream file made with your changes without throwing checksum errors. If your changes shouldn't alter the bitstream, you should check that they don't.
2014-01-28 15:37:14 +00:00
- We would like to have a suite of automatic tests that also check for BD-rate increase and speed decrease in addition to checking that the bitstream is valid. As of yet there is no such suite.
2014-01-31 14:37:05 +00:00
###Unit tests:
- 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:
git submodule init
git submodule update
2014-01-28 15:37:14 +00:00
###Code style:
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.
- 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.
2014-06-12 07:57:32 +00:00
###Resources for HEVC bitstream features:
2014-01-28 15:37:14 +00:00
2014-06-12 07:57:32 +00:00
- A good first resource for HEVC bitstream is JCTVC-N1002 High Efficiency Video Coding (HEVC) Test Model 12 (HM12) Encoder Description
2014-01-28 15:37:14 +00:00
- Many good articles regarding specific parts of HEVC can be found on IEEE Transactions on Circuits and Systems for Video Technology, Combined issue on High Efficiency Video Coding (HEVC) Standards and Research
2014-06-12 07:57:32 +00:00
- The specification tends to follow the reference implementation, not the other way around, so check HM if the specification is unclear.
