TUI Wizard: Interactive Sound Palette Builder

[SorraTheOrc]

TUI Wizard: Interactive Sound Palette Builder

An interactive terminal wizard (toneforge tui) that guides game developers through assembling a coherent sound palette -- from recipe browsing through seed exploration to a deployment-ready folder of WAV files -- without requiring knowledge of CLI commands or the sweep/classify/promote pipeline.

Problem Statement

Game developers using ToneForge must currently learn and manually invoke a dozen CLI commands (list, generate, explore sweep, classify, promote, library export) in the correct sequence to assemble a sound palette. This creates a steep learning curve and a slow, error-prone workflow -- especially for developers with tight deadlines who need to produce a coherent set of sound effects quickly.

Users

Primary: Game developers with project deadlines who need to assemble complete, coherent audio palettes efficiently without mastering ToneForge's CLI surface.

Secondary: Developers new to ToneForge who benefit from guided discovery of recipes and the exploration pipeline.

User Stories

• As a game developer with a deadline, I want to define the sounds I need (e.g. 'card flip', 'victory fanfare', 'coin collect'), have the wizard find the best candidates, let me audition and choose between them, and export the final set -- all in one session.
• As a game developer who is new to ToneForge, I want an interactive wizard that walks me through selecting, previewing, refining, and exporting a set of sound effects for my game, so I can build a complete, coherent audio palette without learning dozens of CLI commands.

Success Criteria

1. Running toneforge tui launches an interactive terminal session that guides the user through the four-stage palette-building workflow (Define, Explore, Review, Export).
2. A developer unfamiliar with ToneForge CLI commands can produce a folder of correctly-named WAV files for a 5-10 recipe palette in a single session.
3. The wizard reuses existing core modules (RecipeRegistry, sweep, mutate, classify, library export, audio player) without duplicating their logic.
4. All existing CLI commands and tests continue to work unchanged (npm test and npx tsc --noEmit pass).
5. New code has unit test coverage for stage logic (manifest building, candidate selection, export pipeline).
6. The wizard handles Ctrl+C cleanly (no orphaned audio processes or partial state) and exits with a clear error in non-TTY environments.

Constraints

• TUI library: Use @inquirer/prompts for interactive prompts. No full-screen TUI frameworks (blessed, ink).
• Terminal-only: No web UI; this is purely a terminal application.
• Non-TTY environments: The wizard must detect non-TTY and exit with a clear error message (no fallback non-interactive mode).
• CLI architecture: The existing CLI is hand-rolled (no commander/yargs). The new tui command must integrate with the existing dispatch pattern in src/cli.ts.
• No new rendering/synthesis logic: The wizard orchestrates existing modules; it does not implement new audio processing.
• Session save/resume: Nice-to-have for v1; defer to a follow-up work item if implementation complexity is high.

Existing State

• All building blocks exist: The sweep, mutate, promote, classify, library export, and audio player modules are fully implemented and tested.
• 100+ recipes are registered across categories (card-game, weapon, footstep, UI, ambient, creature, etc.) with metadata (description, category, tags).
• demos/card-game-sounds.md demonstrates the exact 12-act workflow this wizard encapsulates, proving the pipeline works end-to-end via CLI commands.
• No TUI framework exists in the project: no src/tui/ directory, no interactive prompt libraries in package.json.
• src/output.ts provides styled terminal output (markdown rendering, ANSI formatting, TTY detection).
• web/src/wizard.ts is an unrelated browser-based tutorial wizard.

Desired Change

Architecture

• Add @inquirer/prompts as a dependency.
• Create a new src/tui/ directory containing stage modules, shared types, and session state management.
• Add a toneforge tui command to src/cli.ts that launches the wizard pipeline.

Four-Stage Wizard Pipeline

Stage 1 -- Define Your Palette: Browse recipes by category, preview sounds at a default seed, build a manifest of desired recipes.

Stage 2 -- Explore and Audition: For each manifest recipe, run an automated sweep (default seed range 0:19, 20 seeds) ranked by composite metrics. Present top 3-5 candidates per recipe for audition. Support optional seed mutation for finer refinement. Allow skipping recipes to return to later.

Stage 3 -- Review and Refine: Display the full palette summary with classification attributes (category, intensity, texture, tags). Perform basic coherence checking -- flag recipes with significantly different intensity or texture from the palette median. Allow swapping individual selections or adding/removing recipes.

Stage 4 -- Export: Choose between library-route export (promote to library, then export) or quick export (direct generate-to-disk). Specify output directory and optional category subdirectory organization. Produce WAV files and an optional manifest JSON.

UX Requirements

• Progress feedback (spinner or progress bar) during sweeps.
• Non-blocking audio playback for previewing candidates.
• Backward navigation between stages.
• Graceful Ctrl+C handling (clean exit, no orphaned processes).
• Clear error messages for failed renders or missing samples.

Related Work

Related documents

• demos/card-game-sounds.md -- The 12-act workflow this TUI encapsulates
• src/cli.ts -- Existing CLI command dispatch (new command integrates here)
• src/output.ts -- Terminal output utilities (markdown rendering, ANSI, TTY detection)
• src/core/recipe.ts -- RecipeRegistry API for listing, filtering, metadata
• src/explore/ -- Sweep, mutate, promote, ranking, clustering modules
• src/classify/ -- Classification engine with dimension classifiers
• src/library/ -- Library storage, search, export, regenerate
• src/audio/player.ts -- Cross-platform audio playback

Related work items

• Tag Display Prioritization (TF-0MM7K306X1SLYFOL, completed) -- matchedTags metadata benefits Stage 1 recipe browsing
• Add filtering to list recipes command (TF-0MM7ENNL90AHWC0N, completed) -- recipe filtering capabilities used by Stage 1
• Card Game Sound Selection Demo (TF-0MM7E1IBI127HU3C, completed) -- demonstrates the exact workflow this wizard automates
• Library Export -- WAV by Category (TF-0MM1GOO8S0JE76JX, completed) -- export functionality used by Stage 4
• Explore -- Mutate & Variations (TF-0MM0BW2RQ0C2MESW, completed) -- mutation feature used by Stage 2
• Machine use demo (TF-0MLYUG79Y1KMDPMI, open) -- related to programmatic/interactive use of ToneForge

Related work (automated report)

Generated by find_related skill on 2026-03-01. Conservative relevance threshold applied.

Additional work items

• Explore -- Sweep Runner (TF-0MM0BW00Y0AREXKG, completed) -- Implements sweep() in src/explore/sweep.ts, the core function Stage 2 calls to iterate seeds, render, analyze, and rank candidates for each recipe.
• Add automatic classification to explore sweep pipeline (TF-0MM363OCN13SPE6J, completed) -- Ensures sweep candidates carry classification data (category, intensity, texture, tags), which Stage 3 Review needs for coherence checking and palette summary display.
• Ranking Engine (TF-0MM0BW4ZU0FSLG80, completed) -- Implements composite-metric ranking in src/explore/ranking.ts that Stage 2 uses to select and present top candidates per recipe.
• Direct-to-Device Playback (TF-0MM0YVAEL00NKHNT, completed) -- Provides the low-latency audio playback path in src/audio/player.ts that enables non-blocking preview during Stage 2 audition prompts.
• Lazy Recipe Loading (TF-0MM0YURXB03NLOE3, completed) -- On-demand recipe loading in the registry improves responsiveness of Stage 1 recipe browsing when the user navigates categories with 100+ recipes.
• Investigate and reduce latency of sound generation (TF-0MM0W4YUZ0QF26DG, completed) -- Latency optimizations across the generate pipeline directly affect the interactive auditioning experience in Stage 2, where rapid seed preview is critical for UX.
• Promote Integration -- Direct Library Write (TF-0MM1GP2RS0TNOB44, completed) -- Implements promoteCandidate() in src/explore/promote.ts which writes directly to the Library, providing the library-route export path used by Stage 4.
• CLI Filter Flags & Four-Column Table (TF-0MM7K1YHL12T4EJH, completed) -- Implements --search, --category, --tags flag parsing and the listDetailed() registry API that Stage 1 recipe browsing will use to filter and display recipes.
• Classification Engine Core & Types (TF-0MM0AJ6R01H1XLVU, completed) -- Defines ClassificationEngine and ClassificationResult types in src/classify/ that Stage 3 Review uses to display and compare classification attributes across palette entries.
• Demo 11: Intelligence -- Assisted Decision-Making (TF-0MLXF98WZ1LQGM5W, blocked) -- Future intelligence features (library audit, gap detection, recommendations) overlap conceptually with the wizard's Stage 3 coherence checking; may inform future wizard enhancements.

Additional repository references

• docs/prd/EXPLORE_PRD.md -- Exploration pipeline specification; defines sweep, ranking, and promote APIs the wizard orchestrates.
• docs/prd/CLASSIFY_PRD.md -- Classification taxonomy specification; defines the dimensions (category, intensity, texture, tags) displayed in Stage 3 Review.
• docs/prd/LIBRARY_PRD.md -- Library storage and export specification; defines the export API used by Stage 4.
• src/explore/ranking.ts -- Ranking functions (rankCandidates, keepTopN) used to select top candidates in Stage 2.
• src/explore/clustering.ts -- Clustering function (clusterCandidates) that may be useful for grouping diverse candidates in Stage 2 audition.

Out of Scope (for initial version)

• Web-based UI (terminal-only)
• Real-time waveform visualization
• Batch processing of multiple palettes
• A/B comparison mode (side-by-side playback)
• Undo/redo within stages
• Custom recipe creation within the wizard

Risks & Assumptions

• Risk: Scope creep -- The wizard touches many subsystems (recipes, explore, classify, library, audio). Additional features (A/B comparison, undo/redo, custom recipes) could expand scope significantly. Mitigation: record opportunities for enhancements as separate work items linked to this epic rather than expanding scope.
• Risk: Sweep performance in interactive context -- Even with 20 seeds, sweeps involve rendering + analysis + classification per seed. For large palettes this could feel slow. Mitigation: implement progress feedback and allow the user to adjust the seed range; profile and optimize if needed.
• Risk: @inquirer/prompts compatibility -- The project has no prior experience with this library. API changes or limitations (e.g. around backward navigation, nested prompts) could force workarounds. Mitigation: spike the library early in planning to validate the key interactions (multi-select, preview-while-selecting, back navigation).
• Risk: Audio playback blocking the prompt -- Non-blocking audio playback during selection prompts may require careful process management to avoid zombie audio processes on Ctrl+C. Mitigation: implement a cleanup handler and test across supported platforms.
• Assumption: All existing core modules (sweep, classify, library export, audio player) are stable and their public APIs will not change significantly during implementation.
• Assumption: @inquirer/prompts supports the interaction patterns needed (multi-select with preview, confirmation, text input) without extensive custom extensions.

[SorraTheOrc]

\n\n**opencode**\n\nPlanning Complete. Decomposed into 9 feature work items (8 core + 1 optional):\n\n1. TUI Foundation -- Types, Session State, CLI Entry Point (TF-0MM8S0MHO0033HYE)\n2. Stage 1a -- Recipe Browsing and Preview (TF-0MM8S0Y021PI6KW1)\n3. Stage 1b -- Palette Manifest Builder (TF-0MM8S17RQ0U4Y4H1)\n4. Stage 2a -- Sweep and Ranking (TF-0MM8S1JZX1GYYQT0)\n5. Stage 2b -- Audition and Mutation (TF-0MM8S1W4C0NQ1CW6)\n6. Stage 3 -- Review and Refine (TF-0MM8S29GD0JJ1WTC)\n7. Stage 4 -- Export via Library with Manifest (TF-0MM8S2LKQ1WM38F4)\n8. End-to-End Integration and Polish (TF-0MM8S2ZOH1XPC1X6)\n9. Session Save/Resume -- Optional (TF-0MM8S3BDR1QMN6TZ, medium priority)\n\nKey decisions from interview:\n- Delivery: stage-per-feature with Feature 2 (Define) split into Browse+Preview / Manifest, and Feature 3 (Explore) split into Sweep+Ranking / Audition+Mutation\n- No @inquirer/prompts spike -- build directly\n- Export: library-route only (no quick export), with manifest JSON\n- Navigation: back one stage only\n- Coherence: simple median deviation for intensity/texture\n- Audio preview: play/stop inline\n- Cleanup: full (processes + temp files)\n- Session save/resume: included as optional Feature 9\n\nDependency chain: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9(optional)\n\nNo open questions remain.