How promethiuml/tonalpalette works
Project type and purpose
• This is a front-end, single‐page web application (no backend services) that visualizes incoming MIDI data in real time.
• It uses P5.js for rendering and WebMIDI.js (and the browser’s WebMIDI API) for MIDI input.
File structure
• Top level:
• index.html, public/style.css – the host page and global styles
• src/… – TypeScript source modules:
– midiMonitor.ts – wraps WebMIDI.js and listens for MIDI events
– tonalEstimator.ts – converts raw MIDI into tonal/harmonic information
– particle.ts, sceneObject.ts – data structures for visual objects
– scene.ts – overall scene manager (updates & draws objects)
– constants.ts, types.ts – shared definitions
• libraries/webmidi.js – third-party wrapper for WebMIDI API
• vite.config.js, tsconfig.json – build & development configuration
• dist/… – production bundle output
Extract insights from the README
• Real-time MIDI visualizer for harmony exploration
• Keyboard shortcuts: toggle UI (H), clear (C)
• Demo URL provided
Main components & their relationships
a. Browser Environment
– Hosts the application, loads index.html, runs JavaScript/Vite dev server in development.
b. External Libraries
– WebMIDI.js: abstracts the browser’s WebMIDI API.
– P5.js: rendering engine for 2D canvas animations.
c. MIDI Input Layer (midiMonitor.ts)
– Subscribes to MIDI device messages via WebMIDI.js.
– Emits events to tonalEstimator.
d. Processing Layer
– tonalEstimator.ts: transforms MIDI note on/off into tonal/harmony data (pitch class, chord, scale).
e. Visualization Layer
– scene.ts: orchestrates object lifecycles (spawn, update, remove).
– particle.ts & sceneObject.ts: implement individual visual entities.
f. UI & Controls
– DOM overlay/style.css: show/hide settings panel, clear command via keystrokes.
Architectural patterns & design principles
• Modular separation: Input → Processing → Rendering
• Event-driven data flow: MIDI events trigger processing and visualization updates
• Single responsibility modules: each .ts file handles one concern
• Build pipeline (Vite + ESBuild): TS → ESNext bundle → dist
– Browser / Host Page
– WebMIDI.js (External Library)
– midiMonitor
– tonalEstimator
– palette
– scene Manager
– Particle / SceneObject modules
– P5.js Renderer
– UI Controls (settings panel)
– index.html → loads → main.ts / sketch.ts
– midiMonitor → emits → tonalEstimator → passes tonal data → palette
– scene Manager → uses → P5.js API → draws → canvas
– Keyboard input → UI Controls → toggles → scene or settings overlay
– Blue rectangles: source modules (TS files)
– Green rectangle: External libraries (WebMIDI.js, P5.js)
– Orange rectangles: UI/Controls
d. Annotations:
– Group all src/… modules in a “Frontend Application” container
– Indicate build step: Vite → bundle → dist/