q264 Help

Usage: q264.exe [options] -i inputFile -o outputFile

q264 Version 0.5.0 Built: Dec 11 2015 21:02:06
Path: C:\Program Files (x86)\q264\q264.exe
Copyright (C) 2012-2015 Tetrachrome Software LLC
libav* versions: libavcodec: 57.15.100, libavformat: 57.18.100, libavutil: 55.8.100, libavfilter: 6.15.100

This is an H.264 video encoder that uses Intel Quick Sync Video hardware available on recent Intel CPUs (Sandy Bridge and newer). The tested input file types are .avi, .avs, raw (NV12, YV12, or I420/YUV420P/IYUV), .m2v, .mkv, .m2ts, and .mp4 but more probably work due to libav* libraries. The output file is generally a raw H.264 file, but can also be an mp4 file (see muxing below).

Arguments

Basic

-i inputFile Specifies the input file. Can be various types including those supported by libav*. Use - to mean stdin, e.g. '-i -'. For more information on reading from stdin, see the Standard Input section below.
-o outputFile Specifies the output file. Can be a raw H.264 file, an mp4, or stdout. Use - to mean stdout, e.g. '-o -'. If the string 'Q264SPEC' appears in the path then it will be replaced by a string that contains some key encoding params.
[-h|-?] Show full help. This writes a temp html file and opens it with your platform default application.
[-hs] Show abbreviated (in-line text) help.
[-ht] Show full in-line text help rather than opening an html file.
[-v] Set the output message threshold to verbose. This also turns on progress display.
[-quiet] Set the output message threshold so only warnings and errors will be displayed.
[-rel] Show release notes.
[-version] Just echo version.
[-info] Display info about your system.
[-hwver] Display the MFX API version supported by the driver and hardware on your PC. Prints 0.0 for no hardware support.

Misc

[-y] Force overwrite of output file if it exists.
[-nFrames frameCount] Limit the number of frames to process.
[-dump] Print information about frame type, size etc. for every frame encoded.
[-sar W:H] Specify the sample/pixel aspect ratio of the output video. For example '10:11' for a 4x3 anamorphic DVD, or '40:33' for 16x9. The arguments are parsed as floats, converted to a ratio, and then matched to one of the values specified in Table E-1 of the H.264 spec. There is no automatic computation done regarding cropping or resizing, this is simply put in the stream as the output sample aspect ratio.
[-dstfps float] Specify the output frames per second. For example '29.970'. Default is same as input, or auto-detect.
[-sw] Use software encoder implementation. Default is to use hardware. This is primarily for debugging, and the software dll is no longer included in q264.
[-dx11] Use DirectX 11 instead of the default which is DirectX 9. No effect if -sw is specified. DX9 is the default because DX11 can be slower due to no support for YV12 to NV12 conversion.

Quality and Rate Control

[-p baseline|main|high] The H.264 profile. Default is high.
[-u (1..7)] (Usage) Adjusts the speed vs quality tradeoff. 1 is highest quality. 7 is fastest speed. Default is 6.
[-b bitrate] Target encoded bit rate (kbits per second). As of version 0.4.1 can be over 65535. If not specified, for VBR and AVBR a default is calculated.
[-max bitrate] The max bitrate in kbps for VBR encoding (not AVBR nor CBR). As of version 0.4.1 can be over 65535.
[-avbr] Use the Average Bit Rate bitrate (AVBR) control algorithm. See Bitrate Control below in the full help.
[-la depth] Enable look-ahead (LA) for bitrate control and specifies the number of frames to look ahead (either 0 or from 10 to 100 inclusive). Specifying 0 means to use Intel's default number of look-ahead frames. The algorithm looks ahead at future frames to help with bitrate control. This significantly increases memory use. If not used with ICQ, this is a VBR type rate control method and is mutually exclusive with other bitrate control methods. You can specify the target bitrate with the -b option. -max is ignored when this is specified. Look-ahead is only available on Intel Iris Pro Graphics, Intel Iris Graphics and Intel HD Graphics (4200+ Series). This can be specified simultaneously with -icq to enable LA_ICQ mode (ICQ with look-ahead).
[-lads ds] Specify the look-ahead down-sample factor. Down-sampling reduces the size of future images to speed up the look-ahead processing. The possible values are -1, 0, 2, and 4. Value 0 means no downsampling, which is the slowest and highest quality. Value 2 means to downsample the frame two times before estimation. Value 4 means to downsample the frame four times before estimation. Value -1 is the default and means Unspecified which lets the driver choose. This option was added in API version 1.8.
[-avbrAccuracy percent] The AVBR alg tries to converge within this percent of the nominal value, specified as an integer with units of tenths of a percent, within 100 frames. Default is 25 (meaning 2.5 percent).
[-vbr] Use variable bit rate (VBR) encoding.
[-cbr] Use constant bit rate (CBR) encoding.
[-cqp (0..60)] Use constant quantization parameter (CQP) bitrate control algorithm with the specified quality level. 0 means highest quality, higher values mean lower quality. Over about 52 are all the same. 0 does not appear to be exactly lossless but is nearly so.
[-icq (1..51)] Use Intelligent Constant Quality bitrate control algorithm with the specified quality level. 1 is highest quality. This can be specified simultaneously with -la to enable LA_ICQ mode (ICQ with look-ahead).

Raw inputs

[-c colorFormat] Specifies that the input is a raw stream (no container) and is the specified color format. See below for the list of supported pixel formats.
[-fps frameRate] Input video frame rate (frames per second). This is optional if it can be detected from the input file.
[-srcw width] Source picture width. For raw inputs.
[-srch height] Source picture height. For raw inputs.

Filters

[-dstw width] Destination picture width, for resizing. Default is same size as input. Applied after cropping (if any).
[-dsth height] Destination picture height, for resizing. Default is same size as input. Applied after cropping (if any).
[-crop x0,y0,x1,y1] To crop the picture, these define the region of interest. x1 and y1 are exclusive. This is comma-delimited and can have no spaces. The Y values are top-down, meaning the top of the image is Y=0.
[-tff] Specifies that the input is interlaced and is top-field first. If specified, deinterlace is turned on. See Deinterlace section below.
[-bff] Specifies that the input is interlaced and is bottom-field first. If specified, deinterlace is turned on. See Deinterlace section below.
[-ivtc] Turn on inverse telecine. This uses VPP to do IVTC on telecined input video (for example 30 fps DVD). You do not need to also specify -dstfps for ivtc. See Deinterlace section below.

Advanced options

[-sc scThreshold] Specifies the threshold for scene cut detection. Default is 0 which means no scene cut detection. See Scene Cut Detection below (in the full help) for more details.
[-gopSize int] Max GOP size. 0 means unspecified (which apparently means 256). 1 means every frame is an I frame. Default is 0. This specifies the maximum number of frames between I frames. This is applied independent of scene cut detection, which is not ideal, it is a limitation of the current q264 scene cut implementation.
[-gopRefDist int] Max distance between I or P key frames. 0 means unspecified. If this is 1 then no B frames are created. Default is 0. In other words this specifies the how often I/P frames are required between consecutive B frames.
[-numRefFrames int] Number of reference frames. 0 means unspecified. For hardware encode, this currently must be even. Default is 0.
[-idrInterval int] Specifies how often to make an I frame also be an IDR frame. 0 means every I frame will also be an IDR frame. 1 means every other one, etc. Default is 0. Note that a value of 0 also implies a closed GOP, meaning each group of pictures cannot reference the prior.
[-trellis spec] Turns on trellis quantization for the specified frame types (I, P, and/or B). The spec is a string with letters 'i', 'p', and/or 'b' (order-independent) for example 'b' or 'ip' or 'bip'. In driver 1.7 trellis is ignored in all usages (-u) except 1 due to performance impacts. This is supposed to improve coding efficiency by being smarter about quantizing DCT coefficients.
[-mbbrc] Turn on Macroblock level bitrate control. This usually increases subjective quality at the cost of speed and objective quality.
[-extbrc] Turn on Extended bit rate control algorithm. This usually improves subjective and objective quality but may cause HRD conformance violation and decrease performance.

Description

Examples

Simplest : q264.exe -i foo.avi -o out.264
Avi input: q264.exe -i foo.avi -p main -u 6 -b 1400 -o out.264
Raw input: q264.exe -i foo.raw -c yv12 -srcw 720 -srch 480 -fps 29.97 -o out.264
Crop only: q264.exe -crop 30,50,710,470 -i foo.avi -o out.264
Crop/resize: q264.exe -crop 30,50,710,470 -i foo.avi -dsth 300 -dstw 200 -o out.264

Rate Control Examples

AVBR : q264.exe -i foo.avi -b 1800 -o out.264
VBR : q264.exe -i foo.avi -vbr -b 1800 -o out.264
CBR : q264.exe -i foo.avi -cbr -b 1800 -o out.264
CQP : q264.exe -i foo.avi -cqp 28 -o out.264
ICQ : q264.exe -i foo.avi -icq 28 -o out.264
LA_ICQ : q264.exe -i foo.avi -icq 28 -la 0 -o out.264

Overview

This uses Intel Quick Sync Video hardware for fast color format conversion, unless you specify the -sw option.
Intel Quick Sync Video capability is present on various Intel CPUs starting with 2nd generation Core architecture CPUs (Sandy Bridge).
Some color conversions are done in hardware or are trivial (and so are fast in software), but some are considerably slower.
The input color formats which are currently fast are: RGB24 (RGB3), RGB32 (RGB4), NV12, YV12, I420, YUY2, and YUV422P.

This uses the FFmpeg libraries (libavformat, libavcodec, etc) under the LGPLv2.1 to read non-raw input files. See http://ffmpeg.org/

Input Formats

This can read either raw video or container formats.
For raw video the following pixel formats are supported: nv12, yv12, and i420. The following aliases for i420 also work: yuv420, yuv420p, and iyuv.
For video within containers that libav* can read, the following pixel formats/encoders appear to work (by testing avi's produced by ffmpeg):
asv1, asv2, avrp, bmp, cavs, dpx, ffvhuff, flashsv, flv1, h263p, h264, huffyuv, jpeg2000, jpegls, ljpeg, mjpeg, mpeg1video, mpeg2video,
mpeg4, msmpeg4v2, msmpeg4v3, pam, png, ppm, snow, sunrast, targa, theora, tiff, utvideo, v308, vp8, vp9, wmv1, wmv2, xwd, yuv4, zlib

Standard Input

This can read raw video from stdin by specifying '-i -' for the input. This cannot read container formats (avi, mp4, etc) from stdin.
You must specify the video characteristics (-c, -fps, -srcw, -srch) because they cannot be detected from the stream.
Here is an example ffmpeg command:
ffmpeg -i test.avi -an -vcodec rawvideo -f rawvideo -pix_fmt nv12 - | q264.exe -i - -c nv12 -fps 29.97 -srcw 720 -srch 480 -o test.mp4

Bitrate control

Most of these bitrate methods (except ICQ and LA) are mutually exclusive, meaning only one can be specified at a time.
The default bitrate control method is AVBR (-avbr). You can specify other options to use another method.
The look-ahead (LA) algorithm is a VBR flavor that looks ahead a certain number of frames.
Look-ahead is only available on Intel Iris Pro Graphics, Intel Iris Graphics and Intel HD Graphics (4200+ Series).
The Average VBR (AVBR, -avbr) algorithm tries to converge on the specified target bitrate. The instantaneous bitrate is not capped nor padded.
AVBR tries to converge within a specified percent (default 2.5 percent) of the target within a certain number of frames (hardcoded 100).
The VBR bitrate control method is the Hypothetical Reference Decoding variable bitrate algorithm. You can specify other options to use another method.
The VBR algorithm apparently under-shoots the requested bitrate by about 10 percent so you may want to compensate.
Constant Quantization Parameter (-cqp) is another bitrate control method, it attempts to maintain a specified quality rather than bitrate.
Intelligent Constant Quality (ICQ) is a VBR mode that attempts to maintain a specified quality rather than bitrate.
You can specify either LA or ICQ or both modes simultaneously.

Deinterlace and IVTC

The output h.264 stream is always progressive. Specifying -tff or -bff tells q264 to deinterlace.
Hardware implementation 1.7 (and presumably older) cannot deinterlace RGB sources so neither deinterlace nor IVTC work in that case.
Hardware implementation 1.7 (and presumably older) IVTC appears to be dropping the wrong frames.

Muxing

The output file is generally a raw H.264 file, but can also be an mp4 file. In that case q264 tries to do a video-only mux.
q264 does not do muxing itself, but rather will try to execute another program (mp4box.exe or ffmpeg.exe) to do the mux.
This is just a simple convenience, not a robust mechanism. For example you cannot specify any of the mux arguments nor include audio.
q264 does not take responsibility for the version or location of the external mux program, it relies upon you to set it up if you want to use it.
q264 looks for one of the mux programs in the same directory as q264.exe is located. If neither is found, it tries to use the system path to execute them.
If both mux programs are found then mp4box.exe is used. You can override this by putting ffmpeg.exe (and not mp4box.exe) in the directory with q264.exe.
If q264 is going to try to mux, it writes the h.264 raw data to a temp file (in the same directory as the output mp4) during the transcode.
If q264 completes successfully, it will remove that temp file. However if q264 crashes that temp file may not be deleted.

Note that as of late 2013, there were issues with the ffmpeg mux:
- ffmpeg: Quicktime player presents the frames out of order if there are B frames in the h.264 stream.
You can avoid B frames by using the baseline profile or by specifying a GOP reference distance of 1 (see -gopRefDist argument).
- ffmpeg: Windows Media Player may play back with uneven framerate (stutter) on some systems.

Example mux commands:
mp4box.exe -fps 23.976 -add foo.264 -new foo.mp4
ffmpeg.exe -i foo.264 -vcodec copy foo.mp4

Scene Cut Detection

This is a software feature; it is not computed by Quick Sync hardware.
SCD is outside of the normal bitrate control mechanisms, so turning this on generally causes the resulting bitrate to be affected.
This has a substantial speed penalty (e.g. 50 percent for 1080p) for a relatively small (e.g. <1 percent) PSNR improvement.
A scene cut score is computed for each frame. Use -dump to see scene cut scores for each frame.
If the scene cut score is over the specified threshold then that frame is considered to be a scene cut and an I frame is used for it.
The scene cut score is something like the number of stddevs away from mean, meaning how different each frame is from prior frames.
So a higher threshold makes it less likely that a frame will be detected as a scene cut.
Setting the threshold to less than or equal to 0 disables scene cut detection.

Limitations

q264 has the following limitations:
- Most of the practically infinite permutations of input container and format are untested.
- NumRefFrames must be even for hardware encoding.
- On versions of Windows older than 8/8.1 this requires a Windows user login/session to run.
- On versions of Windows older than 8/8.1 this requires that the Intel graphics hardware be the primary display adapter.
- This doesn't support Unicode input or output paths.