anil.recoil.org
Kitty Graphics Protocol in OCaml
terminal
graphics
ocaml
files
+137
+49
.tangled/workflows/build.yml
+49
.tangled/workflows/build.yml
···
1
+
when:
2
+
- event: ["push", "pull_request"]
3
+
branch: ["main"]
4
+
5
+
engine: nixery
6
+
7
+
dependencies:
8
+
nixpkgs:
9
+
- shell
10
+
- stdenv
11
+
- findutils
12
+
- binutils
13
+
- libunwind
14
+
- ncurses
15
+
- opam
16
+
- git
17
+
- gawk
18
+
- gnupatch
19
+
- gnum4
20
+
- gnumake
21
+
- gnutar
22
+
- gnused
23
+
- gnugrep
24
+
- diffutils
25
+
- gzip
26
+
- bzip2
27
+
- gcc
28
+
- ocaml
29
+
30
+
steps:
31
+
- name: opam
32
+
command: |
33
+
opam init --disable-sandboxing -any
34
+
- name: switch
35
+
command: |
36
+
opam install . --confirm-level=unsafe-yes --deps-only
37
+
- name: build
38
+
command: |
39
+
opam exec -- dune build
40
+
- name: switch-test
41
+
command: |
42
+
opam install . --confirm-level=unsafe-yes --deps-only --with-test
43
+
- name: test
44
+
command: |
45
+
opam exec -- dune runtest --verbose
46
+
- name: doc
47
+
command: |
48
+
opam install -y odoc
49
+
opam exec -- dune build @doc
+18
LICENSE.md
+18
LICENSE.md
···
1
+
(*
2
+
* ISC License
3
+
*
4
+
* Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>
5
+
*
6
+
* Permission to use, copy, modify, and distribute this software for any
7
+
* purpose with or without fee is hereby granted, provided that the above
8
+
* copyright notice and this permission notice appear in all copies.
9
+
*
10
+
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11
+
* WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12
+
* MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13
+
* ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14
+
* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15
+
* ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16
+
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17
+
*
18
+
*)
+66
README.md
+66
README.md
···
1
+
# kgp - Kitty Graphics Protocol for OCaml
2
+
3
+
An OCaml library for displaying images in terminals using the [Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
4
+
5
+
This library can display PNG images in supported terminals (e.g. Kitty, WezTerm, Konsole, Ghostty) with varying levels of support depending on the terminal. Most core features work but some advanced things like animations might be only partially supported outside of Kitty.
6
+
7
+
Other features include:
8
+
- Image transmission with automatic chunking and base64 encoding
9
+
- Multiple placements of the same image
10
+
- Animation support with frame deltas
11
+
- Unicode placeholder mode for proper scrolling
12
+
- tmux passthrough support (requires tmux 3.3+)
13
+
- Terminal capability detection
14
+
15
+
The library provides a Cmdliner term via the `kgp.cli` package to make integration into other CLI tools easier.
16
+
17
+
## Installation
18
+
19
+
```
20
+
opam install kgp
21
+
```
22
+
23
+
## Usage
24
+
25
+
### Library
26
+
27
+
```ocaml
28
+
(* Display a PNG image *)
29
+
let png_data = read_file "image.png" in
30
+
let cmd = Kgp.transmit_and_display ~format:`Png () in
31
+
let buf = Buffer.create 1024 in
32
+
Kgp.write buf cmd ~data:png_data;
33
+
print_string (Buffer.contents buf)
34
+
```
35
+
36
+
```ocaml
37
+
(* Transmit once, display multiple times *)
38
+
let cmd = Kgp.transmit ~image_id:1 ~format:`Png () in
39
+
Kgp.write buf cmd ~data:png_data;
40
+
41
+
let cmd = Kgp.display ~image_id:1 () in
42
+
Kgp.write buf cmd ~data:""
43
+
```
44
+
45
+
### CLI
46
+
47
+
```
48
+
# Display an image
49
+
kgpcat image.png
50
+
51
+
# Display at specific size and position
52
+
kgpcat --place 40x20@10,5 image.png
53
+
54
+
# Display from stdin
55
+
curl -s https://example.com/image.png | kgpcat
56
+
57
+
# Detect terminal support
58
+
kgpcat --detect-support
59
+
60
+
# Clear displayed images
61
+
kgpcat --clear
62
+
```
63
+
64
+
## License
65
+
66
+
ISC