Codec options#

When creating a decoder or encoder (C API: nvimgcodecDecoderCreate / nvimgcodecEncoderCreate; Python: nvimgcodec.Decoder(options=...) / nvimgcodec.Encoder(options=...)), you can pass an optional options string to tune behavior. The format is the same for both decoders and encoders; details are below.

Decoder options format#

The options string is a space-separated list of entries. Each entry typically has the form :<option>=<value>. Entries can also be prefixed with a decoder identifier for per-decoder options (e.g., nvjpeg_cuda_decoder:hybrid_huffman_threshold=0).

  • Global options (apply to the generic decoder / framework): use a leading colon with no decoder name:

    :<option>=<value>

    Example: :num_cuda_streams=4 limits the number of CUDA streams used (must be between 1 and the number of worker threads). Unknown global options are ignored.

  • Per-decoder options (passed to specific decoder plugins when they are created):

    • For a specific decoder: <decoder_id>:<parameter_name>=<parameter_value>

      Example: nvjpeg_cuda_decoder:hybrid_huffman_threshold=0. Only the decoder whose id matches will apply the option.

    • For any decoder that understands the option: :<parameter_name>=<parameter_value>

      Example: :fancy_upsampling=1. The full options string is passed to every decoder; each plugin may ignore or honor the parameter (e.g. multiple JPEG decoders can all honor fancy_upsampling).

You can combine multiple options in one string. Examples:

  • :fancy_upsampling=0

  • :fancy_upsampling=0 nvjpeg_cuda_decoder:hybrid_huffman_threshold=0

  • :num_cuda_streams=2 nvjpeg_cuda_decoder:device_memory_padding=0

Decoder IDs are defined by each extension. Pass nullptr or an empty string if you do not need any options.

In the Python API, the default constructor uses options=":fancy_upsampling=0". To use library defaults (e.g. fancy upsampling enabled), pass options="" or omit the argument if your binding allows it.

Options per decoder#

Global (use prefix :; applied by the generic decoder):

  • num_cuda_streams (integer): Number of CUDA streams to use (1 to number of worker threads). Example: :num_cuda_streams=4.

nvjpeg_cuda_decoder (JPEG, CPU/GPU hybrid):

  • fancy_upsampling (0/1): Use “fancy” chroma upsampling. It reduces color bleeding and blockiness around sharp edges by using interpolation instead of simple pixel replication for chroma components. Default: 1 (enabled). Can be switched off with :fancy_upsampling=0. When set to 0, a faster but lower-quality nearest-neighbor upsampling is used instead.

  • hybrid_huffman_threshold (integer): Pixel count above which GPU hybrid Huffman decoding is used. Default: 1000000.

  • device_memory_padding (integer): Device memory padding in bytes.

  • host_memory_padding (integer): Pinned/host memory padding in bytes.

  • preallocate_buffers (0/1): Preallocate internal buffers.

  • extra_flags (integer): Experimental: Extra nvJPEG creation flags.

nvjpeg_hw_decoder (JPEG, hardware-accelerated):

  • fancy_upsampling (0/1): Same as above.

  • preallocate_width_hint (integer): Hint for preallocated buffer width.

  • preallocate_height_hint (integer): Hint for preallocated buffer height.

  • preallocate_batch_size (integer): Batch size for preallocated buffers.

  • extra_flags (integer): Experimental: Extra nvJPEG creation flags.

nvjpeg_lossless_decoder (Lossless JPEG):

  • fancy_upsampling (0/1): Same as above.

  • extra_flags (integer): Experimental: Extra nvJPEG creation flags.

nvjpeg2k_cuda_decoder (JPEG 2000):

  • num_parallel_tiles (integer): Number of tiles decoded in parallel (shared across all threads). Default: 16.

  • device_memory_padding (integer): Device memory padding in bytes.

  • host_memory_padding (integer): Pinned/host memory padding in bytes.

libjpeg_turbo_decoder (JPEG, CPU):

  • fancy_upsampling (0/1): Use fancy upsampling. Default: 1.

  • fast_idct (0/1): libjpeg-turbo-specific option. If set to 1, enables a faster but slightly less accurate integer IDCT (Inverse Discrete Cosine Transform) algorithm provided by libjpeg-turbo. This can offer higher performance for JPEG decoding, with a possible minor reduction in image fidelity compared to the default (more accurate) algorithm. Default value: 0 (higher accuracy).

Currently, other decoders (e.g. nvtiff, libtiff) do not define custom options; they accept the options string but ignore it.

Encoder options format#

The options string uses the same format as decoder options: a space-separated list of entries. Each entry has the form <option>=<value>, optionally prefixed with an encoder identifier.

  • Global options (apply to the generic encoder / framework): use a leading colon with no encoder name:

    :<option>=<value>

    Example: :num_cuda_streams=4 limits the number of CUDA streams (same as for decoders; must be between 1 and the number of worker threads).

  • Per-encoder options: <encoder_id>:<parameter_name>=<parameter_value>

    Only the encoder whose id matches will apply the option. Example: nvjpeg_cuda_encoder:quality=90. You can combine multiple options, e.g. :num_cuda_streams=2 nvjpeg_cuda_encoder:quality=85. Pass nullptr or an empty string if you do not need any options.

Options per encoder#

Global (use prefix :; applied by the generic encoder):

  • num_cuda_streams (integer): Number of CUDA streams to use (1 to number of worker threads). Example: :num_cuda_streams=4.

Encoder IDs (for per-encoder options, <encoder_id>:<option>=<value>). Built-in extensions register the following encoder IDs:

  • nvjpeg_cuda_encoder — JPEG (CPU/GPU hybrid).

  • nvjpeg_hw_encoder — JPEG (hardware-accelerated, when available).

  • nvjpeg2k_encoder — JPEG 2000.

  • nvtiff_cuda_encoder — TIFF.

  • nvpnm_encoder — PNM (PBM/PGM/PPM).

  • nvbmp_encoder — BMP.

  • opencv_jpeg_encoder, opencv_jpeg2k_encoder, opencv_bmp_encoder, opencv_pnm_encoder — OpenCV-based encoders (CPU fallback).

The built-in encoder extensions currently do not define encoder-specific options in the options string; they accept the options string but only global options (e.g. :num_cuda_streams=4) are applied. Quality and similar settings are set per encode via encode parameters (e.g. nvimgcodecEncodeParams_t with quality_type / quality_value). The per-encoder options format in the string is reserved for future use or custom extensions.