Skip to content
KN-86 Deckline

libcaca — Colour ASCII Art Library

  • Source: https://github.com/cacalabs/libcaca · upstream: http://caca.zoy.org/wiki/libcaca
  • Category: tech / effect — the canonical C library for colour ASCII / text-mode graphics
  • Role for KN-86: the engine reference for converting raster imagery (and via cacaview, video frames) into colour text art for the TUI. Where react-video-ascii defines the interaction grammar in ascii-effects.md, libcaca defines the rendering pipeline.
  • License / caveats: multiple licenses in-repo — WTFPL (the headline license), GPL-2.0, ISC, LGPL-2.1. Permissive enough to study and link; note which component you use so the resulting derivative inherits the right license. We are not vendoring libcaca code; the value is technique reference from a well-aged, well-understood implementation.

What it is

Section titled “What it is”

libcaca is the de-facto C library for colour ASCII / text-mode graphics, originally authored by Sam Hocevar and a long-running project in the demoscene / terminal-graphics adjacency. It exposes a small, stable C API for drawing primitives (lines, boxes, text, images, palette manipulation) and renders to a configurable target via build-time configure flags:

  • ncurses (the most common Linux terminal path)
  • SLang (an alternative terminal abstraction)
  • conio (MS-DOS, historical)
  • native X11 (no terminal at all — direct framebuffer)
  • OpenGL (3D-accelerated)
  • Win32 console
  • Network server mode — render once, serve to many connected clients

It ships two practically useful CLI tools:

  • img2txt — convert any image format Imlib2 can read into colour ASCII or HTML
  • cacaview — an interactive image viewer rendered in the terminal

And it has bindings for Python, PHP, C#, Java, Ruby, and Perl — making it the closest thing to a lingua-franca for image-to-text conversion across language ecosystems.

Key takeaways for KN-86

Section titled “Key takeaways for KN-86”
  • The engine reference for ASCII rendering on KN-86. Per the project-wide ASCII Effect Spec, the rendering pipeline KN-86 commits to is libcaca-shaped: input raster image → glyph-cell quantization → render to text grid with foreground + background color per cell. libcaca’s img2txt is the closest single working reference for the algorithm we need to ship.
  • CPU-only path matters for the Pi Zero 2 W. react-video-ascii is the interaction-grammar north star but it’s WebGL2-accelerated — a path the KN-86 hardware can’t follow on-device. libcaca is CPU-only and well-tuned. On-device KN-86 rendering follows libcaca’s algorithmic shape; on-emulator KN-86 rendering can optionally use a GPU-accelerated path that matches.
  • Multi-target abstraction lesson. libcaca’s render-target indirection (ncurses / SLang / conio / X11 / OpenGL / Win32 / network) is the right architectural shape for KN-86’s desktop emulator + Pi VT framebuffer + headless test harness split. The same draw API, three targets, no per-target conditionals at the application layer.
  • Dithering modes. libcaca documents and implements several dithering modes (none, ordered2/4/8, Floyd-Steinberg, etc.) for the image→cell quantization. For KN-86’s monochrome amber renders, Floyd-Steinberg on the luminance channel against the amber palette ramp is the right starting point. Worth documenting in the ASCII Effect Spec under “Open questions” as a dithering-mode selection follow-up.
  • cacaview as an authoring tool. Cart authors who want to preview ASCII art for their carts can use libcaca’s cacaview against their source imagery to iterate the visual before committing it to the cart bundle. Not part of the KN-86 runtime, but worth mentioning in the cart-authoring SDK docs.
  • Network server mode is a strong architectural pattern for the desktop emulator’s debug overlay — one running instance serving multiple connected debug clients. Not v0.1 but worth knowing as a reference pattern.

What we do not lift

Section titled “What we do not lift”
  • The HTML output target. img2txt --format html emits HTML with inline styles. Not relevant; KN-86 doesn’t render to HTML.
  • The Win32 console target. Not relevant.
  • MS-DOS conio. Not relevant.

License notes

Section titled “License notes”
  • Multiple licenses in-repo. The project headline is WTFPL (“Do What the Fuck You Want To Public License”) — maximally permissive. But individual files carry GPL-2.0, ISC, and LGPL-2.1 in specific cases.
  • KN-86 implementation note: since we’re studying libcaca as technique reference and writing our own implementation against the algorithm — not vendoring libcaca code — the license-mixing concern doesn’t propagate to KN-86 runtime code. KN-86 ships its own implementation under whatever license KN-86 commits to project-wide.
  • If we ever wanted to link against libcaca directly (e.g., shell out from a desktop tool to img2txt to convert cart-author imagery), the per-binary licensing inheritance becomes relevant; check at that point.

Image

Section titled “Image”

libcaca repo social card

GitHub repo social card from opengraph.githubassets.com/1/cacalabs/libcaca — the project’s headline framing on the GitHub social-share preview. Used here because the repo doesn’t carry a hero screenshot in the README.

Notes

Section titled “Notes”
  • Cross-link ascii-effects.md — the project-wide spec libcaca is the engine reference for.
  • Cross-link react-video-ascii.md — the interaction-grammar sibling; libcaca is the engine; react-video-ascii is the API shape.
  • Cross-link asciinator (Batch 3) — the halfblock-▀ rendering technique; libcaca implements that technique among others.
  • Cross-link no-more-secrets (Batch 4) — the decryption-reveal effect; libcaca + no-more-secrets together cover the static + animated ASCII surfaces.
  • Worth a periodic check on upstream. libcaca is mature but still maintained; the cacalabs/libcaca fork on GitHub tracks the upstream caca.zoy.org work. A quarterly check on the algorithms and any new render targets is worth the few minutes.