luaplugin

package
v1.60.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 16, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package luaplugin provides a Lua 5.1 scripting engine for cliamp plugins. Each plugin runs in an isolated GopherLua VM. Plugins are loaded from ~/.config/cliamp/plugins/*.lua at startup.

Index

Constants

View Source 
const (
	EventAppStart      = "app.start"
	EventAppQuit       = "app.quit"
	EventPlaybackState = "playback.state"
	EventTrackChange   = "track.change"
	EventTrackScrobble = "track.scrobble"
	EventPlayerSeek    = "player.seek"   // data: position, duration (seconds)
	EventPlayerVolume  = "player.volume" // data: db
	EventPlayerEQ      = "player.eq"     // data: bands (10-array), preset
	EventPlayerMode    = "player.mode"   // data: shuffle (bool), repeat ("Off"/"All"/"One")
	EventQueueChange   = "queue.change"  // data: count, index, queued
)

Event name constants.

View Source 
const (
	PermControl = "control"
	PermExec    = "exec"
	PermKeymap  = "keymap"
)

Permission strings declared via plugin.register({ permissions = {...} }). Kept as named constants so the guard call sites and docs don't drift.

Variables

This section is empty.

Functions

func Sandbox 

func Sandbox(L *lua.LState)

Sandbox applies the plugin sandbox to L. It is exported for tools that load plugin files outside the runtime (e.g. pluginmgr metadata extraction) and must apply the same stdlib restrictions before executing untrusted code.

Types

type ControlProvider 

type ControlProvider struct {
	SetVolume   func(db float64)
	SetSpeed    func(ratio float64)
	SetEQBand   func(band int, db float64)
	ToggleMono  func()
	TogglePause func()
	Stop        func()
	Seek        func(secs float64)
	SetEQPreset func(name string, bands *[10]float64) // injected via prog.Send
	Next        func()                                // injected via prog.Send
	Prev        func()                                // injected via prog.Send
	// Queue mutators, all injected via prog.Send so the model's Update loop
	// applies them and keeps derived state (cursor, current index) consistent.
	QueueAdd    func(path string)  // resolve path/URL and append
	QueueJump   func(index int)    // make index current and play it
	QueueRemove func(index int)    // remove track at index
	QueueMove   func(from, to int) // reorder
}

ControlProvider supplies write access to player controls. Only available to plugins that declare permissions = {"control"}.

type KeyBinding 

type KeyBinding struct {
	Key         string
	Plugin      string
	Description string
}

KeyBinding describes a plugin-registered keybinding for the Ctrl+K overlay.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns all loaded plugins and dispatches events to them.

func New 

func New(pluginCfg map[string]map[string]string) (*Manager, error)

New scans the plugin directory and loads all .lua files. pluginCfg maps plugin names to their [plugins.<name>] config keys. Returns a Manager (possibly with 0 plugins) and any non-fatal load error.

func (*Manager) Close 

func (m *Manager) Close()

Close fires the "app.quit" event synchronously and shuts down all Lua VMs.

func (*Manager) CommandList 

func (m *Manager) CommandList() []string

CommandList returns a flat list of "<plugin> <command>" strings. Used by `cliamp plugin commands`. Order is unspecified.

func (*Manager) DestroyVis 

func (m *Manager) DestroyVis(name string)

DestroyVis calls a Lua visualizer's destroy() if it exists.

func (*Manager) Emit 

func (m *Manager) Emit(event string, data map[string]any)

Emit dispatches an event to all plugins that registered for it. Each callback runs in its own goroutine with a timeout. The plugin's mutex serializes all LState access so concurrent events are safe.

func (*Manager) EmitCommand 

func (m *Manager) EmitCommand(pluginName, cmdName string, args []string) (string, error)

EmitCommand dispatches a plugin command invoked over IPC and blocks up to commandTimeout for the handler to return a result. A missing plugin/command returns ("", err); a handler error returns ("", err); success returns (result, nil). The result is whatever the handler returned as a string (nil or false stringifies to "").

func (*Manager) EmitKey 

func (m *Manager) EmitKey(key string) bool

EmitKey invokes every plugin callback registered for the given key string. Returns true if at least one callback fired. Called by the UI's main key dispatcher for keys the core doesn't handle.

func (*Manager) EmitSync 

func (m *Manager) EmitSync(event string, data map[string]any)

EmitSync dispatches an event synchronously, blocking until all callbacks finish. Used during shutdown to ensure all handlers complete before LStates are closed.

func (*Manager) HasHook 

func (m *Manager) HasHook(event string) bool

HasHook reports whether any plugin registered for a specific event. Callers use this to skip building event payloads (and any locks they require) when no plugin is listening for that particular event.

func (*Manager) HasHooks 

func (m *Manager) HasHooks() bool

HasHooks reports whether any plugins have registered hooks.

func (*Manager) InitVis 

func (m *Manager) InitVis(name string, rows, cols int)

InitVis calls a Lua visualizer's init(rows, cols) if it exists.

func (*Manager) KeyBindings 

func (m *Manager) KeyBindings() []KeyBinding

KeyBindings returns a snapshot of every plugin-registered keybinding that has a description, sorted by key for stable overlay ordering. Bindings registered without a description are omitted — plugins can opt out of surfacing a key simply by skipping the description argument.

Called once per Ctrl+K overlay open, so the sort cost is noise.

func (*Manager) PluginCount 

func (m *Manager) PluginCount() int

PluginCount returns the number of loaded plugins.

func (*Manager) RenderVis 

func (m *Manager) RenderVis(name string, bands [10]float64, rows, cols int, frame uint64) string

RenderVis calls a Lua visualizer's render(bands, frame) and returns the terminal text. On error, the previous frame is reused.

func (*Manager) SetControlProvider 

func (m *Manager) SetControlProvider(cp ControlProvider)

SetControlProvider sets the function pointers for player control. Only plugins with permissions = {"control"} can use these.

func (*Manager) SetReservedKeys 

func (m *Manager) SetReservedKeys(keys map[string]bool)

SetReservedKeys records the set of keys owned by cliamp's core UI. Plugins attempting to bind one of these keys get a logged warning and their bind call returns false. Called once during startup from main.go.

func (*Manager) SetStateProvider 

func (m *Manager) SetStateProvider(sp StateProvider)

SetStateProvider sets the function pointers used by the Lua API to query live player/playlist state.

func (*Manager) SetUIProvider 

func (m *Manager) SetUIProvider(up UIProvider)

SetUIProvider sets the function pointers for UI output (status messages).

func (*Manager) Visualizers 

func (m *Manager) Visualizers() []string

Visualizers returns the names of all Lua visualizer plugins.

type Plugin 

type Plugin struct {
	Name        string
	Version     string
	Description string
	Type        string // "hook" or "visualizer"
	L           *lua.LState
	// contains filtered or unexported fields
}

Plugin represents a single loaded Lua plugin.

type QueueEntry 

type QueueEntry struct {
	Title  string
	Artist string
	Album  string
	Path   string
	Index  int
	Queued bool
}

QueueEntry is one track in the playlist as exposed to plugins via cliamp.queue.list(). Index is 0-based and matches CurrentIndex; Queued is true when the track sits in the explicit play-next queue.

type StateProvider 

type StateProvider struct {
	PlayerState   func() string  // "playing", "paused", "stopped"
	Position      func() float64 // seconds
	Duration      func() float64 // seconds
	Volume        func() float64 // dB
	Speed         func() float64 // ratio (1.0 = normal)
	Mono          func() bool
	RepeatMode    func() string // "off", "all", "one"
	Shuffle       func() bool
	EQBands       func() [10]float64
	TrackTitle    func() string
	TrackArtist   func() string
	TrackAlbum    func() string
	TrackGenre    func() string
	TrackYear     func() int
	TrackNumber   func() int
	TrackPath     func() string
	TrackIsStream func() bool
	TrackDuration func() int // seconds
	PlaylistCount func() int
	CurrentIndex  func() int          // 0-based
	QueueList     func() []QueueEntry // full playlist in play order
}

StateProvider supplies read-only access to player/playlist state. Functions are set by the caller after model construction so the Lua API can query live state without importing the ui package.

type UIProvider 

type UIProvider struct {
	ShowMessage func(text string, duration time.Duration) // injected via prog.Send
}

UIProvider supplies callbacks that surface plugin output in the TUI. Not permission-gated — these are low-risk, output-only operations.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.