@ephia/dova-sdk 1.0.0

package/src/core/audio/voice-level-meter.ts

@@ -0,0 +1,270 @@
+/**
+ * Niveau vocal minimal pour la barre Standard (RMS brut + enveloppe attack/release).
+ */
+
+export type VoiceLevelSnapshot = {
+  level: number;
+  rms: number;
+};
+
+import { getAudioWorkletModuleUrl } from "./audio-worklet-source";
+
+const VOLUME_THROTTLE_MS = 33;
+const SILENCE_THRESHOLD_RMS = 0.005;
+const RAW_RMS_SCALE = 7;
+const TARGET_SAMPLE_RATE = 16_000;
+
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}
+
+function isAudioContextClosed(audioContext: AudioContext): boolean {
+  return (audioContext.state as AudioContextState) === "closed";
+}
+
+function resampleLinear(
+  input: Float32Array,
+  sourceSampleRate: number,
+  targetSampleRate: number
+): Float32Array {
+  if (sourceSampleRate === targetSampleRate || input.length <= 1) {
+    return input;
+  }
+
+  const outputLength = Math.max(
+    1,
+    Math.round((input.length * targetSampleRate) / sourceSampleRate)
+  );
+  const output = new Float32Array(outputLength);
+  const scale = sourceSampleRate / targetSampleRate;
+
+  for (let i = 0; i < outputLength; i += 1) {
+    const sourceIndex = i * scale;
+    const leftIndex = Math.floor(sourceIndex);
+    const rightIndex = Math.min(leftIndex + 1, input.length - 1);
+    const fraction = sourceIndex - leftIndex;
+    const left = input[leftIndex] ?? 0;
+    const right = input[rightIndex] ?? left;
+    output[i] = left + (right - left) * fraction;
+  }
+
+  return output;
+}
+
+export class VoiceLevelMeter {
+  private audioContext: AudioContext | null = null;
+  private processor: AudioWorkletNode | null = null;
+  private silentGain: GainNode | null = null;
+  private source: MediaStreamAudioSourceNode | null = null;
+  private callbacks = new Set<(snapshot: VoiceLevelSnapshot) => void>();
+  private pendingRms = 0;
+  private lastVolumeUpdateMs = 0;
+  private volumeTimer: ReturnType<typeof setTimeout> | null = null;
+  private _pipelineReady: Promise<void> | null = null;
+  // Startup capture state (shared pipeline avec StartupAudioBuffer)
+  private _captureBuffers: Float32Array[] = [];
+  private _captureTotalSamples = 0;
+  private _captureMaxSamples = 0;
+  private _captureEnabled = false;
+  private _actualSampleRate = TARGET_SAMPLE_RATE;
+
+  attach(stream: MediaStream): Promise<void> {
+    this.detach();
+
+    const AudioContextClass =
+      window.AudioContext ||
+      (window as Window & { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+    if (!AudioContextClass) {
+      console.warn("[VoiceLevelMeter] AudioContext not supported");
+      return Promise.resolve();
+    }
+
+    this._pipelineReady = this._startWorkletPipeline(stream, AudioContextClass);
+    return this._pipelineReady;
+  }
+
+  isAttached(): boolean {
+    return this.processor !== null;
+  }
+
+  private async _startWorkletPipeline(
+    stream: MediaStream,
+    AudioContextClass: typeof AudioContext,
+  ): Promise<void> {
+    try {
+      const audioContext = new AudioContextClass({
+        sampleRate: TARGET_SAMPLE_RATE,
+        latencyHint: "interactive",
+      });
+      this.audioContext = audioContext;
+      this._actualSampleRate = audioContext.sampleRate || TARGET_SAMPLE_RATE;
+
+      if (audioContext.state === "suspended") {
+        await audioContext.resume();
+      }
+      // Guard: detach() a été appelé entre-temps (ex: dispose pendant navigation)
+      if (this.audioContext !== audioContext || isAudioContextClosed(audioContext)) {
+        return;
+      }
+
+      await audioContext.audioWorklet.addModule(getAudioWorkletModuleUrl());
+      // Guard: même vérification après le module load async
+      if (this.audioContext !== audioContext || isAudioContextClosed(audioContext)) {
+        return;
+      }
+
+      const source = audioContext.createMediaStreamSource(stream);
+      const processor = new AudioWorkletNode(audioContext, "ephia-audio-capture");
+      const silentGain = audioContext.createGain();
+      silentGain.gain.value = 0;
+
+      processor.connect(silentGain);
+      silentGain.connect(audioContext.destination);
+
+      processor.port.onmessage = (event: MessageEvent<Float32Array>) => {
+        const inputData = event.data;
+        if (!inputData?.length) return;
+
+        // Startup capture — accumulation FIFO partagée avec le pipeline level
+        if (this._captureEnabled) {
+          const chunk = new Float32Array(inputData);
+          this._captureBuffers.push(chunk);
+          this._captureTotalSamples += chunk.length;
+          while (this._captureTotalSamples > this._captureMaxSamples && this._captureBuffers.length > 0) {
+            const removed = this._captureBuffers.shift()!;
+            this._captureTotalSamples -= removed.length;
+          }
+        }
+
+        let sum = 0;
+        for (let i = 0; i < inputData.length; i++) {
+          const x = inputData[i];
+          sum += x * x;
+        }
+        const rawRms = Math.sqrt(sum / inputData.length);
+        this.pendingRms = clamp01(rawRms * RAW_RMS_SCALE);
+
+        const now = Date.now();
+        if (
+          this.volumeTimer === null &&
+          now - this.lastVolumeUpdateMs > VOLUME_THROTTLE_MS
+        ) {
+          this.volumeTimer = setTimeout(() => {
+            this.volumeTimer = null;
+            this.lastVolumeUpdateMs = Date.now();
+            this._emitSnapshot();
+          }, VOLUME_THROTTLE_MS);
+        }
+      };
+
+      this.source = source;
+      this.processor = processor;
+      this.silentGain = silentGain;
+      source.connect(processor);
+    } catch (err) {
+      console.warn("[VoiceLevelMeter] worklet pipeline failed", err);
+      this.detach();
+    }
+  }
+
+  private _emitSnapshot(): void {
+    const rms = this.pendingRms;
+    const snapshot: VoiceLevelSnapshot = {
+      level: clamp01(rms),
+      rms,
+    };
+    const isSilent = rms < SILENCE_THRESHOLD_RMS;
+    if (isSilent) {
+      snapshot.level = 0;
+      snapshot.rms = 0;
+    }
+    this.callbacks.forEach((cb) => cb(snapshot));
+  }
+
+  detach(): void {
+    if (this.volumeTimer !== null) {
+      clearTimeout(this.volumeTimer);
+      this.volumeTimer = null;
+    }
+    this.pendingRms = 0;
+    this.lastVolumeUpdateMs = 0;
+
+    if (this.source) {
+      try {
+        this.source.disconnect();
+      } catch {
+        /* ignore */
+      }
+      this.source = null;
+    }
+    if (this.processor) {
+      try {
+        this.processor.port.onmessage = null;
+        this.processor.disconnect();
+      } catch {
+        /* ignore */
+      }
+      this.processor = null;
+    }
+    if (this.silentGain) {
+      try {
+        this.silentGain.disconnect();
+      } catch {
+        /* ignore */
+      }
+      this.silentGain = null;
+    }
+    if (this.audioContext) {
+      this.audioContext.close().catch(() => {});
+      this.audioContext = null;
+    }
+  }
+
+  onLevel(callback: (snapshot: VoiceLevelSnapshot) => void): () => void {
+    this.callbacks.add(callback);
+    return () => {
+      this.callbacks.delete(callback);
+    };
+  }
+
+  /** Active la capture startup sur le pipeline existant. maxSamples = taille FIFO. */
+  enableStartupCapture(maxSamples: number): void {
+    this._captureBuffers = [];
+    this._captureTotalSamples = 0;
+    this._captureMaxSamples = Math.ceil(
+      (maxSamples * this._actualSampleRate) / TARGET_SAMPLE_RATE
+    );
+    this._captureEnabled = true;
+  }
+
+  /** Stoppe la capture et retourne le PCM16 accumulé (ou null si vide). Le level meter continue. */
+  drainStartupCapture(): ArrayBuffer | null {
+    this._captureEnabled = false;
+    const buffers = this._captureBuffers;
+    const totalSamples = this._captureTotalSamples;
+    this._captureBuffers = [];
+    this._captureTotalSamples = 0;
+
+    if (buffers.length === 0) return null;
+
+    const float32 = new Float32Array(totalSamples);
+    let offset = 0;
+    for (const buf of buffers) {
+      float32.set(buf, offset);
+      offset += buf.length;
+    }
+
+    const resampled = resampleLinear(
+      float32,
+      this._actualSampleRate,
+      TARGET_SAMPLE_RATE
+    );
+
+    const pcm16 = new Int16Array(resampled.length);
+    for (let i = 0; i < resampled.length; i++) {
+      const s = Math.max(-1, Math.min(1, resampled[i] ?? 0));
+      pcm16[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+    }
+    return pcm16.buffer;
+  }
+}

package/src/core/bindings/EphiaBinding.ts

@@ -0,0 +1,41 @@
+import type { EditorContext, SegmentStage } from "ephia-protocol";
+
+export type UpsertSegmentInput = {
+  id: string;
+  text: string;
+  stage: SegmentStage;
+  source?: string;
+};
+
+export type PreviewSegmentInput = {
+  id: string;
+  text: string;
+};
+
+/**
+ * Interface V2 unifiée pour tous les bindings éditeurs Ephia.
+ *
+ * Règles :
+ *  - même segmentId + upsertSegment = update en place (never append)
+ *  - segmentId connu mais range perdu = warning + no append
+ *  - removeSegments est idempotent
+ *  - cleanup visuel ne supprime jamais l'identité segment
+ */
+export interface EphiaBinding {
+  readonly kind: string;
+  /** Stable reference for this binding instance. Used for idempotent lifecycle management. */
+  readonly identity?: object | string;
+
+  attach(): void;
+  detach(): void;
+
+  getText(): string;
+  getEditorContext(targetId?: string): EditorContext;
+
+  previewSegment?(input: PreviewSegmentInput): void;
+
+  upsertSegment(input: UpsertSegmentInput): void;
+
+  removeSegment(id: string): void;
+  removeSegments(ids: string[]): void;
+}