@m4trix/core 0.5.0

package/dist/react/index.js

@@ -0,0 +1,1316 @@
+import { useRef, useState, useCallback, useEffect } from 'react';
+import { io } from 'socket.io-client';
+
+// src/react/hooks/use-conversation/useConversation.ts
+
+// src/utility/Logger.ts
+var _Logger = class _Logger {
+  constructor(namespace = "") {
+    this.namespace = namespace;
+  }
+  static enableGlobalLogging() {
+    _Logger.globalEnabled = true;
+  }
+  static disableGlobalLogging() {
+    _Logger.globalEnabled = false;
+  }
+  formatPrefix() {
+    return this.namespace ? `[${this.namespace}]` : "";
+  }
+  logIfEnabled(level, ...args) {
+    if (!_Logger.globalEnabled)
+      return;
+    const prefix = this.formatPrefix();
+    if (prefix) {
+      console[level](prefix, ...args);
+    } else {
+      console[level](...args);
+    }
+  }
+  log(...args) {
+    this.logIfEnabled("log", ...args);
+  }
+  debug(...args) {
+    this.logIfEnabled("debug", ...args);
+  }
+  info(...args) {
+    this.logIfEnabled("info", ...args);
+  }
+  warn(...args) {
+    this.logIfEnabled("warn", ...args);
+  }
+  error(...args) {
+    this.logIfEnabled("error", ...args);
+  }
+};
+_Logger.globalEnabled = false;
+var Logger = _Logger;
+
+// src/react/adapter/VoiceEndpointAdapter.ts
+var VoiceEndpointAdapter = class {
+  constructor(config) {
+    this.logger = new Logger("SuTr > EndpointAdapter");
+    this.config = config;
+  }
+};
+var BaseVoiceEndpointAdapter = class extends VoiceEndpointAdapter {
+  constructor(config) {
+    super(config);
+  }
+  /**
+   * Send a voice file to the API endpoint and return a Pump stream of audio chunks
+   */
+  async sendVoiceFile({
+    blob,
+    metadata
+  }) {
+    const formData = new FormData();
+    formData.append("audio", blob);
+    if (metadata) {
+      formData.append("metadata", JSON.stringify(metadata));
+    }
+    this.logger.debug("Sending voice file to", this.config.endpoint, formData);
+    const response = await fetch(
+      `${this.config.baseUrl || ""}${this.config.endpoint}`,
+      {
+        method: "POST",
+        headers: this.config.headers,
+        body: formData
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`API error: ${response.status} ${await response.text()}`);
+    }
+    if (!response.body) {
+      throw new Error("No response body");
+    }
+    return response;
+  }
+};
+
+// src/react/utility/audio/InputAudioController.ts
+var InputAudioController = class {
+  constructor() {
+    this.logger = new Logger("@m4trix/core > InputAudioController");
+  }
+};
+
+// src/react/utility/audio/WebAudioInputAudioController.ts
+var DEFAULT_SLICING_INTERVAL = 3e3;
+var WebAudioInputAudioController = class extends InputAudioController {
+  constructor(audioConfig = {}) {
+    super();
+    this.audioConfig = audioConfig;
+    // ─── Recording state ─────────────────────────────────────────────────────
+    this.audioContextState = {
+      context: null,
+      source: null,
+      analyser: null
+    };
+    this.mediaRecorder = null;
+    this.recordedChunks = [];
+    this.recordingStream = null;
+  }
+  get audioContext() {
+    return this.audioContextState.context;
+  }
+  async createAudioContext() {
+    const context = new AudioContext({
+      sampleRate: this.audioConfig.sampleRate || 16e3,
+      latencyHint: "interactive"
+    });
+    const analyser = context.createAnalyser();
+    analyser.fftSize = 2048;
+    return { context, source: null, analyser };
+  }
+  async cleanupAudioContext() {
+    this.logger.debug("Cleaning up audio context");
+    const { source, context } = this.audioContextState;
+    if (source)
+      source.disconnect();
+    if (context)
+      await context.close();
+    this.audioContextState = { context: null, source: null, analyser: null };
+  }
+  async startRecording({
+    onRecordedChunk,
+    onError
+  } = {}) {
+    try {
+      this.logger.debug("Starting recording");
+      this.recordedChunks = [];
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      this.recordingStream = stream;
+      if (!this.audioContextState.context) {
+        this.audioContextState = await this.createAudioContext();
+      }
+      this.mediaRecorder = new MediaRecorder(stream, {
+        mimeType: "audio/webm;codecs=opus"
+      });
+      this.mediaRecorder.ondataavailable = (e) => {
+        if (e.data.size > 0) {
+          this.recordedChunks.push(e.data);
+          onRecordedChunk?.(e.data);
+          this.logger.debug("Recorded chunk", e.data.size);
+        }
+      };
+      this.mediaRecorder.start(DEFAULT_SLICING_INTERVAL);
+      this.logger.debug("MediaRecorder started");
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to start recording");
+      this.logger.error(error);
+      onError?.(error);
+    }
+  }
+  async stopRecording({
+    onRecordingCompleted
+  } = {}) {
+    this.logger.debug("Stopping recording");
+    if (!this.mediaRecorder || this.mediaRecorder.state === "inactive")
+      return;
+    await new Promise((resolve) => {
+      this.mediaRecorder.onstop = async () => {
+        if (this.recordedChunks.length) {
+          const blob = new Blob(this.recordedChunks, { type: "audio/webm" });
+          onRecordingCompleted?.(blob);
+          this.logger.debug("Recording completed", blob.size);
+        }
+        this.recordingStream?.getTracks().forEach((t) => t.stop());
+        this.recordingStream = null;
+        await this.cleanupAudioContext();
+        resolve();
+      };
+      this.mediaRecorder.stop();
+    });
+  }
+  /**
+   * Cleans up all audio recording resources.
+   */
+  cleanup() {
+    this.cleanupAudioContext();
+    if (this.mediaRecorder && this.mediaRecorder.state !== "inactive") {
+      this.mediaRecorder.stop();
+    }
+    if (this.recordingStream) {
+      this.recordingStream.getTracks().forEach((t) => t.stop());
+      this.recordingStream = null;
+    }
+  }
+};
+
+// src/react/utility/audio/OutputAudioController.ts
+var OutputAudioController = class {
+  constructor(loggerName) {
+    this.logger = new Logger(loggerName);
+  }
+};
+
+// src/react/utility/audio/AudioElementOutputAudioController.ts
+var AudioElementOutputAudioController = class extends OutputAudioController {
+  constructor() {
+    super("@m4trix/core > WebApiOutputAudioController");
+    // ─── Playback state ──────────────────────────────────────────────────────
+    this.currentHtmlAudio = null;
+    this.currentAudioUrl = null;
+  }
+  // ─── One-shot playback ────────────────────────────────────────────────────
+  /**
+   * Play either a Blob or a URL string.
+   * Uses <audio> under the hood for maximum browser compatibility.
+   */
+  async playAudio({
+    source,
+    onComplete
+  }) {
+    if (this.currentHtmlAudio) {
+      this.currentHtmlAudio.pause();
+      this.currentHtmlAudio.src = "";
+      if (this.currentAudioUrl && source instanceof Blob) {
+        URL.revokeObjectURL(this.currentAudioUrl);
+      }
+    }
+    const audio = new Audio();
+    this.currentHtmlAudio = audio;
+    let url;
+    if (source instanceof Blob) {
+      url = URL.createObjectURL(source);
+      this.currentAudioUrl = url;
+      audio.onended = () => {
+        URL.revokeObjectURL(url);
+        onComplete?.();
+      };
+    } else {
+      url = source;
+    }
+    audio.src = url;
+    try {
+      await audio.play();
+    } catch (err) {
+      this.logger.error("Playback failed, user gesture may be required", err);
+    }
+  }
+  // ─── Streaming playback ──────────────────────────────────────────────────
+  /**
+   * Stream audio from a Response via MediaSource Extensions.
+   * @param params.response The fetch Response whose body is an audio stream
+   * @param params.mimeCodec MIME type+codec string, e.g. 'audio/mpeg'
+   * @param params.onComplete Optional callback once the stream ends
+   */
+  async playAudioStream({
+    response,
+    mimeCodec = "audio/mpeg",
+    onComplete
+  }) {
+    if (!response.ok || !response.body) {
+      throw new Error(`Invalid response (${response.status})`);
+    }
+    if (typeof MediaSource === "undefined" || !MediaSource.isTypeSupported(mimeCodec)) {
+      throw new Error(`Unsupported MIME type or codec: ${mimeCodec}`);
+    }
+    await this.stopPlayback();
+    const mediaSource = new MediaSource();
+    const url = URL.createObjectURL(mediaSource);
+    this.currentAudioUrl = url;
+    const audio = new Audio(url);
+    this.currentHtmlAudio = audio;
+    audio.autoplay = true;
+    audio.onended = () => {
+      URL.revokeObjectURL(url);
+      this.currentAudioUrl = null;
+      onComplete?.();
+    };
+    mediaSource.addEventListener(
+      "sourceopen",
+      () => {
+        const sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
+        const reader = response.body.getReader();
+        const pump = async () => {
+          const { done, value } = await reader.read();
+          if (done) {
+            mediaSource.endOfStream();
+            return;
+          }
+          if (value) {
+            sourceBuffer.appendBuffer(value);
+          }
+          if (sourceBuffer.updating) {
+            sourceBuffer.addEventListener("updateend", pump, { once: true });
+          } else {
+            pump();
+          }
+        };
+        pump();
+      },
+      { once: true }
+    );
+    try {
+      await audio.play();
+    } catch (err) {
+      this.logger.error(
+        "Streaming playback failed, user gesture may be required",
+        err
+      );
+    }
+  }
+  // ─── Chunk-based streaming playback ─────────────────────────────────────
+  /**
+   * Initialize a streaming audio context for chunk-based playback.
+   * This creates the necessary MediaSource and SourceBuffer for subsequent chunk additions.
+   * Returns functions to add chunks and end the stream, encapsulated in a closure.
+   *
+   * @param mimeCodec MIME type+codec string, e.g. 'audio/mpeg'
+   * @param onComplete Optional callback once the stream ends
+   * @returns Object containing functions to add chunks and end the stream
+   */
+  async initializeChunkStream({
+    onComplete,
+    mimeCodec = "audio/mpeg"
+  }) {
+    this.logger.debug(`Initializing chunk stream with codec: ${mimeCodec}`);
+    if (typeof MediaSource === "undefined") {
+      throw new Error("MediaSource API is not supported in this browser");
+    }
+    if (!MediaSource.isTypeSupported(mimeCodec)) {
+      this.logger.warn(
+        `Codec ${mimeCodec} not supported, falling back to standard audio/mpeg`
+      );
+      mimeCodec = "audio/mpeg";
+      if (!MediaSource.isTypeSupported(mimeCodec)) {
+        throw new Error(
+          "Neither the specified codec nor the fallback codec are supported"
+        );
+      }
+    }
+    await this.stopPlayback();
+    const mediaSource = new MediaSource();
+    let sourceBuffer = null;
+    const url = URL.createObjectURL(mediaSource);
+    this.currentAudioUrl = url;
+    const audio = new Audio(url);
+    this.currentHtmlAudio = audio;
+    audio.autoplay = false;
+    audio.controls = true;
+    audio.style.display = "none";
+    document.body.appendChild(audio);
+    let playbackStarted = false;
+    let hasReceivedFirstChunk = false;
+    let receivedChunksCount = 0;
+    const pendingChunks = [];
+    let isProcessingQueue = false;
+    this.logger.debug("Waiting for MediaSource to open...");
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error("MediaSource failed to open (timeout)"));
+      }, 5e3);
+      mediaSource.addEventListener(
+        "sourceopen",
+        () => {
+          clearTimeout(timeout);
+          this.logger.debug("MediaSource open event received");
+          try {
+            sourceBuffer = mediaSource.addSourceBuffer(mimeCodec);
+            if (mediaSource.duration === Infinity || isNaN(mediaSource.duration)) {
+              mediaSource.duration = 1e3;
+            }
+            this.logger.debug("SourceBuffer created successfully");
+            resolve();
+          } catch (err) {
+            reject(new Error(`Failed to create SourceBuffer: ${err}`));
+          }
+        },
+        { once: true }
+      );
+    });
+    const logger = this.logger;
+    const processQueue = async () => {
+      if (!sourceBuffer || pendingChunks.length === 0 || isProcessingQueue) {
+        return;
+      }
+      isProcessingQueue = true;
+      try {
+        while (pendingChunks.length > 0) {
+          if (sourceBuffer.updating) {
+            await new Promise((resolve) => {
+              sourceBuffer.addEventListener("updateend", () => resolve(), {
+                once: true
+              });
+            });
+          }
+          const nextChunk = pendingChunks.shift();
+          if (!nextChunk)
+            continue;
+          try {
+            sourceBuffer.appendBuffer(nextChunk);
+            logger.debug(
+              `Processed queued chunk of size ${nextChunk.byteLength}`
+            );
+            if (!playbackStarted && hasReceivedFirstChunk) {
+              await tryStartPlayback();
+            }
+            await new Promise((resolve) => {
+              sourceBuffer.addEventListener("updateend", () => resolve(), {
+                once: true
+              });
+            });
+          } catch (err) {
+            logger.error("Error appending queued chunk to source buffer", err);
+          }
+        }
+      } finally {
+        isProcessingQueue = false;
+      }
+    };
+    const tryStartPlayback = async () => {
+      if (playbackStarted)
+        return;
+      playbackStarted = true;
+      logger.debug("Attempting to start audio playback...");
+      if (receivedChunksCount < 3 && audio.buffered.length > 0 && audio.buffered.end(0) < 0.5) {
+        logger.debug("Not enough data buffered yet, delaying playback");
+        return;
+      }
+      try {
+        if (audio.readyState === 0) {
+          logger.debug(
+            "Audio element not ready yet, waiting for canplay event"
+          );
+          await new Promise((resolve) => {
+            audio.addEventListener("canplay", () => resolve(), { once: true });
+          });
+        }
+        await audio.play();
+        logger.debug("Successfully started audio playback");
+      } catch (err) {
+        logger.error("Failed to start playback", err);
+        document.addEventListener(
+          "click",
+          async () => {
+            try {
+              await audio.play();
+              logger.debug("Started playback after user interaction");
+            } catch (innerErr) {
+              logger.error(
+                "Still failed to play after user interaction",
+                innerErr
+              );
+            }
+          },
+          { once: true }
+        );
+      }
+    };
+    const addChunkToStream = async (chunk) => {
+      if (!sourceBuffer) {
+        throw new Error(
+          "Streaming context was closed or not properly initialized."
+        );
+      }
+      let arrayBufferChunk;
+      if (chunk instanceof Blob) {
+        logger.debug("Converting Blob to ArrayBuffer");
+        arrayBufferChunk = await chunk.arrayBuffer();
+      } else {
+        arrayBufferChunk = chunk;
+      }
+      if (!arrayBufferChunk || arrayBufferChunk.byteLength === 0) {
+        logger.warn("Received empty chunk, skipping");
+        return;
+      }
+      if (!hasReceivedFirstChunk) {
+        hasReceivedFirstChunk = true;
+        logger.debug(
+          `First chunk received, size: ${arrayBufferChunk.byteLength} bytes`
+        );
+      }
+      receivedChunksCount++;
+      pendingChunks.push(arrayBufferChunk);
+      logger.debug(
+        `Added chunk #${receivedChunksCount} to queue (size: ${arrayBufferChunk.byteLength} bytes)`
+      );
+      await processQueue();
+      if (!playbackStarted && hasReceivedFirstChunk && receivedChunksCount >= 3) {
+        await tryStartPlayback();
+      }
+    };
+    const endChunkStream = () => {
+      if (mediaSource && mediaSource.readyState === "open") {
+        try {
+          if (pendingChunks.length > 0 || sourceBuffer && sourceBuffer.updating) {
+            logger.debug("Waiting for pending chunks before ending stream");
+            setTimeout(() => endChunkStream(), 200);
+            return;
+          }
+          if (hasReceivedFirstChunk) {
+            mediaSource.endOfStream();
+            logger.debug("MediaSource stream ended successfully");
+          } else {
+            logger.warn("Stream ended without receiving any chunks");
+          }
+        } catch (err) {
+          logger.error("Error ending MediaSource stream", err);
+        }
+      }
+      audio.onended = null;
+      if (audio.parentNode) {
+        audio.parentNode.removeChild(audio);
+      }
+      if (this.currentAudioUrl === url) {
+        this.currentAudioUrl = null;
+        URL.revokeObjectURL(url);
+      }
+      sourceBuffer = null;
+    };
+    audio.onended = () => {
+      logger.debug("Audio playback completed");
+      endChunkStream();
+      onComplete?.();
+    };
+    return {
+      addChunkToStream,
+      endChunkStream
+    };
+  }
+  /**
+   * Stop any ongoing HTMLAudioElement playback.
+   */
+  async stopPlayback() {
+    if (this.currentHtmlAudio) {
+      try {
+        this.currentHtmlAudio.pause();
+        this.currentHtmlAudio.src = "";
+      } catch (err) {
+        this.logger.error("Error stopping playback", err);
+      }
+      this.currentHtmlAudio = null;
+    }
+    if (this.currentAudioUrl) {
+      URL.revokeObjectURL(this.currentAudioUrl);
+      this.currentAudioUrl = null;
+    }
+  }
+  /**
+   * Cleans up all audio playback resources.
+   */
+  cleanup() {
+    this.stopPlayback();
+  }
+};
+
+// src/react/hooks/use-conversation/useConversation.ts
+Logger.enableGlobalLogging();
+function useConversation(endpoint, {
+  onStartRecording,
+  onStopRecording,
+  onReceive,
+  autoPlay = true,
+  downstreamMode = "STREAM",
+  onError,
+  audioConfig = {},
+  requestData = {},
+  endpointConfig = {}
+}) {
+  const { current: logger } = useRef(
+    new Logger("@m4trix/core > useConversation")
+  );
+  const inputAudioControllerRef = useRef(void 0);
+  const outputAudioControllerRef = useRef(
+    void 0
+  );
+  const endpointAdapterRef = useRef(
+    void 0
+  );
+  const [voiceAgentState, setVoiceAgentState] = useState("READY");
+  const [error, setError] = useState(null);
+  const handleError = useCallback(
+    (state, err) => {
+      setError(err);
+      logger.error(`Error during ${state}:`, err);
+      onError?.(state, err);
+    },
+    [onError]
+  );
+  const startRecording = useCallback(() => {
+    if (inputAudioControllerRef.current) {
+      try {
+        logger.debug("Starting recording");
+        setVoiceAgentState("RECORDING");
+        inputAudioControllerRef.current.startRecording({
+          onError: (err) => {
+            handleError("RECORDING", err);
+          }
+        });
+        onStartRecording?.();
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("RECORDING", err);
+        }
+      }
+    }
+  }, [onStartRecording, handleError]);
+  const stopRecording = useCallback(async () => {
+    if (inputAudioControllerRef.current) {
+      try {
+        logger.debug("Stopping recording");
+        await inputAudioControllerRef.current.stopRecording({
+          onRecordingCompleted: async (allData) => {
+            setVoiceAgentState("PROCESSING");
+            try {
+              const response = await endpointAdapterRef.current?.sendVoiceFile({
+                blob: allData,
+                metadata: requestData
+              });
+              if (!response) {
+                throw new Error("No response received from endpoint");
+              }
+              setVoiceAgentState("RESPONDING");
+              if (autoPlay) {
+                if (downstreamMode === "STREAM") {
+                  await outputAudioControllerRef.current?.playAudioStream({
+                    response,
+                    onComplete: () => {
+                      setVoiceAgentState("READY");
+                    }
+                  });
+                } else if (downstreamMode === "DOWNLOAD") {
+                  const responseBlob = await response.blob();
+                  await outputAudioControllerRef.current?.playAudio({
+                    source: responseBlob,
+                    onComplete: () => {
+                      setVoiceAgentState("READY");
+                    }
+                  });
+                }
+              } else {
+                setVoiceAgentState("READY");
+              }
+              onReceive?.(
+                allData,
+                async () => {
+                  if (outputAudioControllerRef.current) {
+                    if (downstreamMode === "STREAM") {
+                      return outputAudioControllerRef.current.playAudioStream({
+                        response,
+                        onComplete: () => {
+                          setVoiceAgentState("READY");
+                        }
+                      });
+                    } else {
+                      const responseBlob = await response.blob();
+                      return outputAudioControllerRef.current.playAudio({
+                        source: responseBlob,
+                        onComplete: () => {
+                          setVoiceAgentState("READY");
+                        }
+                      });
+                    }
+                  }
+                },
+                async () => {
+                  if (outputAudioControllerRef.current) {
+                    return outputAudioControllerRef.current.stopPlayback();
+                  }
+                }
+              );
+            } catch (err) {
+              if (err instanceof Error) {
+                handleError("PROCESSING", err);
+              }
+              setVoiceAgentState("READY");
+            }
+          }
+        });
+        onStopRecording?.();
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("RECORDING", err);
+        }
+      }
+    }
+  }, [
+    onStopRecording,
+    requestData,
+    autoPlay,
+    downstreamMode,
+    handleError,
+    onReceive
+  ]);
+  useEffect(() => {
+    if (endpointAdapterRef.current) {
+      return;
+    }
+    try {
+      const endpointAdapter = endpointConfig.endpointAdapter ? endpointConfig.endpointAdapter : new BaseVoiceEndpointAdapter({
+        baseUrl: endpointConfig.baseUrl,
+        endpoint,
+        headers: endpointConfig.headers
+      });
+      endpointAdapterRef.current = endpointAdapter;
+      if (!inputAudioControllerRef.current) {
+        inputAudioControllerRef.current = new WebAudioInputAudioController(
+          audioConfig
+        );
+      }
+      if (!outputAudioControllerRef.current) {
+        outputAudioControllerRef.current = new AudioElementOutputAudioController();
+      }
+    } catch (err) {
+      if (err instanceof Error) {
+        handleError("READY", err);
+      }
+    }
+  }, [endpoint, endpointConfig, audioConfig, handleError]);
+  useEffect(() => {
+    return () => {
+      inputAudioControllerRef.current?.cleanup();
+      outputAudioControllerRef.current?.cleanup();
+    };
+  }, []);
+  return {
+    startRecording,
+    stopRecording,
+    voiceAgentState,
+    error,
+    audioContext: inputAudioControllerRef.current?.audioContext || null
+  };
+}
+
+// src/react/adapter/socket/VoiceSocketAdapter.ts
+var VoiceSocketAdapter = class {
+  constructor(config) {
+    this._isConnected = false;
+    this.logger = new Logger("@m4trix/core > VoiceSocketAdapter");
+    this.emitter = new Emitter();
+    this.config = config;
+  }
+  on(event, listener) {
+    this.emitter.on(event, listener);
+  }
+  off(event, listener) {
+    this.emitter.off(event, listener);
+  }
+  once(event, listener) {
+    this.emitter.once(event, listener);
+  }
+  emit(event, data) {
+    this.emitter.emit(event, data);
+  }
+  isConnected() {
+    return this._isConnected;
+  }
+};
+var Emitter = class {
+  constructor() {
+    this.target = new EventTarget();
+  }
+  on(type, listener) {
+    this.target.addEventListener(type, listener);
+  }
+  off(type, listener) {
+    this.target.removeEventListener(type, listener);
+  }
+  once(type, listener) {
+    const wrapper = (event) => {
+      this.off(type, wrapper);
+      listener(event.detail);
+    };
+    this.on(type, wrapper);
+  }
+  emit(type, detail) {
+    this.target.dispatchEvent(new CustomEvent(type, { detail }));
+  }
+};
+var VoiceSocketIOAdapter = class extends VoiceSocketAdapter {
+  constructor(config) {
+    super(config);
+    this.socket = null;
+  }
+  async connect() {
+    return new Promise((resolve, reject) => {
+      if (!this.socket) {
+        this.socket = io(this.config.baseUrl, {
+          extraHeaders: this.config.headers,
+          autoConnect: true
+        });
+      }
+      this.socket.on("connect", () => {
+        this._isConnected = true;
+        this.logger.debug("Connected to socket");
+        this.emit("connect");
+        resolve();
+      });
+      this.socket.on("disconnect", () => {
+        this._isConnected = false;
+        this.emit("disconnect");
+        this.logger.debug("Disconnected from socket");
+        if (this.config.autoReconnect)
+          this.connect();
+      });
+      this.socket.on("connect_error", (error) => {
+        this.logger.error("Error connecting to socket", error);
+        this.emit("error", error);
+        reject(error);
+      });
+      this.socket.on("voice:chunk_received", (chunk) => {
+        this.logger.debug("Received voice chunk", chunk.byteLength);
+        this.onVoiceChunkReceived(chunk);
+      });
+      this.socket.on("voice:received_end_of_response_stream", () => {
+        this.logger.debug("Received end of response stream");
+        this.onReceivedEndOfResponseStream();
+      });
+      this.socket.on("voice:file_received", (blob) => {
+        this.logger.debug("Received voice file");
+        this.onVoiceFileReceived(blob);
+      });
+      this.socket.on("control-message", (message) => {
+        this.logger.debug("Received control message", message);
+        this.emit("control-message", message);
+      });
+    });
+  }
+  disconnect() {
+    this.socket?.disconnect();
+    this.socket = null;
+    this._isConnected = false;
+  }
+  exposeSocket() {
+    return this.socket;
+  }
+  async sendVoiceChunk(chunk, metadata) {
+    this.logger.debug(
+      "Sending voice chunk %i",
+      chunk instanceof Blob ? chunk.size : chunk.byteLength
+    );
+    if (!this.socket || !this.isConnected)
+      throw new Error("Socket not connected");
+    let chunkToSend;
+    if (chunk instanceof Blob) {
+      chunkToSend = await chunk.arrayBuffer();
+    } else {
+      chunkToSend = chunk;
+    }
+    this.logger.debug("[Socket] Sending voice chunk", chunkToSend.byteLength);
+    this.socket.emit("voice:send_chunk", chunkToSend, metadata);
+    this.emit("chunk_sent", chunk);
+  }
+  sendVoiceFile(blob, metadata) {
+    this.logger.debug("Sending voice file", blob, metadata);
+    if (!this.socket || !this.isConnected)
+      throw new Error("Socket not connected");
+    this.socket.emit("voice:send_file", blob, metadata);
+    this.emit("file-sent", blob);
+  }
+  commitVoiceMessage() {
+    if (!this.socket || !this.isConnected)
+      throw new Error("Socket not connected");
+    this.socket.emit("voice:commit");
+  }
+  onVoiceChunkReceived(chunk) {
+    this.emit("chunk-received", chunk);
+  }
+  onVoiceFileReceived(blob) {
+    this.emit("file-received", blob);
+  }
+  onReceivedEndOfResponseStream() {
+    this.emit("received-end-of-response-stream");
+  }
+};
+
+// src/react/utility/audio/WebAudioOutputAudioController.ts
+var STREAM_SAMPLE_RATE = 24e3;
+var CHANNELS = 1;
+var SLICE_DURATION_S = 0.25;
+var FRAMES_PER_SLICE = Math.floor(STREAM_SAMPLE_RATE * SLICE_DURATION_S);
+var BYTES_PER_SLICE = FRAMES_PER_SLICE * 2;
+var SCHED_TOLERANCE = 0.05;
+var WebAudioOutputAudioController = class extends OutputAudioController {
+  constructor() {
+    super("@m4trix/core > WebAudioOutputAudioController");
+    this.audioCtx = new AudioContext();
+    this.gain = this.audioCtx.createGain();
+    this.nextPlayTime = 0;
+    this.activeSources = /* @__PURE__ */ new Set();
+    this.userGestureHookAttached = false;
+    this.gain.connect(this.audioCtx.destination);
+    this.resetScheduler();
+  }
+  // ─────────────────────────────────────────────────────────────────────
+  // One‑shot playback
+  // ─────────────────────────────────────────────────────────────────────
+  async playAudio({
+    source,
+    onComplete
+  }) {
+    await this.stopPlayback();
+    const buf = await this.sourceToArrayBuffer(source);
+    const decoded = await this.decode(buf);
+    await this.ensureContextRunning();
+    const src = this.createSource(decoded, this.audioCtx.currentTime);
+    src.onended = () => {
+      this.activeSources.delete(src);
+      onComplete?.();
+    };
+  }
+  async playAudioStream() {
+  }
+  // ─────────────────────────────────────────────────────────────────────
+  // PCM streaming
+  // ─────────────────────────────────────────────────────────────────────
+  async initializeChunkStream({
+    onComplete
+  }) {
+    await this.stopPlayback();
+    await this.ensureContextRunning();
+    this.resetScheduler();
+    let streamEnded = false;
+    let pending = new Uint8Array(0);
+    const addChunkToStream = async (pkt) => {
+      if (streamEnded) {
+        this.logger.warn("Attempt to add chunk after stream ended \u2013 ignoring.");
+        return;
+      }
+      const bytes = new Uint8Array(
+        pkt instanceof Blob ? await pkt.arrayBuffer() : pkt
+      );
+      if (bytes.length === 0)
+        return;
+      const merged = new Uint8Array(pending.length + bytes.length);
+      merged.set(pending);
+      merged.set(bytes, pending.length);
+      pending = merged;
+      if (pending.length % 2 === 1)
+        return;
+      while (pending.length >= BYTES_PER_SLICE) {
+        const sliceBytes = pending.slice(0, BYTES_PER_SLICE);
+        pending = pending.slice(BYTES_PER_SLICE);
+        const aligned = sliceBytes.buffer.slice(
+          sliceBytes.byteOffset,
+          sliceBytes.byteOffset + sliceBytes.byteLength
+        );
+        const int16 = new Int16Array(aligned);
+        const buf = this.audioCtx.createBuffer(
+          CHANNELS,
+          int16.length,
+          STREAM_SAMPLE_RATE
+        );
+        const data = buf.getChannelData(0);
+        for (let i = 0; i < int16.length; i++)
+          data[i] = int16[i] / 32768;
+        this.scheduleBuffer(buf);
+      }
+    };
+    const endChunkStream = () => {
+      if (streamEnded)
+        return;
+      streamEnded = true;
+      if (onComplete) {
+        if (this.activeSources.size === 0)
+          onComplete();
+        else {
+          const last = Array.from(this.activeSources).pop();
+          if (last) {
+            const prev = last.onended;
+            last.onended = (e) => {
+              if (prev)
+                prev.call(last, e);
+              onComplete();
+            };
+          }
+        }
+      }
+    };
+    return { addChunkToStream, endChunkStream };
+  }
+  // ─────────────────────────────────────────────────────────────────────
+  // Buffer scheduling helpers
+  // ─────────────────────────────────────────────────────────────────────
+  scheduleBuffer(buf) {
+    if (this.nextPlayTime < this.audioCtx.currentTime + SCHED_TOLERANCE) {
+      this.nextPlayTime = this.audioCtx.currentTime + SCHED_TOLERANCE;
+    }
+    this.createSource(buf, this.nextPlayTime);
+    this.nextPlayTime += buf.duration;
+  }
+  createSource(buf, when) {
+    const src = this.audioCtx.createBufferSource();
+    src.buffer = buf;
+    src.connect(this.gain);
+    src.start(when);
+    this.activeSources.add(src);
+    src.onended = () => {
+      this.activeSources.delete(src);
+    };
+    return src;
+  }
+  resetScheduler() {
+    this.nextPlayTime = this.audioCtx.currentTime;
+  }
+  // ─── External resource helpers ───────────────────────────────────────
+  sourceToArrayBuffer(src) {
+    return typeof src === "string" ? fetch(src).then((r) => {
+      if (!r.ok)
+        throw new Error(`${r.status}`);
+      return r.arrayBuffer();
+    }) : src.arrayBuffer();
+  }
+  decode(buf) {
+    return new Promise(
+      (res, rej) => this.audioCtx.decodeAudioData(buf, res, rej)
+    );
+  }
+  // ─── Lifecycle methods ───────────────────────────────────────────────
+  async stopPlayback() {
+    for (const src of this.activeSources) {
+      try {
+        src.stop();
+      } catch {
+      }
+      src.disconnect();
+    }
+    this.activeSources.clear();
+    this.resetScheduler();
+  }
+  cleanup() {
+    this.stopPlayback();
+    if (this.audioCtx.state !== "closed")
+      this.audioCtx.close();
+  }
+  // ─── Autoplay‑policy helper ──────────────────────────────────────────
+  async ensureContextRunning() {
+    if (this.audioCtx.state !== "suspended")
+      return;
+    try {
+      await this.audioCtx.resume();
+    } catch {
+    }
+    if (this.audioCtx.state === "running")
+      return;
+    if (!this.userGestureHookAttached) {
+      this.userGestureHookAttached = true;
+      const resume = async () => {
+        try {
+          await this.audioCtx.resume();
+        } catch {
+        }
+        if (this.audioCtx.state === "running")
+          document.removeEventListener("click", resume);
+      };
+      document.addEventListener("click", resume);
+    }
+  }
+};
+
+// src/react/hooks/use-conversation/useSocketConversation.ts
+Logger.enableGlobalLogging();
+function useSocketConversation({
+  scope,
+  onStartRecording,
+  onStopRecording,
+  onReceive,
+  upstreamMode = "STREAM_WHILE_TALK",
+  onError,
+  audioConfig = {},
+  socketConfig = {}
+}) {
+  const { current: logger } = useRef(
+    new Logger("SuTr > useSocketConversation")
+  );
+  const inputAudioControllerRef = useRef(void 0);
+  const outputAudioControllerRef = useRef(
+    void 0
+  );
+  const socketAdapterRef = useRef(void 0);
+  const [socket, setSocket] = useState(null);
+  const [voiceAgentState, setVoiceAgentState] = useState("READY");
+  const [error, setError] = useState(null);
+  const shouldStreamWhileTalk = upstreamMode === "STREAM_WHILE_TALK";
+  const handleError = useCallback(
+    (state, err) => {
+      setError(err);
+      logger.error(`Error during ${state}:`, err);
+      onError?.(state, err);
+    },
+    [onError]
+  );
+  const subscribeToSocketEventsForChunkDownstreaming = useCallback(
+    async (socketAdapter) => {
+      logger.debug("Setting up audio stream for receiving chunks");
+      try {
+        const { addChunkToStream, endChunkStream } = await outputAudioControllerRef.current.initializeChunkStream({
+          mimeCodec: "audio/mpeg",
+          onComplete: () => {
+            logger.debug("Audio stream playback completed");
+            setVoiceAgentState("READY");
+          }
+        });
+        let chunkCount = 0;
+        const chunkReceivedEmitter = async (chunk) => {
+          if (chunk instanceof ArrayBuffer) {
+            chunkCount++;
+            logger.debug(
+              `Received voice chunk #${chunkCount} from socket, size: ${chunk.byteLength} bytes`
+            );
+            if (!chunk || chunk.byteLength === 0) {
+              logger.warn("Received empty chunk, skipping");
+              return;
+            }
+            try {
+              await addChunkToStream(chunk);
+              logger.debug(
+                `Successfully added chunk #${chunkCount} to audio stream`
+              );
+            } catch (err) {
+              logger.error(
+                `Failed to add chunk #${chunkCount} to audio stream`,
+                err
+              );
+              if (err instanceof Error) {
+                handleError("DOWNSTREAMING", err);
+              }
+            }
+          }
+        };
+        socketAdapter.on("chunk-received", chunkReceivedEmitter);
+        const endOfStreamEmitter = () => {
+          logger.debug(
+            `Received end of stream signal after ${chunkCount} chunks, ending chunk stream`
+          );
+          endChunkStream();
+          setVoiceAgentState("READY");
+        };
+        socketAdapter.on("received-end-of-response-stream", endOfStreamEmitter);
+        return () => {
+          logger.debug("Cleaning up socket event listeners");
+          socketAdapter.off("chunk-received", chunkReceivedEmitter);
+          socketAdapter.off(
+            "received-end-of-response-stream",
+            endOfStreamEmitter
+          );
+          endChunkStream();
+        };
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("DOWNSTREAMING", err);
+        }
+        return () => {
+        };
+      }
+    },
+    [handleError]
+  );
+  const hookupSocketAdapter = useCallback(
+    async (socketAdapter) => {
+      logger.debug("Connecting to socket...");
+      try {
+        await socketAdapter.connect();
+        socketAdapter.on("connect", () => {
+          logger.debug("Socket adapter connected");
+          setVoiceAgentState("READY");
+        });
+        socketAdapter.on("disconnect", () => {
+          logger.debug("Socket adapter disconnected");
+        });
+        socketAdapter.on("error", (err) => {
+          if (err instanceof Error) {
+            handleError(voiceAgentState, err);
+          } else {
+            handleError(voiceAgentState, new Error("Unknown error"));
+          }
+        });
+        setSocket(socketAdapter.exposeSocket());
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("READY", err);
+        }
+      }
+    },
+    [handleError, voiceAgentState]
+  );
+  const startRecording = useCallback(() => {
+    if (inputAudioControllerRef.current) {
+      try {
+        logger.debug("Starting recording");
+        setVoiceAgentState("RECORDING");
+        inputAudioControllerRef.current.startRecording({
+          onRecordedChunk: async (chunk) => {
+            if (shouldStreamWhileTalk) {
+              try {
+                await socketAdapterRef.current?.sendVoiceChunk(chunk);
+              } catch (err) {
+                if (err instanceof Error) {
+                  handleError("RECORDING", err);
+                }
+              }
+            }
+          }
+        });
+        onStartRecording?.();
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("RECORDING", err);
+        }
+      }
+    }
+  }, [onStartRecording, shouldStreamWhileTalk, handleError]);
+  const stopRecording = useCallback(async () => {
+    if (inputAudioControllerRef.current) {
+      try {
+        logger.debug("Stopping recording");
+        await inputAudioControllerRef.current.stopRecording({
+          onRecordingCompleted: async (allData) => {
+            setVoiceAgentState("PROCESSING");
+            try {
+              if (shouldStreamWhileTalk) {
+                logger.debug("Committing voice message");
+                await socketAdapterRef.current?.commitVoiceMessage();
+              } else {
+                await socketAdapterRef.current?.sendVoiceFile(allData);
+              }
+              setVoiceAgentState("DOWNSTREAMING");
+              await subscribeToSocketEventsForChunkDownstreaming(
+                socketAdapterRef.current
+              );
+              onReceive?.(
+                allData,
+                async () => {
+                  if (outputAudioControllerRef.current) {
+                    return outputAudioControllerRef.current.stopPlayback();
+                  }
+                },
+                async () => {
+                  if (outputAudioControllerRef.current) {
+                    return outputAudioControllerRef.current.stopPlayback();
+                  }
+                }
+              );
+            } catch (err) {
+              if (err instanceof Error) {
+                handleError("PROCESSING", err);
+              }
+            }
+          }
+        });
+        onStopRecording?.();
+      } catch (err) {
+        if (err instanceof Error) {
+          handleError("RECORDING", err);
+        }
+      }
+    }
+  }, [
+    onStopRecording,
+    handleError,
+    subscribeToSocketEventsForChunkDownstreaming,
+    onReceive
+  ]);
+  useEffect(() => {
+    if (socketAdapterRef.current) {
+      return;
+    }
+    try {
+      const socketAdapter = socketConfig.socketAdapter ? socketConfig.socketAdapter : new VoiceSocketIOAdapter({
+        scope,
+        baseUrl: socketConfig.baseUrl || "",
+        headers: socketConfig.headers
+      });
+      socketAdapterRef.current = socketAdapter;
+      if (!socketAdapter.isConnected()) {
+        hookupSocketAdapter(socketAdapter);
+      }
+      if (!inputAudioControllerRef.current) {
+        inputAudioControllerRef.current = new WebAudioInputAudioController(
+          audioConfig
+        );
+      }
+      if (!outputAudioControllerRef.current) {
+        outputAudioControllerRef.current = new WebAudioOutputAudioController();
+      }
+    } catch (err) {
+      if (err instanceof Error) {
+        handleError("READY", err);
+      }
+    }
+  }, [scope, socketConfig, hookupSocketAdapter, audioConfig, handleError]);
+  useEffect(() => {
+    return () => {
+      inputAudioControllerRef.current?.cleanup();
+      outputAudioControllerRef.current?.cleanup();
+      if (socketAdapterRef.current) {
+        socketAdapterRef.current.disconnect();
+        socketAdapterRef.current = void 0;
+      }
+    };
+  }, []);
+  return {
+    startRecording,
+    stopRecording,
+    voiceAgentState,
+    error,
+    audioContext: inputAudioControllerRef.current?.audioContext || null,
+    socket
+  };
+}
+
+export { BaseVoiceEndpointAdapter, Emitter, InputAudioController, VoiceEndpointAdapter, VoiceSocketAdapter, useConversation, useSocketConversation };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.js.map