Add Geyser visualizer and tune Sand bass sensitivity

Geyser is a particle fountain rooted at the bottom of the panel: bass
transients eject thick jets that arc back under gravity, sustained loud
passages keep a steady column going, and quiet sections drip. Particles
inherit a tier from the band that produced them, so heavy bass paints
the spray red.

Sand's bass triggers were also tightened so gentler kicks register —
transient + sustained thresholds dropped, and the explosion gate fires
on a smaller fill so it actually triggers during normal listening.

Also factor out a shared Braille-grid rasteriser used by Geyser (and
ready for any future visualizer drawing to a 4x2 dot subgrid).

Author: bjarneo

docs/configuration.md

@@ -44,7 +44,7 @@ eq_preset = "Flat"
 eq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 
 # Visualizer mode (leave empty for default Bars)
-# Options: Bars, BarsDot, Rain, BarsOutline, Bricks, Columns, ClassicPeak, Wave, Scatter, Flame, Retro, Pulse, Matrix, Binary, Sakura, Firework, Bubbles, Logo, Terrain, Scope, Heartbeat, Butterfly, Ascii, Firefly, Mosaic, Sand, None
+# Options: Bars, BarsDot, Rain, BarsOutline, Bricks, Columns, ClassicPeak, Wave, Scatter, Flame, Retro, Pulse, Matrix, Binary, Sakura, Firework, Bubbles, Logo, Terrain, Scope, Heartbeat, Butterfly, Ascii, Firefly, Mosaic, Sand, Geyser, None
 visualizer = "Bars"
 
 # Compact mode: cap UI width at 80 columns (default: fluid/full-width)

ui/vis_braillegrid.go

@@ -0,0 +1,124 @@
+package ui
+
+import "strings"
+
+// brailleGrid is a 4×2 dot-per-cell rasteriser shared by visualizers that draw
+// to a fine subgrid (sand, speaker, lightning, crack, quake, geyser, strings).
+// Each cell stores a tier (1..3 = low/mid/high colour, 0 = empty) and the
+// renderer composes one Braille glyph per character cell.
+type brailleGrid struct {
+	cells   []int8
+	dotRows int
+	dotCols int
+}
+
+func (g *brailleGrid) ensure(rows, cols int) {
+	if rows == g.dotRows && cols == g.dotCols && len(g.cells) == rows*cols {
+		for i := range g.cells {
+			g.cells[i] = 0
+		}
+		return
+	}
+	g.cells = make([]int8, rows*cols)
+	g.dotRows = rows
+	g.dotCols = cols
+}
+
+func (g *brailleGrid) clear() {
+	for i := range g.cells {
+		g.cells[i] = 0
+	}
+}
+
+func (g *brailleGrid) set(x, y int, tier int8) {
+	if x < 0 || x >= g.dotCols || y < 0 || y >= g.dotRows {
+		return
+	}
+	if tier > g.cells[y*g.dotCols+x] {
+		g.cells[y*g.dotCols+x] = tier
+	}
+}
+
+// render flattens the dot grid to len(rows) lines, packing 4×2 dot blocks into
+// Braille glyphs and emitting tier-coloured runs.
+func (g *brailleGrid) render(rows int) string {
+	if g.dotRows < rows*4 || g.dotCols < PanelWidth*2 {
+		return strings.Repeat("\n", max(0, rows-1))
+	}
+	lines := make([]string, rows)
+	for row := 0; row < rows; row++ {
+		var sb, run strings.Builder
+		tag := -1
+		for col := 0; col < PanelWidth; col++ {
+			var braille rune = '⠀'
+			cellTag := -1
+			for dr := 0; dr < 4; dr++ {
+				for dc := 0; dc < 2; dc++ {
+					y := row*4 + dr
+					x := col*2 + dc
+					t := g.cells[y*g.dotCols+x]
+					if t == 0 {
+						continue
+					}
+					braille |= brailleBit[dr][dc]
+					if int(t)-1 > cellTag {
+						cellTag = int(t) - 1
+					}
+				}
+			}
+			if cellTag < 0 {
+				cellTag = 0
+			}
+			if cellTag != tag {
+				flushStyleRun(&sb, &run, tag)
+				tag = cellTag
+			}
+			run.WriteRune(braille)
+		}
+		flushStyleRun(&sb, &run, tag)
+		lines[row] = sb.String()
+	}
+	return strings.Join(lines, "\n")
+}
+
+// drawLine plots a Bresenham line into the grid at the given tier.
+func (g *brailleGrid) drawLine(x0, y0, x1, y1 int, tier int8) {
+	dx := x1 - x0
+	if dx < 0 {
+		dx = -dx
+	}
+	dy := -(y1 - y0)
+	if dy > 0 {
+		dy = -dy
+	}
+	sx := 1
+	if x0 >= x1 {
+		sx = -1
+	}
+	sy := 1
+	if y0 >= y1 {
+		sy = -1
+	}
+	err := dx + dy
+	for {
+		g.set(x0, y0, tier)
+		if x0 == x1 && y0 == y1 {
+			return
+		}
+		e2 := 2 * err
+		if e2 >= dy {
+			err += dy
+			x0 += sx
+		}
+		if e2 <= dx {
+			err += dx
+			y0 += sy
+		}
+	}
+}
+
+// rng64 advances a 64-bit LCG and returns a [0,1) double.
+func rng64(state *uint64) float64 {
+	*state = *state*6364136223846793005 + 1442695040888963407
+	return float64((*state>>33)%1000) / 1000.0
+}

ui/vis_geyser.go

@@ -0,0 +1,128 @@
+package ui
+
+import "time"
+
+// geyserDriver draws a particle fountain rooted at the bottom of the panel.
+// Sustained loudness keeps a steady column of mist, bass transients launch
+// strong vertical jets, and every particle then arcs back down under gravity
+// with a touch of lateral spray. Particles inherit a tier from the band that
+// produced them, so dense bass passages paint the column red and treble
+// embellishments add green sparkles to the canopy.
+type geyserDriver struct {
+	grid      brailleGrid
+	particles []geyserParticle
+	rng       uint64
+	prevBass  float64
+}
+
+type geyserParticle struct {
+	x, y   float64
+	vx, vy float64
+	tier   int8
+	life   int
+}
+
+func newGeyserDriver() visModeDriver { return &geyserDriver{rng: 0xFEED5EED} }
+
+func (*geyserDriver) AnalysisSpec(*Visualizer) VisAnalysisSpec {
+	return spectrumAnalysisSpec(DefaultSpectrumBands)
+}
+
+func (d *geyserDriver) Tick(v *Visualizer, ctx VisTickContext) {
+	defaultDriverTick(v, ctx, d.AnalysisSpec(v))
+	if ctx.OverlayActive {
+		return
+	}
+	dotRows, dotCols := v.Rows*4, PanelWidth*2
+	if dotRows < 4 || dotCols < 4 {
+		return
+	}
+	d.grid.ensure(dotRows, dotCols)
+	d.grid.clear()
+
+	bands := v.SmoothedBands()
+	if len(bands) == 0 {
+		return
+	}
+	bass := bandAvg(bands, 0, max(1, len(bands)/3))
+	mid := bandAvg(bands, len(bands)/3, 2*len(bands)/3)
+	high := bandAvg(bands, 2*len(bands)/3, len(bands))
+	delta := bass - d.prevBass
+	d.prevBass = bass
+
+	jetX := dotCols / 2
+	jetSpread := max(2, dotCols/16)
+
+	// Steady drizzle: spawn rate scales with overall loudness so quiet passages
+	// idle a thin trickle and loud passages keep a column going. Bass weights
+	// most heavily so a heavy bassline alone keeps the column flowing.
+	steady := bass*0.85 + mid*0.25 + high*0.08
+	for i := 0; i < int(steady*6); i++ {
+		d.spawn(jetX, dotRows-1, jetSpread, 1.5+steady*4.5, &bass, &mid, &high)
+	}
+
+	// Transient kick: shoot a thick burst. Triggers on smaller deltas now so
+	// even gentler kick drums register.
+	if delta > 0.06 && bass > 0.15 {
+		burst := 40 + int(delta*180)
+		for i := 0; i < burst; i++ {
+			d.spawn(jetX, dotRows-1, jetSpread*2, 4.5+delta*10.0+bass*4.0, &bass, &mid, &high)
+		}
+	}
+
+	// Advance particles.
+	const gravity = 0.30
+	const drag = 0.992
+	live := d.particles[:0]
+	for _, p := range d.particles {
+		p.vy += gravity
+		p.vx *= drag
+		p.x += p.vx
+		p.y += p.vy
+		p.life++
+		ix, iy := int(p.x), int(p.y)
+		if iy >= dotRows || ix < 0 || ix >= dotCols || p.life > 200 {
+			continue
+		}
+		if iy < 0 {
+			iy = 0
+		}
+		d.grid.set(ix, iy, p.tier)
+		live = append(live, p)
+	}
+	d.particles = live
+}
+
+func (d *geyserDriver) spawn(x, y, spread int, vy float64, bass, mid, high *float64) {
+	jx := x + int(rng64(&d.rng)*float64(2*spread+1)) - spread
+	vyJitter := vy * (0.6 + rng64(&d.rng)*0.5)
+	vxJitter := (rng64(&d.rng) - 0.5) * (1.0 + vy*0.4)
+	r := rng64(&d.rng)
+	var tier int8 = 1
+	switch {
+	case r < *bass:
+		tier = 3
+	case r < *bass+*mid:
+		tier = 2
+	default:
+		_ = high
+	}
+	d.particles = append(d.particles, geyserParticle{
+		x: float64(jx), y: float64(y),
+		vx: vxJitter, vy: -vyJitter,
+		tier: tier,
+	})
+}
+
+func (*geyserDriver) TickInterval(_ *Visualizer, ctx VisTickContext) time.Duration {
+	return defaultDriverTickInterval(ctx)
+}
+func (d *geyserDriver) OnEnter(*Visualizer) {
+	d.grid = brailleGrid{}
+	d.particles = nil
+	d.prevBass = 0
+}
+func (*geyserDriver) OnLeave(*Visualizer) {}
+func (d *geyserDriver) Render(v *Visualizer) string {
+	return d.grid.render(v.Rows)
+}

ui/vis_sand.go

@@ -142,14 +142,14 @@ func (d *sandDriver) Tick(v *Visualizer, ctx VisTickContext) {
 
 	// 0. Explosion check: fires before the normal bump branches so the
 	// grid is cleared *instead* of being merely shaken when overfilled.
-	if delta > 0.10 && bass > 0.25 {
+	if delta > 0.06 && bass > 0.15 {
 		fill := 0
 		for _, g := range d.grid {
 			if g != 0 {
 				fill++
 			}
 		}
-		if float64(fill)/float64(len(d.grid)) > 0.40 {
+		if float64(fill)/float64(len(d.grid)) > 0.30 {
 			// Convert every grain into a ballistic particle and enter the
 			// explosion phase. The simulation will animate the burst over
 			// the next few dozen frames, then resume.
@@ -159,8 +159,8 @@ func (d *sandDriver) Tick(v *Visualizer, ctx VisTickContext) {
 	}
 
 	// 1. Transient bump.
-	if delta > 0.10 && bass > 0.25 {
-		strength := delta*2.5 + bass*0.6
+	if delta > 0.06 && bass > 0.15 {
+		strength := delta*3.5 + bass*0.8
 		if strength > 1.4 {
 			strength = 1.4
 		}
@@ -211,9 +211,9 @@ func (d *sandDriver) Tick(v *Visualizer, ctx VisTickContext) {
 	// 2. Sustained rumble — applies whenever bass is high, regardless of
 	// transient. Smaller per-grain motion but applied every frame, so the bed
 	// keeps churning during a held kick.
-	if bass > 0.45 {
+	if bass > 0.30 {
 		// Strength climbs with how far above the threshold we are.
-		rumble := (bass - 0.45) * 1.6
+		rumble := (bass - 0.30) * 1.8
 		if rumble > 0.6 {
 			rumble = 0.6
 		}

ui/visualizer.go

@@ -63,6 +63,7 @@ const (
 	VisFirefly                    // firefly meadow at dusk
 	VisMosaic                     // static heatmap of flickering tiles
 	VisSand                       // falling-sand cellular automaton
+	VisGeyser                     // bass-driven particle fountain
 	VisNone                       // hidden — no visualizer
 	VisCount                      // sentinel for cycling
 )
@@ -460,6 +461,7 @@ var visModes = [VisCount]visEntry{
 	VisFirefly:     {"Firefly", newRenderOnlyDriver(spectrumAnalysisSpec(DefaultSpectrumBands), (*Visualizer).renderFirefly)},
 	VisMosaic:      {"Mosaic", newMosaicDriver},
 	VisSand:        {"Sand", newSandDriver},
+	VisGeyser:      {"Geyser", newGeyserDriver},
 	VisNone:        {"None", newNoOpDriver},
 }