waves

What it is

waves is a feature-deep terminal music player: it browses a library by the classic Artist → Album → Track hierarchy, builds a play queue you can reorder with undo/redo, switches between several full-screen views with the function keys, searches everything via SQLite FTS5, and adds radio mode and Last.fm scrobbling on top. Where cmus.md is the minimalist baseline, waves is the fuller take — more views, more state, a persistent toggle-able queue panel, and a richer search/discovery layer. For the Toneline it contributes three patterns: F-key view switching, the strict library hierarchy, and the reorderable queue with undo/redo.

UI / interaction

• F-key view switching:

  • F1 — Library (the Artist → Album → Track browser)
  • F2 — File browser (filesystem, with delete)
  • F3 — Playlists (create/manage)
  • F4 — Downloads (Soulseek/slskd integration)

  Four function keys, four whole surfaces — the same “one key, one mode” discipline as cmus, expressed on F-keys instead of digits.

• Library hierarchy — navigation drills Artist → Album → Track, the universal music-catalog tree.

• Persistent queue panel, toggled with p — the queue lives beside the browser rather than as a separate view; you can toggle it on/off and keep building it while you browse. Multi-select, reorder, and undo/redo (Ctrl+Z / Ctrl+Shift+Z).

• Mini-player bar with album art when expanded (v toggles the expanded display).

• Search / — SQLite FTS5 full-text search across library, files, and playlists. ? help. Spacebar play/pause. R cycles repeat modes including radio mode (auto-queues similar artists via Last.fm + local fuzzy matching).

• Chord-style commands — f d (download), f l (Last.fm settings): a leading key opens a small command group, vim-leader style.

Architecture

Bubble Tea drives the rendering/event loop; SQLite + FTS5 is the catalog and the search index in one; integrations (slskd for Soulseek, Last.fm for metadata/scrobbling/radio) sit behind the player. The persistent-panel model (queue always available, toggled not navigated-to) and the undo/redo on queue edits are the structurally interesting parts.

Toneline-relevance (and Deckline note)

• F-key view switching is a clean alternative to cmus’s digit views. A music workstation has several heavy surfaces; binding them to F-keys (or the Sweep equivalent) gives instant mode jumps. The Toneline can choose: digits (cmus) sit on the right-half number cluster; F-keys (waves) would need a function layer. For the Toneline, cmus’s digit model likely wins (the keys are already there), but waves contributes the persistent-panel toggle idea that digit-views lack.
• The persistent toggle-able queue panel (p) is the better pattern for a sequencer. Rather than navigating away to a separate phrase-queue view, keep the performance queue docked beside the sequencer and toggle it on/off — so the operator builds the live set without losing sight of the phrase they’re editing. This is the refinement to layer on top of line.md’s sp/lp phrase queue: line has the queue; waves shows it should be a persistent side panel, not a modal view.
• Undo/redo on queue/arrangement edits is a must-have. Reordering phrases in an arrangement, dropping a pattern, swapping a voice — all need Ctrl+Z. waves makes undo/redo a first-class queue affordance; the Toneline’s arrangement editor should inherit it. (PulseDeck and the Deckline runtime already carry an undo doctrine — pulsedeck.md; waves reinforces it specifically for list/queue edits, which is what a sequencer arrangement is.)
• The Artist→Album→Track hierarchy maps onto Song→Pattern→Phrase→Sequence. The Toneline fiction already nests music as song → patterns → sequences → notes. waves’s drill-down browser is the navigation precedent for moving through that nesting: drill into a song to see its patterns, into a pattern to see its phrases. Same tree-navigation UI, music-authoring semantics instead of catalog semantics.
• FTS5 search is the model for finding phrases/patches at scale. Once an operator has a cartridge full of saved phrases and FM patches, they need to find one. waves’s FTS5 catalog is the precedent for an indexed, fuzzy phrase/patch search on the Toneline.

Deckline note: F-key/numeric multi-view switching and the persistent-toggle-panel pattern are general Deckline runtime patterns — any multi-surface Deckline app (bare-deck HUD, multi-pane cart) benefits from “one key per surface + a dockable side panel you toggle rather than navigate to.”

Single-color adaptation

waves is colorful in its native form, but its information architecture survives monochrome cleanly:

• The Artist→Album→Track tree is indentation + characters (├─ └─), not color — standard tree rendering on the amber grid.
• The current view / now-playing / selected row uses inversion, not a highlight color.
• The toggle-able queue panel is a bordered region (CP437 box-drawing, already in the KN-86 font) docked to one side; its presence/absence is the state, no color needed.
• The mini-player “album art” has no monochrome analog as imagery, but its slot becomes a single-color level meter or phrase-position indicator — repurpose the real estate, drop the photo.

Image

Source: GitHub social card for llehouerou/waves. Shows the hierarchical library browser with the docked queue panel and the mini-player bar.

Notes

• Three takeaways: F-key/multi-view switching, the persistent toggle-able queue panel (the standout — better than a modal queue view for a sequencer), and undo/redo on list edits.
• Pairs with cmus.md as the two view-switching references — cmus (digits, minimalist) vs waves (F-keys, persistent panel + undo). The Toneline takes cmus’s digit binding and waves’s persistent-panel + undo behavior.
• Cross-link line.md — waves’s persistent queue panel is the UI envelope for line’s phrase-queue mechanic.
• Cross-link 4trk.md — the GUI groovebox cousin; both inform the Toneline’s arrangement/library surfaces.