Lua scripting API v5: data reads, actions, timers, storage, events, navigation, and custom screens#363
Merged
Merged
Conversation
Plugins can now read app data, drive most of the app, and build their
own screens:
- Async data reads with a (data, err) callback convention, backed by
per-domain generation counters bumped at network write sites:
get_playlists, get_queue, get_search_results, get_saved_tracks,
get_saved_albums, get_saved_shows, get_recently_played, get_devices,
get_lyrics (15s timeout). Cached sync reads: playlists(), queue(),
search_results(). New GetDevicesSilent/GetRecentlyPlayedSilent
IoEvents keep plugin reads from navigating the UI.
- Actions routed through whitelisted IoEvents: set_repeat/cycle_repeat,
transfer_playback, play_uri, play_context, add_to_queue,
create_playlist, playlist_add_track, playlist_remove_track,
follow/unfollow_playlist, toggle_save_track, save/unsave_album,
save/unsave_show, follow/unfollow_artist.
- Timers: set_timeout/set_interval/cancel_timer, fired from the tick
loop with intake queues, skip-missed-period rescheduling and
one-strike removal of erroring intervals.
- Plugin-scoped persistent storage (storage_get/set/remove/keys), one
flat JSON file per plugin under plugin-data/, throttled flush plus
forced flush on quit via temp-file + rename.
- New events: shuffle_change, repeat_change, device_change,
search_results, route_change ({name} arg); navigation via
navigate(target)/back()/current_route() with a whitelist that
mirrors the matching keybindings.
- Retained-mode custom screens: register_screen with on_key/on_open/
on_close, set_screen with paragraph/list/gauge widgets,
show_screen/close_screen (ownership-checked), keys forwarded as
config.yml-style strings, RouteId::PluginScreen routing plus a
dedicated renderer and handler.
- config() read exposing theme colors and safe behavior scalars
(secrets excluded).
- docs/scripting.md v5 sweep, queue-browser.lua example, changelog.
API_VERSION 4 -> 5 (additive; all v4 snapshot fields preserved).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What's new
A major expansion of the Lua plugin API (v4 shipped in #302), made this a while ago but forgot to merge it:
get_playlists,get_queue,get_search_results,get_saved_tracks/albums/shows,get_recently_played,get_devices,get_lyrics, all with the(data, err)callback convention.set_repeat/cycle_repeat,transfer_playback,play_uri/play_context,add_to_queue, playlist create/edit, and save/follow actions.set_timeout,set_interval,cancel_timer.storage_get/set/remove/keys.navigate,back,current_route, plus aconfig()read of the user config.shuffle_change,repeat_change,device_change,search_results,route_change.register_screen/set_screen/show_screen/close_screenwith paragraph/list/gauge widgets and per-key callbacks (newRouteId::PluginScreen/ActiveBlock::PluginScreen,src/tui/ui/plugin_screen.rs, example pluginexamples/plugins/queue-browser.lua).Documented in
docs/scripting.md.Notes
route_namemap.get_recently_playedgained anavigateflag so plugin data reads don't hijack the current screen; the handler path still navigates as before.Testing
cargo fmt,cargo clippy -- -D warnings(with and withoutscripting), andcargo test --no-default-features --features telemetry,scripting(572 tests) all pass.