albumart

package
v0.1.50 Latest Latest
Warning

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

Go to latest
Published: Sep 21, 2026 License: GPL-3.0 Imports: 25 Imported by: 0

Documentation

Overview

Package albumart provides terminal-based album cover rendering using Kitty or Sixel graphics protocols.

Package albumart provides terminal-based album cover rendering using Kitty graphics protocol.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BlockProtocol added in v0.1.49

type BlockProtocol struct {
	// contains filtered or unexported fields
}

BlockProtocol renders cover art with unicode half blocks. It is the fallback for terminals that support neither Kitty nor Sixel graphics (Alacritty, plain xterm, Terminal.app), where the other protocols emit escapes the terminal silently drops (issue #30).

Unlike Kitty and Sixel, the art is plain text: it goes into the view through Placeholder instead of being written over it with cursor moves, because Bubble Tea truncates rendered lines to the terminal width and would cut it.

func NewBlockProtocol added in v0.1.49

func NewBlockProtocol() *BlockProtocol

NewBlockProtocol creates a block renderer using the terminal's color profile, so 256-color and 16-color terminals get downsampled colors instead of truecolor escapes they cannot honor.

func (*BlockProtocol) Delete added in v0.1.49

func (b *BlockProtocol) Delete(id uint32) string

Delete forgets the image. Nothing to erase in the terminal: the art is text that the next frame overwrites. A stale ID is ignored, so dropping the previous track's image never wipes the one that just replaced it.

func (*BlockProtocol) Place added in v0.1.49

func (b *BlockProtocol) Place(_ uint32, _, _, _, _ int) string

Place emits nothing: the art is already in the view via Placeholder.

func (*BlockProtocol) Placeholder added in v0.1.49

func (b *BlockProtocol) Placeholder(width, height int) string

Placeholder returns the art itself, padded to exactly width x height cells so the surrounding layout never shifts. Blank when no image is prepared.

func (*BlockProtocol) Prepare added in v0.1.49

func (b *BlockProtocol) Prepare(img image.Image, id uint32) (string, error)

func (*BlockProtocol) PrepareFromPNG added in v0.1.49

func (b *BlockProtocol) PrepareFromPNG(pngData []byte, id uint32) (string, error)

func (*BlockProtocol) TargetPixelSize added in v0.1.49

func (b *BlockProtocol) TargetPixelSize(widthCells, heightCells int) (pixelWidth, pixelHeight int)

TargetPixelSize maps one cell to one pixel wide and two pixels tall.

type Cache added in v0.1.37

type Cache struct {
	// contains filtered or unexported fields
}

Cache provides disk-based caching for resized album art images.

func NewCache added in v0.1.37

func NewCache(baseDir string) (*Cache, error)

NewCache creates a new disk cache in the user's cache directory. Returns nil if the cache directory cannot be created.

func (*Cache) Get added in v0.1.37

func (c *Cache) Get(trackPath string, width, height int) []byte

Get retrieves cached PNG data for a track at specific dimensions. Returns nil if not cached.

func (*Cache) Put added in v0.1.37

func (c *Cache) Put(trackPath string, width, height int, data []byte) error

Put stores PNG data for a track at specific dimensions.

type ImageProtocol added in v0.1.42

type ImageProtocol interface {
	// Prepare encodes the image and returns any one-time terminal command.
	// Kitty: transmits to terminal memory, returns escape sequences.
	// Sixel: encodes and caches internally, returns empty string.
	Prepare(img image.Image, id uint32) (string, error)

	// PrepareFromPNG same but from pre-encoded PNG data.
	PrepareFromPNG(pngData []byte, id uint32) (string, error)

	// Place returns the escape sequence to display the image at (row, col).
	// Kitty: references by ID (lightweight).
	// Sixel: emits full image data with cursor positioning.
	Place(id uint32, row, col, width, height int) string

	// Delete returns the escape sequence to remove the image.
	// Sixel: no-op (returns "").
	Delete(id uint32) string

	// Placeholder returns blank space string for lipgloss layout measurement.
	Placeholder(width, height int) string

	// TargetPixelSize returns the pixel dimensions to use when resizing an
	// image that will be displayed in the given number of terminal cells.
	// Kitty: uses standard 8x16 cell assumptions.
	// Sixel: queries actual cell pixel size and leaves 1 row of vertical
	// margin to prevent terminal scroll when the image is near the bottom.
	TargetPixelSize(widthCells, heightCells int) (pixelWidth, pixelHeight int)
}

ImageProtocol abstracts the terminal image display protocol (Kitty or Sixel).

func Detect added in v0.1.42

func Detect() ImageProtocol

Detect returns the best available ImageProtocol for the current terminal. It never returns nil except for an explicit "none" override: terminals with no graphics protocol fall back to unicode half blocks.

Detection asks the terminal itself. Environment variables are useless here: a terminal launched from another one inherits its variables (alacritty started from ghostty keeps TERM_PROGRAM=ghostty), and TERM says nothing about sixel support.

The WAVES_IMAGE_PROTOCOL environment variable can override detection:

  • "kitty": force Kitty protocol
  • "sixel": force Sixel protocol
  • "blocks": force the unicode half-block renderer
  • "none": disable image display

type KittyProtocol added in v0.1.42

type KittyProtocol struct{}

KittyProtocol implements ImageProtocol using the Kitty graphics protocol.

func (*KittyProtocol) Delete added in v0.1.42

func (k *KittyProtocol) Delete(id uint32) string

func (*KittyProtocol) Place added in v0.1.42

func (k *KittyProtocol) Place(id uint32, row, col, width, height int) string

func (*KittyProtocol) Placeholder added in v0.1.42

func (k *KittyProtocol) Placeholder(width, height int) string

func (*KittyProtocol) Prepare added in v0.1.42

func (k *KittyProtocol) Prepare(img image.Image, id uint32) (string, error)

func (*KittyProtocol) PrepareFromPNG added in v0.1.42

func (k *KittyProtocol) PrepareFromPNG(pngData []byte, id uint32) (string, error)

func (*KittyProtocol) TargetPixelSize added in v0.1.42

func (k *KittyProtocol) TargetPixelSize(widthCells, heightCells int) (pixelWidth, pixelHeight int)

type Renderer

type Renderer struct {
	// contains filtered or unexported fields
}

Renderer handles album cover rendering with a terminal image protocol.

func New

func New(protocol ImageProtocol) *Renderer

New creates a new album art renderer with the given protocol and disk caching.

func (*Renderer) Clear

func (r *Renderer) Clear() string

Clear removes the current image from terminal memory.

func (*Renderer) Commit added in v0.1.47

func (r *Renderer) Commit(trackPath string, pngData []byte) string

Commit installs art loaded by LoadTrack and returns the command to write to the terminal. pngData may be nil, meaning the track has no cover: the previous image is then dropped. Cheap, so it belongs in Update.

func (*Renderer) CurrentPath

func (r *Renderer) CurrentPath() string

CurrentPath returns the path of the currently prepared track.

func (*Renderer) GetPlaceholder

func (r *Renderer) GetPlaceholder() string

GetPlaceholder returns blank space for the layout.

func (*Renderer) GetPlacementCmd

func (r *Renderer) GetPlacementCmd(row, col int) string

GetPlacementCmd returns the command to place the image at given position. row and col are 1-based terminal coordinates.

It also re-emits the removal of images replaced since the last frame. A removal returned by Commit is only written once, and skipping tracks quickly overwrites it before it reaches the terminal, leaving ghost art on screen (issue #30). Repeating a removal is a no-op for every protocol.

func (*Renderer) HasImage

func (r *Renderer) HasImage() bool

HasImage returns true if there's a prepared image for the current track.

func (*Renderer) InvalidateCache

func (r *Renderer) InvalidateCache()

InvalidateCache clears the cached path so the next PrepareTrack call will re-extract and re-transmit the album art, even for the same path.

func (*Renderer) LoadTrack added in v0.1.47

func (r *Renderer) LoadTrack(trackPath string) []byte

LoadTrack reads the cover out of a track and resizes it, returning PNG data for Commit. It reads the audio file — hundreds of KB, over the network for a remote library — and resizes it, so it must run off the UI goroutine: it holds no lock while working, only snapshotting the target size (issue #49).

Returns nil when the track has no usable cover, which Commit still needs to know about so it can drop the previous image.

func (*Renderer) NeedsLoad added in v0.1.47

func (r *Renderer) NeedsLoad(trackPath string) bool

NeedsLoad reports whether art still has to be loaded for a track. Cheap, so the UI can ask before starting a load.

func (*Renderer) PrepareFromBytes added in v0.1.28

func (r *Renderer) PrepareFromBytes(data []byte, identifier string) string

PrepareFromBytes prepares album art from raw image bytes. Returns the transmission command that should be written to the terminal once. Returns empty string if already prepared or no cover art. The identifier is used to track if the image has changed.

func (*Renderer) SetSize

func (r *Renderer) SetSize(width, height int)

SetSize sets the display dimensions in terminal cells.

type SixelProtocol added in v0.1.42

type SixelProtocol struct {
	// contains filtered or unexported fields
}

SixelProtocol implements ImageProtocol using the Sixel graphics protocol.

func NewSixelProtocol added in v0.1.42

func NewSixelProtocol() *SixelProtocol

NewSixelProtocol creates a new SixelProtocol instance. It queries the terminal for actual cell pixel dimensions via TIOCGWINSZ.

func (*SixelProtocol) Delete added in v0.1.42

func (s *SixelProtocol) Delete(id uint32) string

func (*SixelProtocol) Place added in v0.1.42

func (s *SixelProtocol) Place(id uint32, row, col, _, _ int) string

func (*SixelProtocol) Placeholder added in v0.1.42

func (s *SixelProtocol) Placeholder(width, height int) string

func (*SixelProtocol) Prepare added in v0.1.42

func (s *SixelProtocol) Prepare(img image.Image, id uint32) (string, error)

func (*SixelProtocol) PrepareFromPNG added in v0.1.42

func (s *SixelProtocol) PrepareFromPNG(pngData []byte, id uint32) (string, error)

func (*SixelProtocol) TargetPixelSize added in v0.1.42

func (s *SixelProtocol) TargetPixelSize(widthCells, heightCells int) (pixelWidth, pixelHeight int)

Jump to

Keyboard shortcuts

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