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 ¶
- type BlockProtocol
- func (b *BlockProtocol) Delete(id uint32) string
- func (b *BlockProtocol) Place(_ uint32, _, _, _, _ int) string
- func (b *BlockProtocol) Placeholder(width, height int) string
- func (b *BlockProtocol) Prepare(img image.Image, id uint32) (string, error)
- func (b *BlockProtocol) PrepareFromPNG(pngData []byte, id uint32) (string, error)
- func (b *BlockProtocol) TargetPixelSize(widthCells, heightCells int) (pixelWidth, pixelHeight int)
- type Cache
- type ImageProtocol
- type KittyProtocol
- func (k *KittyProtocol) Delete(id uint32) string
- func (k *KittyProtocol) Place(id uint32, row, col, width, height int) string
- func (k *KittyProtocol) Placeholder(width, height int) string
- func (k *KittyProtocol) Prepare(img image.Image, id uint32) (string, error)
- func (k *KittyProtocol) PrepareFromPNG(pngData []byte, id uint32) (string, error)
- func (k *KittyProtocol) TargetPixelSize(widthCells, heightCells int) (pixelWidth, pixelHeight int)
- type Renderer
- func (r *Renderer) Clear() string
- func (r *Renderer) Commit(trackPath string, pngData []byte) string
- func (r *Renderer) CurrentPath() string
- func (r *Renderer) GetPlaceholder() string
- func (r *Renderer) GetPlacementCmd(row, col int) string
- func (r *Renderer) HasImage() bool
- func (r *Renderer) InvalidateCache()
- func (r *Renderer) LoadTrack(trackPath string) []byte
- func (r *Renderer) NeedsLoad(trackPath string) bool
- func (r *Renderer) PrepareFromBytes(data []byte, identifier string) string
- func (r *Renderer) SetSize(width, height int)
- type SixelProtocol
- func (s *SixelProtocol) Delete(id uint32) string
- func (s *SixelProtocol) Place(id uint32, row, col, _, _ int) string
- func (s *SixelProtocol) Placeholder(width, height int) string
- func (s *SixelProtocol) Prepare(img image.Image, id uint32) (string, error)
- func (s *SixelProtocol) PrepareFromPNG(pngData []byte, id uint32) (string, error)
- func (s *SixelProtocol) TargetPixelSize(widthCells, heightCells int) (pixelWidth, pixelHeight int)
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) 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
NewCache creates a new disk cache in the user's cache directory. Returns nil if the cache directory cannot be created.
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) 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) Commit ¶ added in v0.1.47
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 ¶
CurrentPath returns the path of the currently prepared track.
func (*Renderer) GetPlaceholder ¶
GetPlaceholder returns blank space for the layout.
func (*Renderer) GetPlacementCmd ¶
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 ¶
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
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
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
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.
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) 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)