From 441a449dba7ba0852f335e6007e272687571087a Mon Sep 17 00:00:00 2001 From: Konstantin Denerz Date: Thu, 19 Nov 2026 22:24:06 +0100 Subject: [PATCH 1/2] feat(plugins): read the audible tap for Lua modes A Lua visualizer got its bands from the latest tap. That window moves only when the device takes samples. With the default 250 ms buffer it jumps 125 ms about every 128 ms (measured on macOS) and stands still in between, 125 to 250 ms ahead of the sound. Only the last 46 ms of each jump reach the FFT, so a plugin that reacts to the beat sees a kick early or not at all. The Lua driver now asks for the audible tap, as ClassicPeak and the raw-sample modes do. The bands follow the sound that plays and are new on every tick. The arguments of render are unchanged. Verified with make check (fmt, vet, tests). --- docs/plugins.md | 4 ++-- site/index.html | 2 +- ui/vis_lua.go | 10 ++++++++++ ui/vis_lua_test.go | 25 +++++++++++++++++++++++++ ui/visualizer_driver_test.go | 8 ++++++-- 5 files changed, 44 insertions(+), 5 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index b241f66fa..fed4fe6e6 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -749,8 +749,8 @@ local p = plugin.register({ }) -- Called every frame (~20 FPS during playback). --- bands: table of 10 numbers (0.0-1.0), indices 1-10, eased between --- analyses as in the built-in spectrum modes +-- bands: table of 10 numbers (0.0-1.0), indices 1-10, of the sound that +-- plays now, eased between analyses as in the built-in spectrum modes -- frame: monotonic counter -- rows: available terminal rows (changes in fullscreen mode) -- cols: available terminal columns diff --git a/site/index.html b/site/index.html index f9ff9cb51..846c86087 100644 --- a/site/index.html +++ b/site/index.html @@ -581,7 +581,7 @@

Extend it with Lua

type = "visualizer" → p:render(bands, frame, rows, cols)
-
Draw your own visualizer from the smoothed spectrum bands. Optional p:init and p:destroy run when the mode is selected and left. Plugin API reference ↗
+
Draw your own visualizer from the smoothed spectrum bands of the sound that plays now. Optional p:init and p:destroy run when the mode is selected and left. Plugin API reference ↗
diff --git a/ui/vis_lua.go b/ui/vis_lua.go index a29a2078f..946952fb9 100644 --- a/ui/vis_lua.go +++ b/ui/vis_lua.go @@ -64,6 +64,16 @@ func (d *luaModeDriver) Render(v *Visualizer) string { return v.luaHost.RenderVis(name, luaBands(v.SmoothedBands()), v.Rows, v.columns(), v.frame) } +// AnalysisSpec reads the audible tap. The latest tap moves only when the +// device takes samples, in jumps of half the speaker buffer, and it runs +// ahead of the sound. A plugin would see a kick early, or miss it between +// two jumps. +func (*luaModeDriver) AnalysisSpec(*Visualizer) VisAnalysisSpec { + spec := spectrumAnalysisSpec(DefaultSpectrumBands) + spec.Tap = VisTapAudible + return spec +} + func (d *luaModeDriver) Tick(v *Visualizer, ctx VisTickContext) { defaultDriverTick(v, ctx, d.AnalysisSpec(v)) } diff --git a/ui/vis_lua_test.go b/ui/vis_lua_test.go index 55bed218f..a4e44c172 100644 --- a/ui/vis_lua_test.go +++ b/ui/vis_lua_test.go @@ -5,6 +5,7 @@ import ( "reflect" "strings" "testing" + "time" ) // fakeLuaHost records the calls that the Visualizer makes to a LuaVisHost. @@ -219,3 +220,27 @@ func TestRegisterLuaVisualizersKeepsNames(t *testing.T) { t.Errorf("AllModeNames()[VisCount] = %q, want the Lua Bars in the cycle", names[VisCount]) } } + +// A Lua mode gets the bands of the sound that plays now, on every tick, as +// the built-in modes on the audible tap do. +func TestLuaVisualizerReadsAudibleTap(t *testing.T) { + v := newLuaTestVisualizer(t, &fakeLuaHost{}) + v.Mode = VisCount + var taps []VisTap + v.Tick(VisTickContext{ + Now: time.Unix(1, 0), + Playing: true, + Analyze: func(spec VisAnalysisSpec) []float64 { + taps = append(taps, NormalizeAnalysisSpec(spec).Tap) + return nil + }, + }) + if len(taps) == 0 { + t.Fatal("Tick did not call Analyze") + } + for _, tap := range taps { + if tap != VisTapAudible { + t.Errorf("Analyze tap = %v, want %v", tap, VisTapAudible) + } + } +} diff --git a/ui/visualizer_driver_test.go b/ui/visualizer_driver_test.go index 2ca5a4cd6..c6ce7df23 100644 --- a/ui/visualizer_driver_test.go +++ b/ui/visualizer_driver_test.go @@ -589,7 +589,7 @@ func TestTerrainTickSkipsAnalyzeUnderOverlay(t *testing.T) { } // The stateful spectrum drivers and the Lua driver take their analysis spec -// and cadence from spectrumDriverBase. +// and cadence from spectrumDriverBase. The Lua driver reads the audible tap. func TestSpectrumDriverBaseDefaults(t *testing.T) { v := NewVisualizer(44100) v.RegisterLuaVisualizers([]string{"plugin"}, nil) @@ -602,7 +602,11 @@ func TestSpectrumDriverBaseDefaults(t *testing.T) { driver := v.driverFor(mode) v.Mode = mode t.Run(v.ModeName(), func(t *testing.T) { - if got, want := driver.AnalysisSpec(v), spectrumAnalysisSpec(DefaultSpectrumBands); got != want { + want := spectrumAnalysisSpec(DefaultSpectrumBands) + if mode >= VisCount { + want.Tap = VisTapAudible + } + if got := driver.AnalysisSpec(v); got != want { t.Errorf("AnalysisSpec = %+v, want %+v", got, want) } for _, ctx := range contexts { From 6cf3e26ff5236144bb75172c85b82c2be8d54539 Mon Sep 17 00:00:00 2001 From: Konstantin Denerz Date: Thu, 19 Nov 2026 22:51:34 +0100 Subject: [PATCH 2/2] test(plugins): cover the plugin tap in the model The first commit tested the analysis spec of the Lua driver. Which tap the model then reads was only tested for built-in modes. TestVisualizerSelectsAudibleTap now has a plugin mode: without the change it reads the latest tap and fails. The docs said the bands belong to the sound that plays now. That holds for the selected visualizer. A plugin in a layout pane gets the bands of the selected visualizer, as before, and the docs say so now. Verified with make check (fmt, vet, tests). --- docs/plugins.md | 2 ++ ui/model/tick_test.go | 9 ++++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/plugins.md b/docs/plugins.md index fed4fe6e6..7fac7bcb0 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -789,6 +789,8 @@ cliamp calls `init` before the first frame after you select the visualizer, with `render` has a 50 ms limit for each frame. If it runs longer or fails, cliamp shows the previous frame. cliamp also shows the previous frame while another callback of the same plugin runs, so a slow hook does not delay the UI. cliamp runs `init` and `destroy` in order with the events of the plugin, and `render` shows the previous frame until `init` has run. +`bands` belong to the sound that plays now while the plugin is the selected visualizer. In a layout pane (`cliamp.layout.set_vis`), the plugin gets the bands of the selected visualizer. + ## Sandbox For security, plugins have restricted access. The sandbox removes unsafe standard-library functions and limits file-system access. diff --git a/ui/model/tick_test.go b/ui/model/tick_test.go index 281cba9d9..7ea967458 100644 --- a/ui/model/tick_test.go +++ b/ui/model/tick_test.go @@ -200,7 +200,7 @@ func TestTickIntervalRawSampleVisualizerUsesRawSampleCadence(t *testing.T) { } func TestVisualizerSelectsAudibleTap(t *testing.T) { - for _, mode := range []string{"Wave", "ClassicPeak", "ClassicLED", "Bars"} { + for _, mode := range []string{"Wave", "ClassicPeak", "ClassicLED", "Bars", "plugin"} { t.Run(mode, func(t *testing.T) { p := &samplingFakeEngine{playbackFakeEngine: &playbackFakeEngine{playing: true}} m := Model{ @@ -211,10 +211,13 @@ func TestVisualizerSelectsAudibleTap(t *testing.T) { height: 24, } m.recomputeLayout() - m.SetVisualizer(mode) + m.RegisterLuaVisualizers([]string{"plugin"}, nil) + if !m.SetVisualizer(mode) { + t.Fatalf("no visualizer %q", mode) + } m.tickVisualizer(time.Unix(1, 0)) wantAudible := 0 - if mode == "Wave" || mode == "ClassicPeak" { + if mode == "Wave" || mode == "ClassicPeak" || mode == "plugin" { wantAudible = 1 } if p.waveformSampleCalls != wantAudible || p.sampleCalls != 1-wantAudible {