go-termimg

README

go-termimg

A Go library for displaying images in terminal emulators using graphics protocols.

Supported Protocols

• Kitty Graphics Protocol - For Kitty and compatible terminals
• Sixel Graphics Protocol - For terminals supporting DEC Sixel (xterm, mlterm, etc.)

Installation

go get github.com/danielgatis/go-termimg

Usage

Simple Usage

package main

import (
    "image"
    _ "image/png"
    "os"

    "github.com/danielgatis/go-termimg/kitty"
    "github.com/danielgatis/go-termimg/sixel"
)

func main() {
    f, _ := os.Open("image.png")
    defer f.Close()
    img, _, _ := image.Decode(f)

    // Kitty protocol
    kitty.Encode(os.Stdout, img)

    // Sixel protocol
    sixel.Encode(os.Stdout, img)
}

With Encoder and Options

package main

import (
    "fmt"
    "image"
    _ "image/png"
    "os"

    "github.com/danielgatis/go-termimg/kitty"
)

func main() {
    f, _ := os.Open("image.png")
    defer f.Close()
    img, _, _ := image.Decode(f)

    enc := kitty.NewEncoder(
        kitty.WithOnBeforeEncode(func() {
            fmt.Println("Starting encoding...")
        }),
        kitty.WithOnAfterEncode(func() {
            fmt.Println("Encoding complete!")
        }),
        kitty.WithOnBeforeEncodeChunk(func(idx int, isLast bool) {
            fmt.Printf("Encoding chunk %d...\n", idx)
        }),
        kitty.WithOnAfterEncodeChunk(func(idx int, isLast bool) {
            if isLast {
                fmt.Printf("Chunk %d encoded (final)\n", idx)
            }
        }),
    )

    enc.Encode(os.Stdout, img)
}

Example CLI

The examples/ directory contains a CLI tool that demonstrates both protocols:

# Display image using Kitty protocol (default)
go run ./examples/main.go image.png

# Display image using Sixel protocol
go run ./examples/main.go -protocol=sixel image.png

# Show encoding progress
go run ./examples/main.go -verbose image.png

Terminal Compatibility

Terminal	Kitty	Sixel
Kitty	✅	❌
WezTerm	✅	✅
iTerm2	✅*	✅
xterm	❌	✅**
mlterm	❌	✅
foot	✅	✅

* iTerm2 uses its own protocol but supports Kitty protocol in recent versions. ** xterm requires -ti vt340 flag for Sixel support.

API Reference

kitty

type Option func(*Encoder)

func WithOnBeforeEncode(fn func()) Option
func WithOnAfterEncode(fn func()) Option
func WithOnBeforeEncodeChunk(fn func(chunkIndex int, isLast bool)) Option
func WithOnAfterEncodeChunk(fn func(chunkIndex int, isLast bool)) Option

func NewEncoder(opts ...Option) *Encoder
func (e *Encoder) Encode(w io.Writer, img image.Image) error

// Helper function
func Encode(w io.Writer, img image.Image) error

sixel

type Option func(*Encoder)

func WithOnBeforeEncode(fn func()) Option
func WithOnAfterEncode(fn func()) Option
func WithOnBeforeEncodeChunk(fn func(chunkIndex int, isLast bool)) Option
func WithOnAfterEncodeChunk(fn func(chunkIndex int, isLast bool)) Option

func NewEncoder(opts ...Option) *Encoder
func (e *Encoder) Encode(w io.Writer, img image.Image) error

// Helper function
func Encode(w io.Writer, img image.Image) error

License

Copyright (c) 2023-present Daniel Gatis

Licensed under MIT License