@meframe/core 0.1.8 → 0.2.0

package/dist/orchestrator/GlobalAudioSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GlobalAudioSession.d.ts","sourceRoot":"","sources":["../../src/orchestrator/GlobalAudioSession.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GlobalAudioSession.d.ts","sourceRoot":"","sources":["../../src/orchestrator/GlobalAudioSession.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/GlobalAudioSession.js

@@ -1,5 +1,6 @@
 import { OfflineAudioMixer } from "../stages/compose/OfflineAudioMixer.js";
 import { MeframeEvent } from "../event/events.js";
+import { AudioMixBlockCache } from "../cache/AudioMixBlockCache.js";
 import { AudioChunkEncoder } from "../stages/encode/AudioChunkEncoder.js";
 import { AudioChunkDecoder } from "../stages/decode/AudioChunkDecoder.js";
 import { hasResourceId, isAudioClip } from "../model/types.js";
@@ -12,20 +13,59 @@ class GlobalAudioSession {
   volume = 1;
   playbackRate = 1;
   isPlaying = false;
-  // Lookahead scheduling state
-  nextScheduleTime = 0;
-  // Next AudioContext time to schedule
-  nextContentTimeUs = 0;
-  // Next timeline position (Us)
-  scheduledSources = /* @__PURE__ */ new Set();
-  LOOKAHEAD_TIME = 0.2;
-  // 200ms lookahead
-  CHUNK_DURATION = 0.1;
-  // 100ms chunks
+  // Preview strategy (unified):
+  // - Always schedule audio in fixed 60s "mix blocks"
+  // - Cache 2~3 mixed AudioBuffer blocks (LRU) to accelerate seek
+  // - Schedule ahead using AudioContext clock to avoid underrun
+  PREVIEW_BLOCK_DURATION_US = 60 * 1e6;
+  // 60s
+  PREVIEW_BLOCK_CACHE_SIZE = 3;
+  PREVIEW_SCHEDULE_AHEAD_SEC = 12;
+  // keep enough scheduled audio to hide mixing latency
+  PREVIEW_BUFFER_GUARD_US = 2e6;
+  // if next block isn't ready near boundary -> buffering
+  PREVIEW_BLOCK_FADE_SEC = 0.01;
+  // 10ms fade-in/out to avoid click at boundaries
+  previewBlockCache = new AudioMixBlockCache(this.PREVIEW_BLOCK_CACHE_SIZE);
+  previewScheduleTask = null;
+  previewScheduleToken = 0;
+  previewMixToken = 0;
+  previewNextBlockIndex = 0;
+  previewNextScheduleTime = 0;
+  // AudioContext time
+  previewFirstBlockOffsetUs = 0;
+  // seek offset within the first block
+  previewLastTimelineUs = 0;
+  previewLastStallWarnAt = 0;
+  // AudioContext time (sec)
+  previewScheduledSources = /* @__PURE__ */ new Set();
+  previewMixQueue = Promise.resolve();
   constructor(deps) {
     this.deps = deps;
     this.mixer = new OfflineAudioMixer(deps.cacheManager, () => this.model);
   }
+  enqueuePreviewMix(work, token) {
+    const run = () => work();
+    const next = this.previewMixQueue.then(
+      () => {
+        if (this.previewMixToken !== token) {
+          return null;
+        }
+        return run();
+      },
+      () => {
+        if (this.previewMixToken !== token) {
+          return null;
+        }
+        return run();
+      }
+    );
+    this.previewMixQueue = next.then(
+      () => void 0,
+      () => void 0
+    );
+    return next;
+  }
   setModel(model) {
     this.model = model;
   }
@@ -35,15 +75,41 @@ class GlobalAudioSession {
     this.deps.cacheManager.putClipAudioData(sessionId, audioData, clipDurationUs, globalTimeUs);
   }
   async ensureAudioForTime(timeUs, options) {
-    if (!this.model) return;
+    const model = this.model;
+    if (!model) return;
     const mode = options?.mode ?? "blocking";
-    const WINDOW_DURATION = 3e6;
-    const windowEndUs = Math.min(this.model.durationUs, timeUs + WINDOW_DURATION);
+    const blockIndex = Math.floor(Math.max(0, timeUs) / this.PREVIEW_BLOCK_DURATION_US);
     if (mode === "probe") {
-      void this.ensureAudioForTimeRange(timeUs, windowEndUs, { mode, loadResource: true });
+      void this.getOrCreateMixedBlock(blockIndex);
+      const blockEndUs2 = (blockIndex + 1) * this.PREVIEW_BLOCK_DURATION_US;
+      const remainingToBoundaryUs2 = blockEndUs2 - Math.max(0, timeUs);
+      const lookaheadUs = Math.floor(this.PREVIEW_SCHEDULE_AHEAD_SEC * 1e6);
+      if (remainingToBoundaryUs2 > 0 && remainingToBoundaryUs2 <= lookaheadUs) {
+        void this.getOrCreateMixedBlock(blockIndex + 1);
+      }
       return;
     }
-    await this.ensureAudioForTimeRange(timeUs, windowEndUs, { mode, loadResource: true });
+    await this.getOrCreateMixedBlock(blockIndex);
+    const blockEndUs = (blockIndex + 1) * this.PREVIEW_BLOCK_DURATION_US;
+    const remainingToBoundaryUs = blockEndUs - Math.max(0, timeUs);
+    if (remainingToBoundaryUs > 0 && remainingToBoundaryUs <= this.PREVIEW_BUFFER_GUARD_US) {
+      await this.getOrCreateMixedBlock(blockIndex + 1);
+    }
+  }
+  isPreviewMixBlockCached(timeUs) {
+    const blockIndex = Math.floor(Math.max(0, timeUs) / this.PREVIEW_BLOCK_DURATION_US);
+    return this.previewBlockCache.get(blockIndex) !== null;
+  }
+  shouldEnterBufferingForUpcomingPreviewAudio(timeUs) {
+    const model = this.model;
+    if (!model) return false;
+    const clampedUs = Math.max(0, timeUs);
+    const blockIndex = Math.floor(clampedUs / this.PREVIEW_BLOCK_DURATION_US);
+    const nextBlockStartUs = (blockIndex + 1) * this.PREVIEW_BLOCK_DURATION_US;
+    if (nextBlockStartUs >= model.durationUs) return false;
+    const remainingToBoundaryUs = nextBlockStartUs - clampedUs;
+    if (remainingToBoundaryUs > this.PREVIEW_BUFFER_GUARD_US) return false;
+    return !this.isPreviewMixBlockCached(nextBlockStartUs);
   }
   /**
    * Fast readiness probe for preview playback.
@@ -114,12 +180,15 @@ class GlobalAudioSession {
     }
     await this.ensureAudioForTime(timeUs, { mode: "blocking" });
     this.isPlaying = true;
-    this.resetPlaybackStates();
-    await this.scheduleAudio(timeUs, audioContext);
+    this.startPreviewBlockScheduling(timeUs, audioContext);
+    await this.scheduleNextPreviewBlock(audioContext, this.previewScheduleToken);
+    void this.scheduleAudio(timeUs, audioContext);
   }
   stopPlayback() {
     this.isPlaying = false;
-    this.stopAllAudioSources();
+    this.stopAllPreviewSources();
+    this.cancelPreviewBlockScheduling();
+    this.previewMixToken += 1;
   }
   updateTime(_timeUs) {
   }
@@ -131,89 +200,219 @@ class GlobalAudioSession {
     if (!this.isPlaying || !this.model || !this.audioContext) {
       return;
     }
-    const lookaheadTime = audioContext.currentTime + this.LOOKAHEAD_TIME;
-    if (this.nextScheduleTime === 0) {
-      this.nextScheduleTime = audioContext.currentTime + 0.01;
-      this.nextContentTimeUs = currentTimelineUs;
-    }
-    while (this.nextScheduleTime < lookaheadTime) {
-      if (this.nextScheduleTime < audioContext.currentTime) {
-        const timeDrift = audioContext.currentTime - this.nextScheduleTime;
-        if (timeDrift > 0.02) {
-          this.nextScheduleTime = audioContext.currentTime + 0.02;
-          const skippedUs = Math.round(timeDrift * 1e6);
-          this.nextContentTimeUs += skippedUs;
-        } else {
-          this.nextScheduleTime = audioContext.currentTime + 0.01;
-        }
-      }
-      const chunkDurationUs = Math.round(this.CHUNK_DURATION * 1e6);
-      const startUs = this.nextContentTimeUs;
-      const endUs = startUs + chunkDurationUs;
-      if (endUs > this.model.durationUs) {
-        break;
-      }
-      try {
-        await this.ensureAudioForTimeRange(startUs, endUs, {
-          mode: "blocking",
-          loadResource: true
-        });
-        const mixedBuffer = await this.mixer.mix(startUs, endUs);
-        if (this.nextScheduleTime < audioContext.currentTime) {
-          const timeDrift = audioContext.currentTime - this.nextScheduleTime;
-          if (timeDrift > 0.02) {
-            console.warn(
-              `[Audio] Skip chunk due to time drift: ${(timeDrift * 1e3).toFixed(1)}ms`
-            );
-            this.nextScheduleTime = audioContext.currentTime + 0.02;
-            this.nextContentTimeUs += chunkDurationUs;
-            continue;
-          }
-          this.nextScheduleTime = audioContext.currentTime + 0.01;
+    this.previewLastTimelineUs = currentTimelineUs;
+    if (this.previewScheduleTask) return;
+    if (this.previewNextScheduleTime === 0) {
+      this.startPreviewBlockScheduling(currentTimelineUs, audioContext);
+    }
+    const token = this.previewScheduleToken;
+    this.previewScheduleTask = this.runPreviewBlockSchedulingLoop(audioContext, token).finally(
+      () => {
+        if (this.previewScheduleToken === token) {
+          this.previewScheduleTask = null;
         }
-        const source = audioContext.createBufferSource();
-        source.buffer = mixedBuffer;
-        source.playbackRate.value = this.playbackRate;
-        const gainNode = audioContext.createGain();
-        gainNode.gain.value = this.volume;
-        source.connect(gainNode);
-        gainNode.connect(audioContext.destination);
-        source.start(this.nextScheduleTime);
-        this.scheduledSources.add(source);
-        source.onended = () => {
-          source.disconnect();
-          gainNode.disconnect();
-          this.scheduledSources.delete(source);
-        };
-        const actualDuration = mixedBuffer.duration;
-        this.nextScheduleTime += actualDuration;
-        this.nextContentTimeUs += chunkDurationUs;
-      } catch (error) {
-        console.warn("[GlobalAudioSession] Mix error, skipping chunk:", error);
-        this.nextScheduleTime += this.CHUNK_DURATION;
-        this.nextContentTimeUs += chunkDurationUs;
       }
-    }
+    );
   }
   /**
    * Reset playback states (called on seek)
    */
   resetPlaybackStates() {
-    this.stopAllAudioSources();
-    this.nextScheduleTime = 0;
-    this.nextContentTimeUs = 0;
+    this.stopAllPreviewSources();
+    this.cancelPreviewBlockScheduling();
+    this.previewMixToken += 1;
   }
   setVolume(volume) {
     this.volume = volume;
+    const audioContext = this.audioContext;
+    if (!audioContext) return;
+    const t = audioContext.currentTime;
+    for (const { gain } of this.previewScheduledSources) {
+      try {
+        gain.gain.cancelScheduledValues(t);
+        gain.gain.setValueAtTime(gain.gain.value, t);
+        gain.gain.linearRampToValueAtTime(volume, t + 0.01);
+      } catch {
+      }
+    }
   }
   setPlaybackRate(rate) {
     this.playbackRate = rate;
     this.resetPlaybackStates();
   }
+  startPreviewBlockScheduling(startTimelineUs, audioContext) {
+    this.cancelPreviewBlockScheduling();
+    this.stopAllPreviewSources();
+    const clampedUs = Math.max(0, startTimelineUs);
+    const blockIndex = Math.floor(clampedUs / this.PREVIEW_BLOCK_DURATION_US);
+    const blockStartUs = blockIndex * this.PREVIEW_BLOCK_DURATION_US;
+    this.previewFirstBlockOffsetUs = clampedUs - blockStartUs;
+    this.previewNextBlockIndex = blockIndex;
+    this.previewNextScheduleTime = audioContext.currentTime + 0.02;
+    this.previewLastTimelineUs = startTimelineUs;
+  }
+  cancelPreviewBlockScheduling() {
+    this.previewScheduleToken += 1;
+    this.previewScheduleTask = null;
+    this.previewNextBlockIndex = 0;
+    this.previewNextScheduleTime = 0;
+    this.previewFirstBlockOffsetUs = 0;
+    this.previewLastTimelineUs = 0;
+  }
+  realignPreviewSchedulingToTimeline(audioContext) {
+    const model = this.model;
+    if (!model) return;
+    const clampedUs = Math.max(0, this.previewLastTimelineUs);
+    const blockIndex = Math.floor(clampedUs / this.PREVIEW_BLOCK_DURATION_US);
+    const blockStartUs = blockIndex * this.PREVIEW_BLOCK_DURATION_US;
+    if (blockStartUs >= model.durationUs) return;
+    this.stopAllPreviewSources();
+    this.previewFirstBlockOffsetUs = clampedUs - blockStartUs;
+    this.previewNextBlockIndex = blockIndex;
+    this.previewNextScheduleTime = audioContext.currentTime + 0.02;
+  }
+  async runPreviewBlockSchedulingLoop(audioContext, token) {
+    while (this.isPlaying && this.previewScheduleToken === token) {
+      const model = this.model;
+      if (!model) return;
+      const nextBlockStartUs = this.previewNextBlockIndex * this.PREVIEW_BLOCK_DURATION_US;
+      if (nextBlockStartUs >= model.durationUs) {
+        this.previewNextScheduleTime = audioContext.currentTime + this.PREVIEW_SCHEDULE_AHEAD_SEC;
+        return;
+      }
+      const scheduleAheadTime = audioContext.currentTime + this.PREVIEW_SCHEDULE_AHEAD_SEC;
+      if (this.previewNextScheduleTime >= scheduleAheadTime) return;
+      const prevBlockIndex = this.previewNextBlockIndex;
+      const prevScheduleTime = this.previewNextScheduleTime;
+      await this.scheduleNextPreviewBlock(audioContext, token);
+      if (this.previewScheduleToken === token && this.previewNextBlockIndex === prevBlockIndex && this.previewNextScheduleTime === prevScheduleTime) {
+        const now = audioContext.currentTime;
+        if (now - this.previewLastStallWarnAt >= 1) {
+          this.previewLastStallWarnAt = now;
+          console.warn(
+            "[GlobalAudioSession][preview] scheduling stalled; stop loop to avoid spin",
+            {
+              prevBlockIndex,
+              prevScheduleTime,
+              now
+            }
+          );
+        }
+        return;
+      }
+    }
+  }
+  async getOrCreateMixedBlock(blockIndex) {
+    const model = this.model;
+    if (!model) return null;
+    const token = this.previewMixToken;
+    return await this.previewBlockCache.getOrCreate(blockIndex, async () => {
+      return await this.enqueuePreviewMix(async () => {
+        const startUs = blockIndex * this.PREVIEW_BLOCK_DURATION_US;
+        const endUs = Math.min(startUs + this.PREVIEW_BLOCK_DURATION_US, model.durationUs);
+        await this.ensureAudioForTimeRange(startUs, endUs, {
+          mode: "blocking",
+          loadResource: true
+        });
+        const mixed = await this.mixer.mix(startUs, endUs);
+        this.deps.cacheManager.clearAudioCache();
+        return mixed;
+      }, token);
+    });
+  }
+  async scheduleNextPreviewBlock(audioContext, token) {
+    const model = this.model;
+    if (!this.isPlaying || !model) return;
+    if (this.previewScheduleToken !== token) return;
+    if (this.previewNextScheduleTime < audioContext.currentTime + 0.01) {
+      this.realignPreviewSchedulingToTimeline(audioContext);
+    }
+    const blockIndex = this.previewNextBlockIndex;
+    const blockStartUs = blockIndex * this.PREVIEW_BLOCK_DURATION_US;
+    if (blockStartUs >= model.durationUs) {
+      this.previewFirstBlockOffsetUs = 0;
+      this.previewNextBlockIndex = blockIndex + 1;
+      this.previewNextScheduleTime = audioContext.currentTime + this.PREVIEW_SCHEDULE_AHEAD_SEC;
+      return;
+    }
+    const buffer = await this.getOrCreateMixedBlock(blockIndex);
+    if (!buffer) {
+      this.previewFirstBlockOffsetUs = 0;
+      this.previewNextBlockIndex = blockIndex + 1;
+      this.previewNextScheduleTime = audioContext.currentTime + 0.02;
+      return;
+    }
+    if (this.previewScheduleToken !== token) return;
+    const rate = this.playbackRate || 1;
+    const offsetUs = this.previewFirstBlockOffsetUs;
+    let startTime = this.previewNextScheduleTime;
+    let offsetSec = offsetUs > 0 ? offsetUs / 1e6 : 0;
+    const now = audioContext.currentTime;
+    if (startTime < now + 0.01) {
+      const targetStartTime = now + 0.02;
+      const skippedSec = Math.max(0, (targetStartTime - startTime) * rate);
+      startTime = targetStartTime;
+      offsetSec += skippedSec;
+    }
+    if (offsetSec >= buffer.duration) {
+      this.previewFirstBlockOffsetUs = 0;
+      this.previewNextBlockIndex = blockIndex + 1;
+      this.previewNextScheduleTime = startTime;
+      return;
+    }
+    const remainingSec = Math.max(0, buffer.duration - offsetSec);
+    if (remainingSec <= 0) return;
+    const source = audioContext.createBufferSource();
+    source.buffer = buffer;
+    source.playbackRate.value = rate;
+    const gainNode = audioContext.createGain();
+    const volume = this.volume;
+    const fadeSec = Math.min(this.PREVIEW_BLOCK_FADE_SEC, remainingSec / 2);
+    gainNode.gain.setValueAtTime(0, startTime);
+    gainNode.gain.linearRampToValueAtTime(volume, startTime + fadeSec);
+    gainNode.gain.setValueAtTime(volume, startTime + Math.max(fadeSec, remainingSec - fadeSec));
+    gainNode.gain.linearRampToValueAtTime(0, startTime + remainingSec);
+    source.connect(gainNode);
+    gainNode.connect(audioContext.destination);
+    source.start(startTime, offsetSec);
+    const entry = { source, gain: gainNode };
+    this.previewScheduledSources.add(entry);
+    source.onended = () => {
+      try {
+        source.disconnect();
+        gainNode.disconnect();
+      } catch {
+      }
+      this.previewScheduledSources.delete(entry);
+    };
+    this.previewFirstBlockOffsetUs = 0;
+    this.previewNextBlockIndex = blockIndex + 1;
+    this.previewNextScheduleTime = startTime + remainingSec / rate;
+  }
+  stopAllPreviewSources() {
+    for (const { source, gain } of this.previewScheduledSources) {
+      try {
+        source.disconnect();
+      } catch {
+      }
+      try {
+        source.stop(0);
+      } catch {
+      }
+      try {
+        gain.disconnect();
+      } catch {
+      }
+    }
+    this.previewScheduledSources.clear();
+  }
   reset() {
-    this.stopAllAudioSources();
+    this.stopAllPreviewSources();
     this.deps.cacheManager.clearAudioCache();
     this.activeClips.clear();
+    this.previewBlockCache.clear();
+    this.cancelPreviewBlockScheduling();
+    this.previewMixToken += 1;
   }
   /**
    * Mix and encode audio for a specific segment (used by ExportScheduler)
@@ -269,16 +468,7 @@ class GlobalAudioSession {
     this.exportEncoder = null;
     this.exportEncoderStream = null;
   }
-  stopAllAudioSources() {
-    for (const source of this.scheduledSources) {
-      try {
-        source.disconnect();
-        source.stop(0);
-      } catch {
-      }
-    }
-    this.scheduledSources.clear();
-  }
+  // Preview source scheduling is managed by stopAllPreviewSources()/previewScheduledSources.
   /**
    * Core method to ensure audio for all clips in a time range
    * Unified implementation used by ensureAudioForTime, scheduleAudio, and export
@@ -466,26 +656,25 @@ class GlobalAudioSession {
       planes.push(buffer.getChannelData(channel));
     }
     return new AudioData({
-      format: "f32",
-      // interleaved format
+      format: "f32-planar",
       sampleRate,
       numberOfFrames,
       numberOfChannels,
       timestamp: timestampUs,
-      data: this.interleavePlanarData(planes)
+      data: this.packPlanarF32Data(planes)
     });
   }
-  interleavePlanarData(planes) {
+  packPlanarF32Data(planes) {
     const numberOfChannels = planes.length;
     const numberOfFrames = planes[0]?.length ?? 0;
     const totalSamples = numberOfChannels * numberOfFrames;
-    const interleaved = new Float32Array(totalSamples);
-    for (let frame = 0; frame < numberOfFrames; frame++) {
-      for (let channel = 0; channel < numberOfChannels; channel++) {
-        interleaved[frame * numberOfChannels + channel] = planes[channel][frame];
-      }
+    const packed = new Float32Array(totalSamples);
+    for (let channel = 0; channel < numberOfChannels; channel++) {
+      const plane = planes[channel];
+      if (!plane) continue;
+      packed.set(plane, channel * numberOfFrames);
     }
-    return interleaved.buffer;
+    return packed.buffer;
   }
 }
 export {