<!-- SPDX-FileCopyrightText: 2025-2026 Coral Pink <coral.pink@disr.it> --> <!-- SPDX-License-Identifier: Apache-2.0 -->

qoi.cr

Implementation of encoder/decoder for QOI format – a simple lossless image format.

Installation

Add this repository as dependency to your shard.yml:

dependencies:
  qoi:
    git: "https://codeberg.org/coralpink/qoi.cr.git"

Usage

Decoding

Read QOI file:

require "qoi"

description, pixels = QOI.decode("./image.qoi")

Read QOI file to raw pixels buffer:

require "qoi"

pixels = IO::Memory.new
description = QOI.decode("./image.qoi", pixels)

Encoding

Write QOI file:

require "qoi"

description = QOI::Description.new(1, 1, :rgb, :srgb)
pixels = [QOI::Pixel.new(0xFF, 0x00, 0x00)]

QOI.encode("./image.qoi", description, pixels)

Write QOI file using raw pixels buffer:

require "qoi"

description = QOI::Description.new(1, 1, :rgb, :srgb)
pixels = IO::Memory.new Bytes[0xFF, 0x00, 0x00]

QOI.encode("./image.qoi", description, pixels)

---

Lower level streaming API is also available, see QOI.encode/QOI.decode sources.

See also test executables: qoi-encode, qoi-decode and qoi-preview (requires SDL3).

shards build --release
./scripts/fetch_test_images.sh

./bin/qoi-preview ./spec/test_images/dice.qoi
./bin/qoi-decode ./spec/test_images/dice.qoi > ./dice.rgb
./bin/qoi-encode -w 800 -h 600 -c 4 -s srgb ./dice.rgb > ./dice.qoi
./bin/qoi-preview ./dice.qoi

# using ImageMagick to convert to QOI/raw RGBA
magick 'le funny meat girl.png' QOI:- | ./bin/qoi-preview
magick 'le funny meat girl.png' RGBA:- | ./bin/qoi-encode -w 256 -h 256 -c 4 | ./bin/qoi-preview

Contributing

Preferably please send patches and/or suggestions to my digital postal box addressed coral dot pink at disr dot it.

License

Licensed under Apache License version 2.0.