diff --git a/docs/plugins.md b/docs/plugins.md
index b241f66fa..7fac7bcb0 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
@@ -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/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/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 {
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 {