Skip to content
KN-86 Deckline

rs-pug

What it is

Section titled “What it is”

rs-pug is a keyboard-driven terminal music player covering YouTube, SoundCloud, and local files. Two design choices set it apart from the rest of the Ratatui music-player crowd: it ships a Lua plugin system (third-party code, cleanly sandboxed, hot-loadable) and JSON theme files with five named presets out of the box — dark, light, nord, gruvbox, and mono. Persistence is SQLite. The “Smart Queue” feature autoplays related tracks by mining genre/tag overlap from the listening history.

Aspirational features for KN-86

Section titled “Aspirational features for KN-86”
  • Lua as the plugin runtime is a strong precedent for KN-86’s KEC Lisp cart authoring model. rs-pug treats third-party Lua as the first-class extensibility surface — plugins can add commands, hook events, transform the queue. KN-86’s cartridges are not plugins in the rs-pug sense (carts are full capability modules per ADR-0001, not extension points to a host application), but the pattern — small embedded interpreter, host-controlled FFI, plugins live in a known directory with discovery rules — is the right reference shape for third-party tooling around KN-86 (e.g., a CIPHER-line authoring helper, a cart pack inspector, an emulator debug overlay).
  • JSON theme files as the unit of theming. Five named themes (dark, light, nord, gruvbox, mono) — human-editable, easy to share, no recompile. Matches the named aesthetic modes framing in the Batch-2 visual identity brief (and the OS-Models reference). KN-86’s nosh-config.toml aesthetic-mode entry should be similarly human-editable and shareable.
  • SQLite for persistence. Single file, well-understood, queryable. Not a recommendation for the on-device KN-86 nOSh runtime (which has its own per-cart save model on the SD card — see ADR-0019) — but for the desktop tooling around KN-86 (the cart authoring tool, the emulator state browser), SQLite is the right answer.
  • Smart Queue as a “what’s next” affordance. Mines history for relatedness, autoplays similar items. For KN-86 think: a mission-board surface that proposes a related contract based on cart history and current reputation. Lifting the autopilot-suggestion idea, not the music-specific implementation.

Image

Section titled “Image”

rs-pug terminal music player

Source: rs-pug README hero shot. Shows the multi-pane player layout (library on the left, queue + now-playing in the middle), the focused-row indicator, and the theme-driven color palette.

Notes

Section titled “Notes”
  • Cross-reference cliamp — also Lua-plugin-driven, also a music player. Two independent confirmations that “Lua as the extension language for a TUI app” is a community-validated pattern.
  • Cross-reference audium for the human-editable JSON portable library idea — same persistence philosophy, different domain (audium leans into “your library is grep-able text,” rs-pug leans into “your library is queryable SQLite”). Both are legitimate.
  • For the KN-86 emulator’s debug overlay (the F12 surface already documented in kn86-emulator/), a small Lua/JSON-config layer for user-extensible debug panels would be a natural place to apply this lesson — though scoped well outside v0.1.