SoundSwarm 🎵

A collaborative web-based music creation app where multiple users can play notes from shared chord progressions to create ambient soundswarms together.

Features

• Collaborative Ambient Drones - Share a link with friends and everyone gets assigned a unique note from the chord
• Multiple Chord Presets - Choose from various chord progressions including ambient pads and classic harmonies
• Customizable Sound Design
  • 4 waveform types (sine, square, triangle, sawtooth)
  • Adjustable detune for thicker sounds
  • Smooth note transitions (glide or crossfade)
• Arpeggiator - Automatically cycle through notes at configurable intervals
• Visual Feedback - Optional canvas visualization that responds to your sound
• Offline Support - Works without a backend using local note assignment
• Mobile Friendly - Full iOS Safari support with proper audio unlocking

Quick Start

1. Clone the repository:

   git clone https://github.com/yourusername/soundswarm.git
   cd soundswarm

2. Serve the files with any static file server:

   # Using Python
   python -m http.server 8000
   
   # Using Node.js
   npx serve
   
   # Using PHP
   php -S localhost:8000

3. Open http://localhost:8000 in your browser

4. Share the URL with friends to create music together!

URL Parameters

Customize the experience with URL parameters:

Parameter	Description	Example
chord	Preset chord name	?chord=CMajor
notes	Custom note list	?notes=C4,E4,G4,B4
sid	Session ID for note coordination	?sid=my-session

Available Chord Presets

• Test - G major with extensions
• BesideYouInTime - Dm7 ambient pad (inspired by Nine Inch Nails)
• CMajor, GMajor, DMajor - Classic major triads
• AmMaj7, EmMaj7 - Minor major seventh chords
• Dsus2, Asus2, Esus4 - Suspended chords
• Gmaj9 - Major ninth chord

Custom Notes

Use the notes parameter with comma-separated note names:

?notes=D3,F3,A3,C4,E4,G4

Note format: NoteName + Octave (e.g., C4, F#3, Bb5)

Project Structure

soundswarm/
├── index.html      # Main HTML structure
├── styles.css      # All styling including grain effect
├── app.js          # Application logic and Web Audio API
├── README.md       # This file
├── LICENSE         # MIT License
├── CONTRIBUTING.md # Contribution guidelines
└── .gitignore      # Git ignore rules

How It Works

Audio Engine

SoundSwarm uses the Web Audio API to generate sounds:

1. Oscillators - Generate the base waveforms
2. Gain Nodes - Control volume with smooth ramps to prevent clicks
3. Filter - Low-pass filter with LFO modulation for movement
4. LFOs - Modulate amplitude and filter for evolving textures

Note Assignment

When multiple users join:

1. Each user's browser requests a note from the chord
2. Notes are assigned to create complementary harmonies
3. Session state is stored in localStorage

iOS Safari Support

iOS requires special handling for Web Audio:

• AudioContext must be created during a user gesture
• Silent oscillator/buffer played to "unlock" audio
• Multiple event listeners ensure reliable playback

Browser Support

• Chrome/Edge 80+
• Firefox 75+
• Safari 14+
• iOS Safari 14+

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the ambient soundscapes of Nine Inch Nails
• Built with the Web Audio API

---

Made by Matthias Feit