Skip to content

OVERVIEW.md

Latest commit

 

History

History
45 lines (32 loc) · 4.34 KB

OVERVIEW.md

File metadata and controls

45 lines (32 loc) · 4.34 KB

BeatBox Overview

What This Repo Is

BeatBox is a VS Code extension that turns the sidebar into a local music player and visualizer stage. The extension host contributes BeatBox in both the activity bar and Explorer, while the webview owns playback, queue management, settings UI, and the shared visualizer runtime.

Architecture

Extension Host

  • src/extension.ts activates the extension, registers both BeatBox webview locations, and exposes a focus command.
  • src/BeatBoxViewProvider.ts resolves the webview, constrains local resource roots, emits CSP-safe HTML, and serves the built Vite bundle.
  • package.json now carries release-facing Marketplace metadata including branding, gallery banner color, packaging scripts, and category/keyword tuning.
  • .vscodeignore trims packaging contents so the generated .vsix stays focused on shippable assets.

Webview App

  • webview-ui/ is a React + TypeScript + Vite application styled around a visualizer-first sidebar experience.
  • The shell is intentionally compact: sparse empty state, icon-led header actions, overlay playlist/settings panels, and a small stage transport instead of a permanent footer.
  • Playback supports append-style multi-track import, create-playlist replacement, drag reorder, delete mode that clears when the playlist overlay closes, seek scrubbing, shuffle history, repeat modes, and queue/session restore after webview recreation.
  • The webview persists session metadata with VS Code getState/setState and caches imported files in IndexedDB so unexpected reloads can recover the current session.
  • The build pipeline runs a dedicated webview TypeScript pass before bundling to catch visualizer and UI mistakes earlier.

Visualizer Runtime

  • webview-ui/src/types.ts defines the shared VisualizerModule, VisualizerInstance, and VisualizerFrame contract.
  • webview-ui/src/visualizers/index.ts is the registry entry point for the shipped lineup.
  • webview-ui/src/components/VisualizerCanvas.tsx contains the canvas mount path and guards renderer init, resize, and render failures with an in-stage fallback card.
  • The current shipped BeatBox roster contains twenty-two visualizers: Aether Bloom, BBS Glitch, Bubblegum Bliss, Chibi Meter, Confetti Blast, Cosmic Nebula, Kaleidoscope, Liquid Crystal, Lumenade, Metallic Candy, Mind Pulse, Neural Synapse, Pixel Heartbeat, Pixel Party, Radial Void, Rainbow Waveform, Solar Flare, Sonic Candy, Starfield, Synth Board, Synthwave, and Unicorn Magic.
  • webview-ui/src/visualizers/solarFlare.ts adds a reactive solar scene with a pulsing sun core, long corona rays, heat-wave rings, and a starfield backdrop.
  • Metallic Candy remains the default first-run impression, while Solar Flare expands the roster with a more cinematic, high-energy scene.

Release Readiness Snapshot

  • Marketplace-facing README copy is now aligned with release packaging instead of internal implementation notes.
  • The README now includes a screenshot gallery covering featured visualizers plus the playlist and settings overlays.
  • npm run package produces a distributable .vsix from the root build and manifest metadata.
  • Release docs now consistently describe the shipped roster, including Solar Flare, and the current product scope.

Current Risks

  • Automated smoke coverage for extension activation and core playback flows is still limited.
  • Extension-backed user preferences are not fully wired into real VS Code settings yet.
  • Local playback is the deliberate v0.1 scope; BeatBox does not provide a persistent workspace media library or streaming integrations.
  • Archived experiments such as sonic_sphere.html and swirling_binary.html remain deferred until they have a clear product reason to ship.