Skip to content
Web Image Formats Research Web Image Formats Research

encoder

module src.encoder

Section titled “module src.encoder”

Image encoding module.

This module handles encoding images to various formats (JPEG, WebP, AVIF, JPEG XL) using external command-line tools.

All encode methods force single-threaded mode so that parallelism is handled at the task level (one process per encoding task).

function get_encoder_version

Section titled “function get_encoder_version”
get_encoder_version(encoder: str) → str | None

Get version string for an encoder tool.

Args:

  • encoder: Name of encoder tool (cjpeg, cwebp, avifenc, cjxl)

Returns: Version string or None if unable to determine

class EncodeResult

Section titled “class EncodeResult”

Result of an encoding operation.

method __init__

Section titled “method __init__”
__init__(
    success: bool,
    output_path: Path | None,
    file_size: int | None,
    error_message: str | None = None
) → None

class ImageEncoder

Section titled “class ImageEncoder”

Handles encoding images to various formats.

method __init__

Section titled “method __init__”
__init__(output_dir: Path) → None

Initialize the image encoder.

Args:

  • output_dir: Directory where encoded images will be stored

method encode_avif

Section titled “method encode_avif”
encode_avif(
    input_path: Path,
    quality: int,
    speed: int = 4,
    chroma_subsampling: str | None = None,
    output_name: str | None = None
) → EncodeResult

Encode image to AVIF format.

Args:

  • input_path: Path to the input image
  • quality: Quality setting (0-100)
  • speed: Encoding speed (0-10, higher is faster)
  • chroma_subsampling: Chroma subsampling mode (“444”, “422”, “420”, “400”). If None, avifenc default is used.
  • output_name: Optional output filename (without extension)

Returns: EncodeResult with encoding details

method encode_jpeg

Section titled “method encode_jpeg”
encode_jpeg(
    input_path: Path,
    quality: int,
    output_name: str | None = None
) → EncodeResult

Encode image to JPEG format.

For inputs that cjpeg cannot read directly (e.g. PNG), the image is converted to PPM in memory and piped to cjpeg via stdin, avoiding any temporary files on disk.

Args:

  • input_path: Path to the input image
  • quality: Quality setting (0-100)
  • output_name: Optional output filename (without extension)

Returns: EncodeResult with encoding details

method encode_jxl

Section titled “method encode_jxl”
encode_jxl(
    input_path: Path,
    quality: int,
    effort: int = 7,
    output_name: str | None = None
) → EncodeResult

Encode image to JPEG XL format.

Args:

  • input_path: Path to the input image
  • quality: Quality setting (0-100)
  • effort: Encoder effort setting (1-10, higher is slower/better), default=7
  • output_name: Optional output filename (without extension)

Returns: EncodeResult with encoding details

method encode_webp

Section titled “method encode_webp”
encode_webp(
    input_path: Path,
    quality: int,
    method: int = 4,
    output_name: str | None = None
) → EncodeResult

Encode image to WebP format.

Args:

  • input_path: Path to the input image
  • quality: Quality setting (0-100)
  • method: Compression method (0=fast, 6=slowest), default=4
  • output_name: Optional output filename (without extension)

Returns: EncodeResult with encoding details