🎹 React Synth Plus

React Synth Plus is a high-performance, headless wavetable synthesizer for React, built on top of the powerful Tone.js engine. Inspired by legendary synthesizers like Xfer Serum, it brings professional-grade audio synthesis to the browser with a modern, reactive developer experience.

---

✨ Key Features

• 🚀 Headless Architecture: Complete separation of audio logic and UI. Build your own synth interface using our custom React hooks.
• 🎨 Pre-built UI Components: Optional, modular components (Keyboard, Filters, FX) for instant dashboard creation.
• 🌊 Wavetable Engine: Smooth morphing between complex wavetable partials.
• 🎸 Built-in FX Rack: Professional distortion, reverb, and feedback delay out of the box.
• 🎹 Intelligent Keyboard Hook: Effortless QWERTY-to-MIDI mapping and polyphonic note management.
• 🧪 Rock Solid: Fully tested with Vitest and React Testing Library.

---

📦 Installation

npm install react-synth-plus

Note: Ensure you have react, react-dom, and tone installed in your project.

1. Using Pre-built UI Components

The fastest way to get started. Import the components and the bundled CSS for a professional look.

import { useState } from 'react';
import { Keyboard, FilterControl, useAudioEngine } from 'react-synth-plus';

// Import the bundled styles (choose ONE of the following):
import 'react-synth-plus/dist/style.css'; 
// or if your bundler supports aliases:
// import 'react-synth-plus/style.css';

const MySynth = () => {
  const { isStarted, init, setParam } = useAudioEngine();
  const [filterState, setFilterState] = useState({ type: 'lowpass', cutoff: 2000 });

  return (
    <div className="p-10 bg-zinc-950 min-h-screen text-white">
      {!isStarted ? (
        <button className="bg-red-500 p-4 rounded" onClick={init}>Start Engine</button>
      ) : (
        <div className="flex flex-col gap-4">
          <FilterControl value={filterState} onChange={setParam} />
          <Keyboard />
        </div>
      )}
    </div>
  );
};

---

🏗️ UI Component Library

React Synth Plus ships with a set of modular, Tailwind-styled components. To use them, ensure you import react-synth-plus/style.css.

Component	Description
<Keyboard />	A full piano roll with mouse, touch, and QWERTY support.
<Visualizer />	Real-time HTML5 Canvas oscilloscope.
<OscillatorControl />	Controls for wavetable selection and morphing.
<FilterControl />	Controls for filter mode and cutoff frequency.
<SubControl />	Controls for the sub-oscillator.
<NoiseControl />	Controls for the noise generator.
<LFOControl />	Controls for LFO rate, depth, and routing.
<EnvelopeControl />	Controls for the master ADSR envelope.
<FXControl />	Controls for distortion, reverb, and delay.

---

🚀 Headless Hooks (Advanced)

Build your own UI logic from scratch using the useAudioEngine hook.

import { useAudioEngine } from 'react-synth-plus';

const MySynth = () => {
  const { isStarted, init, engine } = useAudioEngine();

  return (
    <div>
      {!isStarted ? (
        <button onClick={init}>Initialize Audio</button>
      ) : (
        <button onMouseDown={() => engine.playNote('C4')} onMouseUp={() => engine.stopNote('C4')}>
          Play C4
        </button>
      )}
    </div>
  );
};

2. Controlling Parameters

Manipulate any part of the audio engine (Filters, Envelopes, FX) using the setParam(module, parameter, value) function.

import { useAudioEngine } from 'react-synth-plus';

const FilterControl = () => {
  const { setParam } = useAudioEngine();

  return (
    <input 
      type="range" min="20" max="10000" 
      onChange={(e) => setParam('filter', 'cutoff', parseFloat(e.target.value))} 
    />
  );
};

Available Parameters:

Module	Parameter	Description
osc1	wavetable, wtPos	Select table (basic, harmonic) and morph position (0-1).
filter	type, cutoff	Mode (lowpass, highpass, bandpass) and frequency (Hz).
sub	type, volume	Waveform and gain (0-1) for the sub oscillator.
noise	type, volume	Type (white, pink, brown) and gain (0-1).
lfo	type, rate, depth, target	LFO shape, speed (Hz), depth, and target (cutoff, pitch).
env	attack, release	ADSR timings (seconds) for the master amplitude envelope.
fx	dist, reverbMix, delayMix, delayTime, delayFeedback	Global distortion, reverb mix, and delay rack parameters.

3. Building a Keyboard

Leverage useKeyboard for instant on-screen and QWERTY keyboard support.

import { useKeyboard } from 'react-synth-plus';

const MyKeyboard = () => {
  const { pressedNotes, playNote, stopNote, keys } = useKeyboard();

  return (
    <div className="flex gap-1">
      {keys.map(({ note, key, type }) => (
        <div
          key={note}
          className={`p-4 border ${pressedNotes.has(note) ? 'bg-blue-500' : 'bg-white'}`}
          onMouseDown={() => playNote(note)}
          onMouseUp={() => stopNote(note)}
        >
          {key.toUpperCase()}
        </div>
      ))}
    </div>
  );
};

---

🛠️ Development & Examples

This repository includes a comprehensive Showcase Project that demonstrates all features in a single dashboard.

Run the Showcase

git clone https://github.com/hathibelagal-dev/react-synth-plus.git
cd react-synth-plus
npm install
npm run dev:showcase

Building the Library

npm run build:lib

Running Tests

npm test

---

📐 Architecture

[Your UI Components] <---> [Headless Hooks] <---> [Audio Engine (Tone.js)]
      (Tailwind)          (useAudioEngine)         (PolySynth, FX)

---

📜 License

Distributed under the GPL v3 License. See LICENSE for more information.

---

Made with ❤️ and a lot of oscillators.