Sixel Encoding Optimization

[uriyyo]

Sixel Encoding Optimization

Reworked sixel encoding to reduce output size and improve end-to-end terminal rendering performance.

Most of the core compression and emission ideas in this rewrite were adapted from libsixel, with a Python implementation and an optional NumPy-accelerated fast path.

All encoder settings are now grouped in a SixelOptions dataclass for a clean API that is easy to extend.

Encoding speed

Benchmarks were run on two groups of animated image frames:

• smaller sample frames with simple animation and lighter photographic content
• larger HD-style frames resized to a common benchmark resolution, covering natural scenes, space imagery, UI/motion graphics, abstract animation, and noisy/detail-heavy content

On the larger HD-style set, the new encoder is typically faster while also producing much smaller output:

Dataset	Median speedup
Small animated samples	1.06x
Larger HD-style samples	1.77x

Representative results from the larger HD-style set:

Sample type	Speedup
Urban timelapse	1.76x
Colorful abstract animation	2.10x
Natural scene	2.18x
Clean mechanical animation	2.66x
Planet / space imagery	1.83x

Output size reduction

The biggest win is output size, which directly reduces the amount of sixel data written over the PTY.

Dataset	Median reduction
Small animated samples	-63%
Larger HD-style samples	-76%

Representative results from the larger HD-style set:

Sample type	Reduction
Urban timelapse	-70%
Colorful abstract animation	-85%
Natural scene	-84%
Clean mechanical animation	-89%
Planet / space imagery	-91%

Key optimizations

1. Band-based encoding — Processes full 6-row sixel bands at once instead of encoding row-by-row.

2. Interleaved segment emission — Emits non-overlapping color segments in shared sweeps, reducing redundant carriage returns and padding.

3. Fillable first sweep — Uses a libsixel-style fill pass that compresses especially well with RLE.

4. Gap splitting — Large empty gaps are split into separate segments instead of being bridged with excessive ? padding.

5. Palette compaction — Deduplicates colors that map to the same sixel RGB values and reorders palette entries for smaller output.

6. Active color reuse — Avoids re-emitting color-select commands when the same color is already active.

7. NumPy vectorized path — Adds an accelerated path for band packing with a pure-Python fallback.

[uriyyo]

Demo how you can play gif using textual serve in your browser

Screen.Recording.2026-03-30.181124.mp4

[lnqs]

That's impressive. Happy to merge the PR once the conflict is resolved.

[uriyyo]

Hi @lnqs,

I update PR, I used https://github.com/saitoha/libsixel as ref to see what are best ways to optimize sixel encoding.

[uriyyo]

Update PR again to fix all lint errors

[uriyyo]

Now it's green ✅

[lnqs]

Merge and release are on the way, thanks!