interview-widget 3.3.1 → 3.3.3-beta.0

package/README.md

@@ -72,6 +72,7 @@ export default function App() {
             language: "en",
           },
           tts: { provider: "piper" },
+          avatar: { provider: "none" },
           timers: {
             thinkingDuration: 30,
             answeringDuration: 120,
@@ -201,10 +202,13 @@ Pass this object to `InterviewWidgetProvider` via the `config` prop. Tables list
 
 ### UI
 
-| Prop         | Type           | Default   | Description                            |
-| ------------ | -------------- | --------- | -------------------------------------- |
-| baseColor    | `string (hex)` | "#3B82F6" | Primary brand color used by the widget |
-| borderRadius | `string (CSS)` | "8px"     | Global corner radius for components    |
+| Prop                    | Type           | Default                                                         | Description                                                   |
+| ----------------------- | -------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
+| baseColor               | `string (hex)` | "#3B82F6"                                                       | Primary brand color used by the widget                        |
+| borderRadius            | `string (CSS)` | "8px"                                                           | Global corner radius for components                           |
+| retryProgressSavedText  | `string`       | `"Your progress is saved — tap Retry or exit the interview..."` | Text to show in next-question retry modal                     |
+| retryMaxAttempts        | `number`       | 3                                                               | Maximum number of attempts allowed for retrying next question |
+| retryNoAttemptsLeftText | `string`       | `"Retry limit reached. Please exit and resume later."`          | Error message shown when max attempts are reached             |
 
 ### Interview
 
@@ -216,6 +220,7 @@ Pass this object to `InterviewWidgetProvider` via the `config` prop. Tables list
 | timers               | `object`  | [see below](#timers)             | Per-phase and global timing configuration   |
 | stt                  | `object`  | [see below](#stt-speech-to-text) | Speech-to-Text provider settings            |
 | tts                  | `object`  | [see below](#tts-text-to-speech) | Text-to-Speech provider settings            |
+| avatar               | `object`  | [see below](#avatar)             | Optional avatar question-delivery provider  |
 | proctoring           | `object`  | [see below](#proctoring)         | Proctoring settings and cheating detection  |
 
 #### Timers
@@ -236,6 +241,12 @@ Pass this object to `InterviewWidgetProvider` via the `config` prop. Tables list
 | model    | `"whisper-large-v3-turbo" \| string` | "whisper-large-v3-turbo" | STT model identifier                   |
 | language | `string`                             | "en"                     | Language code passed to the STT engine |
 
+#### Avatar
+
+| Prop     | Type                      | Default  | Description                                                                                 |
+| -------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------- |
+| provider | `"none" \| "spatius"` | `"none"` | Keep the standard SSE/audio flow or render streamed questions through Spatius Direct Mode. |
+
 #### TTS (Text-To-Speech)
 
 | Prop     | Type      | Default | Description       |

package/dist/StreamingAudioPlayer-DmOtqI_a-BX7ptCkK.js

@@ -0,0 +1,430 @@
+import { A as C, l as a, e as g, a as c } from "./index-DXUDYyS8.js";
+var m = Object.defineProperty, f = (r, t, e) => t in r ? m(r, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : r[t] = e, s = (r, t, e) => f(r, typeof t != "symbol" ? t + "" : t, e);
+class p {
+  // Mark if AudioContext is being resumed, avoid concurrent resume requests
+  constructor(t) {
+    s(this, "audioContext", null), s(this, "sampleRate"), s(this, "channelCount"), s(this, "debug"), s(this, "sessionId"), s(this, "sessionStartTime", 0), s(this, "pausedTimeOffset", 0), s(this, "pausedAt", 0), s(this, "pausedAudioContextTime", 0), s(this, "scheduledTime", 0), s(this, "isPlaying", !1), s(this, "isPaused", !1), s(this, "autoStartEnabled", !0), s(this, "autoContinue", !1), s(this, "audioChunks", []), s(this, "scheduledChunks", 0), s(this, "activeSources", /* @__PURE__ */ new Set()), s(this, "lastScheduledChunkEndTime", 0), s(this, "lastGetCurrentTimeLog", 0), s(this, "scheduledChunkInfo", []), s(this, "gainNode", null), s(this, "volume", 1), s(this, "onEndedCallback"), s(this, "stateChangeHandler"), s(this, "isResuming", !1), this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`, this.sampleRate = (t == null ? void 0 : t.sampleRate) ?? C.audio.sampleRate, this.channelCount = (t == null ? void 0 : t.channelCount) ?? 1, this.debug = (t == null ? void 0 : t.debug) ?? !1;
+  }
+  /**
+   * Initialize audio context (create and ensure it's ready)
+   */
+  async initialize() {
+    if (!this.audioContext)
+      try {
+        this.audioContext = new AudioContext({
+          sampleRate: this.sampleRate
+        }), this.gainNode = this.audioContext.createGain(), this.gainNode.gain.value = this.volume, this.gainNode.connect(this.audioContext.destination), this.audioContext.state === "suspended" && await this.audioContext.resume(), this.stateChangeHandler = (t) => {
+          t.target.state === "suspended" && this.isPlaying && !this.isPaused && this.ensureAudioContextRunning().catch((i) => {
+            a.error("[StreamingAudioPlayer] Failed to auto-resume AudioContext after external suspend:", i);
+          });
+        }, this.audioContext.addEventListener("statechange", this.stateChangeHandler), this.log("AudioContext initialized", {
+          sessionId: this.sessionId,
+          sampleRate: this.audioContext.sampleRate,
+          state: this.audioContext.state
+        });
+      } catch (t) {
+        const e = g(t);
+        throw c("audio_session_init_failed", "warning", {
+          session_id: this.sessionId,
+          reason: e
+        }), a.error("Failed to initialize AudioContext:", e), t instanceof Error ? t : new Error(e);
+      }
+  }
+  /**
+   * Ensure AudioContext is running (auto-resume if suspended)
+   * Only auto-resume when playing and not paused, avoid interfering with normal pause/resume logic
+   * 
+   * Optimizations:
+   * - Fast path: if already in running state, return directly
+   * - Avoid concurrent resume: use isResuming flag to prevent duplicate resume requests
+   * - Handle closed state: if AudioContext is closed, cannot resume
+   * @internal
+   */
+  async ensureAudioContextRunning() {
+    if (!this.audioContext)
+      return;
+    const t = this.audioContext.state;
+    if (t !== "running") {
+      if (t === "closed") {
+        this.log("AudioContext is closed, cannot resume", {
+          sessionId: this.sessionId,
+          state: t
+        });
+        return;
+      }
+      if (t === "suspended" && this.isPlaying && !this.isPaused) {
+        if (this.isResuming) {
+          this.log("AudioContext resume already in progress, skipping duplicate request", {
+            sessionId: this.sessionId,
+            state: t
+          });
+          return;
+        }
+        this.isResuming = !0;
+        try {
+          this.log("AudioContext is suspended during playback, resuming...", {
+            sessionId: this.sessionId,
+            state: t,
+            isPlaying: this.isPlaying,
+            isPaused: this.isPaused
+          }), await this.audioContext.resume(), this.log("AudioContext resumed successfully", {
+            sessionId: this.sessionId,
+            state: this.audioContext.state
+          });
+        } catch (e) {
+          a.error("[StreamingAudioPlayer] Failed to resume AudioContext:", e), c("audio_context_resume_failed", "error", {
+            session_id: this.sessionId,
+            reason: e instanceof Error ? e.message : String(e)
+          });
+        } finally {
+          this.isResuming = !1;
+        }
+      }
+    }
+  }
+  /**
+   * Add audio chunk (16-bit PCM)
+   */
+  addChunk(t, e = !1) {
+    if (!this.audioContext) {
+      a.error("AudioContext not initialized");
+      return;
+    }
+    this.isPlaying && !this.isPaused && this.audioContext.state === "suspended" && this.ensureAudioContextRunning().catch((i) => {
+      a.error("[StreamingAudioPlayer] Failed to ensure AudioContext running in addChunk:", i);
+    }), this.audioChunks.push({ data: t, isLast: e }), this.log(`Added chunk ${this.audioChunks.length}`, {
+      size: t.length,
+      totalChunks: this.audioChunks.length,
+      isLast: e,
+      isPlaying: this.isPlaying,
+      scheduledChunks: this.scheduledChunks
+    }), this.autoContinue && this.isPaused && (this.log("[StreamingAudioPlayer] autoContinue=true, auto-resuming playback"), this.autoContinue = !1, this.resume().catch((i) => {
+      a.error("Failed to auto-resume playback:", i);
+    })), !this.isPlaying && this.autoStartEnabled && this.audioChunks.length > 0 ? (this.log("[StreamingAudioPlayer] Auto-starting playback from addChunk"), this.startPlayback().catch((i) => {
+      a.error("[StreamingAudioPlayer] Failed to start playback from addChunk:", i);
+    })) : this.isPlaying && !this.isPaused ? (this.log("[StreamingAudioPlayer] Already playing, scheduling next chunk"), this.scheduleNextChunk()) : this.log("[StreamingAudioPlayer] Not playing and no chunks, waiting for more chunks");
+  }
+  /**
+   * Start new session (stop current and start fresh)
+   */
+  async startNewSession(t, e = 0) {
+    if (this.stop(), this.sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`, this.audioChunks = [], this.scheduledChunks = 0, this.pausedTimeOffset = 0, this.pausedAt = 0, this.pausedAudioContextTime = 0, this.autoContinue = !1, this.log("Starting new session", {
+      chunks: t.length,
+      leadingSilenceMs: e
+    }), e > 0) {
+      const i = Math.floor(e / 1e3 * this.sampleRate) * this.channelCount, u = new Uint8Array(i * 2);
+      this.addChunk(u, !1);
+    }
+    for (const i of t)
+      this.addChunk(i.data, i.isLast);
+  }
+  /**
+   * Start playback
+   */
+  async startPlayback() {
+    if (!this.audioContext) {
+      this.log("[StreamingAudioPlayer] Cannot start playback: AudioContext not initialized");
+      return;
+    }
+    if (this.isPlaying) {
+      this.log("[StreamingAudioPlayer] Cannot start playback: Already playing");
+      return;
+    }
+    await this.ensureAudioContextRunning(), this.isPlaying = !0, this.sessionStartTime = this.audioContext.currentTime, this.scheduledTime = this.sessionStartTime, this.lastScheduledChunkEndTime = 0, this.scheduledChunkInfo = [], this.autoContinue = !1, this.log("[StreamingAudioPlayer] Starting playback", {
+      sessionStartTime: this.sessionStartTime,
+      bufferedChunks: this.audioChunks.length,
+      scheduledChunks: this.scheduledChunks,
+      activeSources: this.activeSources.size,
+      audioContextState: this.audioContext.state
+    }), this.scheduleAllChunks();
+  }
+  /**
+   * Schedule all pending chunks
+   */
+  scheduleAllChunks() {
+    for (; this.scheduledChunks < this.audioChunks.length; )
+      this.scheduleNextChunk();
+  }
+  /**
+   * Schedule next audio chunk
+   */
+  scheduleNextChunk() {
+    if (!this.audioContext) {
+      this.log("[StreamingAudioPlayer] Cannot schedule chunk: AudioContext not initialized");
+      return;
+    }
+    if (!this.isPlaying || this.isPaused) {
+      this.log("[StreamingAudioPlayer] Cannot schedule chunk: Not playing or paused");
+      return;
+    }
+    this.audioContext.state === "suspended" && this.ensureAudioContextRunning().catch((n) => {
+      a.error("[StreamingAudioPlayer] Failed to ensure AudioContext running in scheduleNextChunk:", n);
+    });
+    const t = this.scheduledChunks;
+    if (t >= this.audioChunks.length) {
+      this.log(`[StreamingAudioPlayer] No more chunks to schedule (chunkIndex: ${t}, totalChunks: ${this.audioChunks.length})`);
+      return;
+    }
+    const e = this.audioChunks[t];
+    if (e.data.length === 0 && !e.isLast) {
+      this.scheduledChunks++;
+      return;
+    }
+    const i = e.data, u = e.isLast, o = this.pcmToAudioBuffer(i);
+    if (!o) {
+      a.error("Failed to create AudioBuffer from PCM data"), c("audio_buffer_creation_failed", "error", {
+        session_id: this.sessionId
+      });
+      return;
+    }
+    try {
+      const n = this.audioContext.createBufferSource();
+      n.buffer = o, n.connect(this.gainNode);
+      const l = this.scheduledTime;
+      n.start(l);
+      const h = Math.max(l, this.audioContext.currentTime);
+      this.scheduledChunkInfo.push({
+        startTime: h,
+        duration: o.duration
+      }), this.activeSources.add(n), n.onended = () => {
+        if (this.activeSources.delete(n), this.activeSources.size === 0) {
+          const d = this.audioChunks[this.scheduledChunks - 1];
+          d && !d.isLast ? (this.log("All audio chunks ended but end=false, pausing and setting autoContinue"), c("audio_buffer_stall", "warning", {
+            scheduled_chunks: this.scheduledChunks,
+            audio_time: this.getCurrentTime()
+          }), this.autoContinue = !0, this.pause()) : u && (this.log("Last audio chunk ended, marking playback as ended"), this.markEnded());
+        }
+      }, this.scheduledTime += o.duration, this.lastScheduledChunkEndTime = this.scheduledTime - this.sessionStartTime - this.pausedTimeOffset, this.scheduledChunks++, this.log(`[StreamingAudioPlayer] Scheduled chunk ${t + 1}/${this.audioChunks.length}`, {
+        startTime: this.scheduledTime - o.duration,
+        duration: o.duration,
+        nextScheduleTime: this.scheduledTime,
+        isLast: u,
+        activeSources: this.activeSources.size
+      });
+    } catch (n) {
+      a.error("Failed to schedule audio chunk:", n), c("schedule_chunk_failed", "error", {
+        session_id: this.sessionId,
+        reason: n instanceof Error ? n.message : String(n)
+      });
+    }
+  }
+  /**
+   * Convert PCM data to AudioBuffer
+   * Input: 16-bit PCM (int16), Output: AudioBuffer (float32 [-1, 1])
+   */
+  pcmToAudioBuffer(t) {
+    if (!this.audioContext)
+      return null;
+    if (t.length === 0) {
+      const l = Math.floor(this.sampleRate * 0.01), h = this.audioContext.createBuffer(
+        this.channelCount,
+        l,
+        this.sampleRate
+      );
+      for (let d = 0; d < this.channelCount; d++)
+        h.getChannelData(d).fill(0);
+      return h;
+    }
+    const e = new Uint8Array(t), i = new Int16Array(e.buffer, 0, e.length / 2), u = i.length / this.channelCount, o = this.audioContext.createBuffer(
+      this.channelCount,
+      u,
+      this.sampleRate
+    );
+    for (let n = 0; n < this.channelCount; n++) {
+      const l = o.getChannelData(n);
+      for (let h = 0; h < u; h++) {
+        const d = h * this.channelCount + n;
+        l[h] = i[d] / 32768;
+      }
+    }
+    return o;
+  }
+  /**
+   * Get current playback time (seconds)
+   * Returns total actual playback duration
+   * @internal
+   */
+  getCurrentTime() {
+    if (!this.audioContext || !this.isPlaying)
+      return 0;
+    if (this.isPaused)
+      return this.pausedAt;
+    const t = this.audioContext.currentTime;
+    if (this.activeSources.size === 0 && this.scheduledChunks > 0)
+      return Math.max(0, this.lastScheduledChunkEndTime);
+    let e = 0;
+    for (let i = 0; i < this.scheduledChunkInfo.length; i++) {
+      const u = this.scheduledChunkInfo[i], o = u.startTime + u.duration;
+      if (t < u.startTime)
+        break;
+      if (o <= t)
+        e += u.duration;
+      else {
+        const n = t - u.startTime;
+        e += n;
+        break;
+      }
+    }
+    return Math.max(0, e);
+  }
+  /**
+   * Get total duration of buffered audio (seconds)
+   * Calculate total duration of all buffered chunks
+   * @internal
+   */
+  getBufferedDuration() {
+    if (!this.audioContext)
+      return 0;
+    let t = 0;
+    for (const e of this.audioChunks) {
+      const i = e.data.length / (this.sampleRate * this.channelCount * 2);
+      t += i;
+    }
+    return t;
+  }
+  /**
+   * Get current AudioContext time
+   * @returns Current AudioContext time in seconds, or 0 if AudioContext is not initialized
+   */
+  getAudioContextTime() {
+    var t;
+    return ((t = this.audioContext) == null ? void 0 : t.currentTime) ?? 0;
+  }
+  /**
+   * Pause playback
+   */
+  pause() {
+    !this.isPlaying || this.isPaused || !this.audioContext || (this.pausedAt = this.getCurrentTime(), this.pausedAudioContextTime = this.audioContext.currentTime, this.isPaused = !0, this.audioContext.state === "running" && this.audioContext.suspend().catch((t) => {
+      a.error("Failed to suspend AudioContext:", t), this.isPaused = !1;
+    }), this.log("Playback paused", {
+      pausedAt: this.pausedAt,
+      pausedAudioContextTime: this.pausedAudioContextTime,
+      audioContextState: this.audioContext.state
+    }));
+  }
+  /**
+   * Resume playback
+   */
+  async resume() {
+    if (!this.isPaused || !this.audioContext || !this.isPlaying)
+      return;
+    if (this.autoContinue = !1, this.audioContext.state === "suspended")
+      try {
+        await this.audioContext.resume();
+      } catch (e) {
+        throw a.error("Failed to resume AudioContext:", e), e;
+      }
+    const t = this.audioContext.currentTime;
+    this.sessionStartTime = this.pausedAudioContextTime - this.pausedAt - this.pausedTimeOffset, this.isPaused = !1, this.scheduledChunks < this.audioChunks.length && this.scheduleAllChunks(), this.log("Playback resumed", {
+      pausedAt: this.pausedAt,
+      pausedAudioContextTime: this.pausedAudioContextTime,
+      currentAudioContextTime: t,
+      adjustedSessionStartTime: this.sessionStartTime,
+      audioContextState: this.audioContext.state
+    });
+  }
+  /**
+   * Stop playback
+   */
+  stop() {
+    if (this.audioContext) {
+      this.isPaused && this.audioContext.state === "suspended" && (this.audioContext.resume().catch(() => {
+      }), this.isPaused = !1), this.isPlaying = !1, this.isPaused = !1, this.isResuming = !1, this.sessionStartTime = 0, this.scheduledTime = 0;
+      for (const t of this.activeSources) {
+        t.onended = null;
+        try {
+          t.stop(0);
+        } catch {
+        }
+        try {
+          t.disconnect();
+        } catch {
+        }
+      }
+      this.activeSources.clear(), this.audioChunks = [], this.scheduledChunks = 0, this.autoContinue = !1, this.log("[StreamingAudioPlayer] Playback stopped, state reset");
+    }
+  }
+  /**
+   * Enable or disable auto-start (for delayed start scenarios)
+   */
+  setAutoStart(t) {
+    this.autoStartEnabled = t, this.log(`Auto-start ${t ? "enabled" : "disabled"}`);
+  }
+  /**
+   * Start playback manually (for delayed start scenarios)
+   * This allows starting playback after transition animation completes
+   */
+  async play() {
+    if (!this.isPlaying) {
+      this.autoStartEnabled = !0;
+      try {
+        await this.startPlayback();
+      } catch (t) {
+        a.error("[StreamingAudioPlayer] Failed to start playback from play():", t);
+      }
+    }
+  }
+  /**
+   * Mark playback as ended
+   */
+  markEnded() {
+    var t;
+    this.log("Playback ended"), this.isPlaying = !1, (t = this.onEndedCallback) == null || t.call(this);
+  }
+  /**
+   * Set ended callback
+   */
+  onEnded(t) {
+    this.onEndedCallback = t;
+  }
+  /**
+   * Check if playing
+   */
+  isPlayingNow() {
+    return this.isPlaying && !this.isPaused;
+  }
+  /**
+   * Dispose and cleanup
+   */
+  dispose() {
+    this.stop(), this.audioContext && this.stateChangeHandler && (this.audioContext.removeEventListener("statechange", this.stateChangeHandler), this.stateChangeHandler = void 0), this.audioContext && (this.audioContext.close(), this.audioContext = null, this.gainNode = null), this.audioChunks = [], this.scheduledChunks = 0, this.sessionStartTime = 0, this.pausedTimeOffset = 0, this.pausedAt = 0, this.pausedAudioContextTime = 0, this.scheduledTime = 0, this.onEndedCallback = void 0, this.log("StreamingAudioPlayer disposed");
+  }
+  /**
+   * Flush buffered audio
+   * - hard: stops all playing sources and clears all chunks
+   * - soft (default): clears UNSCHEDULED chunks only
+   */
+  flush(t) {
+    if ((t == null ? void 0 : t.hard) === !0) {
+      this.stop(), this.audioChunks = [], this.scheduledChunks = 0, this.sessionStartTime = 0, this.pausedAt = 0, this.scheduledTime = 0, this.log("Flushed (hard)");
+      return;
+    }
+    this.scheduledChunks < this.audioChunks.length && this.audioChunks.splice(this.scheduledChunks), this.log("Flushed (soft)", { remainingScheduled: this.scheduledChunks });
+  }
+  /**
+   * Set volume (0.0 - 1.0)
+   * Note: This only controls avatar audio player volume, does not affect system volume
+   * @param volume Volume value, range 0.0 to 1.0 (0.0 is mute, 1.0 is max volume)
+   * @internal
+   */
+  setVolume(t) {
+    (t < 0 || t > 1) && (a.warn(`[StreamingAudioPlayer] Volume out of range: ${t}, clamping to [0, 1]`), t = Math.max(0, Math.min(1, t))), this.volume = t, this.gainNode && (this.gainNode.gain.value = t);
+  }
+  /**
+   * Get current volume
+   * @returns Current volume value (0.0 - 1.0)
+   * @internal
+   */
+  getVolume() {
+    return this.volume;
+  }
+  /**
+   * Debug logging
+   */
+  log(t, e) {
+    this.debug && a.log(`[StreamingAudioPlayer] ${t}`, e || "");
+  }
+}
+export {
+  p as StreamingAudioPlayer
+};

package/dist/_headers

@@ -0,0 +1,2 @@
+/*.wasm
+  Content-Type: application/wasm