@happyvertical/speech 0.78.0

package/dist/index.js

@@ -0,0 +1,694 @@
+class SpeechError extends Error {
+  constructor(message, code, adapter) {
+    super(message);
+    this.code = code;
+    this.adapter = adapter;
+    this.name = "SpeechError";
+  }
+}
+class SpeechConfigurationError extends SpeechError {
+  constructor(message, adapter) {
+    super(message, "SPEECH_CONFIGURATION_ERROR", adapter);
+    this.name = "SpeechConfigurationError";
+  }
+}
+class InvalidSpeechAdapterError extends SpeechError {
+  constructor(type, kind) {
+    super(`Invalid ${kind} speech adapter type: ${type}`, "INVALID_ADAPTER");
+    this.name = "InvalidSpeechAdapterError";
+  }
+}
+class SpeechProviderError extends SpeechError {
+  status;
+  responseBody;
+  constructor(adapter, message, options = {}) {
+    super(message, "SPEECH_PROVIDER_ERROR", adapter);
+    this.name = "SpeechProviderError";
+    this.status = options.status;
+    this.responseBody = options.responseBody;
+    if (options.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+}
+function normalizeBaseUrl(baseUrl) {
+  if (!baseUrl.trim()) {
+    throw new SpeechConfigurationError("Speech adapter baseUrl is required");
+  }
+  return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}
+function resolveSpeechUrl(baseUrl, path) {
+  return new URL(path.replace(/^\//, ""), normalizeBaseUrl(baseUrl)).toString();
+}
+function resolveFetch(fetchOverride) {
+  if (fetchOverride) {
+    return fetchOverride;
+  }
+  const globalFetch = globalThis.fetch;
+  if (!globalFetch) {
+    throw new SpeechConfigurationError(
+      "No fetch implementation available for speech adapter"
+    );
+  }
+  return globalFetch.bind(globalThis);
+}
+function mergeHeaders(options, extra) {
+  const headers = new Headers(options.headers);
+  if (options.apiKey && !headers.has("authorization")) {
+    headers.set("authorization", `Bearer ${options.apiKey}`);
+  }
+  if (extra) {
+    new Headers(extra).forEach((value, key) => {
+      headers.set(key, value);
+    });
+  }
+  return headers;
+}
+class HttpSpeechAdapter {
+  baseUrl;
+  fetchImpl;
+  apiKey;
+  headers;
+  timeoutMs;
+  constructor(options) {
+    this.baseUrl = options.baseUrl;
+    this.fetchImpl = resolveFetch(options.fetch);
+    this.apiKey = options.apiKey;
+    this.headers = options.headers;
+    this.timeoutMs = options.timeoutMs;
+  }
+  async post(adapterName, path, init, readResponse) {
+    const timeoutController = this.timeoutMs && this.timeoutMs > 0 ? new AbortController() : void 0;
+    const timeout = timeoutController && this.timeoutMs ? setTimeout(() => timeoutController.abort(), this.timeoutMs) : void 0;
+    const requestSignal = composeAbortSignals(
+      init.signal,
+      timeoutController?.signal
+    );
+    try {
+      const response = await this.fetchImpl(
+        resolveSpeechUrl(this.baseUrl, path),
+        {
+          ...init,
+          method: "POST",
+          headers: mergeHeaders(
+            { apiKey: this.apiKey, headers: this.headers },
+            init.headers
+          ),
+          signal: requestSignal.signal
+        }
+      );
+      await assertOk(response, adapterName);
+      return await readResponse(response);
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      requestSignal.cleanup();
+    }
+  }
+}
+function composeAbortSignals(...signals) {
+  const activeSignals = signals.filter(
+    (signal) => Boolean(signal)
+  );
+  if (activeSignals.length === 0) {
+    return { cleanup: () => void 0 };
+  }
+  if (activeSignals.length === 1) {
+    return { signal: activeSignals[0], cleanup: () => void 0 };
+  }
+  const controller = new AbortController();
+  let cleanup = () => void 0;
+  const abortFrom = (signal) => {
+    if (!controller.signal.aborted) {
+      controller.abort(signal.reason);
+    }
+    cleanup();
+  };
+  const onAbort = (event) => {
+    abortFrom(event.target);
+  };
+  cleanup = () => {
+    for (const signal of activeSignals) {
+      signal.removeEventListener("abort", onAbort);
+    }
+  };
+  for (const signal of activeSignals) {
+    if (signal.aborted) {
+      abortFrom(signal);
+      return { signal: controller.signal, cleanup: () => void 0 };
+    }
+  }
+  for (const signal of activeSignals) {
+    signal.addEventListener("abort", onAbort, { once: true });
+  }
+  return { signal: controller.signal, cleanup };
+}
+async function assertOk(response, adapterName) {
+  if (response.ok) {
+    return;
+  }
+  const responseBody = await response.text().catch(() => void 0);
+  throw new SpeechProviderError(
+    adapterName,
+    `${adapterName} speech request failed with HTTP ${response.status}`,
+    {
+      status: response.status,
+      responseBody
+    }
+  );
+}
+function appendAudioInput(form, audio, fieldName = "audio") {
+  const filename = audio.filename ?? "audio";
+  const data = audio.data;
+  if (typeof Blob !== "undefined" && data instanceof Blob) {
+    const contentType2 = audio.contentType ?? (data.type || "application/octet-stream");
+    const blob = data.type === contentType2 ? data : new Blob([data], { type: contentType2 });
+    form.append(fieldName, blob, filename);
+    return;
+  }
+  const contentType = audio.contentType ?? "application/octet-stream";
+  const blobPart = data instanceof Uint8Array ? arrayBufferFromBytes(data) : data;
+  form.append(fieldName, new Blob([blobPart], { type: contentType }), filename);
+}
+function appendOptionalFormValue(form, name, value) {
+  if (value === void 0 || value === null) {
+    return;
+  }
+  form.append(name, String(value));
+}
+function createHappyVerticalSynthesisForm(request, defaultVoice) {
+  const form = new FormData();
+  const voice = request.voice && typeof request.voice !== "string" ? request.voice : void 0;
+  form.set("text", request.text);
+  appendOptionalFormValue(
+    form,
+    "language",
+    request.language ?? voice?.language
+  );
+  appendOptionalFormValue(
+    form,
+    "speaker",
+    voiceToString(request.voice, defaultVoice)
+  );
+  appendOptionalFormValue(form, "speed", request.speed);
+  appendOptionalFormValue(form, "voice_prompt", voice?.prompt);
+  return form;
+}
+function voiceToString(voice, fallback) {
+  if (!voice) {
+    return fallback;
+  }
+  if (typeof voice === "string") {
+    return voice;
+  }
+  return voice.id ?? voice.name ?? voice.speakerId ?? fallback;
+}
+function compactJson(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entryValue]) => entryValue !== void 0)
+  );
+}
+function contentTypeToFormat(contentType) {
+  const match = /^audio\/([^;]+)/.exec(contentType);
+  return match?.[1];
+}
+function arrayBufferFromBytes(bytes) {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer;
+}
+function decodeBase64(base64) {
+  if (typeof Buffer !== "undefined") {
+    return arrayBufferFromBytes(Buffer.from(base64, "base64"));
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes.buffer;
+}
+function getNumber(value, ...keys) {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "number") {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function getString(value, ...keys) {
+  for (const key of keys) {
+    const candidate = value[key];
+    if (typeof candidate === "string") {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function normalizeWordTimings(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  return value.flatMap((entry) => {
+    if (!entry || typeof entry !== "object") {
+      return [];
+    }
+    const record = entry;
+    const word = getString(record, "word", "text", "token");
+    const startSeconds = getNumber(
+      record,
+      "startSeconds",
+      "start",
+      "start_time"
+    );
+    const endSeconds = getNumber(record, "endSeconds", "end", "end_time");
+    if (!word || startSeconds === void 0 || endSeconds === void 0) {
+      return [];
+    }
+    return [
+      {
+        word,
+        startSeconds,
+        endSeconds,
+        confidence: getNumber(record, "confidence"),
+        speakerId: getString(record, "speakerId", "speaker", "speaker_id")
+      }
+    ];
+  });
+}
+function normalizeTranscriptSegments(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  return value.flatMap((entry) => {
+    if (!entry || typeof entry !== "object") {
+      return [];
+    }
+    const record = entry;
+    const text = getString(record, "text", "transcript");
+    if (!text) {
+      return [];
+    }
+    return [
+      {
+        text,
+        startSeconds: getNumber(record, "startSeconds", "start", "start_time"),
+        endSeconds: getNumber(record, "endSeconds", "end", "end_time"),
+        confidence: getNumber(record, "confidence"),
+        speakerId: getString(record, "speakerId", "speaker", "speaker_id")
+      }
+    ];
+  });
+}
+async function readTranscriptResponse(response, adapterName) {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) {
+    const text2 = await response.text();
+    return {
+      text: text2,
+      provider: adapterName
+    };
+  }
+  const json = await response.json();
+  const text = getString(json, "text", "transcript", "transcription") ?? "";
+  return {
+    text,
+    language: getString(json, "language", "lang"),
+    durationSeconds: getNumber(json, "durationSeconds", "duration"),
+    words: normalizeWordTimings(
+      json.words ?? json.wordTimings ?? json.word_timings
+    ),
+    segments: normalizeTranscriptSegments(json.segments),
+    provider: getString(json, "provider") ?? adapterName,
+    model: getString(json, "model"),
+    raw: json
+  };
+}
+async function readSynthesizedSpeechResponse(response, adapterName) {
+  const responseContentType = response.headers.get("content-type") ?? "application/octet-stream";
+  if (!responseContentType.includes("application/json")) {
+    const audio = await response.arrayBuffer();
+    const sampleRate = parseHeaderNumber(response, "x-sample-rate");
+    return {
+      audio,
+      contentType: responseContentType,
+      format: contentTypeToFormat(responseContentType),
+      sampleRate,
+      provider: adapterName
+    };
+  }
+  const json = await response.json();
+  const contentType = getString(json, "contentType", "content_type", "mimeType", "mime_type") ?? "application/octet-stream";
+  const encodedAudio = getString(
+    json,
+    "audio",
+    "audioContent",
+    "audio_content"
+  );
+  if (!encodedAudio) {
+    throw new SpeechProviderError(
+      adapterName,
+      `${adapterName} JSON speech response did not include base64 audio`
+    );
+  }
+  return {
+    audio: decodeBase64(encodedAudio),
+    contentType,
+    format: getString(json, "format", "response_format") ?? contentTypeToFormat(contentType),
+    sampleRate: getNumber(json, "sampleRate", "sample_rate"),
+    channels: getNumber(json, "channels"),
+    durationSeconds: getNumber(json, "durationSeconds", "duration"),
+    words: normalizeWordTimings(
+      json.words ?? json.wordTimings ?? json.word_timings
+    ),
+    provider: getString(json, "provider") ?? adapterName,
+    model: getString(json, "model"),
+    raw: json
+  };
+}
+function parseHeaderNumber(response, headerName) {
+  const value = response.headers.get(headerName);
+  if (!value) {
+    return void 0;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+class OpenAICompatibleSpeechSynthesizer extends HttpSpeechAdapter {
+  type = "openai-compatible";
+  speechPath;
+  defaultModel;
+  defaultVoice;
+  constructor(options) {
+    super(options);
+    this.speechPath = options.speechPath ?? "/v1/audio/speech";
+    this.defaultModel = options.defaultModel ?? "tts-1";
+    this.defaultVoice = options.defaultVoice ?? "alloy";
+  }
+  async synthesize(request) {
+    const outputFormat = request.outputFormat ?? "mp3";
+    const payload = compactJson({
+      model: request.model ?? this.defaultModel,
+      input: request.text,
+      voice: voiceToString(request.voice, this.defaultVoice),
+      // biome-ignore lint/style/useNamingConvention: OpenAI-compatible API uses snake_case.
+      response_format: outputFormat,
+      speed: request.speed
+    });
+    const speech = await this.post(
+      this.type,
+      this.speechPath,
+      {
+        headers: {
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(payload),
+        signal: request.signal
+      },
+      (response) => readSynthesizedSpeechResponse(response, this.type)
+    );
+    return {
+      ...speech,
+      format: speech.format ?? outputFormat,
+      model: speech.model ?? String(payload.model)
+    };
+  }
+}
+class Qwen3SpeechSynthesizer extends HttpSpeechAdapter {
+  type = "qwen3-tts";
+  speechPath;
+  defaultModel;
+  defaultVoice;
+  constructor(options) {
+    super(options);
+    this.speechPath = options.speechPath ?? "/v1/audio/speech";
+    this.defaultModel = options.defaultModel ?? "qwen3-tts";
+    this.defaultVoice = options.defaultVoice;
+  }
+  async synthesize(request) {
+    const form = createHappyVerticalSynthesisForm(request, this.defaultVoice);
+    const speech = await this.post(
+      this.type,
+      this.speechPath,
+      {
+        body: form,
+        signal: request.signal
+      },
+      (response) => readSynthesizedSpeechResponse(response, this.type)
+    );
+    return {
+      ...speech,
+      format: speech.format ?? request.outputFormat,
+      model: speech.model ?? request.model ?? this.defaultModel
+    };
+  }
+}
+class StudioServerTranscriber extends HttpSpeechAdapter {
+  type = "studio-server";
+  transcribePath;
+  constructor(options) {
+    super(options);
+    this.transcribePath = options.transcribePath ?? "/v1/transcribe";
+  }
+  async transcribe(request) {
+    const form = new FormData();
+    appendAudioInput(form, request.audio);
+    appendOptionalFormValue(form, "language", request.language);
+    return this.post(
+      this.type,
+      this.transcribePath,
+      {
+        body: form,
+        signal: request.signal
+      },
+      (response) => readTranscriptResponse(response, this.type)
+    );
+  }
+}
+class StudioServerSpeechSynthesizer extends HttpSpeechAdapter {
+  type = "studio-server";
+  synthesizePath;
+  defaultVoice;
+  constructor(options) {
+    super(options);
+    this.synthesizePath = options.synthesizePath ?? "/v1/tts/synthesize";
+    this.defaultVoice = options.defaultVoice;
+  }
+  async synthesize(request) {
+    const form = createHappyVerticalSynthesisForm(request, this.defaultVoice);
+    return this.post(
+      this.type,
+      this.synthesizePath,
+      {
+        body: form,
+        signal: request.signal
+      },
+      (response) => readSynthesizedSpeechResponse(response, this.type)
+    );
+  }
+}
+async function getSpeech(options = {}, context = {}) {
+  const transcriber = options.transcriber === false ? void 0 : await getOptionalTranscriber(options.transcriber, context);
+  const synthesizer = options.synthesizer === false ? void 0 : await getOptionalSpeechSynthesizer(options.synthesizer, context);
+  return {
+    transcriber,
+    synthesizer,
+    async transcribe(request) {
+      if (!transcriber) {
+        throw new SpeechConfigurationError("No STT provider configured");
+      }
+      return transcriber.transcribe(request);
+    },
+    async synthesize(request) {
+      if (!synthesizer) {
+        throw new SpeechConfigurationError("No TTS provider configured");
+      }
+      return synthesizer.synthesize(request);
+    }
+  };
+}
+async function getTranscriber(options = {}, context = {}) {
+  const resolved = normalizeTranscriberOptions(options, context);
+  switch (resolved.type) {
+    case "studio-server":
+      return new StudioServerTranscriber(resolved);
+    default:
+      throw new InvalidSpeechAdapterError(
+        resolved.type ?? "unknown",
+        "STT"
+      );
+  }
+}
+async function getSpeechSynthesizer(options, context = {}) {
+  const resolved = normalizeSpeechSynthesizerOptions(options, context);
+  switch (resolved.type) {
+    case "studio-server":
+      return new StudioServerSpeechSynthesizer(resolved);
+    case "qwen3-tts":
+      return new Qwen3SpeechSynthesizer(resolved);
+    case "openai-compatible":
+      return new OpenAICompatibleSpeechSynthesizer(resolved);
+    default:
+      throw new InvalidSpeechAdapterError(
+        resolved.type ?? "unknown",
+        "TTS"
+      );
+  }
+}
+function getAvailableSpeechAdapters() {
+  return {
+    transcribers: ["studio-server"],
+    synthesizers: ["studio-server", "qwen3-tts", "openai-compatible"]
+  };
+}
+async function getOptionalTranscriber(options, context) {
+  if (!options && !hasTranscriberEnv(context.env ?? defaultEnv())) {
+    return void 0;
+  }
+  return getTranscriber(options, context);
+}
+async function getOptionalSpeechSynthesizer(options, context) {
+  if (!options && !hasSynthesizerEnv(context.env ?? defaultEnv())) {
+    return void 0;
+  }
+  return getSpeechSynthesizer(options, context);
+}
+function normalizeTranscriberOptions(options = {}, context) {
+  const env = context.env ?? defaultEnv();
+  const type = options.type ?? readEnv(
+    env,
+    "HAVE_SPEECH_STT_TYPE",
+    "HAVE_SPEECH_STT_ADAPTER",
+    "STT_ADAPTER"
+  ) ?? "studio-server";
+  const baseUrl = options.baseUrl ?? readEnv(env, "HAVE_SPEECH_STT_BASE_URL", "STT_BASE_URL");
+  if (type !== "studio-server") {
+    throw new InvalidSpeechAdapterError(type, "STT");
+  }
+  if (!baseUrl?.trim()) {
+    throw new SpeechConfigurationError("STT baseUrl is required", type);
+  }
+  return {
+    ...options,
+    type,
+    baseUrl: baseUrl.trim(),
+    fetch: options.fetch ?? context.fetch,
+    headers: options.headers ?? context.headers,
+    apiKey: options.apiKey ?? readEnv(env, "HAVE_SPEECH_STT_API_KEY", "STT_API_KEY", "SPEECH_API_KEY"),
+    timeoutMs: options.timeoutMs ?? parseOptionalInteger(
+      readEnv(env, "HAVE_SPEECH_STT_TIMEOUT_MS", "STT_TIMEOUT_MS")
+    ),
+    transcribePath: options.transcribePath ?? readEnv(env, "HAVE_SPEECH_STT_PATH", "STT_PATH")
+  };
+}
+function normalizeSpeechSynthesizerOptions(options, context) {
+  const env = context.env ?? defaultEnv();
+  const type = options?.type ?? readEnv(
+    env,
+    "HAVE_SPEECH_TTS_TYPE",
+    "HAVE_SPEECH_TTS_ADAPTER",
+    "TTS_ADAPTER"
+  );
+  const baseUrl = options?.baseUrl ?? readEnv(env, "HAVE_SPEECH_TTS_BASE_URL", "TTS_BASE_URL");
+  if (!type) {
+    throw new SpeechConfigurationError("TTS provider type is required");
+  }
+  if (type !== "studio-server" && type !== "qwen3-tts" && type !== "openai-compatible") {
+    throw new InvalidSpeechAdapterError(type, "TTS");
+  }
+  if (!baseUrl?.trim()) {
+    throw new SpeechConfigurationError("TTS baseUrl is required", type);
+  }
+  const shared = {
+    type,
+    baseUrl: baseUrl.trim(),
+    fetch: options?.fetch ?? context.fetch,
+    headers: options?.headers ?? context.headers,
+    apiKey: options?.apiKey ?? readEnv(env, "HAVE_SPEECH_TTS_API_KEY", "TTS_API_KEY", "SPEECH_API_KEY"),
+    timeoutMs: options?.timeoutMs ?? parseOptionalInteger(
+      readEnv(env, "HAVE_SPEECH_TTS_TIMEOUT_MS", "TTS_TIMEOUT_MS")
+    )
+  };
+  if (type === "studio-server") {
+    return {
+      ...shared,
+      type,
+      synthesizePath: options?.synthesizePath ?? readEnv(env, "HAVE_SPEECH_TTS_PATH", "TTS_PATH"),
+      defaultVoice: options?.defaultVoice ?? readEnv(env, "HAVE_SPEECH_TTS_VOICE", "TTS_VOICE")
+    };
+  }
+  if (type === "qwen3-tts") {
+    return {
+      ...shared,
+      type,
+      speechPath: options?.speechPath ?? readEnv(env, "HAVE_SPEECH_TTS_PATH", "TTS_PATH"),
+      defaultModel: options?.defaultModel ?? readEnv(env, "HAVE_SPEECH_TTS_MODEL", "TTS_MODEL"),
+      defaultVoice: options?.defaultVoice ?? readEnv(env, "HAVE_SPEECH_TTS_VOICE", "TTS_VOICE")
+    };
+  }
+  if (type === "openai-compatible") {
+    return {
+      ...shared,
+      type,
+      speechPath: options?.speechPath ?? readEnv(env, "HAVE_SPEECH_TTS_PATH", "TTS_PATH"),
+      defaultModel: options?.defaultModel ?? readEnv(env, "HAVE_SPEECH_TTS_MODEL", "TTS_MODEL"),
+      defaultVoice: options?.defaultVoice ?? readEnv(env, "HAVE_SPEECH_TTS_VOICE", "TTS_VOICE")
+    };
+  }
+  throw new InvalidSpeechAdapterError(type, "TTS");
+}
+function hasTranscriberEnv(env) {
+  return hasAnyEnv(
+    env,
+    "HAVE_SPEECH_STT_TYPE",
+    "HAVE_SPEECH_STT_ADAPTER",
+    "HAVE_SPEECH_STT_BASE_URL",
+    "STT_ADAPTER",
+    "STT_BASE_URL"
+  );
+}
+function hasSynthesizerEnv(env) {
+  return hasAnyEnv(
+    env,
+    "HAVE_SPEECH_TTS_TYPE",
+    "HAVE_SPEECH_TTS_ADAPTER",
+    "HAVE_SPEECH_TTS_BASE_URL",
+    "TTS_ADAPTER",
+    "TTS_BASE_URL"
+  );
+}
+function readEnv(env, ...keys) {
+  for (const key of keys) {
+    const value = env[key];
+    if (value?.trim()) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function hasAnyEnv(env, ...keys) {
+  return keys.some((key) => Boolean(env[key]?.trim()));
+}
+function parseOptionalInteger(value) {
+  if (!value) {
+    return void 0;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function defaultEnv() {
+  return globalThis.process?.env ?? {};
+}
+export {
+  InvalidSpeechAdapterError,
+  SpeechConfigurationError,
+  SpeechError,
+  SpeechProviderError,
+  getAvailableSpeechAdapters,
+  getSpeech,
+  getSpeechSynthesizer,
+  getTranscriber
+};
+//# sourceMappingURL=index.js.map