audio-mixer-ui 0.7.0 → 0.8.0

package/README.md

@@ -128,6 +128,70 @@ await masterAudio.initialize(musicData)
 
 **Note:** Engine type must be set before initialization. See [audio-mixer-engine](https://www.npmjs.com/package/audio-mixer-engine) for setup details.
 
+## Soundfont Configuration
+
+**Important:** The audio mixer requires a General MIDI soundfont for synthesis. The library does **NOT** bundle a soundfont to keep the npm package lightweight (~1MB instead of ~26MB).
+
+### Option 1: Host Soundfont in Your Public Folder (Default)
+
+Place a soundfont file in your app's public folder:
+
+```
+your-app/
+  public/
+    FluidR3Mono_GM.sf3  ← Place soundfont here
+  src/
+    ...
+```
+
+The library will automatically look for `/FluidR3Mono_GM.sf3` by default. No configuration needed!
+
+### Option 2: Use a CDN or Custom URL
+
+Configure a custom soundfont URL when initializing:
+
+```js
+const masterAudio = useMasterAudioControl({
+  soundfontUrl: 'https://your-cdn.com/soundfonts/FluidR3Mono_GM.sf3'
+})
+
+// Then initialize as normal
+await masterAudio.initialize(musicData)
+```
+
+### Recommended Soundfonts
+
+- **FluidR3Mono_GM.sf3** (23MB) - High quality, mono, General MIDI
+  - MIT licensed
+  - Download: Search for "FluidR3Mono_GM" or check FluidSynth documentation
+
+- **FluidR3_GM.sf2** (142MB) - Stereo version with more detail
+  - Larger file size, higher quality
+
+### Demo Soundfont
+
+The live demo at GitLab Pages includes a bundled soundfont for convenience. Your production app should host its own soundfont file.
+
+### Fallback Behavior
+
+If the custom soundfont URL fails to load, the library will try these default paths in order:
+1. `/FluidR3Mono_GM.sf3`
+2. `/FluidR3_GM.sf2`
+3. `/soundfont.sf2`
+
+If none are found, initialization will fail with an error.
+
+### Example: Environment-Based Configuration
+
+```js
+// Use CDN in production, local in development
+const soundfontUrl = import.meta.env.PROD
+  ? 'https://cdn.example.com/FluidR3Mono_GM.sf3'
+  : '/FluidR3Mono_GM.sf3'
+
+const masterAudio = useMasterAudioControl({ soundfontUrl })
+```
+
 ## Musical Data Structure
 
 The components expect musical timing data in this format: