audio-mixer-ui 0.5.3 → 0.8.0

package/README.md

@@ -1,17 +1,14 @@
 # Audio Mixer UI Components
 
-A Vue 3 component library for building audio mixer interfaces with musical navigation and control features. 
-Originally developed for a choir practice application, these components provide audio controls with responsive design and accessibility features.
+Vue 3 component library for building audio mixer interfaces with musical navigation and control features.
 
 ## Features
 
-- **Audio Controls**: Custom sliders, buttons, and level meters with haptic feedback
-- **Musical Navigation**: Bar/beat input, practice marks, tempo controls with bidirectional time mapping
-- **Responsive Design**: Optimized layouts for mobile, tablet, and desktop
-- **Event-Driven Architecture**: Clean separation between UI and audio engine
-- **Accessibility Ready**: ARIA labels, keyboard navigation, screen reader support
-- **Lightweight**: No heavy UI framework dependencies, just Vue 3
-- **TypeScript Ready**: Full TypeScript definitions included
+- Audio controls with level meters and haptic feedback
+- Musical navigation (bar/beat input, practice marks, tempo controls)
+- Responsive design for mobile, tablet, and desktop
+- Event-driven architecture with separate UI and audio layers
+- ARIA labels, keyboard navigation, and screen reader support
 
 ## Installation
 
@@ -80,61 +77,119 @@ app.mount('#app')
 
 ## Core Components
 
-The library exports components that automatically integrate with Pinia stores:
+Components automatically integrate with Pinia stores:
 
-### Layout Components
-- **`MixerLayout`** - Responsive container that auto-renders parts from store data
-- **`MixerControls`** - Transport controls connected to audio state
-
-### Audio Controls
-- **`AudioSlider`** - Professional fader with live level indicators
-- **`AudioButton`** - Button with visual/haptic feedback
-- **`PartControl`** - Complete part mixer (auto-generated from store)
-- **`TriState`** - Mute/Solo toggle
-
-### Musical Navigation
-- **`BarInput`** - Bar navigation with practice mark integration
-- **`TimeInput`** - Time display synced to playback position
+- **`MixerLayout`** - Responsive container that renders parts from store data
+- **`MixerControls`** - Transport controls (play, stop, pause)
+- **`AudioSlider`** - Fader with live level indicators
+- **`PartControl`** - Individual part mixer (volume, mute, solo)
+- **`BarInput`** - Bar navigation with practice marks
+- **`TimeInput`** - Time display synced to playback
 - **`SpeedInput`** - Playback speed control
 
-### Utilities
-- **`BaseNumericInput`** - Foundation for numeric inputs
-- **`TitleText`** - Responsive text display
-
 ## State Management
 
-Components automatically connect to Pinia stores for reactive state management. The library exports three main stores:
+Components connect to Pinia stores automatically:
 
 ```js
 import {
-  useAudioStateStore,     // Current playback state (time, volume, playing)
+  useAudioStateStore,     // Playback state (time, volume, playing)
   useMusicDataStore,      // Musical structure (beats, parts, marks)
   usePlaybackStateStore,  // Transport settings (loop, metronome)
-  useMasterAudioControl   // Master composable for audio control
+  useMasterAudioControl   // Master composable for control
 } from 'audio-mixer-ui'
 
-// Components automatically connect to stores - no manual wiring needed
-const audioState = useAudioStateStore()
-const musicData = useMusicDataStore()
 const masterAudio = useMasterAudioControl()
 
-// Initialize with your musical data
+// Initialize with musical data
 masterAudio.initialize(musicData)
+
+// Control playback
+masterAudio.play()
+masterAudio.stop()
+masterAudio.setBar(5, 1)
+masterAudio.setPartVolume('Soprano', 0.8)
 ```
 
-## Integration Pattern
+## Audio Engine Configuration
 
-Components handle user interactions via the master audio composable:
+Choose between SpessaSynth (soundfont-based, 10-50MB) or Lightweight (sample-based, ~4MB):
 
 ```js
-// Inside components, actions are coordinated through the master composable
+import { audioEngineConfig } from 'audio-mixer-ui'
+
+// Use LightweightAudioEngine (default is SpessaSynth)
+audioEngineConfig.setEngineType('lightweight')
+
+// Then initialize as normal
 const masterAudio = useMasterAudioControl()
+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:
 
-// User interactions trigger master audio methods
-masterAudio.play()
-masterAudio.stop()
-masterAudio.setBar(5, 1)  // bar 5, repeat 1
-masterAudio.setPartVolume('Soprano', 0.8)
+```
+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
@@ -188,38 +243,21 @@ npm run lint
 
 ## Architecture
 
-The library follows an event-driven layered architecture:
+Event-driven layered architecture:
 
-1. **Components** - Vue 3 components with composition API
-2. **Composables** - Reusable logic for audio control and state management  
-3. **Stores** - Pinia stores for reactive state
-4. **Services** - Audio engine integration layer
+1. **Components** - Vue 3 with Composition API
+2. **Composables** - Shared logic for audio control and state
+3. **Stores** - Pinia for reactive state management
+4. **Services** - Audio engine integration
 
-### Key Design Principles
+Key principles: Audio thread isolation, event-driven coordination, runtime part discovery.
 
-- **Audio Thread Isolation**: Audio processing separated from reactive UI state
-- **Event-Driven Coordination**: Real-time synchronization via event bus
-- **Dynamic Configuration**: Runtime discovery of parts and musical structure
-- **Responsive First**: Mobile-first design with progressive enhancement
+## Requirements
 
-## Browser Support
-
-- Modern browsers with ES2020+ support
-- Vue 3.4+ and Pinia for state management
-- Web Audio API for audio features
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new functionality
-4. Ensure all tests pass
-5. Submit a pull request
+- Vue 3.4+
+- Pinia
+- Modern browser with Web Audio API support
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) file for details.
-
-## Related Projects
-
-This component library was extracted from a larger choir practice application.
+MIT License - see [LICENSE](./LICENSE) file for details.