@viji-dev/core 0.8.17 → 0.9.0

package/README.md

@@ -131,13 +131,17 @@ interface VijiCoreConfig {
   // Performance configuration
   frameRateMode?: 'full' | 'half' | 'quarter' | 'eighth'; // refresh rate / 1,2,4,8
   
-  // Input streams
+  // Input streams (mutually exclusive with mediaSource)
   audioStream?: MediaStream;            // Audio input for analysis
   videoStream?: MediaStream;            // Video input (main, CV enabled)
   videoStreams?: MediaStream[];         // Additional video streams (no CV)
-  
+
+  // Engine sharing: attach to another core's media analysis engines.
+  // One analysis pipeline serves all attached cores; analysis state
+  // (BPM lock, onset patterns) survives core transitions.
+  mediaSource?: VijiCore;
+
   // Feature toggles
-  noInputs?: boolean;                   // Disable all input processing
   allowUserInteraction?: boolean;       // Enable mouse/keyboard/touch events
   allowDeviceInteraction?: boolean;     // Enable device sensors (motion/orientation/geolocation)
 }
@@ -1272,50 +1276,52 @@ The core provides extensive performance optimization capabilities:
 - **Efficient Communication**: Optimized message passing between components
 - **Memory Management**: Automatic resource cleanup and memory leak prevention
 
-### Multi-Instance Support
+### Multi-Instance Support & Shared Media Engines
 
-The core supports multiple concurrent instances for complex applications:
+The core supports multiple concurrent instances. Instances that should share
+analysis attach to a sibling's media engines via `mediaSource` — one audio
+pipeline / one AudioContext / one beat stack serves all attached cores, and
+the engines survive until the LAST attached core is destroyed:
 
 ```typescript
-// Main scene with full features
+// Main scene owns the engines
 const mainCore = new VijiCore({
   hostContainer: document.getElementById('main-scene'),
   resolution: { width: 1920, height: 1080 },
   frameRateMode: 'full',
   allowUserInteraction: true,
-  audioStream: sharedAudioStream,
-  videoStream: sharedVideoStream
+  audioStream,
+  videoStream
 });
 
-// Preview instance with reduced features
-const previewCore = new VijiCore({
-  hostContainer: document.getElementById('preview'),
-  resolution: 0.25, // 25% resolution for performance
-  frameRateMode: 'half',
-  noInputs: true,
-  allowUserInteraction: false,
-  audioStream: sharedAudioStream // Shared efficiently across instances
+// Second view shares mainCore's engines: zero extra analysis cost,
+// identical audio/beat data in both scenes
+const secondCore = new VijiCore({
+  hostContainer: document.getElementById('second-view'),
+  sceneCode: otherSceneCode,
+  mediaSource: mainCore
 });
 
-// Thumbnail instance for gallery view
+// Thumbnail instance for gallery view (no streams, no mediaSource:
+// no analysis engines are constructed at all — lazy creation)
 const thumbnailCore = new VijiCore({
   hostContainer: document.getElementById('thumbnail'),
   resolution: 0.1, // 10% resolution
   frameRateMode: 'half',
-  noInputs: true,
   allowUserInteraction: false
 });
 
-// To change scenes, create a new instance and destroy the old one
+// Scene transitions: construct the successor REFERENCING the old core,
+// then destroy the old one. The engine reference is taken synchronously
+// in the constructor, so analysis state (BPM lock, onset patterns)
+// carries across with zero gap — no export/import step.
 const newCore = new VijiCore({
   hostContainer: document.getElementById('scene-host'),
   sceneCode: newSceneCode,
-  audioStream: sharedAudioStream,
-  videoStream: sharedVideoStream
+  mediaSource: oldCore
 });
-
-// Automatic comprehensive cleanup when destroyed
-await oldCore.destroy();
+await newCore.initialize();
+await oldCore.destroy(); // engines survive — newCore still references them
 ```
 
 ## 🔍 Error Handling