Termext - Terminal Extensions for OCaml#

A clean OCaml library implementing Kitty terminal protocols for enhanced terminal output.

Overview#

Termext provides OCaml bindings for modern terminal protocols:

• Text Sizing: The Kitty text sizing protocol for rendering text at different sizes
• Graphics: The Kitty graphics protocol for displaying images and animations

Features#

Text Sizing (Textsize module)#

• ✨ Clean, type-safe API with validation
• 🎯 Full protocol support (scale, width, fractional sizing, alignment)
• 🚀 Convenient helper functions (double, triple, superscript, subscript)
• 📐 Fmt-style formatters

Graphics (Termgraph module - In Development)#

• 🖼️ PNG image display
• 📁 File and direct transmission
• 🎬 Animation support
• 🎨 Z-index layering
• 📦 Fmt-style formatters
• 🎯 Type-safe placement control

Installation#

# Via opam (once published)
opam install termext

# Or add to your dune-project dependencies
(depends
  (termext (>= 0.1.0)))

Quick Start#

Text Sizing#

(* Simple convenience functions *)
print_string (Termext.Textsize.double "Hello, World!");;
print_string (Termext.Textsize.triple "Big Text");;
print_string (Termext.Textsize.half "Small text");;

(* Superscripts and subscripts *)
print_string "E=mc";
print_string (Termext.Textsize.superscript "2");;

print_string "H";
print_string (Termext.Textsize.subscript "2");
print_string "O";;

(* Fmt integration *)
Fmt.pr "The answer is %a\n"
  (Termext.Textsize.styled_double Fmt.int) 42;;

Graphics (Preview)#

(* Display a PNG file *)
print_string (Termext.Termgraph.display_png_file "image.png");;

(* With size control *)
print_string (Termext.Termgraph.display_png_file
  ~rows:10
  ~columns:20
  "logo.png");;

(* Fmt integration *)
let img = Termext.Termgraph.v
  ~rows:15
  (Termext.Termgraph.File { path = "banner.png" })
  ()
in
Fmt.pr "Welcome! %a\n" Termext.Termgraph.pp img;;

(* Animation *)
let anim_id = Termext.Termgraph.image_id_of_string "spinner" in
let frame1 = Termext.Termgraph.Animation.frame
  ~gap:100
  (Termext.Termgraph.File { path = "frame1.png" })
  1
in
print_string (Termext.Termgraph.Animation.render_frame anim_id frame1);;

API Overview#

Textsize Module#

Types & Builders

• vertical, horizontal - Alignment types
• v ?scale ?width ?fraction ?vertical ?horizontal () - Create sizing metadata
• empty - Empty metadata

Convenience Functions

• double, triple, quadruple - Quick size multipliers
• half - Half-sized text
• superscript, subscript - Typographic positioning
• scaled n - Arbitrary scale factor

Rendering

• render metadata text - Generate escape sequence
• render_to_channel oc metadata text - Write to channel
• pp, styled - Fmt formatters

Termgraph Module (In Development)#

Core Types

• format - RGB, RGBA, PNG
• compression - No_compression, Zlib
• transmission - Direct, File
• image_id, placement_id - Identifiers

Placement

• v ?image_id ?x ?y ?width ?height ?rows ?columns ?z_index transmission () - Create placement

Animation

• Animation.frame - Define animation frames
• Animation.render_frame - Upload frames
• Animation.render_control - Control playback

Deletion

• Delete.render - Delete images by various criteria

Convenience

• display_png_file - Quick PNG display
• display_png_bytes - Display PNG from bytes
• pp, pp_delete, pp_animation_* - Fmt formatters

See TODO.md for implementation status and roadmap.

Building from Source#

cd termext
dune build
dune exec example/demo.exe           # Text sizing demo
dune exec example/graphics_demo.exe  # Graphics demo (requires PNG files)

Terminal Compatibility#

This library generates escape sequences for Kitty terminal protocols.

Text Sizing Protocol:

• ✅ Kitty (v0.40.0+)
• ✅ Ghostty

Graphics Protocol:

• ✅ Kitty
• ✅ Ghostty
• ⚠️ WezTerm (partial support)
• ⚠️ Konsole (partial support)

Other terminals will typically ignore these sequences gracefully (no errors, just no special rendering).

Protocol Reference#

Text Sizing: OSC 66 sequences - ESC ] 66 ; metadata ; text BEL

• See: Kitty Text Sizing Protocol

Graphics: APC sequences - ESC _G<control>;<payload>ESC \

• See: Kitty Graphics Protocol

Dependencies#

• fmt: Formatting library (already widely used)
• base64: Base64 encoding for graphics transmission
• camlzip: Zlib compression for graphics (optional optimization)

License#

MIT

Contributing#

Contributions welcome! Please feel free to submit issues or pull requests.