ui

Documentation

Index

• Constants
• Variables
• func ApplyThemeColors(t theme.Theme)
• func SetPadding(h, v int)
• func VisModeNames() []string
• type LuaVisRenderer
• type VisAnalysisSpec
  • func NormalizeAnalysisSpec(spec VisAnalysisSpec) VisAnalysisSpec
• type VisMode
  • func StringToVisModeExact(name string) (VisMode, bool)
• type VisTickContext
• type Visualizer
  • func NewVisualizer(sampleRate float64) *Visualizer
  • func (v *Visualizer) AllModeNames() []string
  • func (v *Visualizer) Analyze(samples []float64, spec VisAnalysisSpec) []float64
  • func (v *Visualizer) Bands() []float64
  • func (v *Visualizer) ConsumeRefresh() bool
  • func (v *Visualizer) CycleMode()
  • func (v *Visualizer) EnsureSampleBuf(size int) []float64
  • func (v *Visualizer) Frame() uint64
  • func (v *Visualizer) ModeName() string
  • func (v *Visualizer) RefreshPending() bool
  • func (v *Visualizer) RegisterLuaVisualizers(names []string, renderer LuaVisRenderer)
  • func (v *Visualizer) Render() string
  • func (v *Visualizer) RequestRefresh()
  • func (v *Visualizer) SampleBuf() []float64
  • func (v *Visualizer) SetMode(mode VisMode)
  • func (v *Visualizer) SmoothedBands() []float64
  • func (v *Visualizer) Tick(ctx VisTickContext)
  • func (v *Visualizer) TickInterval(ctx VisTickContext) time.Duration

Constants

const (
	TickAnim    = 16 * time.Millisecond  // ~60 FPS — smooth bar/wave/scope animation cadence
	TickWave    = TickAnim               // ~60 FPS — waveform modes (no FFT)
	TickFast    = 50 * time.Millisecond  // 20 FPS — per-frame-animated spectrum modes
	TickAnalyze = 33 * time.Millisecond  // ~30 Hz — FFT analysis cadence (independent of animation)
	TickSlow    = 200 * time.Millisecond // 5 FPS — visualizer off or overlay
	// TickLowPowerPlaying keeps playback bookkeeping responsive while avoiding
	// the 20 FPS time/seek refresh cost when low-power mode is enabled.
	TickLowPowerPlaying = 500 * time.Millisecond // 2 FPS — low-power playback UI cadence
	// TickIdle is used when the player is stopped or paused with nothing
	// animating (no overlay, no buffering, no pending status / reconnect).
	// Bubbletea wakes immediately on key / IPC / MPRIS / plugin messages, so
	// the tick at this cadence only services time-based self-changes
	// (status-message expiry, log-line aging) — those tolerate the latency.
	TickIdle = 1500 * time.Millisecond // ~0.7 Hz — fully idle, minimal CPU
)

Tick intervals: fast for visualizer animation, slow for time/seek display.

const (
	DefaultSpectrumBands = 10

	DefaultVisRows = 5
)

Variables

var (
	ColorTitle   color.Color = lipgloss.ANSIColor(10) // bright green
	ColorText    color.Color = lipgloss.ANSIColor(15) // bright white
	ColorDim     color.Color = lipgloss.ANSIColor(7)  // white (light gray)
	ColorAccent  color.Color = lipgloss.ANSIColor(11) // bright yellow
	ColorPlaying color.Color = lipgloss.ANSIColor(10) // bright green
	ColorSeekBar color.Color = lipgloss.ANSIColor(11) // bright yellow
	ColorVolume  color.Color = lipgloss.ANSIColor(2)  // green
	ColorError   color.Color = lipgloss.ANSIColor(9)  // bright red
	ColorKeyBG   color.Color = lipgloss.ANSIColor(8)  // bright black (dark gray)
	ColorKeyFG   color.Color = lipgloss.ANSIColor(15) // bright white

	// Spectrum gradient: green -> yellow -> red
	SpectrumLow  color.Color = lipgloss.ANSIColor(10) // bright green
	SpectrumMid  color.Color = lipgloss.ANSIColor(11) // bright yellow
	SpectrumHigh color.Color = lipgloss.ANSIColor(9)  // bright red
)

CLIAMP color palette using standard ANSI terminal colors (0-15). These adapt to the user's terminal theme for consistent appearance.

var FrameStyle = lipgloss.NewStyle().
	Padding(paddingV, PaddingH).
	Width(80)

FrameStyle is the outer frame style for the TUI.

var PaddingH = 3

PaddingH is the horizontal padding inside the frame.

var PanelWidth = 80 - 2*PaddingH

PanelWidth is the usable inner width of the frame. Updated dynamically in WindowSizeMsg based on terminal width.

Functions

func ApplyThemeColors

func ApplyThemeColors(t theme.Theme)

ApplyThemeColors updates all color variables and rebuilds spectrum styles. If the theme is the default (empty hex values), ANSI fallback colors are restored.

func SetPadding

func SetPadding(h, v int)

SetPadding updates the frame padding and derived styles.

func VisModeNames

func VisModeNames() []string

VisModeNames returns the display names of all built-in visualizer modes.

Types

type LuaVisRenderer

type LuaVisRenderer func(name string, bands [DefaultSpectrumBands]float64, rows, cols int, frame uint64) string

LuaVisRenderer is the callback type for rendering a Lua visualizer frame.

type VisAnalysisSpec

type VisAnalysisSpec struct {
	BandCount int
	FFTSize   int
}

func NormalizeAnalysisSpec

func NormalizeAnalysisSpec(spec VisAnalysisSpec) VisAnalysisSpec

type VisMode

type VisMode int

VisMode selects the visualizer rendering style.

const (
	VisBars        VisMode = iota // smooth fractional blocks
	VisBarsDot                    // bars with braille dot stipple
	VisRain                       // falling rain droplets within bar shapes
	VisBarsOutline                // top-edge outline of bars
	VisBricks                     // solid bricks with gaps
	VisColumns                    // many thin columns
	VisClassicPeak                // classic falling peak caps over thin columns
	VisWave                       // braille waveform oscilloscope
	VisScatter                    // braille particle sparkle
	VisFlame                      // braille rising flame tendrils
	VisRetro                      // 80s synthwave perspective grid with wave
	VisPulse                      // braille pulsating circle
	VisMatrix                     // falling matrix rain characters
	VisBinary                     // streaming binary 0s and 1s
	VisSakura                     // falling cherry blossom petals
	VisFirework                   // exploding firework bursts
	VisBubbles                    // rising hollow ring bubbles
	VisLogo                       // CLIAMP pixel text
	VisTerrain                    // scrolling side-view mountain range
	VisScope                      // Lissajous XY oscilloscope
	VisHeartbeat                  // ECG pulse monitor trace
	VisButterfly                  // mirrored Rorschach spectrum
	VisAscii                      // dense shade-block columns (website style)
	VisFirefly                    // firefly meadow at dusk
	VisMosaic                     // static heatmap of flickering tiles
	VisSand                       // falling-sand cellular automaton
	VisGeyser                     // bass-driven particle fountain
	VisClassicLED                 // Winamp 2.9 LED matrix with falling peak caps
	VisNone                       // hidden — no visualizer
	VisCount                      // sentinel for cycling
)

func StringToVisModeExact

func StringToVisModeExact(name string) (VisMode, bool)

StringToVisModeExact converts a name to VisMode, returning false if not found.

type VisTickContext

type VisTickContext struct {
	Now           time.Time
	Playing       bool
	Paused        bool
	OverlayActive bool
	Analyze       func(VisAnalysisSpec) []float64
}

type Visualizer

type Visualizer struct {
	Mode VisMode
	Rows int // display height in terminal rows (default 5)
	// contains filtered or unexported fields
}

Visualizer performs FFT analysis and renders spectrum bars.

func NewVisualizer

func NewVisualizer(sampleRate float64) *Visualizer

NewVisualizer creates a Visualizer for the given sample rate.

func (*Visualizer) AllModeNames

func (v *Visualizer) AllModeNames() []string

AllModeNames returns the display names of every selectable visualizer mode in cycle order: built-in modes followed by any registered Lua visualizers. The index of each name equals its VisMode value, so a picker can map a list row directly to a mode.

func (*Visualizer) Analyze

func (v *Visualizer) Analyze(samples []float64, spec VisAnalysisSpec) []float64

Analyze runs FFT on raw audio samples and returns normalized band levels (0-1).

func (*Visualizer) Bands

func (v *Visualizer) Bands() []float64

Bands returns the current spectrum band values.

func (*Visualizer) ConsumeRefresh

func (v *Visualizer) ConsumeRefresh() bool

func (*Visualizer) CycleMode

func (v *Visualizer) CycleMode()

CycleMode advances to the next visualizer mode, including Lua visualizers.

func (*Visualizer) EnsureSampleBuf

func (v *Visualizer) EnsureSampleBuf(size int) []float64

func (*Visualizer) Frame

func (v *Visualizer) Frame() uint64

Frame returns the current animation frame counter.

func (*Visualizer) ModeName

func (v *Visualizer) ModeName() string

ModeName returns the display name of the current mode.

func (*Visualizer) RefreshPending

func (v *Visualizer) RefreshPending() bool

RefreshPending reports whether a refresh has been requested.

func (*Visualizer) RegisterLuaVisualizers

func (v *Visualizer) RegisterLuaVisualizers(names []string, renderer LuaVisRenderer)

RegisterLuaVisualizers adds Lua visualizer names so they can be cycled through with the v key. renderer is called when a Lua visualizer is active.

func (*Visualizer) Render

func (v *Visualizer) Render() string

Render dispatches to the active visualizer mode.

func (*Visualizer) RequestRefresh

func (v *Visualizer) RequestRefresh()

func (*Visualizer) SampleBuf

func (v *Visualizer) SampleBuf() []float64

SampleBuf returns the internal sample buffer (for slicing after SamplesInto).

func (*Visualizer) SetMode

func (v *Visualizer) SetMode(mode VisMode)

SetMode switches to mode if it is within range (built-in or Lua) and requests a refresh. Out-of-range values are ignored, matching the SetVisualizer guard.

func (*Visualizer) SmoothedBands

func (v *Visualizer) SmoothedBands() []float64

SmoothedBands returns the eased per-frame band values used by spectrum renderers. Falls back to the raw bands until smoothing has run at least once.

func (*Visualizer) Tick

func (v *Visualizer) Tick(ctx VisTickContext)

func (*Visualizer) TickInterval

func (v *Visualizer) TickInterval(ctx VisTickContext) time.Duration