1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
|
Kvazaar
=======
An open-source HEVC encoder licensed under 3-clause BSD
Join channel [#ultravideo](https://web.libera.chat/#ultravideo) in [Libera.Chat](https://libera.chat/) IRC network to contact us or come to our Discord [Discord](https://discord.gg/fZpub7BPUA)
Kvazaar is still under development. Speed and RD-quality will continue to improve.
http://ultravideo.fi/#encoder for more information.
- Linux [Kvazaar_tests](https://github.com/ultravideo/kvazaar/actions/workflows/kvazaar.yml)
- Windows [Build status](https://ci.appveyor.com/project/Ultravideo/kvazaar)
## 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)
- [Autotools on MinGW](#autotools-on-mingw)
- [OS X](#os-x)
- [Visual Studio](#visual-studio)
- [Docker](#docker)
- [Visualization (Windows only)](#visualization-windows-only)
- [Paper](#paper)
- [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)
## Using Kvazaar
### 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
[comment]: # "BEGIN KVAZAAR HELP MESSAGE"
```
Kvazaar v2.3.2 2025-09-16
Kvazaar license: 3-clause BSD
Usage:
kvazaar -i <input> --input-res <width>x<height> -o <output>
Required:
-i, --input <filename> : Input file
--input-res <res> : Input resolution [auto]
- auto: Detect from file name.
- <int>x<int>: width times height
-o, --output <filename> : Output file
Presets:
--preset <preset> : Set options to a preset [medium]
- ultrafast, superfast, veryfast, faster,
fast, medium, slow, slower, veryslow
placebo
Input:
-n, --frames <integer> : Number of frames to code [all]
--seek <integer> : First frame to code [0]
--input-fps <num>[/<denom>] : Frame rate of the input video [25]
--source-scan-type <string> : Source scan type [progressive]
- progressive: Progressive scan
- tff: Top field first
- bff: Bottom field first
--input-format <string> : P420 or P400 [P420]
--input-bitdepth <int> : 8-16 [8]
--loop-input : Re-read input file forever.
--input-file-format <string> : Input file format [auto]
- auto: Check the file ending for format
- y4m (skips frame headers)
- yuv
Options:
--help : Print this help message and exit.
--version : Print version information and exit.
--(no-)aud : Use access unit delimiters. [disabled]
--debug <filename> : Output internal reconstruction.
--(no-)cpuid : Enable runtime CPU optimizations. [enabled]
--hash <string> : Decoded picture hash [checksum]
- none: 0 bytes
- checksum: 18 bytes
- md5: 56 bytes
--(no-)psnr : Calculate PSNR for frames. [enabled]
--(no-)info : Add encoder info SEI. [enabled]
--(no-)enable-logging : Enable logging for regular encoder performance,
error messages are always disblayed. [enabled]
--crypto <string> : Selective encryption. Crypto support must be
enabled at compile-time. Can be 'on' or 'off' or
a list of features separated with a '+'. [off]
- on: Enable all encryption features.
- off: Disable selective encryption.
- mvs: Motion vector magnitudes.
- mv_signs: Motion vector signs.
- trans_coeffs: Coefficient magnitudes.
- trans_coeff_signs: Coefficient signs.
- intra_pred_modes: Intra prediction modes.
--key <string> : Encryption key [16,213,27,56,255,127,242,112,
97,126,197,204,25,59,38,30]
--stats-file-prefix : A prefix used for stats files that include
bits, lambda, distortion, and qp for each ctu.
These are meant for debugging and are not
written unless the prefix is defined.
Video structure:
-q, --qp <integer> : Quantization parameter [22]
-p, --period <integer> : Period of intra pictures [64]
- 0: Only first picture is intra.
- 1: All pictures are intra.
- N: Every Nth picture is intra.
--vps-period <integer> : 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> : Number of reference frames, in range 1..15 [4]
--gop <string> : GOP structure [16]
- 0: Disabled
- 8: B-frame pyramid of length 8
- 16: B-frame pyramid of length 16
- lp-<string>: Low-delay P/B-frame GOP
(e.g. lp-g8d4t2, see README)
--intra-qp-offset <int>: QP offset for intra frames [-51..51] [auto]
- N: Set QP offset to N.
- auto: Select offset automatically based
on GOP length.
--(no-)open-gop : Use open GOP configuration. [enabled]
--cqmfile <filename> : Read custom quantization matrices from a file.
--scaling-list <string>: Set scaling list mode. [off]
- off: Disable scaling lists.
- custom: use custom list (with --cqmfile).
- default: Use default lists.
--bitrate <integer> : Target bitrate [0]
- 0: Disable rate control.
- N: Target N bits per second.
--rc-algorithm <string>: Select used rc-algorithm. [lambda]
- lambda: rate control from:
DOI: 10.1109/TIP.2014.2336550
- oba: DOI: 10.1109/TCSVT.2016.2589878
--(no-)intra-bits : Use Hadamard cost based allocation for intra
frames. Default on for gop 8 and off for lp-gop
--(no-)clip-neighbour : On oba based rate control whether to clip
lambda values to same frame's ctus or previous'.
Default on for RA GOPS and disabled for LP.
--(no-)lossless : Use lossless coding. [disabled]
--mv-constraint <string> : Constrain movement vectors. [none]
- none: No constraint
- frametile: Constrain within the tile.
- frametilemargin: Constrain even more.
--roi <filename> : Use a delta QP map for region of interest.
Reads an array of delta QP values from a file.
Text and binary files are supported and detected
from the file extension (.txt/.bin). If a known
extension is not found, the file is treated as
a text file. The file can include one or many
ROI frames each in the following format:
width and height of the QP delta map followed
by width * height delta QP values in raster
order. In binary format, width and height are
32-bit integers whereas the delta QP values are
signed 8-bit values. The map can be of any size
and will be scaled to the video size. The file
reading will loop if end of the file is reached.
See roi.txt in the examples folder.
--set-qp-in-cu : Set QP at CU level keeping pic_init_qp_minus26.
in PPS and slice_qp_delta in slize header zero.
--(no-)erp-aqp : Use adaptive QP for 360 degree video with
equirectangular projection. [disabled]
--level <number> : Use the given HEVC level in the output and give
an error if level limits are exceeded. [6.2]
- 1, 2, 2.1, 3, 3.1, 4, 4.1, 5, 5.1, 5.2, 6,
6.1, 6.2
--force-level <number> : Same as --level but warnings instead of errors.
--high-tier : Used with --level. Use high tier bitrate limits
instead of the main tier limits during encoding.
High tier requires level 4 or higher.
--(no-)vaq <integer> : Enable variance adaptive quantization with given
strength, in range 1..20. Recommended: 5.
[disabled]
Compression tools:
--(no-)deblock <beta:tc> : Deblocking filter. [0:0]
- beta: Between -6 and 6
- tc: Between -6 and 6
--sao <string> : Sample Adaptive Offset [full]
- off: SAO disabled
- band: Band offset only
- edge: Edge offset only
- full: Full SAO
--(no-)rdoq : Rate-distortion optimized quantization [enabled]
--(no-)rdoq-skip : Skip RDOQ for 4x4 blocks. [disabled]
--(no-)signhide : Sign hiding [disabled]
--(no-)smp : Symmetric motion partition [disabled]
--(no-)amp : Asymmetric motion partition [disabled]
--rd <integer> : Mode search complexity [0]
- 0: Skip intra if inter is good enough.
- 1: Rough intra mode search with SATD.
- 2: Refine mode search with SSE.
- 3: More SSE candidates for inter and
chroma mode search for 4x4 intra.
- 4: Even more SSE candidates for both.
- 5: Try all intra modes.
--(no-)mv-rdo : Rate-distortion optimized motion vector costs
[disabled]
--(no-)zero-coeff-rdo : If a CU is set inter, check if forcing zero
residual improves the RD cost. [enabled]
--(no-)full-intra-search : Try all intra modes during rough search.
[disabled]
--(no-)intra-chroma-search : Test non-derived intra chroma modes.
[disabled]
--(no-)transform-skip : Try transform skip [disabled]
--me <string> : Integer motion estimation algorithm [hexbs]
- hexbs: Hexagon Based Search
- tz: Test Zone Search
- full: Full Search
- full8, full16, full32, full64
- dia: Diamond Search
--me-steps <integer> : Motion estimation search step limit. Only
affects 'hexbs' and 'dia'. [-1]
--subme <integer> : Fractional pixel motion estimation level [4]
- 0: Integer motion estimation only
- 1: + 1/2-pixel horizontal and vertical
- 2: + 1/2-pixel diagonal
- 3: + 1/4-pixel horizontal and vertical
- 4: + 1/4-pixel diagonal
--(no-)fast-bipred : Only perform fast bipred search. [enabled]
--pu-depth-inter <int>-<int> : Inter prediction units sizes [0-3]
- 0, 1, 2, 3: from 64x64 to 8x8
- Accepts a list of values separated by ','
for setting separate depths per GOP layer
(values can be omitted to use the first
value for the respective layer).
--pu-depth-intra <int>-<int> : Intra prediction units sizes [1-4]
- 0, 1, 2, 3, 4: from 64x64 to 4x4
- Accepts a list of values separated by ','
for setting separate depths per GOP layer
(values can be omitted to use the first
value for the respective layer).
--ml-pu-depth-intra : Predict the pu-depth-intra using machine
learning trees, overrides the
--pu-depth-intra parameter. [disabled]
--(no-)combine-intra-cus: Whether the encoder tries to code a cu
on lower depth even when search is not
performed on said depth. Should only
be disabled if cus absolutely must not
be larger than limited by the search.
[enabled]
--force-inter : Force the encoder to use inter always.
This is mostly for debugging and is not
guaranteed to produce sensible bitstream or
work at all. [disabled]
--tr-depth-intra <int> : Transform split depth for intra blocks [0]
--(no-)bipred : Bi-prediction [enabled]
--cu-split-termination <string> : CU split search termination [zero]
- off: Don't terminate early.
- zero: Terminate when residual is zero.
--me-early-termination <string> : Motion estimation termination [on]
- off: Don't terminate early.
- on: Terminate early.
- sensitive: Terminate even earlier.
--fast-residual-cost <int> : Skip CABAC cost for residual coefficients
when QP is below the limit. [0]
--fast-coeff-table <string> : Read custom weights for residual
coefficients from a file instead of using
defaults [default]
--fast-rd-sampling : Enable learning data sampling for fast coefficient
table generation
--fastrd-accuracy-check : Evaluate the accuracy of fast coefficient
prediction
--fastrd-outdir : Directory to which to output sampled data or accuracy
data, into <fastrd-outdir>/0.txt to 50.txt, one file
for each QP that blocks were estimated on
--(no-)intra-rdo-et : Check intra modes in rdo stage only until
a zero coefficient CU is found. [disabled]
--(no-)early-skip : Try to find skip cu from merge candidates.
Perform no further search if skip is found.
For rd=0..1: Try the first candidate.
For rd=2.. : Try the best candidate based
on luma satd cost. [enabled]
--max-merge <integer> : Maximum number of merge candidates, 1..5 [5]
--(no-)implicit-rdpcm : Implicit residual DPCM. Currently only supported
with lossless coding. [disabled]
--(no-)tmvp : Temporal motion vector prediction [enabled]
Parallel processing:
--threads <integer> : Number of threads to use [auto]
- 0: Process everything with main thread.
- N: Use N threads for encoding.
- auto: Select automatically.
--owf <integer> : Frame-level 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. Enabling wpp with tiles is,
however, an experimental feature since it is
not supported in any HEVC profile.
--tiles <int>x<int> : Split picture into width x height uniform tiles.
--tiles-width-split <string>|u<int> :
- <string>: A comma-separated list of tile
column pixel coordinates.
- u<int>: Number of tile columns of uniform
width.
--tiles-height-split <string>|u<int> :
- <string>: A comma-separated list of tile
row column pixel coordinates.
- u<int>: Number of tile rows of uniform
height.
--slices <string> : Control how slices are used.
- tiles: Put tiles in independent slices.
- wpp: Put rows in dependent slices.
- tiles+wpp: Do both.
--partial-coding <x-offset>!<y-offset>!<slice-width>!<slice-height>
: Encode partial frame.
Parts must be merged to form a valid bitstream.
X and Y are CTU offsets.
Slice width and height must be divisible by CTU
in pixels unless it is the last CTU row/column.
This parameter is used by kvaShare.
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]
- undef, component, pal, ntsc, secam, mac
--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]
Deprecated parameters: (might be removed at some point)
-w, --width <integer> : Use --input-res.
-h, --height <integer> : Use --input-res.
```
[comment]: # "END KVAZAAR HELP MESSAGE"
### LP-GOP syntax
The LP-GOP syntax is "lp-g(num)d(num)t(num)", where
- 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.
```
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
```
## Presets
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.
| | 0-uf | 1-sf | 2-vf | 3-fr | 4-f | 5-m | 6-s | 7-sr | 8-vs | 9-p |
| -------------------- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |
| rd | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 2 | 3 | 3 |
| pu-depth-intra | 2-3 | 2-3 | 2-3 | 2-3 | 1-3 | 1-4 | 1-4 | 1-4 | 1-4 | 1-4 |
| pu-depth-inter | 1-2 | 1-2 | 1-3 | 1-3 | 1-3 | 0-3 | 0-3 | 0-3 | 0-3 | 0-3 |
| me | hexbs | hexbs | hexbs | hexbs | hexbs | hexbs | hexbs | hexbs | tz | tz |
| gop | 8 | 8 | 8 | 8 | 8 | 16 | 16 | 16 | 16 | 16 |
| ref | 1 | 1 | 1 | 1 | 2 | 4 | 4 | 4 | 4 | 4 |
| bipred | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
| deblock | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
| signhide | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 1 |
| subme | 0 | 2 | 2 | 4 | 4 | 4 | 4 | 4 | 4 | 4 |
| sao | off | full | full | full | full | full | full | full | full | full |
| rdoq | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 1 | 1 | 1 |
| rdoq-skip | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| transform-skip | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 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 | 1 | 1 |
| amp | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 |
| cu-split-termination | zero | zero | zero | zero | zero | zero | zero | zero | zero | off |
| me-early-termination | sens. | sens. | sens. | sens. | sens. | on | on | off | off | off |
| intra-rdo-et | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| early-skip | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 0 |
| fast-residual-cost | 28 | 28 | 28 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| max-merge | 5 | 5 | 5 | 5 | 5 | 5 | 5 | 5 | 5 | 5 |
## Kvazaar library
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.
## Compiling Kvazaar
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.
### Autotools
Depending on the platform, some additional tools are required for compiling Kvazaar with autotools.
For Ubuntu, the required packages are `automake autoconf libtool m4 build-essential`.
Run the following commands to compile and install Kvazaar.
./autogen.sh
./configure
make
sudo make install
sudo ldconfig
See `./configure --help` for more options.
**When building shared library with visual studio the tests will fail to link, the main binary will still work**
### Autotools on MinGW
It is recommended to use Clang instead of GCC in MinGW environments. GCC also works, but AVX2 optimizations will be disabled because of a known GCC issue from 2012, so performance will suffer badly. Instead of `./configure`, run
CC=clang ./configure
to build Kvazaar using Clang.
### CMake
Depending on the platform, some additional tools are required for compiling Kvazaar with CMake.
For Ubuntu, the required packages are `build-essential cmake`.
### OS X
- Install Homebrew
- run ```brew install automake libtool yasm```
- Refer to Autotools instructions
### Visual Studio
- At least VisualStudio 2015.2 is required.
- Project files can be found under build/.
- Requires external [vsyasm.exe](http://yasm.tortall.net/Download.html)
in %PATH%
### Docker
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)
### Visualization (Windows only)
Compiling `kvazaar_cli` project in the `visualizer` branch results in a Kvazaar executable with visualization enabled.
Additional Requirements: [`SDL2`](https://www.libsdl.org/download-2.0.php), [`SDL2-ttf`](https://www.libsdl.org/projects/SDL_ttf/).
Directory `visualizer_extras` has to be added into the same directory level as the kvazaar project directory. Inside should be directories `include` and `lib` found from the development library zip packages.
`SDL2.dll`, `SDL2_ttf.dll`, `libfreetype-6.dll`, and `zlib1.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`).
Note: The solution should be compiled on the x64 platform in visual studio.
Optional font file `arial.ttf` is to be placed in the working directory, if block info tool is used.
## Paper
Please cite [this paper](https://dl.acm.org/citation.cfm?doid=2964284.2973796) for Kvazaar:
```M. Viitanen, A. Koivula, A. Lemmetti, A. Yl�-Outinen, J. Vanne, and T. D. H�m�l�inen, �Kvazaar: open-source HEVC/H.265 encoder,� in Proc. ACM Int. Conf. Multimedia, Amsterdam, The Netherlands, Oct. 2016.```
Or in BibTex:
```
@inproceedings{Kvazaar2016,
author = {Viitanen, Marko and Koivula, Ari and Lemmetti, Ari and Yl\"{a}-Outinen, Arttu and Vanne, Jarno and H\"{a}m\"{a}l\"{a}inen, Timo D.},
title = {Kvazaar: Open-Source HEVC/H.265 Encoder},
booktitle = {Proceedings of the 24th ACM International Conference on Multimedia},
year = {2016},
isbn = {978-1-4503-3603-1},
location = {Amsterdam, The Netherlands},
url = {http://doi.acm.org/10.1145/2964284.2973796},
}
```
## Contributing to Kvazaar
We are happy to look at pull requests in Github. There is still lots of work to be done.
### Code documentation
You can generate Doxygen documentation pages by running the command
"doxygen docs.doxy". Here is a rough sketch of the module structure:
### For version control we try to follow these conventions:
- 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.
- Every commit should at least compile.
### Testing
- 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 VTM.
- Compilation is checked on GCC and Clang on Linux, and Clang on OSX.
- Windows msys2 and msvc builds are 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.
### 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
- On Linux, run ```make test```.
### Code style
We try to follow the following conventions:
- C99 without features not supported by Visual Studio 2015 (VLAs).
- // 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.
- Symbols defined in headers prefixed with kvz_ or KVZ_.
- Includes in alphabetic order.
|
