unspeech 0.1.13 → 0.1.16

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as _xsai_ext_providers_utils0 from "@xsai-ext/providers/utils";
 import { SpeechProviderWithExtraOptions } from "@xsai-ext/providers/utils";
-import { CommonRequestOptions } from "@xsai/shared";
+import { CommonRequestOptions, WithUnknown } from "@xsai/shared";
 
 //#region src/types/voice.d.ts
 interface Voice {
@@ -88,6 +88,92 @@ interface UnMicrosoftOptionCustomSSML {
 }
 /** @see {@link https://elevenlabs.io/docs/api-reference/text-to-speech/convert#request} */
 type UnMicrosoftOptions = (UnMicrosoftOptionAutoSSML | UnMicrosoftOptionCustomSSML) & UnMicrosoftOptionCommon;
+/**
+ * Default Microsoft output format used when callers only ask for OpenAI-style
+ * `mp3`. This keeps the common path on a compact 24kHz MP3 instead of the
+ * backend's maximum-quality 48kHz default.
+ */
+declare const DEFAULT_MICROSOFT_OUTPUT_FORMAT = "audio-24khz-48kbitrate-mono-mp3";
+/**
+ * Checks whether a Microsoft voice id is safe to embed in SSML attributes.
+ *
+ * Use when:
+ * - A caller builds SSML locally before sending it to unspeech.
+ *
+ * Expects:
+ * - Microsoft neural voice ids such as `en-US-AvaMultilingualNeural`.
+ *
+ * Returns:
+ * - `true` for the canonical letters/digits/hyphen shape.
+ */
+declare function isMicrosoftVoiceId(voice: string): boolean;
+/**
+ * Resolves OpenAI-style short audio format names to Microsoft output formats.
+ *
+ * Before:
+ * - `"mp3"`
+ * - `"wav"`
+ * - `"audio-24khz-48kbitrate-mono-mp3"`
+ *
+ * After:
+ * - `"audio-24khz-48kbitrate-mono-mp3"`
+ * - `"riff-24khz-16bit-mono-pcm"`
+ * - `"audio-24khz-48kbitrate-mono-mp3"`
+ */
+declare function resolveMicrosoftOutputFormat(responseFormat: string | undefined): string;
+/**
+ * Infers the MIME type for a Microsoft output format.
+ *
+ * Before:
+ * - `"audio-24khz-48kbitrate-mono-mp3"`
+ * - `"ogg-24khz-16bit-mono-opus"`
+ * - `"riff-24khz-16bit-mono-pcm"`
+ *
+ * After:
+ * - `"audio/mpeg"`
+ * - `"audio/ogg"`
+ * - `"audio/wav"`
+ */
+declare function inferMicrosoftContentType(format: string): string;
+/**
+ * Normalizes a speech speed multiplier into Microsoft SSML prosody rate.
+ *
+ * Before:
+ * - `1.0`
+ * - `1.2`
+ * - `0.8`
+ *
+ * After:
+ * - `""`
+ * - `"+20%"`
+ * - `"-20%"`
+ */
+declare function microsoftSpeedToProsodyRate(speed: number | undefined): string;
+/**
+ * Escapes plain text before inserting it into Microsoft SSML.
+ *
+ * Before:
+ * - `"Tom & <Jerry>"`
+ *
+ * After:
+ * - `"Tom &amp; &lt;Jerry&gt;"`
+ */
+declare function escapeMicrosoftSsmlText(text: string): string;
+/**
+ * Builds a Microsoft-compatible SSML envelope.
+ *
+ * Use when:
+ * - Sending plain text through unspeech's Microsoft backend while preserving
+ *   speed/prosody control.
+ *
+ * Expects:
+ * - `text` is plain text. Already-built SSML should be passed through with
+ *   `disableSsml`.
+ *
+ * Returns:
+ * - A `<speak>` document that Microsoft accepts as `application/ssml+xml`.
+ */
+declare function buildMicrosoftSsml(text: string, voice: string, speed: number | undefined): string;
 /**
  * [Microsoft / Azure AI](https://speech.microsoft.com/portal) provider for [UnSpeech](https://github.com/moeru-ai/unspeech)
  * only.
@@ -267,6 +353,50 @@ interface UnElevenLabsOptions {
  */
 declare function createUnElevenLabs(apiKey: string, baseURL?: string): SpeechProviderWithExtraOptions<"eleven_english_sts_v2" | "eleven_flash_v2" | "eleven_flash_v2_5" | "eleven_multilingual_sts_v2" | "eleven_multilingual_v2", UnElevenLabsOptions> & VoiceProviderWithExtraOptions<UnElevenLabsOptions>;
 //#endregion
+//#region src/backend/stepfun.d.ts
+interface UnStepfunOptions {
+  /**
+   * Audio volume. Range: 0.1 to 2.0.
+   *
+   * @default 1
+   */
+  volume?: number;
+  /**
+   * Voice labels for `step-tts-2` and `step-tts-mini`.
+   *
+   * Not supported by `stepaudio-2.5-tts`; use `instruction` instead.
+   */
+  voiceLabel?: {
+    language?: '粤语' | '四川话' | '日语' | string;
+    emotion?: string;
+    style?: string;
+  };
+  /**
+   * Global natural-language guidance for `stepaudio-2.5-tts`.
+   */
+  instruction?: string;
+  /**
+   * Output sample rate.
+   *
+   * @default 24000
+   */
+  sampleRate?: 8000 | 16000 | 22050 | 24000 | 48000 | number;
+  pronunciationMap?: {
+    tone: string[];
+  };
+  streamFormat?: 'audio' | 'sse';
+  markdownFilter?: boolean;
+}
+/**
+ * [StepFun / 阶跃星辰](https://platform.stepfun.com/) provider for
+ * [UnSpeech](https://github.com/moeru-ai/unspeech).
+ *
+ * @param apiKey - StepFun API key
+ * @param baseURL - UnSpeech Instance URL
+ * @returns SpeechProviderWithExtraOptions
+ */
+declare function createUnStepfun(apiKey: string, baseURL?: string): SpeechProviderWithExtraOptions<`stepfun/${string}`, UnStepfunOptions> & VoiceProviderWithExtraOptions<UnStepfunOptions>;
+//#endregion
 //#region src/backend/volcengine.d.ts
 interface UnVolcengineOptions {
   app?: {
@@ -370,7 +500,7 @@ declare function createUnVolcengine(apiKey: string, baseURL?: string): SpeechPro
 //#endregion
 //#region src/backend/index.d.ts
 /** @see {@link https://github.com/moeru-ai/unspeech} */
-declare function createUnSpeech(apiKey: string, baseURL?: string): _xsai_ext_providers_utils0.SpeechProviderWithExtraOptions<`alibaba/${string}` | `aliyun/${string}` | `deepgram/${string}` | `elevenlabs/${string}` | `koemotion/${string}` | `openai/${string}` | `volcano/${string}` | `volcengine/${string}`, UnSpeechOptions> & VoiceProviderWithExtraOptions<{
+declare function createUnSpeech(apiKey: string, baseURL?: string): _xsai_ext_providers_utils0.SpeechProviderWithExtraOptions<`alibaba/${string}` | `aliyun/${string}` | `deepgram/${string}` | `elevenlabs/${string}` | `koemotion/${string}` | `openai/${string}` | `stepfun/${string}` | `volcano/${string}` | `volcengine/${string}`, UnSpeechOptions> & VoiceProviderWithExtraOptions<{
   appId: string;
   backend: "volcano";
 } | {
@@ -380,11 +510,77 @@ declare function createUnSpeech(apiKey: string, baseURL?: string): _xsai_ext_pro
   backend: "azure" | "microsoft";
   region: MicrosoftRegions | string;
 } | {
-  backend: "ali" | "alibaba" | "alibaba-model-studio" | "aliyun" | "bailian" | "deepgram" | "elevenlabs" | "koemotion" | "openai";
+  backend: "ali" | "alibaba" | "alibaba-model-studio" | "aliyun" | "bailian" | "deepgram" | "elevenlabs" | "koemotion" | "openai" | "step" | "stepfun";
 }>;
 //#endregion
+//#region src/utils/generate-speech-response.d.ts
+type StringFetch$1 = (input: string, init: RequestInit) => Promise<Response>;
+interface GenerateSpeechResponseOptions extends Omit<CommonRequestOptions, 'fetch'> {
+  fetch?: StringFetch$1 | typeof globalThis.fetch;
+  input: string;
+  /** @default `mp3` */
+  responseFormat?: 'aac' | 'flac' | 'mp3' | 'opus' | 'pcm' | 'wav' | string;
+  /** @default `1.0` */
+  speed?: number;
+  voice: string;
+}
+interface GenerateSpeechResponseResult {
+  body: ArrayBuffer;
+  contentType: null | string;
+  response: Response;
+}
+interface UnSpeechAPIErrorOptions {
+  requestBody: string;
+  response: Response;
+  responseBody: string;
+}
+/**
+ * Error thrown when unspeech returns a non-2xx response.
+ *
+ * Use when:
+ * - Callers need to preserve unspeech/upstream status codes for fallback,
+ *   retries, or diagnostics.
+ *
+ * Expects:
+ * - The caller has already read the response body text.
+ *
+ * Returns:
+ * - An Error carrying status, response body, headers, and URL metadata.
+ */
+declare class UnSpeechAPIError extends Error {
+  requestBody: string;
+  response: Response;
+  responseBody: string;
+  responseHeaders: Record<string, string>;
+  status: number;
+  statusCode: number;
+  statusText: string;
+  url: string;
+  constructor(message: string, options: UnSpeechAPIErrorOptions);
+}
+/**
+ * Generates speech through unspeech and preserves response metadata.
+ *
+ * Use when:
+ * - A server proxy needs the binary audio bytes plus headers such as
+ *   `content-type`.
+ * - A router needs non-2xx status/body metadata for fallback decisions.
+ *
+ * Expects:
+ * - `baseURL` points at an unspeech v1 endpoint.
+ * - Provider-specific options are passed through as xsAI-compatible fields
+ *   such as `extraBody`, which are serialized into OpenAI-style snake_case.
+ *
+ * Returns:
+ * - The generated audio bytes, the `content-type` header when present, and
+ *   the original `Response`.
+ */
+declare function generateSpeechResponse(options: WithUnknown<GenerateSpeechResponseOptions>): Promise<GenerateSpeechResponseResult>;
+//#endregion
 //#region src/utils/list-voices.d.ts
-interface ListVoicesOptions extends Omit<CommonRequestOptions, 'model'> {
+type StringFetch = (input: string, init: RequestInit) => Promise<Response>;
+interface ListVoicesOptions extends Omit<CommonRequestOptions, 'fetch' | 'model'> {
+  fetch?: StringFetch | typeof globalThis.fetch;
   query?: string;
 }
 interface ListVoicesResponse {
@@ -392,4 +588,4 @@ interface ListVoicesResponse {
 }
 declare function listVoices(options: ListVoicesOptions): Promise<Voice[]>;
 //#endregion
-export { ListVoicesOptions, ListVoicesResponse, MicrosoftRegions, UnAlibabaCloudOptions, UnDeepgramOptions, UnElevenLabsOptions, UnMicrosoftOptionAutoSSML, UnMicrosoftOptionCommon, UnMicrosoftOptionCustomSSML, UnMicrosoftOptions, UnSpeechOptions, UnVolcengineOptions, Voice, VoiceFormat, VoiceLanguage, VoiceProvider, VoiceProviderWithExtraOptions, createUnAlibabaCloud, createUnDeepgram, createUnElevenLabs, createUnMicrosoft, createUnSpeech, createUnVolcengine, listVoices };
+export { DEFAULT_MICROSOFT_OUTPUT_FORMAT, GenerateSpeechResponseOptions, GenerateSpeechResponseResult, ListVoicesOptions, ListVoicesResponse, MicrosoftRegions, UnAlibabaCloudOptions, UnDeepgramOptions, UnElevenLabsOptions, UnMicrosoftOptionAutoSSML, UnMicrosoftOptionCommon, UnMicrosoftOptionCustomSSML, UnMicrosoftOptions, UnSpeechAPIError, UnSpeechAPIErrorOptions, UnSpeechOptions, UnStepfunOptions, UnVolcengineOptions, Voice, VoiceFormat, VoiceLanguage, VoiceProvider, VoiceProviderWithExtraOptions, buildMicrosoftSsml, createUnAlibabaCloud, createUnDeepgram, createUnElevenLabs, createUnMicrosoft, createUnSpeech, createUnStepfun, createUnVolcengine, escapeMicrosoftSsmlText, generateSpeechResponse, inferMicrosoftContentType, isMicrosoftVoiceId, listVoices, microsoftSpeedToProsodyRate, resolveMicrosoftOutputFormat };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { createSpeechProviderWithExtraOptions, merge } from "@xsai-ext/providers/utils";
-import { objCamelToSnake, requestHeaders, requestURL, responseJSON } from "@xsai/shared";
+import { objCamelToSnake, requestBody, requestHeaders, requestURL } from "@xsai/shared";
 
 //#region src/backend/alibabacloud.ts
 /**
@@ -123,6 +123,118 @@ function createUnElevenLabs(apiKey, baseURL = "http://localhost:5933/v1/") {
 //#endregion
 //#region src/backend/microsoft.ts
 /**
+* Default Microsoft output format used when callers only ask for OpenAI-style
+* `mp3`. This keeps the common path on a compact 24kHz MP3 instead of the
+* backend's maximum-quality 48kHz default.
+*/
+const DEFAULT_MICROSOFT_OUTPUT_FORMAT = "audio-24khz-48kbitrate-mono-mp3";
+const MICROSOFT_VOICE_ID = /^[a-z0-9-]+$/i;
+/**
+* Checks whether a Microsoft voice id is safe to embed in SSML attributes.
+*
+* Use when:
+* - A caller builds SSML locally before sending it to unspeech.
+*
+* Expects:
+* - Microsoft neural voice ids such as `en-US-AvaMultilingualNeural`.
+*
+* Returns:
+* - `true` for the canonical letters/digits/hyphen shape.
+*/
+function isMicrosoftVoiceId(voice) {
+	return MICROSOFT_VOICE_ID.test(voice);
+}
+/**
+* Resolves OpenAI-style short audio format names to Microsoft output formats.
+*
+* Before:
+* - `"mp3"`
+* - `"wav"`
+* - `"audio-24khz-48kbitrate-mono-mp3"`
+*
+* After:
+* - `"audio-24khz-48kbitrate-mono-mp3"`
+* - `"riff-24khz-16bit-mono-pcm"`
+* - `"audio-24khz-48kbitrate-mono-mp3"`
+*/
+function resolveMicrosoftOutputFormat(responseFormat) {
+	if (!responseFormat) return DEFAULT_MICROSOFT_OUTPUT_FORMAT;
+	if (responseFormat.includes("-")) return responseFormat;
+	if (responseFormat === "mp3") return DEFAULT_MICROSOFT_OUTPUT_FORMAT;
+	if (responseFormat === "wav") return "riff-24khz-16bit-mono-pcm";
+	if (responseFormat === "opus") return "ogg-24khz-16bit-mono-opus";
+	return responseFormat;
+}
+/**
+* Infers the MIME type for a Microsoft output format.
+*
+* Before:
+* - `"audio-24khz-48kbitrate-mono-mp3"`
+* - `"ogg-24khz-16bit-mono-opus"`
+* - `"riff-24khz-16bit-mono-pcm"`
+*
+* After:
+* - `"audio/mpeg"`
+* - `"audio/ogg"`
+* - `"audio/wav"`
+*/
+function inferMicrosoftContentType(format) {
+	if (format.includes("mp3")) return "audio/mpeg";
+	if (format.includes("opus")) return "audio/ogg";
+	if (format.includes("pcm") || format.startsWith("riff")) return "audio/wav";
+	return "application/octet-stream";
+}
+/**
+* Normalizes a speech speed multiplier into Microsoft SSML prosody rate.
+*
+* Before:
+* - `1.0`
+* - `1.2`
+* - `0.8`
+*
+* After:
+* - `""`
+* - `"+20%"`
+* - `"-20%"`
+*/
+function microsoftSpeedToProsodyRate(speed) {
+	if (speed == null || speed === 1) return "";
+	const delta = Math.round((speed - 1) * 100);
+	if (delta === 0) return "";
+	return delta > 0 ? `+${delta}%` : `${delta}%`;
+}
+/**
+* Escapes plain text before inserting it into Microsoft SSML.
+*
+* Before:
+* - `"Tom & <Jerry>"`
+*
+* After:
+* - `"Tom &amp; &lt;Jerry&gt;"`
+*/
+function escapeMicrosoftSsmlText(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+/**
+* Builds a Microsoft-compatible SSML envelope.
+*
+* Use when:
+* - Sending plain text through unspeech's Microsoft backend while preserving
+*   speed/prosody control.
+*
+* Expects:
+* - `text` is plain text. Already-built SSML should be passed through with
+*   `disableSsml`.
+*
+* Returns:
+* - A `<speak>` document that Microsoft accepts as `application/ssml+xml`.
+*/
+function buildMicrosoftSsml(text, voice, speed) {
+	const safe = escapeMicrosoftSsmlText(text);
+	const rate = microsoftSpeedToProsodyRate(speed);
+	return `<speak version='1.0' xml:lang='en-US'><voice name='${voice}'>${rate ? `<prosody rate='${rate}'>${safe}</prosody>` : safe}</voice></speak>`;
+}
+/**
 * [Microsoft / Azure AI](https://speech.microsoft.com/portal) provider for [UnSpeech](https://github.com/moeru-ai/unspeech)
 * only.
 *
@@ -236,15 +348,104 @@ function createUnSpeech(apiKey, baseURL = "http://localhost:5933/v1/") {
 	} });
 }
 
+//#endregion
+//#region src/utils/generate-speech-response.ts
+/**
+* Error thrown when unspeech returns a non-2xx response.
+*
+* Use when:
+* - Callers need to preserve unspeech/upstream status codes for fallback,
+*   retries, or diagnostics.
+*
+* Expects:
+* - The caller has already read the response body text.
+*
+* Returns:
+* - An Error carrying status, response body, headers, and URL metadata.
+*/
+var UnSpeechAPIError = class extends Error {
+	requestBody;
+	response;
+	responseBody;
+	responseHeaders;
+	status;
+	statusCode;
+	statusText;
+	url;
+	constructor(message, options) {
+		super(message);
+		this.name = "UnSpeechAPIError";
+		this.requestBody = options.requestBody;
+		this.response = options.response;
+		this.responseBody = options.responseBody;
+		this.responseHeaders = Object.fromEntries(options.response.headers.entries());
+		this.status = options.response.status;
+		this.statusCode = options.response.status;
+		this.statusText = options.response.statusText;
+		this.url = options.response.url;
+	}
+};
+/**
+* Generates speech through unspeech and preserves response metadata.
+*
+* Use when:
+* - A server proxy needs the binary audio bytes plus headers such as
+*   `content-type`.
+* - A router needs non-2xx status/body metadata for fallback decisions.
+*
+* Expects:
+* - `baseURL` points at an unspeech v1 endpoint.
+* - Provider-specific options are passed through as xsAI-compatible fields
+*   such as `extraBody`, which are serialized into OpenAI-style snake_case.
+*
+* Returns:
+* - The generated audio bytes, the `content-type` header when present, and
+*   the original `Response`.
+*/
+async function generateSpeechResponse(options) {
+	const body = requestBody(options);
+	const response = await (options.fetch ?? globalThis.fetch)(requestURL("audio/speech", options.baseURL).toString(), {
+		body,
+		headers: requestHeaders({
+			"Content-Type": "application/json",
+			...options.headers
+		}, options.apiKey),
+		method: "POST",
+		signal: options.abortSignal
+	});
+	if (!response.ok) {
+		const responseBody = await response.text().catch(() => "");
+		throw new UnSpeechAPIError(`unspeech audio speech ${response.status}: ${responseBody.slice(0, 256)}`, {
+			requestBody: body,
+			response,
+			responseBody
+		});
+	}
+	return {
+		body: await response.arrayBuffer(),
+		contentType: response.headers.get("content-type"),
+		response
+	};
+}
+
 //#endregion
 //#region src/utils/list-voices.ts
 async function listVoices(options) {
-	return (options.fetch ?? globalThis.fetch)(requestURL(options.query ? `api/voices?${options.query}` : "api/voices", options.baseURL), {
+	const response = await (options.fetch ?? globalThis.fetch)(requestURL(options.query ? `api/voices?${options.query}` : "api/voices", options.baseURL).toString(), {
 		headers: requestHeaders({ ...options.headers }, options.apiKey),
 		method: "GET",
 		signal: options.abortSignal
-	}).then(responseJSON).then(({ voices }) => voices);
+	});
+	if (!response.ok) {
+		const responseBody = await response.text().catch(() => "");
+		throw new UnSpeechAPIError(`unspeech voices ${response.status}: ${responseBody.slice(0, 256)}`, {
+			requestBody: "",
+			response,
+			responseBody
+		});
+	}
+	return (await response.json()).voices;
 }
 
 //#endregion
-export { createUnAlibabaCloud, createUnDeepgram, createUnElevenLabs, createUnMicrosoft, createUnSpeech, createUnVolcengine, listVoices };
+export { UnSpeechAPIError, buildMicrosoftSsml, createUnAlibabaCloud, createUnDeepgram, createUnElevenLabs, createUnMicrosoft, createUnSpeech, createUnVolcengine, escapeMicrosoftSsmlText, generateSpeechResponse, inferMicrosoftContentType, isMicrosoftVoiceId, listVoices, microsoftSpeedToProsodyRate, resolveMicrosoftOutputFormat };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unspeech",
   "type": "module",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "description": "Client SDK for unSpeech",
   "author": "Moeru AI",
   "license": "MIT",