KGP — Kitty Graphics Protocol Go Bindings on KGP

Basic Image Display

Mon, 01 Jan 0001 00:00:00 +0000

PNG from File

 go
 
 
package main

import (
 "fmt"
 "os"
 "github.com/SerenaFontaine/kgp"
)

func main() {
 data, err := os.ReadFile("image.png")
 if err != nil {
 panic(err)
 }

 cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(data).
 Build()

 fmt.Print(cmd.Encode())
}

RGBA with Dimensions

PNG embeds dimensions; RGB and RGBA require explicit dimensions.

 go
 
 
rgbaData := kgp.SolidColorImage(800, 600, 255, 0, 0, 255) // Red

cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatRGBA).
 Dimensions(800, 600).
 TransmitDirect(rgbaData).
 Build()
fmt.Print(cmd.Encode())

RGB (24-bit, no alpha)

 go
 
 
import "image"

img := loadYourImage()
rgbData := kgp.ImageToRGB(img)
width, height := img.Bounds().Dx(), img.Bounds().Dy()

cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatRGB).
 Dimensions(width, height).
 TransmitDirect(rgbData).
 Build()
fmt.Print(cmd.Encode())

From image.Image (Convenience)

 go
 
 
img, _ := image.Decode(file)
cmd, err := kgp.TransmitImage(img)
if err != nil {
 panic(err)
}
fmt.Print(cmd.Encode())

Command

Mon, 01 Jan 0001 00:00:00 +0000

Command represents a complete Kitty Graphics Protocol command.

Creating Commands

Commands are created via builders. Do not instantiate Command directly.

 go
 
 
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(data).
 Build() // Returns *Command

Methods

Encode

 go
 
func (c *Command) Encode() string

Returns the complete escape sequence as a string, including the APC delimiters ESC_G and ESC\. Payload data is base64-encoded.

EncodeChunked

 go
 
func (c *Command) EncodeChunked(maxChunkSize int) []string

Splits the payload into multiple escape sequences for chunked transmission. Required when payload exceeds terminal limits (e.g., over SSH).

Multiple Placements

Mon, 01 Jan 0001 00:00:00 +0000

Transmit once, display many times. Saves bandwidth and memory.

Transmit Then Put

 go
 
 
// 1. Transmit image (no display)
transmitCmd := kgp.NewTransmit().
 ImageID(10).
 Format(kgp.FormatPNG).
 TransmitDirect(pngData).
 Build()
fmt.Print(transmitCmd.Encode())

// 2. Create placements
placement1 := kgp.NewPut(10).
 DisplaySize(20, 15).
 ZIndex(1).
 Build()
fmt.Print(placement1.Encode())

placement2 := kgp.NewPut(10).
 DisplaySize(10, 7).
 CellOffset(5, 5).
 Build()
fmt.Print(placement2.Encode())

Same Image, Different Sizes

 go
 
 
transmitCmd := kgp.NewTransmit().
 ImageID(100).
 Format(kgp.FormatPNG).
 TransmitDirect(pngData).
 Build()
fmt.Print(transmitCmd.Encode())

// Small
fmt.Print(kgp.NewPut(100).DisplaySize(5, 5).Build().Encode())
fmt.Print(" ")

// Medium
fmt.Print(kgp.NewPut(100).DisplaySize(8, 8).Build().Encode())
fmt.Print(" ")

// Large
fmt.Print(kgp.NewPut(100).DisplaySize(12, 12).Build().Encode())
fmt.Println()

Placement IDs for Targeting

Use PlacementID when you need to delete or update specific placements.

TransmitBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Builds transmit or transmit+display commands. Transmit uploads image data; transmit+display also creates the initial placement.

Constructors

NewTransmit

 go
 
func NewTransmit() *TransmitBuilder

Creates a transmit-only builder (action t). Image data is uploaded but not displayed. Use with NewPut() for placements.

NewTransmitDisplay

 go
 
func NewTransmitDisplay() *TransmitBuilder

Creates a transmit-and-display builder (action T). Uploads and displays in one command.

Methods

Image Identification

Method	Signature	Description
`ImageID`	`(id uint32)`	Set image ID (auto-generated if omitted)
`ImageNumber`	`(num uint32)`	Set image number (application-specific, non-unique)

Format & Dimensions

Method	Signature	Description
`Format`	`(format Format)`	Set format: `FormatRGB`, `FormatRGBA`, `FormatPNG`
`Dimensions`	`(width, height int)`	Required for RGB/RGBA formats

Transmission

Method	Signature	Description
`TransmitDirect`	`(data []byte)`	Embed data in escape sequence (default)
`TransmitFile`	`(path string)`	Read from file path
`TransmitFileWithOffset`	`(path string, offset, size int)`	Read from file with byte range
`ValidateTempPath`	`(path string) error`	Validate temporary-file path requirement
`TryTransmitTemp`	`(path string) (*TransmitBuilder, error)`	Temporary file with error return on invalid path
`TransmitTemp`	`(path string)`	Temporary file; panics if path is invalid
`TransmitSharedMemory`	`(name string, size int)`	POSIX shared memory object
`Compress`	`()`	Enable ZLIB compression (use with pre-compressed data)

Placement Options

Method	Signature	Description
`PlacementID`	`(id uint32)`	Set placement ID for initial placement
`CellOffset`	`(x, y int)`	Pixel offset within starting cell
`DisplaySize`	`(columns, rows int)`	Display size in terminal cells
`SourceRect`	`(x, y, width, height int)`	Crop source to rectangle
`ZIndex`	`(z int)`	Z-index (negative=below text, positive=above)
`CursorMovement`	`(move bool)`	`true`=cursor moves after, `false`=stays
`RelativeTo`	`(parentImageID, parentPlacementID uint32, offsetH, offsetV int)`	Relative positioning
`VirtualPlacement`	`()`	Invisible placement for Unicode placeholders

Response

Method	Signature	Description
`ResponseSuppression`	`(mode ResponseSuppression)`	`ResponseAll`, `ResponseErrorsOnly`, `ResponseOKOnly`

Build

 go
 
func (tb *TransmitBuilder) Build() *Command

Constructs the final *Command. Call exactly once per builder.

Cropping and Scaling

Mon, 01 Jan 0001 00:00:00 +0000

Source Rect (Crop)

Display only a portion of the source image.

 go
 
 
// Display top-left 400×300 region
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(pngData).
 SourceRect(0, 0, 400, 300).
 Build()
fmt.Print(cmd.Encode())

Display Size (Scale)

Control how many terminal cells the image occupies.

 go
 
 
// Crop center 100×100, display in 10×10 cells
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(largePNG).
 SourceRect(50, 50, 100, 100).
 DisplaySize(10, 10).
 Build()
fmt.Print(cmd.Encode())

Put with Crop and Scale

 go
 
 
// Already transmitted image ID 20
place := kgp.NewPut(20).
 SourceRect(100, 100, 200, 200). // Crop
 DisplaySize(15, 15). // Scale
 Build()
fmt.Print(place.Encode())

Cell Offset

Position the image within the starting cell.

PutBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Creates placement commands for existing images. Use after NewTransmit() to display an image in multiple locations or with different display parameters.

Constructor

NewPut

 go
 
func NewPut(imageID uint32) *PutBuilder

Creates a put builder for the specified image. The image must already exist (transmitted previously).

Methods

Image & Placement Identification

Method	Signature	Description
`ImageNumber`	`(num uint32)`	Application-specific image number (non-unique)
`PlacementID`	`(id uint32)`	Set placement ID (auto-generated if omitted)

Display Options

Method	Signature	Description
`CellOffset`	`(x, y int)`	Pixel offset within starting cell
`DisplaySize`	`(columns, rows int)`	Display size in terminal cells
`SourceRect`	`(x, y, width, height int)`	Display only a region of the source image
`ZIndex`	`(z int)`	Z-index (negative=below text, positive=above)
`CursorMovement`	`(move bool)`	`true`=cursor advances, `false`=cursor stays
`RelativeTo`	`(parentImageID, parentPlacementID uint32, offsetH, offsetV int)`	Position relative to parent placement
`VirtualPlacement`	`()`	Invisible placement for Unicode placeholders

Response

Method	Signature	Description
`ResponseSuppression`	`(mode ResponseSuppression)`	Control which responses are sent

Build

 go
 
func (pb *PutBuilder) Build() *Command

DeleteBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Builds delete commands. Delete modes determine what is removed and whether image data is freed.

Constructor

NewDelete

 go
 
func NewDelete(mode DeleteMode) *DeleteBuilder

Creates a delete builder. The mode must be one of the DeleteBy* constants.

Methods

Mode-specific parameters (call only the ones relevant to the chosen mode):

Method	Signature	Used With Modes
`ImageID`	`(id uint32)`	`DeleteByImageID`, `DeleteByImageIDFree`
`ImageNumber`	`(num uint32)`	`DeleteByImageNumber`, `DeleteByImageNumberFree`
`PlacementID`	`(id uint32)`	`DeleteByPlacementID`, `DeleteByPlacementIDFree`
`Cell`	`(x, y int)`	`DeleteByCell`, `DeleteByCellFree`
`Column`	`(x int)`	`DeleteByColumn`, `DeleteByColumnFree`
`Row`	`(y int)`	`DeleteByRow`, `DeleteByRowFree`
`ZIndex`	`(z int)`	`DeleteByZIndex`, `DeleteByZIndexFree`
`IDRange`	`(startID, endID int)`	`DeleteByIDRange`, `DeleteByIDRangeFree`

Method	Signature	Description
`ResponseSuppression`	`(mode ResponseSuppression)`	Control responses

Note: For DeleteByImageID, DeleteByImageIDFree, DeleteByPlacementID, and DeleteByPlacementIDFree, you must also set ImageID via ImageID() when the mode requires it. The protocol uses i for both image ID and (in some modes) other purposes; the builder maps these correctly.

Z-Index Layering

Mon, 01 Jan 0001 00:00:00 +0000

Control whether images appear above or below text.

Negative z-index: below text (background)
Positive z-index: above text (overlay)
Zero: default (implementation-defined)

Background Image

 go
 
 
bgCmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(bgData).
 ZIndex(-10).
 CursorMovement(false).
 Build()
fmt.Print(bgCmd.Encode())
fmt.Println("Text rendered on top of the image")

Foreground Overlay

 go
 
 
fgCmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(iconData).
 ZIndex(10).
 Build()
fmt.Print(fgCmd.Encode())

Layered Composition

 go
 
 
// Back layer
fmt.Print(kgp.NewTransmitDisplay().
 ImageID(1).
 Format(kgp.FormatPNG).
 TransmitDirect(bgData).
 ZIndex(-2).
 CursorMovement(false).
 Build().Encode())

// Middle layer
fmt.Print(kgp.NewTransmitDisplay().
 ImageID(2).
 Format(kgp.FormatPNG).
 TransmitDirect(midData).
 ZIndex(-1).
 CursorMovement(false).
 Build().Encode())

// Front layer
fmt.Print(kgp.NewTransmitDisplay().
 ImageID(3).
 Format(kgp.FormatPNG).
 TransmitDirect(fgData).
 ZIndex(1).
 Build().Encode())

Animation Builders

Mon, 01 Jan 0001 00:00:00 +0000

Animation support uses three builders: FrameBuilder (add frames), AnimateBuilder (control playback), and ComposeBuilder (compose frames).

FrameBuilder

Adds animation frames to an existing image.

NewFrame

 go
 
func NewFrame(imageID uint32) *FrameBuilder

Methods

Method	Signature	Description
`FrameData`	`(data []byte)`	Raw frame image data
`Format`	`(format Format)`	Format for frame (required for RGB/RGBA)
`Dimensions`	`(width, height int)`	Required for RGB/RGBA
`FrameNumber`	`(frameNum uint32)`	Edit existing frame (replace instead of append)
`BackgroundFrame`	`(frameNum uint32)`	Frame to use as background (0 = base image)
`Gap`	`(milliseconds uint32)`	Delay before next frame in ms
`Composition`	`(mode CompositionMode)`	`CompositionBlend` or `CompositionReplace`
`BackgroundColor`	`(rgba uint32)`	32-bit RGBA background color
`ResponseSuppression`	`(mode ResponseSuppression)`	Control responses

AnimateBuilder

Controls animation playback.

Deletion

Mon, 01 Jan 0001 00:00:00 +0000

Delete All Placements

Keep image data in memory for reuse:

 go
 
fmt.Print(kgp.DeleteAll().Encode())

Free everything:

 go
 
fmt.Print(kgp.DeleteAllFree().Encode())

Delete by Image ID

 go
 
 
fmt.Print(kgp.DeleteImage(10).Encode()) // Preserve data
fmt.Print(kgp.DeleteImageFree(10).Encode()) // Free memory

Delete at Cursor

 go
 
fmt.Print(kgp.DeleteAtCursor().Encode())

Delete by Z-Index

 go
 
 
cmd := kgp.NewDelete(kgp.DeleteByZIndex).
 ZIndex(5).
 Build()
fmt.Print(cmd.Encode())

Delete by Placement ID

 go
 
 
cmd := kgp.NewDelete(kgp.DeleteByPlacementID).
 ImageID(100).
 PlacementID(2).
 Build()
fmt.Print(cmd.Encode())

Delete by Cell Coordinates

 go
 
 
cmd := kgp.NewDelete(kgp.DeleteByCell).
 Cell(10, 5).
 Build()
fmt.Print(cmd.Encode())

Delete by Image ID Range

 go
 
 
cmd := kgp.NewDelete(kgp.DeleteByIDRange).
 IDRange(10, 50).
 Build()
fmt.Print(cmd.Encode())

Free memory for a range of image IDs:

Animation

Mon, 01 Jan 0001 00:00:00 +0000

Basic Animation Flow

Transmit base frame (or first frame)
Add frames with NewFrame
Create placement
Control playback with NewAnimate or helpers

Transmit Base, Add Frames

 go
 
 
// Base image (frame 0)
baseCmd := kgp.NewTransmit().
 ImageID(20).
 Format(kgp.FormatPNG).
 TransmitDirect(frame0Data).
 Build()
fmt.Print(baseCmd.Encode())

// Frame 1
frame1Cmd := kgp.NewFrame(20).
 FrameData(frame1Data).
 Gap(100).
 Build()
fmt.Print(frame1Cmd.Encode())

// Frame 2 with composition
frame2Cmd := kgp.NewFrame(20).
 Format(kgp.FormatRGBA).
 Dimensions(80, 80).
 FrameData(frame2Data).
 Gap(100).
 BackgroundFrame(0).
 Composition(kgp.CompositionBlend).
 Build()
fmt.Print(frame2Cmd.Encode())

Playback Control

 go
 
 
// Play once
fmt.Print(kgp.PlayAnimation(20).Encode())

// Loop infinitely
fmt.Print(kgp.PlayAnimationLoop(20).Encode())

// Stop at current frame
fmt.Print(kgp.StopAnimation(20).Encode())

// Reset to first frame
fmt.Print(kgp.ResetAnimation(20).Encode())

Custom Loop Count

Loop count follows the Kitty protocol: 0 is ignored, 1 means infinite, and N>1 loops N-1 times.

QueryBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Queries terminal capabilities. Send a minimal graphics command; the terminal responds with OK if supported.

Constructor

NewQuery

 go
 
func NewQuery() *QueryBuilder

Methods

Method	Signature	Description
`Format`	`(format Format)`	Format to test
`Dimensions`	`(width, height int)`	Test dimensions
`TransmitMedium`	`(medium TransmitMedium)`	Medium to test
`TestData`	`(data []byte)`	Minimal payload (e.g., 3 bytes for RGB)

Build

 go
 
func (qb *QueryBuilder) Build() *Command

QuerySupport

Convenience function for the most common query:

Relative Positioning

Mon, 01 Jan 0001 00:00:00 +0000

Place child images relative to a parent placement. Useful for overlays, badges, and anchored UI elements.

Parent and Child

 go
 
 
// Parent image
parentCmd := kgp.NewTransmitDisplay().
 ImageID(100).
 PlacementID(1).
 Format(kgp.FormatPNG).
 TransmitDirect(parentData).
 Build()
fmt.Print(parentCmd.Encode())

// Child: 10 cells right, 0 cells down from parent
childCmd := kgp.NewPut(100).
 PlacementID(2).
 RelativeTo(100, 1, 10, 0).
 Build()
fmt.Print(childCmd.Encode())

RelativeTo Parameters

 go
 
RelativeTo(parentImageID, parentPlacementID uint32, offsetH, offsetV int)

parentImageID — Image ID of the parent
parentPlacementID — Placement ID of the parent
offsetH — Horizontal offset in cells (positive = right)
offsetV — Vertical offset in cells (positive = down)

Badge on Avatar

 go
 
 
// Avatar (parent)
avatarCmd := kgp.NewTransmitDisplay().
 ImageID(50).
 PlacementID(1).
 Format(kgp.FormatPNG).
 TransmitDirect(avatarData).
 Build()
fmt.Print(avatarCmd.Encode())

// Transmit badge (no display)
fmt.Print(kgp.NewTransmit().
 ImageID(51).
 Format(kgp.FormatPNG).
 TransmitDirect(badgeData).
 Build().Encode())

// Badge (child) — top-right of avatar
badgeCmd := kgp.NewPut(51).
 PlacementID(1).
 DisplaySize(2, 2).
 RelativeTo(50, 1, 8, -1).
 Build()
fmt.Print(badgeCmd.Encode())

Response

Mon, 01 Jan 0001 00:00:00 +0000

Parsed terminal response to a graphics command.

Struct

 go
 
 
type Response struct {
 ImageID uint32 // Assigned image ID
 ImageNumber uint32 // Assigned image number (if requested)
 PlacementID uint32 // Assigned placement ID
 Success bool // true if OK
 ErrorCode string // e.g., "ENOSPC", "ENOENT", "EINVAL"
 Message string // Error message (if any)
}

ParseResponse

 go
 
func ParseResponse(response string) (*Response, error)

Parses a terminal response string in permissive mode. This parser accepts responses with or without APC markers and tolerates unknown/malformed control-data pairs when possible.

Chunked Transmission

Mon, 01 Jan 0001 00:00:00 +0000

For large images or remote connections (e.g., SSH), split the payload into chunks. The terminal reassembles them.

Basic Chunking

 go
 
 
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(largePNGData).
 Build()

chunks := cmd.EncodeChunked(4096)
for _, chunk := range chunks {
 fmt.Print(chunk)
}

Chunk Size Requirements

Maximum: 4096 bytes per chunk
Alignment: Must be divisible by 4 (base64 encoding)

 go
 
 
// Valid
cmd.EncodeChunked(4096)
cmd.EncodeChunked(2048)
cmd.EncodeChunked(1024)

// Invalid — will panic
cmd.EncodeChunked(4097) // > 4096
cmd.EncodeChunked(1002) // not divisible by 4

When to Use Chunking

Large PNG or RGBA payloads that exceed terminal limits
Slow or unreliable connections (SSH, serial)
Some terminal implementations enforce payload size limits

Constants

Mon, 01 Jan 0001 00:00:00 +0000

Formats

Constant	Value	Description
`FormatRGB`	24	24-bit RGB (3 bytes per pixel)
`FormatRGBA`	32	32-bit RGBA (4 bytes per pixel, default)
`FormatPNG`	100	PNG with embedded dimensions

Transmit Mediums

Constant	Value	Description
`TransmitDirect`	`"d"`	Embed data in escape sequence (default)
`TransmitFile`	`"f"`	Read from regular file
`TransmitTemp`	`"t"`	Temporary file (terminal deletes after read)
`TransmitSharedMem`	`"s"`	POSIX shared memory

Compression

Constant	Value
`CompressionZlib`	`"z"`

Delete Modes

Preserve data (lowercase): Delete placement(s) but keep image data in memory.

Compression

Mon, 01 Jan 0001 00:00:00 +0000

ZLIB compression reduces payload size for raw RGB/RGBA data. PNG is already compressed.

Compress RGBA

 go
 
 
rgbaData := kgp.SolidColorImage(800, 600, 255, 0, 0, 255)
compressed, err := kgp.CompressZlib(rgbaData)
if err != nil {
 panic(err)
}

cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatRGBA).
 Dimensions(800, 600).
 Compress().
 TransmitDirect(compressed).
 Build()
fmt.Print(cmd.Encode())

TransmitImageRGBA Helper

 go
 
 
// With compression
cmd, err := kgp.TransmitImageRGBA(img, true)
if err != nil {
 panic(err)
}
fmt.Print(cmd.Encode())

// Without compression
cmd, err = kgp.TransmitImageRGBA(img, false)

When to Compress

Raw RGBA/RGB: Often benefits from compression, especially for gradients or similar colors
PNG: Already compressed; no need for Compress()
Solid colors: Compression may not help much; test for your use case

Helper Functions

Mon, 01 Jan 0001 00:00:00 +0000

Convenience functions for common operations.

Transmit Helpers

TransmitImage

 go
 
func TransmitImage(img image.Image) (*Command, error)

Transmits and displays an image.Image as PNG. Uses image/png for encoding.

TransmitImageWithID

 go
 
func TransmitImageWithID(img image.Image, imageID uint32) (*Command, error)

Same as TransmitImage but with a specific image ID.

TransmitImageRGBA

 go
 
func TransmitImageRGBA(img image.Image, compress bool) (*Command, error)

Transmits as raw RGBA. If compress is true, applies ZLIB compression.

Delete Helpers

Function	Description
`DeleteAll()`	Delete all placements, preserve data
`DeleteAllFree()`	Delete all and free memory
`DeleteImage(imageID uint32)`	Delete placements of image, preserve data
`DeleteImageFree(imageID uint32)`	Delete image and free memory
`DeleteAtCursor()`	Delete at cursor, preserve data
`DeleteAtCursorFree()`	Delete at cursor and free

Animation Helpers

Function	Description
`PlayAnimation(imageID uint32)`	Play using protocol `LoopCount(2)`
`PlayAnimationLoop(imageID uint32)`	Play with infinite looping
`PlayAnimationWithLoopCount(imageID, count uint32)`	Play with explicit protocol loop-count value
`StopAnimation(imageID uint32)`	Stop at current frame
`ResetAnimation(imageID uint32)`	Stop and reset to first frame

Image Utilities

Conversion

Function	Description
`ImageToRGBA(img image.Image) []byte`	Convert to raw RGBA bytes
`ImageToRGB(img image.Image) []byte`	Convert to raw RGB bytes
`ImageToPNG(img image.Image) ([]byte, error)`	Encode as PNG

Compression

 go
 
func CompressZlib(data []byte) ([]byte, error)

Compresses data with ZLIB (RFC 1950). Use with TransmitDirect() and Compress().

File and Shared Memory Transmission

Mon, 01 Jan 0001 00:00:00 +0000

Alternatives to embedding data directly in escape sequences.

Transmit from File

 go
 
 
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitFile("/path/to/image.png").
 Build()
fmt.Print(cmd.Encode())

File with Offset and Size

Read a byte range from the file:

 go
 
 
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitFileWithOffset("/path/to/image.png", 1024, 50000).
 Build()
fmt.Print(cmd.Encode())

Temporary File

The terminal deletes the file after reading. Path must contain tty-graphics-protocol for security.

 go
 
 
path := "/tmp/tty-graphics-protocol-" + strconv.Itoa(os.Getpid()) + ".png"
_ = os.WriteFile(path, pngData, 0644)
defer os.Remove(path)

cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitTemp(path). // panics if path is invalid
 Build()
fmt.Print(cmd.Encode())

Temporary File (Non-Panicking)

 go
 
 
path := "/tmp/tty-graphics-protocol-" + strconv.Itoa(os.Getpid()) + ".png"
_ = os.WriteFile(path, pngData, 0644)
defer os.Remove(path)

tb := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG)

if _, err := tb.TryTransmitTemp(path); err != nil {
 log.Fatal(err)
}

cmd := tb.
 Build()
fmt.Print(cmd.Encode())

Shared Memory (POSIX)

Most efficient for local applications. Create a shared memory object and pass its name and size.

Error Handling

Mon, 01 Jan 0001 00:00:00 +0000

Parse terminal responses to detect and handle errors.

Basic Parsing

 go
 
 
resp, err := kgp.ParseResponse(responseStr)
if err != nil {
 fmt.Println("Invalid response format:", err)
 return
}

if resp.Success {
 fmt.Printf("Image ID: %d, Placement ID: %d\n", resp.ImageID, resp.PlacementID)
} else {
 fmt.Printf("Error: %s - %s\n", resp.ErrorCode, resp.Message)
}

Error Code Handling

 go
 
 
resp, err := kgp.ParseResponse(responseStr)
if err != nil {
 return err
}

if !resp.Success {
 switch resp.ErrorCode {
 case "ENOSPC":
 // Storage quota exceeded — delete old images
 fmt.Print(kgp.DeleteAllFree().Encode())
 // Retry...
 case "ENOENT":
 // Image not found — may have been deleted
 case "EINVAL":
 // Invalid parameters — check your command
 case "EIO":
 // I/O error — terminal problem
 default:
 fmt.Printf("Unknown error: %s - %s\n", resp.ErrorCode, resp.Message)
 }
}

Suppressing OK Responses

Reduce response traffic when you don’t need confirmation:

Demo Application

Mon, 01 Jan 0001 00:00:00 +0000

The examples/demo package provides an interactive walkthrough of KGP features.

Running the Demo

 bash
 
 
cd examples/demo
go run .

Place a file named sf.png in the demo directory for the external PNG loading demo.

Demo Sequence

Image Formats — PNG, RGBA, RGB
Compression — ZLIB compressed RGBA
External PNG — Load from sf.png
Cropping and Scaling — Source rect and display size
Multiple Placements — One image, multiple displays
Placement Sizes — Same image at different cell sizes
Z-Index — Background image behind text
Query Support — Check terminal capabilities
Animation — Color-changing square with movement

Code Structure

 go
 
 
// Clear screen
fmt.Print("\x1b[2J\x1b[H")

// Create image data
redSquare := createColoredSquare(100, 100, color.RGBA{R: 255, G: 0, B: 0, A: 255})
pngData, _ := kgp.ImageToPNG(redSquare)

// Transmit and display
cmd := kgp.NewTransmitDisplay().
 ImageID(1).
 Format(kgp.FormatPNG).
 TransmitDirect(pngData).
 ResponseSuppression(kgp.ResponseErrorsOnly).
 Build()
fmt.Print(cmd.Encode())

Helper Functions in Demo

createColoredSquare(width, height, color) — Solid color image
createGradientSquare(width, height) — Gradient for cropping demo
clearScreen() — ANSI clear and home
waitForEnter(reader) — Pause for user input

Terminal Support

Mon, 01 Jan 0001 00:00:00 +0000

The Kitty Graphics Protocol is supported by:

Terminal	Support	Notes
Kitty	Full	Version 0.19.0+
WezTerm	Partial	Core features supported
Konsole	Experimental	KDE Konsole

Verify Support

Before rendering graphics, check support:

 go
 
 
cmd := kgp.QuerySupport()
fmt.Print(cmd.Encode())
// Terminal responds with OK if supported

Performance Tips

Local applications: Use TransmitSharedMemory for best performance
Remote applications: Use PNG format to reduce transmission size
Large images: Enable compression with Compress()
Repeated images: Use placements (NewPut) instead of re-transmitting
Animations: Use gap frames and frame composition efficiently