Kitty Graphics Protocol in OCaml
anil.recoil.org
terminal
graphics
ocaml
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Data Transmission Method
7
8 Specifies how image data is transmitted to the terminal.
9
10 {2 Protocol Details}
11
12 The transmission method is specified via the [t] key in the control data:
13 - [t=d] for direct (inline) transmission (default)
14 - [t=f] for regular file
15 - [t=t] for temporary file (deleted after reading)
16
17 {2 Direct Transmission}
18
19 [{`Direct}] sends data inline within the escape sequence itself. The data is
20 base64-encoded in the payload section. This is the simplest method and works
21 over any connection (including SSH).
22
23 For images larger than 4096 bytes (after base64 encoding), the data is
24 automatically split into chunks using the [m=] key:
25 - [m=1] indicates more chunks follow
26 - [m=0] indicates the final chunk
27
28 {2 File Transmission}
29
30 [{`File}] tells the terminal to read data from a file path. The path is sent
31 base64-encoded in the payload. Additional parameters:
32 - [S=] specifies the number of bytes to read
33 - [O=] specifies the byte offset to start reading from
34
35 File transmission only works when the terminal and client share a filesystem
36 (i.e., local terminals, not SSH).
37
38 Security: The terminal will refuse to read device files, sockets, or files
39 in sensitive locations like [/proc], [/sys], or [/dev].
40
41 {2 Temporary File Transmission}
42
43 [{`Tempfile}] is like [{`File}] but the terminal deletes the file after
44 reading. The file must be in a recognized temporary directory:
45 - [/tmp]
46 - [/dev/shm]
47 - The [TMPDIR] environment variable location
48 - Platform-specific temp directories containing [tty-graphics-protocol] *)
49
50type t = [ `Direct | `File | `Tempfile ]
51(** Transmission methods.
52
53 - [`Direct] - Data is sent inline in the escape sequence (base64-encoded).
54 Works over any connection including SSH. Automatic chunking for large
55 images.
56 - [`File] - Terminal reads from a file path sent in the payload. Only works
57 when terminal and client share a filesystem.
58 - [`Tempfile] - Like [`File] but terminal deletes the file after reading.
59 File must be in a recognized temporary directory. *)
60
61val to_char : t -> char
62(** Convert to protocol character.
63
64 Returns ['d'] for [`Direct], ['f'] for [`File], or ['t'] for [`Tempfile].
65 These values are used in the [t=] control data key. *)