@ephia/dova-sdk 1.0.0

package/src/core/client/audio-capture.ts

@@ -0,0 +1,263 @@
+/**
+ * AudioCaptureManager — micro, MediaStream, niveaux audio, buffers de capture.
+ *
+ * Rôle : getUserMedia, warmup, VoiceLevelMeter, startup/reconnect capture.
+ * Possède : streams actif/warmup, meter, silence tracking.
+ * Ne fait pas : publish transport, routing events.
+ */
+
+import { Room } from "livekit-client";
+import { VoiceLevelMeter } from "../audio/voice-level-meter";
+import { EphiaSdkError } from "../../shared/errors/EphiaSdkError";
+import {
+  initialAudioState,
+  type EphiaAudioState,
+} from "../../shared/state/audio-state";
+
+export type AudioCaptureDeps = {
+  onAudioState: (state: EphiaAudioState) => void;
+  getLocalAudioPublished: () => boolean;
+};
+
+export class AudioCaptureManager {
+  readonly voiceLevelMeter = new VoiceLevelMeter();
+  private _activeStream: MediaStream | null = null;
+  private _warmupStream: MediaStream | null = null;
+  private _warmupPromise: Promise<void> | null = null;
+  private _levelUnsubscribe?: () => void;
+  private _silenceStartMs: number | null = null;
+  private _lastAudioState: EphiaAudioState = { ...initialAudioState };
+  private readonly deps: AudioCaptureDeps;
+
+  constructor(deps: AudioCaptureDeps) {
+    this.deps = deps;
+  }
+
+  get lastAudioState(): EphiaAudioState {
+    return this._lastAudioState;
+  }
+
+  get silenceStartMs(): number | null {
+    return this._silenceStartMs;
+  }
+
+  get hasActiveStream(): boolean {
+    return !!this._activeStream;
+  }
+
+  get hasWarmupStream(): boolean {
+    return !!this._warmupStream;
+  }
+
+  setActiveStream(stream: MediaStream | null): void {
+    this._activeStream = stream;
+  }
+
+  emitAudioState(state: EphiaAudioState): void {
+    this._lastAudioState = { ...state };
+    this.deps.onAudioState(this._lastAudioState);
+  }
+
+  patchAudioState(patch: Partial<EphiaAudioState>): void {
+    this.emitAudioState({ ...this._lastAudioState, ...patch });
+  }
+
+  stopAudioLevelImmediately(): void {
+    this._levelUnsubscribe?.();
+    this._levelUnsubscribe = undefined;
+    this.voiceLevelMeter.detach();
+    this.patchAudioState({
+      level: 0,
+      rms: 0,
+      peak: 0,
+      isSilent: true,
+      silenceDurationMs: 0,
+      localAudioPublished: false,
+      muted: false,
+    });
+  }
+
+  async warmupMic(): Promise<void> {
+    if (/^((?!chrome|android).)*safari/i.test(navigator.userAgent)) return;
+    if (
+      this._warmupStream &&
+      this._warmupStream.getAudioTracks().some((t) => t.readyState === "live")
+    ) {
+      console.info("[EphiaAudioClient] warmupMic: already warmed up");
+      return;
+    }
+    if (this._warmupPromise) {
+      return this._warmupPromise;
+    }
+
+    this._warmupPromise = this.acquireMicStream()
+      .then(async (stream) => {
+        this._warmupStream = stream;
+        await this.voiceLevelMeter.attach(stream);
+        console.info("[EphiaAudioClient] warmupMic:done", {
+          trackCount: stream.getAudioTracks().length,
+        });
+      })
+      .catch((err) => {
+        console.warn("[EphiaAudioClient] warmupMic:failed", err);
+      })
+      .finally(() => {
+        this._warmupPromise = null;
+      });
+
+    return this._warmupPromise;
+  }
+
+  injectWarmupStream(stream: MediaStream): void {
+    this.cleanupWarmupStream();
+    this._warmupStream = stream;
+    this.voiceLevelMeter.attach(stream).catch(() => {});
+  }
+
+  enableStartupCapture(maxSamples: number): void {
+    this.voiceLevelMeter.enableStartupCapture(maxSamples);
+  }
+
+  drainStartupCapture(): ArrayBuffer | null {
+    return this.voiceLevelMeter.drainStartupCapture();
+  }
+
+  async acquireMicStream(deviceId?: string): Promise<MediaStream> {
+    if (
+      this._warmupStream &&
+      this._warmupStream.getAudioTracks().some((t) => t.readyState === "live")
+    ) {
+      const warmupTracks = this._warmupStream.getAudioTracks();
+      const warmupDeviceId = warmupTracks[0]?.getSettings().deviceId;
+      // N'utilise le warmup que s'il correspond au deviceId demandé.
+      if (!deviceId || warmupDeviceId === deviceId) {
+        console.info("[EphiaAudioClient] getUserMedia: using warmed-up stream", {
+          warmupDeviceId,
+        });
+        const stream = this._warmupStream;
+        this._warmupStream = null;
+        return stream;
+      }
+      console.info("[EphiaAudioClient] getUserMedia: warmup device mismatch, releasing warmup", {
+        warmupDeviceId,
+        requestedDeviceId: deviceId,
+      });
+      this.cleanupWarmupStream();
+    }
+    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia) {
+      const isSecure = typeof window !== "undefined" && window.isSecureContext === false;
+      throw new EphiaSdkError(
+        "audio.no_input_device",
+        isSecure
+          ? "getUserMedia not available in non-secure context (requires HTTPS or localhost)"
+          : "getUserMedia not available in this browser/context"
+      );
+    }
+    console.info("[EphiaAudioClient] getUserMedia:start", deviceId ? { deviceId } : undefined);
+    const audioConstraints: MediaTrackConstraints = {
+      echoCancellation: { ideal: false },
+      noiseSuppression: { ideal: false },
+      autoGainControl: { ideal: false },
+      channelCount: { ideal: 1 },
+      sampleRate: { ideal: 16000 },
+    };
+    if (deviceId) {
+      audioConstraints.deviceId = { exact: deviceId };
+    }
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: audioConstraints });
+    const tracks = stream.getAudioTracks();
+    console.info("[EphiaAudioClient] getUserMedia:done", {
+      trackCount: tracks.length,
+      tracks: tracks.map((t) => ({
+        id: t.id,
+        label: t.label,
+        readyState: t.readyState,
+      })),
+    });
+    return stream;
+  }
+
+  async setupAudioLevel(stream: MediaStream): Promise<void> {
+    const track = stream.getAudioTracks()[0];
+    if (!track) return;
+
+    const trackSettings = track.getSettings();
+    const deviceId = trackSettings.deviceId ?? "";
+    const deviceLabel = track.label ?? "";
+
+    this.emitAudioState({
+      permission: "granted",
+      hasInputDevice: true,
+      inputDeviceId: deviceId,
+      inputDeviceLabel: deviceLabel,
+      level: 0,
+      rms: 0,
+      peak: 0,
+      isSilent: false,
+      silenceDurationMs: 0,
+      muted: track.muted,
+      localAudioPublished: false,
+      micReady: true,
+      speaking: false,
+    });
+
+    this._levelUnsubscribe?.();
+    if (!this.voiceLevelMeter.isAttached()) {
+      try {
+        await this.voiceLevelMeter.attach(stream);
+      } catch (err) {
+        console.warn(
+          "[EphiaAudioClient] _setupAudioLevel: voiceLevelMeter attach failed (non-fatal)",
+          err
+        );
+      }
+    }
+    this._levelUnsubscribe = this.voiceLevelMeter.onLevel((snapshot) => {
+      const isSilent = snapshot.level < 0.005;
+      if (isSilent && this._silenceStartMs === null) {
+        this._silenceStartMs = Date.now();
+      } else if (!isSilent) {
+        this._silenceStartMs = null;
+      }
+      const silenceDurationMs =
+        isSilent && this._silenceStartMs !== null ? Date.now() - this._silenceStartMs : 0;
+      this.patchAudioState({
+        permission: "granted",
+        hasInputDevice: true,
+        inputDeviceId: deviceId,
+        inputDeviceLabel: deviceLabel,
+        level: snapshot.level,
+        rms: snapshot.rms,
+        peak: snapshot.rms,
+        isSilent,
+        silenceDurationMs,
+        muted: track.muted,
+        localAudioPublished: this.deps.getLocalAudioPublished(),
+        micReady: true,
+      });
+    });
+  }
+
+  cleanupActiveStream(): void {
+    this._levelUnsubscribe?.();
+    this._levelUnsubscribe = undefined;
+    this._silenceStartMs = null;
+    this.voiceLevelMeter.detach();
+    if (this._activeStream) {
+      this._activeStream.getTracks().forEach((t) => t.stop());
+      this._activeStream = null;
+    }
+  }
+
+  cleanupWarmupStream(): void {
+    if (this._warmupStream) {
+      this._warmupStream.getTracks().forEach((t) => t.stop());
+      this._warmupStream = null;
+    }
+    this._warmupPromise = null;
+  }
+
+  async getAvailableMicrophones(): Promise<MediaDeviceInfo[]> {
+    return Room.getLocalDevices("audioinput");
+  }
+}

package/src/core/client/client-options.ts

@@ -0,0 +1,39 @@
+import type { EphiaAudioEvent } from "ephia-protocol";
+import type { Transport } from "../transport/Transport";
+import type { EphiaSessionOptions } from "../../shared/types/session";
+import type { EphiaClientState } from "./client-state";
+import type { EphiaAudioState } from "../../shared/state/audio-state";
+
+export type EphiaStartOptions = {
+  startupBufferMs?: number;
+  /**
+   * Target SDK initiale à transmettre au backend dès la création de session.
+   * Évite que l'agent démarre sur sa target par défaut avant le premier event data-channel.
+   */
+  initialTargetId?: string;
+  /** Contexte local envoyé au backend lors d'un session.resume. */
+  context?: string;
+};
+
+export type EphiaStartResult = {
+  /** Identifiant de la session démarrée, ou null si aucune session n'a été créée. */
+  sessionId: string | null;
+};
+
+export interface EphiaAudioClientOptions {
+  apiKey?: string;
+  bearerToken?: string;
+  clientType?: string;
+  apiUrl?: string;
+  transport?: Transport;
+  sessionOptions?: EphiaSessionOptions;
+  noiseFilter?: boolean;
+  /** Active le VAD gate RMS (mute track en silence). Défaut: true */
+  vadGate?: boolean;
+  /** deviceId audioinput à utiliser pour acquireMicStream (ex. BlackHole). */
+  preferredAudioInputDeviceId?: string;
+  onEvent?: (event: EphiaAudioEvent) => void;
+  onStateChange?: (state: EphiaClientState) => void;
+  onError?: (error: { code: string; message: string }) => void;
+  onAudioState?: (state: EphiaAudioState) => void;
+}

package/src/core/client/client-state.ts

@@ -0,0 +1,18 @@
+/** Alias de EphiaSessionStatus — tous les statuts sont des états valides de la machine. */
+export type EphiaClientStatus = import("../session/session-machine").EphiaSessionStatus;
+
+export interface EphiaClientState {
+  status: EphiaClientStatus;
+  sessionId: string | null;
+  roomName: string | null;
+  error: { code: string; message: string } | null;
+  isMicEnabled: boolean;
+}
+
+export const initialClientState: EphiaClientState = {
+  status: "idle",
+  sessionId: null,
+  roomName: null,
+  error: null,
+  isMicEnabled: false,
+};

package/src/core/client/constants.ts

@@ -0,0 +1,23 @@
+import { PROTOCOL_VERSION as WIRE_PROTOCOL_VERSION } from "ephia-protocol";
+
+export const SDK_VERSION = "2.0.0";
+export const PROTOCOL_VERSION = WIRE_PROTOCOL_VERSION;
+export const AUDIO_SESSIONS_PATH = "/api/v1/audio/sessions";
+
+/** Durée max de validité d'une session préchargée avant refetch (5 min). */
+export const TOKEN_MAX_AGE_MS = 5 * 60 * 1000;
+/** TTL token LiveKit côté backend (6h). Refresh à 80%. */
+export const ACTIVE_TOKEN_TTL_MS = 6 * 60 * 60 * 1000;
+/** Timeout attente session.closed — backend draine en ≤5s, marge incluse. */
+export const SESSION_END_CLOSED_TIMEOUT_MS = 10_000;
+/** Grace period avant error sur déconnexion transport inattendue. */
+export const DISCONNECT_GRACE_MS = 6_000;
+
+export function createCommandId(prefix: string): string {
+  const cryptoLike = globalThis.crypto as Crypto | undefined;
+  const id =
+    typeof cryptoLike?.randomUUID === "function"
+      ? cryptoLike.randomUUID()
+      : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  return `${prefix}:${id}`;
+}