Ultraziq Documentation

Build Environment & Dependencies

Core

Built with x265 API version 215

Linux (x86_64) Ubuntu 24.04.3 LTS

GCC: 13.3.0 • NASM: 2.16.01

Windows 11 Pro MinGW-W64

GCC: 13.2.0 • NASM: 2.15

ARM Linux aarch64

Ubuntu: 24.04.3 LTS • GCC: 13.3.0

Quick Setup

Set environment variables to activate your license and link optimized libraries. See details below for system-wide setup.

# Linux / ARM
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/abs/path/to/lib

# Add custom x265 lib paths & license key
export LD_LIBRARY_PATH=/path/to/x265/lib:/path/to/x264/lib:$LD_LIBRARY_PATH
export LICENSEE_KEY=your_key_here

# Windows (Command Prompt)
set PATH=%PATH%;C:\abs\path\to\lib

# Add custom x265 lib paths & license key
set PATH=%PATH%;C:\custom\x265\bin;C:\custom\x266\bin
set LICENSEE_KEY=your_key_here

# Verify
./ultraziq --version

Note: Internet connection required for license synchronization.

Detailed Installation & Verification

Package Structure

bin/: Ultraziq encoder executable
lib/: Optimized shared libraries (.so / .dll)
include/: Header files (uhdkit.h) for API integration

Verification of Dependencies

Ensure Ultraziq is loading the correct library version (API 215) and not a system-default version:

# Linux: Check linked path
ldd ./ultraziq | grep x265
# Output: libx265.so.215 => /path/to/libx265.so.215

Troubleshooting Tip:

If you get "library not found" errors, verify the absolute path in your export command and ensure the user has read permissions for the lib/ folder.

Usage Examples

1. High-Performance Parallel Encoding

./ultraziq --codec hevc --feature seg-parallel --gops 4x8 \
  --input input.yuv --input-res 3840x2160 --fps 60 \
  --bitrate 15000 -o output.hevc

Encodes 4K content using 4 parallel segments with 8 threads each.

2. 3-Stream Adaptive Bitrate Ladder

./ultraziq --feature abr-ladder --split "3[1080p][720p][480p]" \
  --map [1080p] --bitrate 5000 \
  --map [720p] --scale 1280x720 --bitrate 2500 \
  --map [480p] --scale 854x480 --bitrate 1000 \
  --input master.yuv -o ladder_out

Global CLI Options

Executable & Help

--help, -h / --version, -V

Display help text or current version details. Returns 0 on success.

Input & Output Handling

# Positional usage (Implied)
./ultraziq in.yuv out.hevc

The first positional argument is treated as the input; the second as the output bitstream.

Options

--feature <string>

Enable specialized Ultraziq modules.

Feature	Description
`pcs`	Constant performance mode; reactive FPS stabilization.
`multiencoder`	Simultaneous multi-bitrate encodes with analysis reuse.Allows scaling input to multiple resolutions and encoding each resoultion at multiple bitrate/crf/qp values.
`seg-parallel`	Encode multiple Segments in parallel in x265.
`live2pass`	Improves performance by doing a fast first pass on a scaled down resolution of the content and reusing some analysis data from that in the 2nd pass on the original higher resolution content.
`abr-ladder`	End-to-end adaptive bitrate ladder execution.

--flush-pic / --no-flush-pic

Allow flushing of frames at the end of each segment in seg-parallel and live2pass. When disabled, flushing of frames at the end of segment is avoided to get consistent output.

Default:
                enabled

--queue-depth <int>

Set queue-depth for input streams. The bigger the input queue, better the performance but at the cost of memory. If the goal is to minimize memory footprint, smaller queue depth should be specified. If multiple splits with same input resolution specify different queue-depths, max depth is set. Default: keyint

ABR-Ladder Options

--enable-lookahead / --no-enable-lookahead

Enable or disable lookahead for abr-ladder feature. Disabling gives better performance. Default disabled

Performance Control System Options

--fps-set-point <float>

Ultraziq dynamically adjusts internal encoder parameters during encoding to maintain the specified target FPS and ensure consistent performance. Recommended to use when dealing with complex frames. Default = 0(disabled)

--pcs-boost-factor <double>

Hysteresis control for error responsiveness. Higher values increase reaction speed.

--pcs-integral-reset <integer>

Resets the integral component at the specified interval. Very small values may slow the controller. Recommended range: 200–300. Default = 0 (disabled)

--pcs-status-print-interval <integer>

Sets the controller status log interval (in seconds). Effective only when logLevel == 2.

Default =
                1

--pcs-fps-windows <integer>

Number of frames used to compute running FPS for parameter adjustment. Higher values smooth changes; lower values make it more aggressive with potential quality impact. Supported only with x264 PCS.

Default =
                50

Multi-Bitrate Encoder Options

--split <string>

Defines the number of input splits for Adaptive Bitrate (ABR) encoding. Example: -split "2[a][b]" or "3[i0][i1][i2]". The split count must be followed by labels in []. Each label maps CLI options to a specific stream.

--map <string>

Maps settings to a specific split label (e.g., --map [a]). Must match a label from --split and be parsed after it. All parameters following a --map apply only to that stream. Note: preset/tune must be the first options after each --map (if stream-specific).

--scale <WidthxHeight>

Sets resolution for a split stream. The input is downscaled to this size and encoded with parameters defined after its --map. If omitted, the original input resolution is used.

--scaling <string>

Selects downscaling algorithm: lanczos, bicubic, or bilinear. Default = bicubic.

--show-banner

Prints a summary of the configured bitrate ladder.

--bitrate <string>

Comma-separated bitrates (e.g., "1000,2000,3000"). Launches multiple encoder instances—one per bitrate—using the same parameters. Outputs separate bitstreams for each.

--crf <string>

Comma-separated CRF values (e.g., "18,20,30"). Starts multiple encoder instances—one per CRF value—with shared parameters.

--qp <string>

Comma-separated QP values (e.g., "18,20,22"). Starts multiple encoder instances—one per QP value—with shared parameters.

--vbv-bufsize <string>

Comma-separated values (e.g., "7000,5000,3000") setting VBV buffer size per encoder instance.

--vbv-maxrate <string>

Comma-separated values (e.g., "1000,2000,3000") setting VBV max rate per encoder instance.

--vbv-init <string>

Comma-separated float values (e.g., "0.8,0.9,0.7") defining initial VBV buffer occupancy per encoder instance.

Segment Parallel Options

--gops <<NumGops>x<NumThreads>>

Defines number of segment encoders and pool threads per segment. Can be combined with --pools to bind segments to nodes. Supported pool symbols: '+' and '-' (when NumGops > 1). If NumGops = 1, pool thread count must match NumThreads.

--gops-update-rc

Enables rate control synchronization across segments to reduce visual artifacts. Default = enabled.

--p2-gops <<NumGops>x<NumThreads>>

Defines segment encoders and pool threads for second pass (full-resolution pass). Works with --pools similar to --gops. Default = 1x1. Must be configured (along with --gops) for live2pass to be effective.

Live2Pass Options

--p1-gops <<NumGops>x<NumThreads>>

Sets parallel segment encoders and pool threads for first pass (low-resolution pass). Default: single x265 instance,which auto-selects thread count.

--p1-bitrate <integer>

Target bitrate for fast low-resolution first pass. Typically lower than final output bitrate since it applies to scaled-down input.

--p1-vbv-bufsize <integer>

Sets VBV buffer size for first pass (low-resolution).

--p1-vbv-maxrate <integer>

Sets VBV max rate for first pass (low-resolution).

--scaling-threads <integer>

Number of worker threads used for scaling input resolution in pass-1. Default = 1.