Imported Upstream version 1.4+222+hg5f9f7194267b
[deb_x265.git] / doc / reST / cli.rst
... / ...
CommitLineData
1*********************
2Command Line Options
3*********************
4
5.. _string-options-ref:
6
7Note that unless an option is listed as **CLI ONLY** the option is also
8supported by x265_param_parse(). The CLI uses getopt to parse the
9command line options so the short or long versions may be used and the
10long options may be truncated to the shortest unambiguous abbreviation.
11Users of the API must pass x265_param_parse() the full option name.
12
13Preset and tune have special implications. The API user must call
14x265_param_default_preset() with the preset and tune parameters they
15wish to use, prior to calling x265_param_parse() to set any additional
16fields. The CLI does this for the user implicitly, so all CLI options
17are applied after the user's preset and tune choices, regardless of the
18order of the arguments on the command line.
19
20If there is an extra command line argument (not an option or an option
21value) the CLI will treat it as the input filename. This effectively
22makes the :option:`--input` specifier optional for the input file. If
23there are two extra arguments, the second is treated as the output
24bitstream filename, making :option:`--output` also optional if the input
25filename was implied. This makes :command:`x265 in.y4m out.hevc` a valid
26command line. If there are more than two extra arguments, the CLI will
27consider this an error and abort.
28
29Generally, when an option expects a string value from a list of strings
30the user may specify the integer ordinal of the value they desire. ie:
31:option:`--log-level` 3 is equivalent to :option:`--log-level` debug.
32
33Executable Options
34==================
35
36.. option:: --help, -h
37
38 Display help text
39
40 **CLI ONLY**
41
42.. option:: --version, -V
43
44 Display version details
45
46 **CLI ONLY**
47
48Logging/Statistic Options
49=========================
50
51.. option:: --log-level <integer|string>
52
53 Logging level. Debug level enables per-frame QP, metric, and bitrate
54 logging. If a CSV file is being generated, debug level makes the log
55 be per-frame rather than per-encode. Full level enables hash and
56 weight logging. -1 disables all logging, except certain fatal
57 errors, and can be specified by the string "none".
58
59 0. error
60 1. warning
61 2. info **(default)**
62 3. debug
63 4. full
64
65.. option:: --no-progress
66
67 Disable periodic progress reports from the CLI
68
69 **CLI ONLY**
70
71.. option:: --csv <filename>
72
73 Writes encoding results to a comma separated value log file. Creates
74 the file if it doesnt already exist, else adds one line per run. if
75 :option:`--log-level` is debug or above, it writes one line per
76 frame. Default none
77
78.. option:: --cu-stats, --no-cu-stats
79
80 Records statistics on how each CU was coded (split depths and other
81 mode decisions) and reports those statistics at the end of the
82 encode. Default disabled
83
84.. option:: --ssim, --no-ssim
85
86 Calculate and report Structural Similarity values. It is
87 recommended to use :option:`--tune` ssim if you are measuring ssim,
88 else the results should not be used for comparison purposes.
89 Default disabled
90
91.. option:: --psnr, --no-psnr
92
93 Calculate and report Peak Signal to Noise Ratio. It is recommended
94 to use :option:`--tune` psnr if you are measuring PSNR, else the
95 results should not be used for comparison purposes. Default
96 disabled
97
98Performance Options
99===================
100
101.. option:: --asm <integer:false:string>, --no-asm
102
103 x265 will use all detected CPU SIMD architectures by default. You can
104 disable all assembly by using :option:`--no-asm` or you can specify
105 a comma separated list of SIMD architectures to use, matching these
106 strings: MMX2, SSE, SSE2, SSE3, SSSE3, SSE4, SSE4.1, SSE4.2, AVX, XOP, FMA4, AVX2, FMA3
107
108 Some higher architectures imply lower ones being present, this is
109 handled implicitly.
110
111 One may also directly supply the CPU capability bitmap as an integer.
112
113.. option:: --frame-threads, -F <integer>
114
115 Number of concurrently encoded frames. Using a single frame thread
116 gives a slight improvement in compression, since the entire reference
117 frames are always available for motion compensation, but it has
118 severe performance implications. Default is an autodetected count
119 based on the number of CPU cores and whether WPP is enabled or not.
120
121 Over-allocation of frame threads will not improve performance, it
122 will generally just increase memory use.
123
124.. option:: --threads <integer>
125
126 Number of threads to allocate for the worker thread pool This pool
127 is used for WPP and for distributed analysis and motion search:
128 :option:`--wpp` :option:`--pmode` and :option:`--pme` respectively.
129
130 If :option:`--threads` 1 is specified, then no thread pool is
131 created. When no thread pool is created, all the thread pool
132 features are implicitly disabled. If all the pool features are
133 disabled by the user, then the pool is implicitly disabled.
134
135 Default 0, one thread is allocated per detected hardware thread
136 (logical CPU cores)
137
138.. option:: --wpp, --no-wpp
139
140 Enable Wavefront Parallel Processing. The encoder may begin encoding
141 a row as soon as the row above it is at least two CTUs ahead in the
142 encode process. This gives a 3-5x gain in parallelism for about 1%
143 overhead in compression efficiency.
144
145 This feature is implicitly disabled when no thread pool is present.
146
147 Default: Enabled
148
149.. option:: --pmode, --no-pmode
150
151 Parallel mode decision, or distributed mode analysis. When enabled
152 the encoder will distribute the analysis work of each CU (merge,
153 inter, intra) across multiple worker threads. Only recommended if
154 x265 is not already saturating the CPU cores. In RD levels 3 and 4
155 it will be most effective if --rect is enabled. At RD levels 5 and
156 6 there is generally always enough work to distribute to warrant the
157 overhead, assuming your CPUs are not already saturated.
158
159 --pmode will increase utilization without reducing compression
160 efficiency. In fact, since the modes are all measured in parallel it
161 makes certain early-outs impractical and thus you usually get
162 slightly better compression when it is enabled (at the expense of
163 not skipping improbable modes). This bypassing of early-outs can
164 cause pmode to slow down encodes, especially at faster presets.
165
166 This feature is implicitly disabled when no thread pool is present.
167
168 Default disabled
169
170.. option:: --pme, --no-pme
171
172 Parallel motion estimation. When enabled the encoder will distribute
173 motion estimation across multiple worker threads when more than two
174 references require motion searches for a given CU. Only recommended
175 if x265 is not already saturating CPU cores. :option:`--pmode` is
176 much more effective than this option, since the amount of work it
177 distributes is substantially higher. With --pme it is not unusual
178 for the overhead of distributing the work to outweigh the
179 parallelism benefits.
180
181 This feature is implicitly disabled when no thread pool is present.
182
183 --pme will increase utilization on many core systems with no effect
184 on the output bitstream.
185
186 Default disabled
187
188.. option:: --preset, -p <integer|string>
189
190 Sets parameters to preselected values, trading off compression efficiency against
191 encoding speed. These parameters are applied before all other input parameters are
192 applied, and so you can override any parameters that these values control. See
193 :ref:`presets <presets>` for more detail.
194
195 0. ultrafast
196 1. superfast
197 2. veryfast
198 3. faster
199 4. fast
200 5. medium **(default)**
201 6. slow
202 7. slower
203 8. veryslow
204 9. placebo
205
206.. option:: --tune, -t <string>
207
208 Tune the settings for a particular type of source or situation. The changes will
209 be applied after :option:`--preset` but before all other parameters. Default none.
210 See :ref:`tunings <tunings>` for more detail.
211
212 **Values:** psnr, ssim, grain, zero-latency, fast-decode, cbr.
213
214Input/Output File Options
215=========================
216
217These options all describe the input video sequence or, in the case of
218:option:`--dither`, operations that are performed on the sequence prior
219to encode. All options dealing with files (names, formats, offsets or
220frame counts) are only applicable to the CLI application.
221
222.. option:: --input <filename>
223
224 Input filename, only raw YUV or Y4M supported. Use single dash for
225 stdin. This option name will be implied for the first "extra"
226 command line argument.
227
228 **CLI ONLY**
229
230.. option:: --y4m
231
232 Parse input stream as YUV4MPEG2 regardless of file extension,
233 primarily intended for use with stdin (ie: :option:`--input` -
234 :option:`--y4m`). This option is implied if the input filename has
235 a ".y4m" extension
236
237 **CLI ONLY**
238
239.. option:: --input-depth <integer>
240
241 YUV only: Bit-depth of input file or stream
242
243 **Values:** any value between 8 and 16. Default is internal depth.
244
245 **CLI ONLY**
246
247.. option:: --dither
248
249 Enable high quality downscaling. Dithering is based on the diffusion
250 of errors from one row of pixels to the next row of pixels in a
251 picture. Only applicable when the input bit depth is larger than
252 8bits and internal bit depth is 8bits. Default disabled
253
254 **CLI ONLY**
255
256.. option:: --input-res <wxh>
257
258 YUV only: Source picture size [w x h]
259
260 **CLI ONLY**
261
262.. option:: --input-csp <integer|string>
263
264 YUV only: Source color space. Only i420, i422, and i444 are
265 supported at this time. The internal color space is always the
266 same as the source color space (libx265 does not support any color
267 space conversions).
268
269 0. i400
270 1. i420 **(default)**
271 2. i422
272 3. i444
273 4. nv12
274 5. nv16
275
276.. option:: --fps <integer|float|numerator/denominator>
277
278 YUV only: Source frame rate
279
280 **Range of values:** positive int or float, or num/denom
281
282.. option:: --interlaceMode <false|tff|bff>, --no-interlaceMode
283
284 0. progressive pictures **(default)**
285 1. top field first
286 2. bottom field first
287
288 HEVC encodes interlaced content as fields. Fields must be provided to
289 the encoder in the correct temporal order. The source dimensions
290 must be field dimensions and the FPS must be in units of fields per
291 second. The decoder must re-combine the fields in their correct
292 orientation for display.
293
294.. option:: --seek <integer>
295
296 Number of frames to skip at start of input file. Default 0
297
298 **CLI ONLY**
299
300.. option:: --frames, -f <integer>
301
302 Number of frames of input sequence to be encoded. Default 0 (all)
303
304 **CLI ONLY**
305
306.. option:: --output, -o <filename>
307
308 Bitstream output file name. If there are two extra CLI options, the
309 first is implicitly the input filename and the second is the output
310 filename, making the :option:`--output` option optional.
311
312 The output file will always contain a raw HEVC bitstream, the CLI
313 does not support any container file formats.
314
315 **CLI ONLY**
316
317Profile, Level, Tier
318====================
319
320.. option:: --profile <string>
321
322 Enforce the requirements of the specified profile, ensuring the
323 output stream will be decodable by a decoder which supports that
324 profile. May abort the encode if the specified profile is
325 impossible to be supported by the compile options chosen for the
326 encoder (a high bit depth encoder will be unable to output
327 bitstreams compliant with Main or Mainstillpicture).
328
329 API users must use x265_param_apply_profile() after configuring
330 their param structure. Any changes made to the param structure after
331 this call might make the encode non-compliant.
332
333 **Values:** main, main10, mainstillpicture, main422-8, main422-10, main444-8, main444-10
334
335 **CLI ONLY**
336
337.. option:: --level-idc <integer|float>
338
339 Minimum decoder requirement level. Defaults to 0, which implies
340 auto-detection by the encoder. If specified, the encoder will
341 attempt to bring the encode specifications within that specified
342 level. If the encoder is unable to reach the level it issues a
343 warning and aborts the encode. If the requested requirement level is
344 higher than the actual level, the actual requirement level is
345 signaled.
346
347 Beware, specifying a decoder level will force the encoder to enable
348 VBV for constant rate factor encodes, which may introduce
349 non-determinism.
350
351 The value is specified as a float or as an integer with the level
352 times 10, for example level **5.1** is specified as "5.1" or "51",
353 and level **5.0** is specified as "5.0" or "50".
354
355 Annex A levels: 1, 2, 2.1, 3, 3.1, 4, 4.1, 5, 5.1, 5.2, 6, 6.1, 6.2
356
357.. option:: --high-tier, --no-high-tier
358
359 If :option:`--level-idc` has been specified, the option adds the
360 intention to support the High tier of that level. If your specified
361 level does not support a High tier, a warning is issued and this
362 modifier flag is ignored.
363
364.. note::
365 :option:`--profile`, :option:`--level-idc`, and
366 :option:`--high-tier` are only intended for use when you are
367 targeting a particular decoder (or decoders) with fixed resource
368 limitations and must constrain the bitstream within those limits.
369 Specifying a profile or level may lower the encode quality
370 parameters to meet those requirements but it will never raise
371 them.
372
373Mode decision / Analysis
374========================
375
376.. option:: --rd <0..6>
377
378 Level of RDO in mode decision. The higher the value, the more
379 exhaustive the analysis and the more rate distortion optimization is
380 used. The lower the value the faster the encode, the higher the
381 value the smaller the bitstream (in general). Default 3
382
383 Note that this table aims for accuracy, but is not necessarily our
384 final target behavior for each mode.
385
386 +-------+---------------------------------------------------------------+
387 | Level | Description |
388 +=======+===============================================================+
389 | 0 | sa8d mode and split decisions, intra w/ source pixels |
390 +-------+---------------------------------------------------------------+
391 | 1 | recon generated (better intra), RDO merge/skip selection |
392 +-------+---------------------------------------------------------------+
393 | 2 | RDO splits and merge/skip selection |
394 +-------+---------------------------------------------------------------+
395 | 3 | RDO mode and split decisions, chroma residual used for sa8d |
396 +-------+---------------------------------------------------------------+
397 | 4 | Adds RDO Quant |
398 +-------+---------------------------------------------------------------+
399 | 5 | Adds RDO prediction decisions |
400 +-------+---------------------------------------------------------------+
401 | 6 | Currently same as 5 |
402 +-------+---------------------------------------------------------------+
403
404 **Range of values:** 0: least .. 6: full RDO analysis
405
406Options which affect the coding unit quad-tree, sometimes referred to as
407the prediction quad-tree.
408
409.. option:: --ctu, -s <64|32|16>
410
411 Maximum CU size (width and height). The larger the maximum CU size,
412 the more efficiently x265 can encode flat areas of the picture,
413 giving large reductions in bitrate. However this comes at a loss of
414 parallelism with fewer rows of CUs that can be encoded in parallel,
415 and less frame parallelism as well. Because of this the faster
416 presets use a CU size of 32. Default: 64
417
418.. option:: --rect, --no-rect
419
420 Enable analysis of rectangular motion partitions Nx2N and 2NxN
421 (50/50 splits, two directions). Default disabled
422
423.. option:: --amp, --no-amp
424
425 Enable analysis of asymmetric motion partitions (75/25 splits, four
426 directions). At RD levels 0 through 4, AMP partitions are only
427 considered at CU sizes 32x32 and below. At RD levels 5 and 6, it
428 will only consider AMP partitions as merge candidates (no motion
429 search) at 64x64, and as merge or inter candidates below 64x64.
430
431 The AMP partitions which are searched are derived from the current
432 best inter partition. If Nx2N (vertical rectangular) is the best
433 current prediction, then left and right asymmetrical splits will be
434 evaluated. If 2NxN (horizontal rectangular) is the best current
435 prediction, then top and bottom asymmetrical splits will be
436 evaluated, If 2Nx2N is the best prediction, and the block is not a
437 merge/skip, then all four AMP partitions are evaluated.
438
439 This setting has no effect if rectangular partitions are disabled.
440 Default disabled
441
442.. option:: --early-skip, --no-early-skip
443
444 Measure full CU size (2Nx2N) merge candidates first; if no residual
445 is found the analysis is short circuited. Default disabled
446
447.. option:: --fast-cbf, --no-fast-cbf
448
449 Short circuit analysis if a prediction is found that does not set
450 the coded block flag (aka: no residual was encoded). It prevents
451 the encoder from perhaps finding other predictions that also have no
452 residual but require less signaling bits or have less distortion.
453 Only applicable for RD levels 5 and 6. Default disabled
454
455.. option:: --fast-intra, --no-fast-intra
456
457 Perform an initial scan of every fifth intra angular mode, then
458 check modes +/- 2 distance from the best mode, then +/- 1 distance
459 from the best mode, effectively performing a gradient descent. When
460 enabled 10 modes in total are checked. When disabled all 33 angular
461 modes are checked. Only applicable for :option:`--rd` levels 4 and
462 below (medium preset and faster).
463
464.. option:: --b-intra, --no-b-intra
465
466 Enables the evaluation of intra modes in B slices. Default disabled.
467
468.. option:: --cu-lossless, --no-cu-lossless
469
470 For each CU, evaluate lossless (transform and quant bypass) encode
471 of the best non-lossless mode option as a potential rate distortion
472 optimization. If the global option :option:`--lossless` has been
473 specified, all CUs will be encoded as lossless unconditionally
474 regardless of whether this option was enabled. Default disabled.
475
476 Only effective at RD levels 3 and above, which perform RDO mode
477 decisions.
478
479.. option:: --tskip, --no-tskip
480
481 Enable evaluation of transform skip (bypass DCT but still use
482 quantization) coding for 4x4 TU coded blocks.
483
484 Only effective at RD levels 3 and above, which perform RDO mode
485 decisions. Default disabled
486
487.. option:: --tskip-fast, --no-tskip-fast
488
489 Only evaluate transform skip for NxN intra predictions (4x4 blocks).
490 Only applicable if transform skip is enabled. For chroma, only
491 evaluate if luma used tskip. Inter block tskip analysis is
492 unmodified. Default disabled
493
494Analysis re-use options, to improve performance when encoding the same
495sequence multiple times (presumably at varying bitrates). The encoder
496will not reuse analysis if the resolution and slice type parameters do
497not match.
498
499.. option:: --analysis-mode <string|int>
500
501 Specify whether analysis information of each frame is output by encoder
502 or input for reuse. By reading the analysis data writen by an
503 earlier encode of the same sequence, substantial redundant work may
504 be avoided.
505
506 The following data may be stored and reused:
507 I frames - split decisions and luma intra directions of all CUs.
508 P/B frames - motion vectors are dumped at each depth for all CUs.
509
510 **Values:** off(0), save(1): dump analysis data, load(2): read analysis data
511
512.. option:: --analysis-file <filename>
513
514 Specify a filename for analysis data (see :option:`--analysis-mode`)
515 If no filename is specified, x265_analysis.dat is used.
516
517Options which affect the transform unit quad-tree, sometimes referred to
518as the residual quad-tree (RQT).
519
520.. option:: --tu-intra-depth <1..4>
521
522 The transform unit (residual) quad-tree begins with the same depth
523 as the coding unit quad-tree, but the encoder may decide to further
524 split the transform unit tree if it improves compression efficiency.
525 This setting limits the number of extra recursion depth which can be
526 attempted for intra coded units. Default: 1, which means the
527 residual quad-tree is always at the same depth as the coded unit
528 quad-tree
529
530 Note that when the CU intra prediction is NxN (only possible with
531 8x8 CUs), a TU split is implied, and thus the residual quad-tree
532 begins at 4x4 and cannot split any futhrer.
533
534.. option:: --tu-inter-depth <1..4>
535
536 The transform unit (residual) quad-tree begins with the same depth
537 as the coding unit quad-tree, but the encoder may decide to further
538 split the transform unit tree if it improves compression efficiency.
539 This setting limits the number of extra recursion depth which can be
540 attempted for inter coded units. Default: 1. which means the
541 residual quad-tree is always at the same depth as the coded unit
542 quad-tree unless the CU was coded with rectangular or AMP
543 partitions, in which case a TU split is implied and thus the
544 residual quad-tree begins one layer below the CU quad-tree.
545
546Temporal / motion search options
547================================
548
549.. option:: --me <integer|string>
550
551 Motion search method. Generally, the higher the number the harder
552 the ME method will try to find an optimal match. Diamond search is
553 the simplest. Hexagon search is a little better. Uneven
554 Multi-Hexegon is an adaption of the search method used by x264 for
555 slower presets. Star is a three step search adapted from the HM
556 encoder: a star-pattern search followed by an optional radix scan
557 followed by an optional star-search refinement. Full is an
558 exhaustive search; an order of magnitude slower than all other
559 searches but not much better than umh or star.
560
561 0. dia
562 1. hex **(default)**
563 2. umh
564 3. star
565 4. full
566
567.. option:: --subme, -m <0..7>
568
569 Amount of subpel refinement to perform. The higher the number the
570 more subpel iterations and steps are performed. Default 2
571
572 +----+------------+-----------+------------+-----------+-----------+
573 | -m | HPEL iters | HPEL dirs | QPEL iters | QPEL dirs | HPEL SATD |
574 +====+============+===========+============+===========+===========+
575 | 0 | 1 | 4 | 0 | 4 | false |
576 +----+------------+-----------+------------+-----------+-----------+
577 | 1 | 1 | 4 | 1 | 4 | false |
578 +----+------------+-----------+------------+-----------+-----------+
579 | 2 | 1 | 4 | 1 | 4 | true |
580 +----+------------+-----------+------------+-----------+-----------+
581 | 3 | 2 | 4 | 1 | 4 | true |
582 +----+------------+-----------+------------+-----------+-----------+
583 | 4 | 2 | 4 | 2 | 4 | true |
584 +----+------------+-----------+------------+-----------+-----------+
585 | 5 | 1 | 8 | 1 | 8 | true |
586 +----+------------+-----------+------------+-----------+-----------+
587 | 6 | 2 | 8 | 1 | 8 | true |
588 +----+------------+-----------+------------+-----------+-----------+
589 | 7 | 2 | 8 | 2 | 8 | true |
590 +----+------------+-----------+------------+-----------+-----------+
591
592 At --subme values larger than 2, chroma residual cost is included
593 in all subpel refinement steps and chroma residual is included in
594 all motion estimation decisions (selecting the best reference
595 picture in each list, and chosing between merge, uni-directional
596 motion and bi-directional motion). The 'slow' preset is the first
597 preset to enable the use of chroma residual.
598
599.. option:: --merange <integer>
600
601 Motion search range. Default 57
602
603 The default is derived from the default CTU size (64) minus the luma
604 interpolation half-length (4) minus maximum subpel distance (2)
605 minus one extra pixel just in case the hex search method is used. If
606 the search range were any larger than this, another CTU row of
607 latency would be required for reference frames.
608
609 **Range of values:** an integer from 0 to 32768
610
611.. option:: --max-merge <1..5>
612
613 Maximum number of neighbor (spatial and temporal) candidate blocks
614 that the encoder may consider for merging motion predictions. If a
615 merge candidate results in no residual, it is immediately selected
616 as a "skip". Otherwise the merge candidates are tested as part of
617 motion estimation when searching for the least cost inter option.
618 The max candidate number is encoded in the SPS and determines the
619 bit cost of signaling merge CUs. Default 2
620
621.. option:: --temporal-mvp, --no-temporal-mvp
622
623 Enable temporal motion vector predictors in P and B slices.
624 This enables the use of the motion vector from the collocated block
625 in the previous frame to be used as a predictor. Default is enabled
626
627.. option:: --weightp, -w, --no-weightp
628
629 Enable weighted prediction in P slices. This enables weighting
630 analysis in the lookahead, which influences slice decisions, and
631 enables weighting analysis in the main encoder which allows P
632 reference samples to have a weight function applied to them prior to
633 using them for motion compensation. In video which has lighting
634 changes, it can give a large improvement in compression efficiency.
635 Default is enabled
636
637.. option:: --weightb, --no-weightb
638
639 Enable weighted prediction in B slices. Default disabled
640
641Spatial/intra options
642=====================
643
644.. option:: --strong-intra-smoothing, --no-strong-intra-smoothing
645
646 Enable strong intra smoothing for 32x32 intra blocks. Default enabled
647
648.. option:: --constrained-intra, --no-constrained-intra
649
650 Constrained intra prediction. When generating intra predictions for
651 blocks in inter slices, only intra-coded reference pixels are used.
652 Inter-coded reference pixels are replaced with intra-coded neighbor
653 pixels or default values. The general idea is to block the
654 propagation of reference errors that may have resulted from lossy
655 signals. Default disabled
656
657.. option:: --rdpenalty <0..2>
658
659 When set to 1, transform units of size 32x32 are given a 4x bit cost
660 penalty compared to smaller transform units, in intra coded CUs in P
661 or B slices.
662
663 When set to 2, transform units of size 32x32 are not even attempted,
664 unless otherwise required by the maximum recursion depth. For this
665 option to be effective with 32x32 intra CUs,
666 :option:`--tu-intra-depth` must be at least 2. For it to be
667 effective with 64x64 intra CUs, :option:`--tu-intra-depth` must be
668 at least 3.
669
670 Note that in HEVC an intra transform unit (a block of the residual
671 quad-tree) is also a prediction unit, meaning that the intra
672 prediction signal is generated for each TU block, the residual
673 subtracted and then coded. The coding unit simply provides the
674 prediction modes that will be used when predicting all of the
675 transform units within the CU. This means that when you prevent
676 32x32 intra transform units, you are preventing 32x32 intra
677 predictions.
678
679 Default 0, disabled.
680
681 **Values:** 0:disabled 1:4x cost penalty 2:force splits
682
683Psycho-visual options
684=====================
685
686Left to its own devices, the encoder will make mode decisions based on a
687simple rate distortion formula, trading distortion for bitrate. This is
688generally effective except for the manner in which this distortion is
689measured. It tends to favor blurred reconstructed blocks over blocks
690which have wrong motion. The human eye generally prefers the wrong
691motion over the blur and thus x265 offers psycho-visual adjustments to
692the rate distortion algorithm.
693
694:option:`--psy-rd` will add an extra cost to reconstructed blocks which
695do not match the visual energy of the source block. The higher the
696strength of :option:`--psy-rd` the more strongly it will favor similar
697energy over blur and the more aggressively it will ignore rate
698distortion. If it is too high, it will introduce visal artifacts and
699increase bitrate enough for rate control to increase quantization
700globally, reducing overall quality. psy-rd will tend to reduce the use
701of blurred prediction modes, like DC and planar intra and bi-directional
702inter prediction.
703
704:option:`--psy-rdoq` will adjust the distortion cost used in
705rate-distortion optimized quantization (RDO quant), enabled in
706:option:`--rd` 4 and above, favoring the preservation of energy in the
707reconstructed image. :option:`--psy-rdoq` prevents RDOQ from blurring
708all of the encoding options which psy-rd has to chose from. At low
709strength levels, psy-rdoq will influence the quantization level
710decisions, favoring higher AC energy in the reconstructed image. As
711psy-rdoq strength is increased, more non-zero coefficient levels are
712added and fewer coefficients are zeroed by RDOQ's rate distortion
713analysis. High levels of psy-rdoq can double the bitrate which can have
714a drastic effect on rate control, forcing higher overall QP, and can
715cause ringing artifacts. psy-rdoq is less accurate than psy-rd, it is
716biasing towards energy in general while psy-rd biases towards the energy
717of the source image. But very large psy-rdoq values can sometimes be
718beneficial, preserving film grain for instance.
719
720As a general rule, when both psycho-visual features are disabled, the
721encoder will tend to blur blocks in areas of difficult motion. Turning
722on small amounts of psy-rd and psy-rdoq will improve the perceived
723visual quality. Increasing psycho-visual strength further will improve
724quality and begin introducing artifacts and increase bitrate, which may
725force rate control to increase global QP. Finding the optimal
726psycho-visual parameters for a given video requires experimentation. Our
727recommended defaults (1.0 for both) are generally on the low end of the
728spectrum.
729
730The lower the bitrate, the lower the optimal psycho-visual settings. If
731the bitrate is too low for the psycho-visual settings, you will begin to
732see temporal artifacts (motion judder). This is caused when the encoder
733is forced to code skip blocks (no residual) in areas of difficult motion
734because it is the best option psycho-visually (they have great amounts
735of energy and no residual cost). One can lower psy-rd settings when
736judder is happening, and allow the encoder to use some blur in these
737areas of high motion.
738
739.. option:: --psy-rd <float>
740
741 Influence rate distortion optimizated mode decision to preserve the
742 energy of the source image in the encoded image at the expense of
743 compression efficiency. It only has effect on presets which use
744 RDO-based mode decisions (:option:`--rd` 3 and above). 1.0 is a
745 typical value. Default disabled. Experimental
746
747 **Range of values:** 0 .. 2.0
748
749.. option:: --psy-rdoq <float>
750
751 Influence rate distortion optimized quantization by favoring higher
752 energy in the reconstructed image. This generally improves perceived
753 visual quality at the cost of lower quality metric scores. It only
754 has effect on slower presets which use RDO Quantization
755 (:option:`--rd` 4, 5 and 6). 1.0 is a typical value. Default
756 disabled. High values can be beneficial in preserving high-frequency
757 detail like film grain. Experimental
758
759 **Range of values:** 0 .. 50.0
760
761
762Slice decision options
763======================
764
765.. option:: --open-gop, --no-open-gop
766
767 Enable open GOP, allow I-slices to be non-IDR. Default enabled
768
769.. option:: --keyint, -I <integer>
770
771 Max intra period in frames. A special case of infinite-gop (single
772 keyframe at the beginning of the stream) can be triggered with
773 argument -1. Use 1 to force all-intra. Default 250
774
775.. option:: --min-keyint, -i <integer>
776
777 Minimum GOP size. Scenecuts closer together than this are coded as I
778 or P, not IDR. Minimum keyint is clamped to be at least half of
779 :option:`--keyint`. If you wish to force regular keyframe intervals
780 and disable adaptive I frame placement, you must use
781 :option:`--no-scenecut`.
782
783 **Range of values:** >=0 (0: auto)
784
785.. option:: --scenecut <integer>, --no-scenecut
786
787 How aggressively I-frames need to be inserted. The higher the
788 threshold value, the more aggressive the I-frame placement.
789 :option:`--scenecut` 0 or :option:`--no-scenecut` disables adaptive
790 I frame placement. Default 40
791
792.. option:: --rc-lookahead <integer>
793
794 Number of frames for slice-type decision lookahead (a key
795 determining factor for encoder latency). The longer the lookahead
796 buffer the more accurate scenecut decisions will be, and the more
797 effective cuTree will be at improving adaptive quant. Having a
798 lookahead larger than the max keyframe interval is not helpful.
799 Default 20
800
801 **Range of values:** Between the maximum consecutive bframe count (:option:`--bframes`) and 250
802
803.. option:: --b-adapt <integer>
804
805 Adaptive B frame scheduling. Default 2
806
807 **Values:** 0:none; 1:fast; 2:full(trellis)
808
809.. option:: --bframes, -b <0..16>
810
811 Maximum number of consecutive b-frames. Use :option:`--bframes` 0 to
812 force all P/I low-latency encodes. Default 4. This parameter has a
813 quadratic effect on the amount of memory allocated and the amount of
814 work performed by the full trellis version of :option:`--b-adapt`
815 lookahead.
816
817.. option:: --bframe-bias <integer>
818
819 Bias towards B frames in slicetype decision. The higher the bias the
820 more likely x265 is to use B frames. Can be any value between -90
821 and 100 and is clipped to that range. Default 0
822
823.. option:: --b-pyramid, --no-b-pyramid
824
825 Use B-frames as references, when possible. Default enabled
826
827.. option:: --ref <1..16>
828
829 Max number of L0 references to be allowed. This number has a linear
830 multiplier effect on the amount of work performed in motion search,
831 but will generally have a beneficial affect on compression and
832 distortion. Default 3
833
834Quality, rate control and rate distortion options
835=================================================
836
837.. option:: --bitrate <integer>
838
839 Enables single-pass ABR rate control. Specify the target bitrate in
840 kbps. Default is 0 (CRF)
841
842 **Range of values:** An integer greater than 0
843
844.. option:: --crf <0..51.0>
845
846 Quality-controlled variable bitrate. CRF is the default rate control
847 method; it does not try to reach any particular bitrate target,
848 instead it tries to achieve a given uniform quality and the size of
849 the bitstream is determined by the complexity of the source video.
850 The higher the rate factor the higher the quantization and the lower
851 the quality. Default rate factor is 28.0.
852
853.. option:: --crf-max <0..51.0>
854
855 Specify an upper limit to the rate factor which may be assigned to
856 any given frame (ensuring a max QP). This is dangerous when CRF is
857 used in combination with VBV as it may result in buffer underruns.
858 Default disabled
859
860.. option:: --crf-min <0..51.0>
861
862 Specify an lower limit to the rate factor which may be assigned to
863 any given frame (ensuring a min compression factor).
864
865.. option:: --vbv-bufsize <integer>
866
867 Specify the size of the VBV buffer (kbits). Enables VBV in ABR
868 mode. In CRF mode, :option:`--vbv-maxrate` must also be specified.
869 Default 0 (vbv disabled)
870
871.. option:: --vbv-maxrate <integer>
872
873 Maximum local bitrate (kbits/sec). Will be used only if vbv-bufsize
874 is also non-zero. Both vbv-bufsize and vbv-maxrate are required to
875 enable VBV in CRF mode. Default 0 (disabled)
876
877.. option:: --vbv-init <float>
878
879 Initial buffer occupancy. The portion of the decode buffer which
880 must be full before the decoder will begin decoding. Determines
881 absolute maximum frame size. May be specified as a fractional value
882 between 0 and 1, or in kbits. In other words these two option pairs
883 are equivalent::
884
885 --vbv-bufsize 1000 --vbv-init 900
886 --vbv-bufsize 1000 --vbv-init 0.9
887
888 Default 0.9
889
890 **Range of values:** fractional: 0 - 1.0, or kbits: 2 .. bufsize
891
892.. option:: --qp, -q <integer>
893
894 Specify base quantization parameter for Constant QP rate control.
895 Using this option enables Constant QP rate control. The specified QP
896 is assigned to P slices. I and B slices are given QPs relative to P
897 slices using param->rc.ipFactor and param->rc.pbFactor unless QP 0
898 is specified, in which case QP 0 is used for all slice types. Note
899 that QP 0 does not cause lossless encoding, it only disables
900 quantization. Default disabled (CRF)
901
902 **Range of values:** an integer from 0 to 51
903
904.. option:: --lossless, --no-lossless
905
906 Enables true lossless coding by bypassing scaling, transform,
907 quantization and in-loop filter processes. This is used for
908 ultra-high bitrates with zero loss of quality. Reconstructed output
909 pictures are bit-exact to the input pictures. Lossless encodes
910 implicitly have no rate control, all rate control options are
911 ignored. Slower presets will generally achieve better compression
912 efficiency (and generate smaller bitstreams). Default disabled.
913
914.. option:: --aq-mode <0|1|2>
915
916 Adaptive Quantization operating mode. Raise or lower per-block
917 quantization based on complexity analysis of the source image. The
918 more complex the block, the more quantization is used. This offsets
919 the tendency of the encoder to spend too many bits on complex areas
920 and not enough in flat areas.
921
922 0. disabled
923 1. AQ enabled **(default)**
924 2. AQ enabled with auto-variance
925
926.. option:: --aq-strength <float>
927
928 Adjust the strength of the adaptive quantization offsets. Setting
929 :option:`--aq-strength` to 0 disables AQ. Default 1.0.
930
931 **Range of values:** 0.0 to 3.0
932
933.. option:: --cutree, --no-cutree
934
935 Enable the use of lookahead's lowres motion vector fields to
936 determine the amount of reuse of each block to tune adaptive
937 quantization factors. CU blocks which are heavily reused as motion
938 reference for later frames are given a lower QP (more bits) while CU
939 blocks which are quickly changed and are not referenced are given
940 less bits. This tends to improve detail in the backgrounds of video
941 with less detail in areas of high motion. Default enabled
942
943.. option:: --nr-intra <integer>, --nr-inter <integer>
944
945 Noise reduction - an adaptive deadzone applied after DCT
946 (subtracting from DCT coefficients), before quantization. It does
947 no pixel-level filtering, doesn't cross DCT block boundaries, has no
948 overlap, The higher the strength value parameter, the more
949 aggressively it will reduce noise.
950
951 Enabling noise reduction will make outputs diverge between different
952 numbers of frame threads. Outputs will be deterministic but the
953 outputs of -F2 will no longer match the outputs of -F3, etc.
954
955 **Values:** any value in range of 0 to 2000. Default 0 (disabled).
956
957.. option:: --pass <integer>
958
959 Enable multi-pass rate control mode. Input is encoded multiple times,
960 storing the encoded information of each pass in a stats file from which
961 the consecutive pass tunes the qp of each frame to improve the quality
962 of the output. Default disabled
963
964 1. First pass, creates stats file
965 2. Last pass, does not overwrite stats file
966 3. Nth pass, overwrites stats file
967
968 **Range of values:** 1 to 3
969
970.. option:: --stats <filename>
971
972 Specify file name of of the multi-pass stats file. If unspecified
973 the encoder will use x265_2pass.log
974
975.. option:: --slow-firstpass, --no-slow-firstpass
976
977 Enable a slow and more detailed first pass encode in multi-pass rate
978 control mode. Speed of the first pass encode is slightly lesser and
979 quality midly improved when compared to the default settings in a
980 multi-pass encode. Default disabled (turbo mode enabled)
981
982 When **turbo** first pass is not disabled, these options are
983 set on the first pass to improve performance:
984
985 * :option:`--fast-intra`
986 * :option:`--no-rect`
987 * :option:`--no-amp`
988 * :option:`--early-skip`
989 * :option:`--ref` = 1
990 * :option:`--max-merge` = 1
991 * :option:`--me` = DIA
992 * :option:`--subme` = MIN(2, :option:`--subme`)
993 * :option:`--rd` = MIN(2, :option:`--rd`)
994
995.. option:: --cbqpoffs <integer>
996
997 Offset of Cb chroma QP from the luma QP selected by rate control.
998 This is a general way to spend more or less bits on the chroma
999 channel. Default 0
1000
1001 **Range of values:** -12 to 12
1002
1003.. option:: --crqpoffs <integer>
1004
1005 Offset of Cr chroma QP from the luma QP selected by rate control.
1006 This is a general way to spend more or less bits on the chroma
1007 channel. Default 0
1008
1009 **Range of values:** -12 to 12
1010
1011.. option:: --ipratio <float>
1012
1013 QP ratio factor between I and P slices. This ratio is used in all of
1014 the rate control modes. Some :option:`--tune` options may change the
1015 default value. It is not typically manually specified. Default 1.4
1016
1017.. option:: --pbratio <float>
1018
1019 QP ratio factor between P and B slices. This ratio is used in all of
1020 the rate control modes. Some :option:`--tune` options may change the
1021 default value. It is not typically manually specified. Default 1.3
1022
1023.. option:: --qcomp <float>
1024
1025 qComp sets the quantizer curve compression factor. It weights the
1026 frame quantizer based on the complexity of residual (measured by
1027 lookahead). Default value is 0.6. Increasing it to 1 will
1028 effectively generate CQP
1029
1030.. option:: --qstep <integer>
1031
1032 The maximum single adjustment in QP allowed to rate control. Default
1033 4
1034
1035.. option:: --ratetol <float>
1036
1037 The degree of rate fluctuation that x265 tolerates. Rate tolerance
1038 is used along with overflow (difference between actual and target
1039 bitrate), to adjust qp. Default is 1.0
1040
1041.. option:: --qblur <float>
1042
1043 Temporally blur quants. Default 0.5
1044
1045.. option:: --cplxblur <float>
1046
1047 temporally blur complexity. default 20
1048
1049Quantization Options
1050====================
1051
1052Note that rate-distortion optimized quantization (RDOQ) is enabled
1053implicitly at :option:`--rd` 4, 5, and 6 and disabled implicitly at all
1054other levels.
1055
1056.. option:: --signhide, --no-signhide
1057
1058 Hide sign bit of one coeff per TU (rdo). The last sign is implied.
1059 This requires analyzing all the coefficients to determine if a sign
1060 must be toggled, and then to determine which one can be toggled with
1061 the least amount of distortion. Default enabled
1062
1063.. option:: --qpfile <filename>
1064
1065 Specify a text file which contains frametypes and QPs for some or
1066 all frames. The format of each line is:
1067
1068 framenumber frametype QP
1069
1070 Frametype can be one of [I,i,P,B,b]. **B** is a referenced B frame,
1071 **b** is an unreferenced B frame. **I** is a keyframe (random
1072 access point) while **i** is a I frame that is not a keyframe
1073 (references are not broken).
1074
1075 Specifying QP (integer) is optional, and if specified they are
1076 clamped within the encoder to qpmin/qpmax.
1077
1078.. option:: --scaling-list <filename>
1079
1080 Quantization scaling lists. HEVC supports 6 quantization scaling
1081 lists to be defined; one each for Y, Cb, Cr for intra prediction and
1082 one each for inter prediction.
1083
1084 x265 does not use scaling lists by default, but this can also be
1085 made explicit by :option:`--scaling-list` *off*.
1086
1087 HEVC specifies a default set of scaling lists which may be enabled
1088 without requiring them to be signaled in the SPS. Those scaling
1089 lists can be enabled via :option:`--scaling-list` *default*.
1090
1091 All other strings indicate a filename containing custom scaling
1092 lists in the HM format. The encode will abort if the file is not
1093 parsed correctly. Custom lists must be signaled in the SPS
1094
1095.. option:: --lambda-file <filename>
1096
1097 Specify a text file containing values for x265_lambda_tab and
1098 x265_lambda2_tab. Each table requires MAX_MAX_QP+1 (70) float
1099 values.
1100
1101 The text file syntax is simple. Comma is considered to be
1102 white-space. All white-space is ignored. Lines must be less than 2k
1103 bytes in length. Content following hash (#) characters are ignored.
1104 The values read from the file are logged at :option:`--log-level`
1105 debug.
1106
1107 Note that the lambda tables are process-global and so the new values
1108 affect all encoders running in the same process.
1109
1110 Lambda values affect encoder mode decisions, the lower the lambda
1111 the more bits it will try to spend on signaling information (motion
1112 vectors and splits) and less on residual. This feature is intended
1113 for experimentation.
1114
1115Loop filters
1116============
1117
1118.. option:: --deblock=<int>:<int>, --no-deblock
1119
1120 Toggle deblocking loop filter, optionally specify deblocking
1121 strength offsets.
1122
1123 <int>:<int> - parsed as tC offset and Beta offset
1124 <int>,<int> - parsed as tC offset and Beta offset
1125 <int> - both tC and Beta offsets assigned the same value
1126
1127 If unspecified, the offsets default to 0. The offsets must be in a
1128 range of -6 (lowest strength) to 6 (highest strength).
1129
1130 To disable the deblocking filter entirely, use --no-deblock or
1131 --deblock=false. Default enabled, with both offsets defaulting to 0
1132
1133 If deblocking is disabled, or the offsets are non-zero, these
1134 changes from the default configuration are signaled in the PPS.
1135
1136.. option:: --sao, --no-sao
1137
1138 Toggle Sample Adaptive Offset loop filter, default enabled
1139
1140.. option:: --sao-non-deblock, --no-sao-non-deblock
1141
1142 Specify how to handle depencency between SAO and deblocking filter.
1143 When enabled, non-deblocked pixels are used for SAO analysis. When
1144 disabled, SAO analysis skips the right/bottom boundary areas.
1145 Default disabled
1146
1147VUI (Video Usability Information) options
1148=========================================
1149
1150x265 emits a VUI with only the timing info by default. If the SAR is
1151specified (or read from a Y4M header) it is also included. All other
1152VUI fields must be manually specified.
1153
1154.. option:: --sar <integer|w:h>
1155
1156 Sample Aspect Ratio, the ratio of width to height of an individual
1157 sample (pixel). The user may supply the width and height explicitly
1158 or specify an integer from the predefined list of aspect ratios
1159 defined in the HEVC specification. Default undefined (not signaled)
1160
1161 1. 1:1 (square)
1162 2. 12:11
1163 3. 10:11
1164 4. 16:11
1165 5. 40:33
1166 6. 24:11
1167 7. 20:11
1168 8. 32:11
1169 9. 80:33
1170 10. 18:11
1171 11. 15:11
1172 12. 64:33
1173 13. 160:99
1174 14. 4:3
1175 15. 3:2
1176 16. 2:1
1177
1178.. option:: --crop-rect <left,top,right,bottom>
1179
1180 Define the (overscan) region of the image that does not contain
1181 information because it was added to achieve certain resolution or
1182 aspect ratio. The decoder may be directed to crop away this region
1183 before displaying the images via the :option:`--overscan` option.
1184 Default undefined (not signaled)
1185
1186.. option:: --overscan <show|crop>
1187
1188 Specify whether it is appropriate for the decoder to display or crop
1189 the overscan area. Default unspecified (not signaled)
1190
1191.. option:: --videoformat <integer|string>
1192
1193 Specify the source format of the original analog video prior to
1194 digitizing and encoding. Default undefined (not signaled)
1195
1196 0. component
1197 1. pal
1198 2. ntsc
1199 3. secam
1200 4. mac
1201 5. undefined
1202
1203.. option:: --range <full|limited>
1204
1205 Specify output range of black level and range of luma and chroma
1206 signals. Default undefined (not signaled)
1207
1208.. option:: --colorprim <integer|string>
1209
1210 Specify color primitive to use when converting to RGB. Default
1211 undefined (not signaled)
1212
1213 1. bt709
1214 2. undef
1215 3. **reserved**
1216 4. bt470m
1217 5. bt470bg
1218 6. smpte170m
1219 7. smpte240m
1220 8. film
1221 9. bt2020
1222
1223.. option:: --transfer <integer|string>
1224
1225 Specify transfer characteristics. Default undefined (not signaled)
1226
1227 1. bt709
1228 2. undef
1229 3. **reserved**
1230 4. bt470m
1231 5. bt470bg
1232 6. smpte170m
1233 7. smpte240m
1234 8. linear
1235 9. log100
1236 10. log316
1237 11. iec61966-2-4
1238 12. bt1361e
1239 13. iec61966-2-1
1240 14. bt2020-10
1241 15. bt2020-12
1242
1243.. option:: --colormatrix <integer|string>
1244
1245 Specify color matrix setting i.e set the matrix coefficients used in
1246 deriving the luma and chroma. Default undefined (not signaled)
1247
1248 0. GBR
1249 1. bt709
1250 2. undef
1251 3. **reserved**
1252 4. fcc
1253 5. bt470bg
1254 6. smpte170m
1255 7. smpte240m
1256 8. YCgCo
1257 9. bt2020nc
1258 10. bt2020c
1259
1260.. option:: --chromaloc <0..5>
1261
1262 Specify chroma sample location for 4:2:0 inputs. Consult the HEVC
1263 specification for a description of these values. Default undefined
1264 (not signaled)
1265
1266Bitstream options
1267=================
1268
1269.. option:: --repeat-headers, --no-repeat-headers
1270
1271 If enabled, x265 will emit VPS, SPS, and PPS headers with every
1272 keyframe. This is intended for use when you do not have a container
1273 to keep the stream headers for you and you want keyframes to be
1274 random access points. Default disabled
1275
1276.. option:: --info, --no-info
1277
1278 Emit an informational SEI with the stream headers which describes
1279 the encoder version, build info, and encode parameters. This is very
1280 helpful for debugging purposes but encoding version numbers and
1281 build info could make your bitstreams diverge and interfere with
1282 regression testing. Default enabled
1283
1284.. option:: --hrd, --no-hrd
1285
1286 Enable the signalling of HRD parameters to the decoder. The HRD
1287 parameters are carried by the Buffering Period SEI messages and
1288 Picture Timing SEI messages providing timing information to the
1289 decoder. Default disabled
1290
1291.. option:: --aud, --no-aud
1292
1293 Emit an access unit delimiter NAL at the start of each slice access
1294 unit. If :option:`--repeat-headers` is not enabled (indicating the
1295 user will be writing headers manually at the start of the stream)
1296 the very first AUD will be skipped since it cannot be placed at the
1297 start of the access unit, where it belongs. Default disabled
1298
1299.. option:: --hash <integer>
1300
1301 Emit decoded picture hash SEI, so the decoder may validate the
1302 reconstructed pictures and detect data loss. Also useful as a
1303 debug feature to validate the encoder state. Default None
1304
1305 1. MD5
1306 2. CRC
1307 3. Checksum
1308
1309Debugging options
1310=================
1311
1312.. option:: --recon, -r <filename>
1313
1314 Output file containing reconstructed images in display order. If the
1315 file extension is ".y4m" the file will contain a YUV4MPEG2 stream
1316 header and frame headers. Otherwise it will be a raw YUV file in the
1317 encoder's internal bit depth.
1318
1319 **CLI ONLY**
1320
1321.. option:: --recon-depth <integer>
1322
1323 Bit-depth of output file. This value defaults to the internal bit
1324 depth and currently cannot to be modified.
1325
1326 **CLI ONLY**
1327
1328.. vim: noet