mod

Overview

mod is a React library for building modular audio applications using the Web Audio API. Compose audio processing chains with declarative React components, just like building a modular synthesizer.

Features

• 🎛️ Modular Design - Composable audio components that can be connected in any configuration
• ⚡ Type-Safe - Full TypeScript support with comprehensive type definitions
• 🎨 Flexible API - Three usage patterns: render props, controlled props, and imperative refs
• 🔌 Extensive Module Library - Sources, processors, CV generators, mixers, visualizations, and more
• 📊 Real-time Control - React-driven parameter control with smooth automation
• 🎵 Professional Audio - Built on the Web Audio API for high-quality sound

Installation

npm install @mode-7/mod

Quick Start

import { AudioProvider, ToneGenerator, Filter, Monitor } from '@mode-7/mod';
import { useRef } from 'react';

function SimpleSynth() {
  const toneOut = useRef(null);
  const filterOut = useRef(null);

  return (
    <AudioProvider>
      <ToneGenerator output={toneOut}>
        {({ frequency, setFrequency, gain, setGain }) => (
          <div>
            <input
              type="range"
              min="20"
              max="2000"
              value={frequency}
              onChange={(e) => setFrequency(Number(e.target.value))}
            />
            <input
              type="range"
              min="0"
              max="1"
              step="0.01"
              value={gain}
              onChange={(e) => setGain(Number(e.target.value))}
            />
          </div>
        )}
      </ToneGenerator>

      <Filter input={toneOut} output={filterOut}>
        {({ frequency, setFrequency }) => (
          <input
            type="range"
            min="20"
            max="20000"
            value={frequency}
            onChange={(e) => setFrequency(Number(e.target.value))}
          />
        )}
      </Filter>

      <Monitor input={filterOut}>
        {({ gain, setGain, isMuted, setMuted }) => (
          <div>
            <input
              type="range"
              min="0"
              max="2"
              step="0.01"
              value={gain}
              onChange={(e) => setGain(Number(e.target.value))}
            />
            <button onClick={() => setMuted(!isMuted)}>
              {isMuted ? 'Unmute' : 'Mute'}
            </button>
          </div>
        )}
      </Monitor>
    </AudioProvider>
  );
}

Module Categories

Sources

• ToneGenerator - Oscillator with sine, square, sawtooth, and triangle waveforms
• NoiseGenerator - White and pink noise generator
• Microphone - Live audio input from microphone
• MP3Deck - Audio file playback with loop control
• StreamingAudioDeck - Stream audio from URLs

CV (Control Voltage)

• LFO - Low-frequency oscillator for modulation
• ADSR - Attack-Decay-Sustain-Release envelope generator with gate input
• Sequencer - Step sequencer for creating rhythmic patterns
• Clock - Precise timing source for triggering envelopes and sequencers

Processors

• Filter - Multi-mode filter (lowpass, highpass, bandpass, etc.)
• Delay - Delay effect with feedback control
• Reverb - Convolution reverb with adjustable decay
• Compressor - Dynamic range compression
• Distortion - Waveshaping distortion
• Panner - Stereo panning
• EQ - 3-band equalizer
• Chorus - Chorus effect
• Phaser - Phaser effect
• Flanger - Flanger effect
• Tremolo - Amplitude modulation
• BitCrusher - Lo-fi bit reduction
• Limiter - Peak limiter
• Gate - Noise gate
• AutoWah - Envelope-following filter
• RingModulator - Ring modulation effect

Mixers

• Mixer - 4-channel mixer with level control
• CrossFade - Crossfade between two inputs with multiple curve modes

Output

• Monitor - Audio output with device selection and muting

Visualizations

• Oscilloscope - Waveform visualization showing time-domain audio data
• SpectrumAnalyzer - Frequency spectrum visualization with color-coded bars
• LevelMeter - Audio level meter with peak detection and clipping indicator

Architecture

mod follows a modular architecture inspired by hardware synthesizers:

1. Wrap your app in <AudioProvider> - Initializes the Web Audio context
2. Create modules - Each module is a React component representing an audio node
3. Connect modules - Pass refs between modules to create audio chains
4. Render controls - Use render props to build custom UIs for each module

CV Modulation

Connect CV (Control Voltage) sources to audio module parameters:

const lfoOut = useRef(null);
const toneOut = useRef(null);

<LFO output={lfoOut} />
<ToneGenerator cv={lfoOut} output={toneOut} />
<Monitor input={toneOut} />

Rhythmic Triggering

Use the Clock module to trigger ADSR envelopes:

const clockOut = useRef(null);
const adsrOut = useRef(null);
const toneOut = useRef(null);

<Clock output={clockOut} />
<ADSR gate={clockOut} output={adsrOut} />
<ToneGenerator cv={adsrOut} output={toneOut} />
<Monitor input={toneOut} />

Browser Support

mod requires a modern browser with Web Audio API support:

• Chrome 35+
• Firefox 25+
• Safari 14.1+
• Edge 79+

Development

# Install dependencies
npm install

# Start demo app
npm run dev

# Build library
npm run build

# Build all packages
npm run build:all

Examples

Check out the Playground to see mod in action and experiment with different module combinations.

Documentation

Full documentation is available at mode-7.github.io/mod/docs

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.