How lhuthng/synrecordia works
1. Overall shape
- This is a client-side React application built with Vite. There is no custom backend in the repo; everything runs in the browser and the app is deployed as static assets.
2. Primary user-facing subsystems
- The app has two main experiences: a song player and an interactive visualizer. Users can choose songs, control playback, adjust tempo, loop, and switch instrument settings while seeing synchronized note/fingering graphics.
3. Application shell
- src/main.jsx mounts the app into index.html.
- src/App.jsx is the top-level composition point that ties together the header, directory/navigation, player, visualizer, details panels, and instrument controls.
4. Playback and timing
- src/components/Player.jsx is the core orchestration layer for playback.
- It uses Tone.js for audio scheduling and transport-style timing.
- This component drives play/pause/restart, BPM changes, scrubbing, repeat/loop behavior, and per-track selection.
5. Visualization pipeline
- src/components/Visualizer.jsx renders the note timeline and active-note effects.
- It is backed by PIXI.js via src/hooks/usePixiVisualizer.js, which likely handles the imperative canvas layer and animation updates.
- The visualizer consumes playback state and song note data to keep the graphics aligned with audio.
6. Instrument abstraction layer
- src/components/instruments/ contains the instrument-specific UI and logic.
- InstrumentManager.jsx coordinates instrument instances, while Piano.jsx and Recorder.jsx represent the supported instruments.
- Instrument.jsx appears to be the shared abstraction for instrument controls such as volume and variant selection.
7. Sample loading model
- Instrument audio is shipped as static public assets under public/samples/<instrument>/<version>/.
- Each version directory contains an index.json manifest plus the MP3 files for that sample set.
- The src/libs/packedSampler/ layer is the bridge between the UI and these manifest-driven sample packs, with instrument-specific loaders in piano.js and recorder.js.
8. Song/content model
- Musical content is stored as JSON in public/songs/.
- public/songs/index.json likely acts as the catalog, while each song file encodes tracks, notes, tempo, and metadata used by the player and visualizer.
- The UI reads these files directly over HTTP from the static host.
9. Shared utilities and UI helpers
- src/components/utils/ and src/libs/utils.js contain reusable logic for things like geometry, colors, fingering, and constants.
- src/assets/references/fingering-chart.json provides domain reference data used to render or map recorder fingering visuals.
10. Content and asset boundaries
- public/ is the hard boundary for anything that must be served directly by the host: samples, songs, redirects, robots, and the web manifest.
- public/_redirects suggests Netlify-style static hosting behavior.
- The app itself does not appear to depend on remote APIs at runtime.
11. Tooling and build pipeline
- vite.config.js defines the frontend build/development pipeline.
- eslint.config.js is the main code-quality tool.
- package.json and package-lock.json define the browser runtime dependencies, notably React, Tone.js, and PIXI.js.
12. Repository scripts and asset preparation
- The scripts/ folder contains one-off content-processing tools rather than runtime code.
- These scripts convert or reshape audio and song assets, generate sitemaps, trim/prepare recorder samples, shift octave data, and organize sample-pack structure.
- They support the static asset pipeline that the browser app consumes.
13. Planned extension points
- The README calls out future support for MIDI import/conversion and live play mode via Web MIDI or microphone pitch detection.
- Architecturally, these would add a new input-ingestion layer feeding the same song/track model used by playback and visualization.
14. Diagram-friendly summary
- Think of the system as: static song/sample content in public/ → packed sampler loaders → Tone.js playback → PIXI.js visualizer → React UI controls.
- The only major runtime boundary is the browser; all media, configuration, and song data are fetched from static files served by the host.
Main entry points: App.jsx App · InstrumentManager.jsx InstrumentMgr · Player.jsx Player · Visualizer.jsx Visualizer
Components 21
React app
Browser UI composition and runtime shell
- main · Bootstraps the React app into the page
src/main.jsx - App · Top-level app shell that wires together all major UI areas
src/App.jsx - Header · Primary top bar and navigation chrome
src/components/Header.jsx - Directory · Song/library navigation and selection
src/components/Directory.jsx - Details · Metadata and contextual details for the current song or track
src/components/Details.jsx
Playback and visuals
Timing, audio scheduling, and canvas visualization
- Player · Controls transport, tempo, looping, scrubbing, and track selection
src/components/Player.jsx - usePlayer · Shared playback state and control logic
src/hooks/usePlayer.js - Visualizer · Renders synchronized note and fingering graphics
src/components/Visualizer.jsx - Pixi hook · Imperative PIXI.js rendering and animation layer
src/hooks/usePixiVisualizer.js
Instruments
Instrument controls and sample-pack integration
- InstrumentMgr · Switches and coordinates active instrument instances
src/components/instruments/InstrumentManager.jsx - Instrument · Shared instrument controls such as volume and variants
src/components/instruments/Instrument.jsx - Piano · Piano instrument controls and behavior
src/components/instruments/Piano.jsx - Recorder · Recorder instrument controls and behavior
src/components/instruments/Recorder.jsx - Sampler factory · Creates packed samplers from static sample-pack manifests
src/libs/packedSampler/factory.js - piano loader · Piano sample-pack loader
src/libs/packedSampler/piano.js - recorder loader · Recorder sample-pack loader
src/libs/packedSampler/recorder.js
Static content
Songs, samples, and reference assets served by the host
- Songs · Song JSON files and library index served as static content
public/songs/index.json - Samples · Versioned instrument sample packs and manifests
public/samples/piano/index.json - Fingering chart · Recorder fingering reference used by the UI
src/assets/references/fingering-chart.json
Scripts
One-off asset preparation and content processing tools
- Asset scripts · One-off scripts that transform audio and song assets
scripts/wav2mp3-folder.mjs - Vite config · Frontend build and dev server configuration
vite.config.js
Connections 24
- main → App: mounts · Entry point mounts the top-level app
- App → Header: includes · App shell renders header chrome
- App → Directory: includes · App shell exposes song browsing
- App → Player: includes · App shell embeds playback controls
- App → Visualizer: includes · App shell embeds synchronized visual output
- App → Details: includes · App shell shows song and track details
- App → InstrumentMgr: includes · App shell hosts instrument switching and controls
- Player → usePlayer: uses · Player delegates shared playback state and actions
- Player → Songs: loads · Playback consumes song JSON content
- Player → InstrumentMgr: drives · Playback selects and schedules instrument tracks
- Visualizer → Pixi hook: renders via · Visualizer uses PIXI-backed canvas updates
- Visualizer → Songs: syncs to · Visualizer aligns graphics to song note data
- InstrumentMgr → Instrument: coordinates · Manager wraps shared instrument abstraction
- InstrumentMgr → Piano: hosts · Supports piano instrument variant
- InstrumentMgr → Recorder: hosts · Supports recorder instrument variant
- Piano → piano loader: loads samples via · Piano UI binds to piano sample loader
- Recorder → recorder loader: loads samples via · Recorder UI binds to recorder sample loader
- piano loader → Sampler factory: built by · Instrument loader is created through the packed-sampler bridge
- recorder loader → Sampler factory: built by · Instrument loader is created through the packed-sampler bridge
- Sampler factory → Samples: reads · Sampler bridge consumes manifest-driven sample packs
- Recorder → Fingering chart: references · Recorder UI uses fingering reference data
- Asset scripts → Samples: prepares · Scripts reshape and convert sample assets
- Asset scripts → Songs: prepares · Scripts generate or transform song assets
- Vite config → main: bundles · Build pipeline serves the app entry