Ultraziq Documentation

Build Environment & Dependencies

Core

Built with x265 API version 215

Linux (x86_64)

GCC: 13.3.0 • NASM: 2.16.01

Windows 11 Pro MinGW-W64

GCC: 13.2.0 • NASM: 2.15

ARM Linux aarch64

GCC: 13.3.0 • NASM: 2.16.01

Setup & Requirements

Configure your environment to link the Ultraziq toolkit and activate your license. Ensure you have extracted the package and have your LICENSEE_KEY ready.

Environment Activation

# LINUX / ARM (BASH)
# 1. Link the dynamic libraries of the extracted Ultraziq package & x265
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/ultraziq/lib

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/x265/lib

# 2. Activate your license key
export LICENSEE_KEY=your_key_here

# WINDOWS (CMD)
# 1. Add bin and lib to system path of the extracted Ultraziq package & x265
set PATH=%PATH%;C:\path\to\ultraziq\bin;C:\path\to\ultraziq\lib

set PATH=%PATH%;C:\path\to\x265\lib

# 2. Activate your license key
set LICENSEE_KEY=your_key_here

Note: To make these changes permanent, add the export commands to your ~/.bashrc (Linux) or use setx (Windows).

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 Installation

Confirm that Ultraziq is using the correct optimized libraries and that your license is active:

# Verify Version & Codec
./ultraziq --version

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

Troubleshooting:

If you see "library not found", verify that the path in LD_LIBRARY_PATH matches your actual extraction folder exactly. For permission issues, Ensure the lib/ folder has read & execute permissions.

Build x265 from Source

Linux & ARM (BASH)

Required for systems where x265 libraries are not pre-installed. Supports both x86_64 and aarch64 architectures.

# 1. Install Build Dependencies
sudo apt-get update
sudo apt-get install -y cmake gcc g++ nasm git

# 2. Clone Official Repository
git clone https://bitbucket.org/multicoreware/x265_git.git
cd x265_git/build/linux

# 3. Compile & Install - The toolkit requires API version 215
cmake ../../source
make -j $(nproc)
sudo make install
sudo ldconfig

Note: Ensure your linker paths(LD_LIBRARY_PATH) are updated to include the newly built x265.so.

Windows (MinGW-W64)

Required if x265 libraries are not pre-installed. On Windows, MinGW-w64 is recommended to ensure binary compatibility

# 1. Use MSYS2 Terminal
pacman -S mingw-w64-x86_64-cmake \
          mingw-w64-x86_64-gcc \
          mingw-w64-x86_64-nasm

# 2. Clone & Build
git clone https://bitbucket.org/multicoreware/x265_git.git
cd x265_git/build/msys

# 3. Configure & Compile
./make-Makefiles.sh
make -j $(nproc)
make install

Note: Ensure your linker paths(LD_LIBRARY_PATH) are updated to include the newly built x265.dll.

Usage Examples

1. High-Performance Parallel Encoding

./ultraziq --codec hevc --feature seg-parallel --gops 4x8 --no-open-gop --no-scenecut \
  --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 \
  --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.