- Live Demo
- User Guide
- Overview
- Graphical Programming Interface: Exportable to JavaScript Code
- Key Features
- PWA Support
- Getting Started
- Architecture
- Examples
- Contributing
Screen.Recording.2025-06-02.at.00.21.40.mov
🌐 Try Visual Web Audio Online - Experience the application in your browser!
📚 Complete User Guide - Comprehensive documentation covering all features, from basic usage to advanced techniques. Perfect for both beginners and experienced users.
The user guide includes:
- Getting Started: System requirements and first steps
- Interface Overview: Detailed explanation of all UI components
- Node Types & Connections: Complete reference for all audio nodes
- Recording & Project Management: How to save and manage your work
- Keyboard Shortcuts: Efficiency tips and shortcuts
- Troubleshooting: Solutions to common issues
- Tips & Best Practices: Expert advice for creating great audio graphs
A type-driven React TypeScript application for visual Web Audio API editing that bridges visual audio engineering with code generation. This project demonstrates innovative type-driven development by extracting all node information directly from TypeScript's Web Audio API definitions.
📖 For a detailed technical analysis of how this application works, including architecture diagrams and data flow, see our Architecture Documentation.
Unlike traditional audio editors that hardcode node definitions, this project:
- Extracts metadata directly from TypeScript's Web Audio API definitions (
@types/web) - Automatically discovers new nodes and properties when TypeScript definitions are updated
- Ensures type safety throughout the entire application
- Stays current with Web Audio API evolution without manual updates
Visual Web Audio offers a unique Graphical Programming Interface that transforms visual audio graphs into executable JavaScript code:
- Visual Design: Create complex audio graphs using drag-and-drop interface
- Real-time Validation: Visual feedback ensures valid connections and properties
- Code Generation: Export visual graphs as clean, executable JavaScript code
- Copy-to-Clipboard: One-click copying with syntax highlighting
- Exports to Fully Functional and Dependency-Free JS Code:
Just copy the generated code in a basic HTML file:
<body>
<script>
// Paste here the generated code
</script>
</body>- Visual Audio Graph Editor: Drag-and-drop node creation with type validation and color-coded connections
- Copy/Paste Nodes: Multi-node selection with copy/cut/paste support (Ctrl+C/X/V) that preserves connections and works across browser tabs
- Metadata-Driven Architecture: 22+ Web Audio API nodes automatically discovered from TypeScript definitions
- Custom Nodes System: 10+ interactive custom nodes including buttons, sliders, MIDI input, and sound file players with pause/resume persistence
- Voice Effects Processing: Real-time microphone input with robot voice, vocoder, harmonizer, and transformer effects
- Audio Recording & Management: Record audio output to WAV format with download, rename, and delete capabilities stored locally in IndexedDB
- Project Management: Export/Import projects as JSON with unsaved changes tracking and undo/redo system / IndexedDB storage
- Real-time Audio Processing: Web Audio API integration with memory leak prevention and lifecycle management
- Error Handling: Comprehensive error boundaries and connection validation
- Progressive Web App: Installable with offline support and caching
Visual Web Audio is a Progressive Web App (PWA) that can be installed on your device for a native app-like experience. Features include:
- Offline Functionality: Core app works offline - create graphs, use nodes, export projects
- Installable: Add to home screen on mobile/desktop
- Automatic Updates: Always get the latest version
- Fast Loading: Cached resources for instant startup
The application works offline with most features available:
✅ Available Offline:
- Create and edit audio graphs
- Use all Web Audio API nodes and custom nodes
- Export/import projects as JSON
- Generate JavaScript code
- Local project storage (IndexedDB) - persists between sessions
❌ Requires Internet:
- Loading external audio files from URLs
- Checking for app updates
- Accessing online examples or documentation
The application includes an intelligent update system that ensures users always have the latest version:
- Build Timestamps: Each build includes a unique timestamp for version detection
- Smart Checking: Automatically checks for updates when the app is accessed and every 24 hours
- User-Friendly Notifications: Non-intrusive update notifications with "Update Now" or "Later" options
- Seamless Updates: One-click updates with automatic page refresh
- Background Monitoring: Service worker continuously monitors for new versions
When an update is available, you'll see a blue notification in the top-right corner. Click "Update Now" to instantly get the latest features and improvements!
- Node.js 18+
- npm or yarn
# Clone and install
git clone https://github.com/miltonlaufer/visualwebaudio.git
cd visualwebaudio
npm install
# Start development server (includes automatic type extraction)
npm run dev
# Other useful commands
npm run build # Build for production
npm run test # Run tests
npm run test:watch # Run tests in watch mode
npm run test:ui # Run tests with UI
npm run test:coverage # Run tests with coverage report
npm run test:coverage:ui # Run tests with coverage and UI
npm run type-check # TypeScript type checking
npm run lint # ESLint code qualityGitHub Actions automatically runs type checking, tests, and linting on all PRs.
- Automatic API Updates: Updating
@types/webbrings new Web Audio features automatically - Type Safety: Full TypeScript coverage ensures runtime reliability
- Reduced Maintenance: No manual node definitions to maintain
- Future-Proof: Adapts to API changes without code modifications
Visual Web Audio uses a sophisticated type-driven architecture that automatically extracts metadata from TypeScript's Web Audio API definitions, combined with clean domain-driven design patterns. For a detailed technical deep-dive, see our Architecture Documentation.
- Type-Driven Development: Automatic extraction of Web Audio API metadata from TypeScript definitions
- Domain Layer: Pure business logic with Strategy, Repository, and Facade patterns
- MST State Management: Hierarchical state management with MobX State Tree
- Service Layer: AudioNodeFactory and CustomNodeFactory for node creation
- React Components: Modular component architecture with React Flow
src/
domain/ # Pure business logic (no React/MobX dependencies)
music/ # MIDI and scale utilities
nodes/ # Node strategies and registry
strategies/ # Strategy pattern for custom node behaviors
NodeRegistry.ts # Repository pattern for metadata access
audio/ # AudioConnector facade
stores/ # MobX State Tree stores
RootStore.ts # Composition root
AudioGraphStore.ts # Core audio graph state
GraphStore.ts # Graph topology facade
AudioRuntimeStore.ts # Audio runtime facade
UIStore.ts # UI state management
services/ # Node factories
components/ # React components
- Strategy Pattern: Custom node behaviors via
INodeStrategyinterface - Repository Pattern:
NodeRegistryfor centralized metadata access - Facade Pattern:
AudioConnector,GraphStore,UIStorefor simplified APIs - Factory Pattern:
AudioNodeFactory,CustomNodeFactoryfor node creation - Adapter Pattern:
NodeAdapterfor unified node representation - Observer Pattern: MobX reactions for state synchronization
For implementation details, architecture diagrams, and design patterns, please refer to the Architecture Documentation.
- React 19 with TypeScript
- Vite for development and building
- MobX State Tree for type-safe state management
- React Flow for visual graph editing
- Tailwind CSS for styling
- Vitest for testing (60.4% coverage)
The application includes 21+ working audio examples:
Basic Audio Processing: Basic Oscillator, Microphone Input with Delay, Delay Effect, Filter Sweep, Stereo Panning, Compressor Effect, Tremolo Effect, Ring Modulation, Chord Synthesis, Waveshaper Distortion, Phaser Effect, Simple Noise, Amplitude Envelope, Beat Frequency, Convolution Reverb, Microphone Reverb, Stereo Effects
Voice Effects (NEW): Robot Voice (Ring Mod), Vocoder Voice, Voice Harmonizer, Voice Pitch Shifter - Transform your voice with real-time microphone processing
Synthesizers: Vintage Analog Synth - Classic analog synthesizer with oscillators, filters, and envelopes
The application includes several custom nodes for enhanced functionality:
- Slider Node: Interactive slider for controlling values
- Button Node: Clickable button for triggering events
- Display Node: Shows numeric values with customizable precision
- Random Node: Generates random values at specified intervals
- Timer Node: Generates periodic triggers with configurable timing
- Sound File Node: Loads and plays audio files
- MIDI Input Node: Receives MIDI messages from connected devices
- MIDI to Frequency Node: Converts MIDI note numbers to frequencies
- Scale to MIDI Node: Converts scale degrees to MIDI notes based on key and mode
- Logic Nodes: Greater Than, Equals, and Select nodes for conditional logic
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Ensure all checks pass:
npm run type-check && npm run test && npm run lint - Submit a pull request
MIT License - see the LICENSE file for details.