media

package
v0.120.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 3, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package media normalises binary media (currently images) so that it can be attached to an LLM message without exhausting the context window or breaching a provider payload limit.

The entry point is Normalize. It decodes an image, scales it down until it fits a pixel and byte budget, and re-encodes it. Encoding may change format (a large PNG screenshot usually becomes a JPEG) because a lossless format often cannot meet a byte budget at a useful resolution.

Index

Constants

View Source
const (
	MediaTypePNG  = "image/png"
	MediaTypeJPEG = "image/jpeg"
	MediaTypeGIF  = "image/gif"
	MediaTypeWebP = "image/webp"
)

Media type constants for the image formats this package understands.

View Source
const (
	// DefaultMaxEdge is the largest allowed width or height, in pixels.
	DefaultMaxEdge = 1568
	// DefaultMaxEncodedBytes is the largest allowed encoded payload, in
	// bytes, measured before base64 expansion.
	DefaultMaxEncodedBytes = 3_500_000
	// IngestLimitBytes is a hard ceiling on the on-disk size of a file
	// this package will even attempt to decode. It guards against a
	// decompression bomb and against loading a huge file into memory.
	IngestLimitBytes = 20 * 1024 * 1024
	// MaxDecodePixels caps the pixel count of an image this package will
	// decode. The byte limit alone is not enough: a flat image deflates to
	// almost nothing, so a file far below IngestLimitBytes can declare a
	// canvas that needs gigabytes of pixel storage. 50 million pixels is
	// about 200 MB as RGBA, and still holds an 8K screenshot.
	MaxDecodePixels = 50_000_000
)

Default limits. These match the behaviour of comparable agents, but the maximum edge is lower than a naive 2000 px: providers downscale an image whose long edge is above roughly 1568 px anyway, so extra pixels only cost bytes, never detail.

Variables

View Source
var (
	// ErrNotImage reports that the data is not a supported image format.
	ErrNotImage = errors.New("not a supported image")
	// ErrTooLarge reports that the file is above the ingest limit and was
	// never decoded.
	ErrTooLarge = errors.New("media exceeds ingestion limit")
	// ErrDecode reports that the data could not be decoded as an image.
	ErrDecode = errors.New("image could not be decoded")
	// ErrIrreducible reports that the image could not be made to fit the
	// configured budget.
	ErrIrreducible = errors.New("image could not be resized below the size limit")
)

Errors returned by this package. Callers should compare with errors.Is.

Functions

func DetectMediaType

func DetectMediaType(data []byte, name string) string

DetectMediaType returns the image media type of data, using the file signature first and the file name extension as a fallback. It returns an empty string when the data is not a supported image.

func IsImageExt

func IsImageExt(name string) bool

IsImageExt reports whether name has an extension this package can decode. Use it for a cheap check before a file is read.

Types

type Limits

type Limits struct {
	// MaxEdge is the largest allowed width or height, in pixels.
	MaxEdge int
	// MaxEncodedBytes is the largest allowed encoded payload, in bytes.
	MaxEncodedBytes int
	// NoResize rejects an oversized image instead of scaling it down.
	NoResize bool
}

Limits holds the budget applied to an image. A zero field means "use the default", so the zero Limits value is the default policy.

type Result

type Result struct {
	// Data is the encoded image payload.
	Data []byte
	// MediaType is the MIME type of Data. It can differ from the input
	// media type when re-encoding changed the format.
	MediaType string
	// Width and Height are the pixel dimensions of Data.
	Width, Height int
	// Resized reports whether the image was scaled down.
	Resized bool
	// OriginalWidth and OriginalHeight are the dimensions before scaling.
	OriginalWidth, OriginalHeight int
	// OriginalBytes is the length of the input payload.
	OriginalBytes int
}

Result is a normalised image ready to attach to a message.

func Normalize

func Normalize(data []byte, name string, limits Limits) (Result, error)

Normalize decodes data, scales it down if it is above the budget in limits, and returns an encoded image that fits. The name is used only to help detect the media type and in error messages.

Normalize returns the original bytes untouched when the image already fits, so a small image costs one decode and no re-encode.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL