Modulr

Modulr is a browser-based, node-driven music creation tool. Build a patch by wiring synth, effect, and utility nodes in a visual graph, then play it in real time using the Web Audio API. It is designed to feel like a modular hardware synth rack, but with an n8n-style node editor, presets, and reusable macro instruments.

Features

• Node-based patching with React Flow canvas
• Real-time audio synthesis in the browser (no server audio)
• Source nodes: Oscillator, FM Synth, Noise, Karplus-Strong, Drum Synth, Granular
• Effects: Filter, Delay, Reverb, Distortion/Waveshaper
• Utility and control: Amp, LFO, Sequencer, Master Out
• Macro instruments: save a selected sub-graph as a reusable instrument
• Preset library and local patch save/load
• Keyboard shortcuts: Space play/stop, Delete remove selected, Ctrl/Cmd+Z undo

What You Can Do

• Design synth patches by connecting nodes (sources, effects, utilities)
• Play/stop the audio engine and adjust BPM
• Save and load patches locally in the browser
• Create reusable macro instruments from a selected sub-graph
• Browse and load factory presets
• Build rhythmic patterns with the sequencer node

Tech Stack

• Frontend: React 19, Vite, React Flow, Zustand, Tailwind CSS
• Audio: Web Audio API
• Backend: Express (development server + production static serving)
• Data: LocalStorage (patches, instruments)

Architecture

• Frontend-first: all synthesis and sequencing happen client-side.
• Express server: serves the Vite app in development and static assets in production.
• Persistence: patches and instruments are stored in localStorage under modulr-patches and modulr-instruments.
• State sync: Zustand store mirrors React Flow state and drives the audio engine.

Modules

• Audio Engine (client/src/audio/engine.ts): creates Web Audio nodes, manages connections, and handles macro instruments.
• State Store (client/src/store/useStore.ts): React Flow state, patch history/undo, persistence, and audio sync.
• Node Components (client/src/components/nodes/): UI and controls for each node type.
• Presets (client/src/data/presets.ts): factory patches and categories.
• Canvas / UI (client/src/pages/Home.tsx): main editor, transport, menus, and user interactions.
• Server (server/): Express app with Vite middleware for dev and static serving in production.

Node Types

• Sources: Oscillator, FM Synth, Noise, Karplus-Strong, Drum Synth, Granular
• Effects: Filter, Delay, Reverb, Distortion/Waveshaper
• Utility: Amp, Master Out
• Modulation/Control: LFO, Sequencer

Macro Instruments

Macro instruments let you turn a selection of nodes into a reusable instrument node.

• Select 2+ nodes, then save as an instrument with a name, color, and exposed parameters.
• Internals are stored with macroId::nodeId IDs to keep them grouped.
• Input/output gain nodes are created to manage external routing.
• Stored in localStorage under modulr-instruments and listed under the “Instruments” section in Add Node.

Audio Engine Notes

• Effects like Delay and Reverb use input/output node pairs for dry/wet routing.
• connect() routes via output nodes: getOutputNode(source) -> getInputNode(target).
• Sequencer uses a scheduling loop with lookahead for timing stability.

Key Files

• client/src/audio/engine.ts - Core audio engine (Web Audio API)
• client/src/store/useStore.ts - Zustand store (graph + audio state)
• client/src/pages/Home.tsx - Main canvas with React Flow
• client/src/components/nodes/ - All node type components
• client/src/components/nodes/MacroNode.tsx - Macro/instrument node UI
• client/src/components/InstrumentDialog.tsx - Save-as-instrument dialog
• client/src/data/presets.ts - Factory preset patches
• client/src/index.css - UI theme tokens

Recent Changes (Feb 2026)

• Added Macro Instruments (save selected nodes as reusable instruments)
• Added Karplus-Strong string synthesis node
• Added Drum Synth node (kick/snare/hihat/clap/tom)
• Added Distortion/Waveshaper effect node
• Added Granular Synth node with sample upload
• Added Ctrl/Cmd+Z undo (50-step history)
• Improved trackpad zoom and added more node types (Delay, Reverb, Noise, LFO)

Run The App

• Requirements: Node.js 18+ recommended

npm install
npm run dev

Optional:

• npm run dev:client for Vite only
• npm run build then npm run start for production

Scripts

• npm run dev - Express + Vite dev server
• npm run dev:client - Vite dev server only
• npm run build - Build client and bundle server to dist/index.cjs
• npm run start - Run production server
• npm run check - TypeScript check
• npm run db:push - Push schema to Postgres (requires DATABASE_URL)

Environment Variables

• PORT - Server port (default: 5000)
• DATABASE_URL - Required only for npm run db:push

Project Structure

• client/ - React app, UI, and audio engine
• client/src/audio/ - Web Audio engine
• client/src/components/nodes/ - Node UIs
• client/src/pages/Home.tsx - Main canvas
• client/src/store/useStore.ts - Zustand state and persistence
• server/ - Express server + Vite dev integration
• shared/ - Shared schema (Drizzle + Zod)

Usage Notes

• Audio starts only after user interaction (browser autoplay policy).
• Saved patches and instruments are per-browser and stored locally.

Contributing

Contributions are welcome, especially new node types, UI improvements, and audio engine enhancements.

Add a New Node Type

1. Implement audio behavior in client/src/audio/engine.ts and add a node handler with input/output nodes.
2. Add default parameters in client/src/store/useStore.ts under defaultNodeData.
3. Create the node UI in client/src/components/nodes/ and wire controls to the store.
4. Register the node in nodeTypes and NODE_CATALOG in client/src/pages/Home.tsx.
5. Optional: add example patches in client/src/data/presets.ts.

General Contribution Workflow

1. Create a branch.
2. Make focused changes with clear naming.
3. Run npm run check before opening a PR.
4. Include a short description and screenshots/gifs if UI changes are involved.

License

MIT