Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion site/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -581,7 +581,7 @@ <h2>Extend it with Lua</h2>
</div>
<div class="api-i">
<div class="sig">type = "visualizer" → p:render(bands, frame, rows, cols)</div>
<div class="d">Draw your own visualizer from the smoothed spectrum bands. Optional <code>p:init</code> and <code>p:destroy</code> run when the mode is selected and left. <a href="https://github.com/bjarneo/cliamp/blob/main/docs/plugins.md">Plugin API reference ↗</a></div>
<div class="d">Draw your own visualizer from the smoothed spectrum bands of the sound that plays now. Optional <code>p:init</code> and <code>p:destroy</code> run when the mode is selected and left. <a href="https://github.com/bjarneo/cliamp/blob/main/docs/plugins.md">Plugin API reference ↗</a></div>
</div>
</div>
</div>
Expand Down
9 changes: 6 additions & 3 deletions ui/model/tick_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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{
Expand All @@ -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 {
Expand Down
10 changes: 10 additions & 0 deletions ui/vis_lua.go
Original file line number Diff line number Diff line change
Expand Up @@ -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))
}
Expand Down
25 changes: 25 additions & 0 deletions ui/vis_lua_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"reflect"
"strings"
"testing"
"time"
)

// fakeLuaHost records the calls that the Visualizer makes to a LuaVisHost.
Expand Down Expand Up @@ -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)
}
}
}
8 changes: 6 additions & 2 deletions ui/visualizer_driver_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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 {
Expand Down