@absolutejs/voice-azure 0.0.1-beta.1

package/README.md

@@ -0,0 +1,82 @@
+# `@absolutejs/voice-azure`
+
+Azure Speech (Cognitive Services) adapter for `@absolutejs/voice`.
+
+Currently ships **Neural Text-to-Speech** via Azure's REST `/cognitiveservices/v1` endpoint. Streaming Speech-to-Text via Azure's WebSocket USP protocol is the next package update (see "Roadmap" below).
+
+## Install
+
+```sh
+bun add @absolutejs/voice-azure
+```
+
+`@absolutejs/voice` is a runtime dependency.
+
+## TTS
+
+```ts
+import { voice } from "@absolutejs/voice";
+import { azureTTS } from "@absolutejs/voice-azure";
+
+const app = voice({
+  // ... stt + other voice options ...
+  tts: azureTTS({
+    region: "eastus",
+    subscriptionKey: process.env.AZURE_SPEECH_KEY!,
+    voice: "en-US-JennyNeural",
+    // optional:
+    outputFormat: "raw-24khz-16bit-mono-pcm", // default
+    language: "en-US",                         // default
+    voiceStyle: "cheerful",
+    styleDegree: 1.5,
+    prosody: { rate: "fast", pitch: "+5%" },
+  }),
+});
+```
+
+For telephony bridges, use a μ-law raw format at 8 kHz:
+
+```ts
+azureTTS({
+  region,
+  subscriptionKey,
+  voice: "en-US-AriaNeural",
+  outputFormat: "raw-8khz-8bit-mono-mulaw",
+});
+```
+
+Bearer-token auth (10-minute Azure auth tokens) is also supported:
+
+```ts
+azureTTS({ region, token, voice });
+```
+
+## Options
+
+| Option | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `subscriptionKey` / `token` | one of | — | Subscription key sent as `Ocp-Apim-Subscription-Key`, or short-lived bearer token sent as `Authorization`. |
+| `voice` | yes | — | Azure voice name, e.g. `en-US-JennyNeural`, `fr-FR-DeniseNeural`. |
+| `region` | yes\* | — | Azure region (`eastus`, `westus`, `francecentral`, …). \* Or pass `baseUrl` directly. |
+| `baseUrl` | no | `https://{region}.tts.speech.microsoft.com` | Override for sovereign clouds or Azure private endpoints. |
+| `endpointPath` | no | `/cognitiveservices/v1` | Override if you front the service with a gateway. |
+| `outputFormat` | no | `raw-24khz-16bit-mono-pcm` | Must be a `raw-*` format (mp3/wav variants are rejected because they aren't streamable frame-by-frame). |
+| `language` | no | `en-US` | Used in the SSML `xml:lang` attribute. |
+| `voiceStyle` | no | — | Azure neural style (`cheerful`, `empathetic`, `customerservice`, …). |
+| `styleDegree` | no | — | Only applied when `voiceStyle` is set (0..2 typically). |
+| `prosody` | no | — | `{ rate, pitch, volume }` — strings forwarded to the SSML `<prosody>` element. |
+| `userAgent` | no | `@absolutejs/voice-azure` | Sent as `User-Agent`. |
+| `fetch` | no | `globalThis.fetch` | Inject for tests; opportunistic HTTP/2 multiplexing is enabled for HTTPS targets. |
+
+## Notes
+
+- Only `raw-*` output formats are supported because the voice runtime needs framed PCM/μ-law/α-law to feed transports without buffering the whole response. If you need MP3/WAV for offline assets, call the Azure REST API directly.
+- The adapter aborts the in-flight HTTP request on `session.close(reason)` and refuses further `send()` calls.
+- Whitespace-only `send()` is a no-op (matches the ElevenLabs and Cartesia adapters).
+- Bearer tokens expire after 10 minutes by default — refresh externally and pass the new value into a fresh adapter, or stick with `subscriptionKey` for long-running deployments.
+
+## Roadmap
+
+- **STT (streaming via WebSocket USP)** — next package update. Will land as `azureSTT({ region, subscriptionKey, language, ... })` in this same package without breaking existing `azureTTS` callers.
+- **Custom voices / endpoint id** — once the TTS path has a paying customer who needs it.
+- **Speaker recognition / pronunciation assessment** — out of scope for the voice-agent path; covered better by direct Azure SDK use.

package/dist/azure.d.ts

@@ -0,0 +1,3 @@
+import type { TTSAdapter } from '@absolutejs/voice';
+import type { AzureTTSOptions } from './types';
+export declare const azureTTS: (config: AzureTTSOptions) => TTSAdapter;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { azureTTS } from './azure';
+export type { AzureTTSAuth, AzureTTSOptions, AzureTTSOutputFormat, AzureTTSProsody } from './types';

package/dist/index.js

@@ -0,0 +1,232 @@
+// @bun
+// src/azure.ts
+var DEFAULT_OUTPUT_FORMAT = "raw-24khz-16bit-mono-pcm";
+var DEFAULT_LANGUAGE = "en-US";
+var DEFAULT_USER_AGENT = "@absolutejs/voice-azure";
+var DEFAULT_ENDPOINT_PATH = "/cognitiveservices/v1";
+var isHttpsUrl = (url) => typeof url === "string" ? url.startsWith("https://") : url.protocol === "https:";
+var h2IfHttps = (url) => isHttpsUrl(url) ? { protocol: "http2" } : {};
+var createListenerMap = () => ({
+  audio: new Set,
+  close: new Set,
+  error: new Set
+});
+var emit = async (listeners, event, payload) => {
+  for (const listener of listeners[event]) {
+    await listener(payload);
+  }
+};
+var resolveErrorMessage = (error) => {
+  if (typeof error === "string" && error.trim())
+    return error;
+  if (error instanceof Error && error.message.trim())
+    return error.message;
+  return "Azure TTS request failed";
+};
+var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+var escapeAttr = (value) => escapeXml(value);
+var parseSampleRate = (format) => {
+  const match = format.match(/(?:audio|raw)-(\d+)(?:khz|hz)/i);
+  if (!match)
+    return 24000;
+  const value = Number(match[1]);
+  if (!Number.isFinite(value))
+    return 24000;
+  return format.toLowerCase().includes("hz") && !format.toLowerCase().includes("khz") ? value : value * 1000;
+};
+var resolveRawSampleRate = (format) => {
+  const lower = format.toLowerCase();
+  if (lower.startsWith("raw-")) {
+    const segment = lower.split("-")[1] ?? "";
+    if (segment.endsWith("khz")) {
+      const value = Number(segment.slice(0, -3));
+      return Number.isFinite(value) ? value * 1000 : 24000;
+    }
+    if (segment.endsWith("hz")) {
+      const value = Number(segment.slice(0, -2));
+      return Number.isFinite(value) ? value : 24000;
+    }
+  }
+  return parseSampleRate(format);
+};
+var resolveAudioFormat = (format) => {
+  const lower = format.toLowerCase();
+  if (!lower.startsWith("raw-")) {
+    throw new Error(`Unsupported Azure output format "${format}" for @absolutejs/voice TTS streaming. ` + `Use a "raw-*" format such as raw-24khz-16bit-mono-pcm or raw-8khz-8bit-mono-mulaw.`);
+  }
+  const sampleRateHz = resolveRawSampleRate(format);
+  if (lower.endsWith("-mulaw")) {
+    return {
+      channels: 1,
+      container: "raw",
+      encoding: "mulaw",
+      sampleRateHz
+    };
+  }
+  if (lower.endsWith("-alaw")) {
+    return {
+      channels: 1,
+      container: "raw",
+      encoding: "alaw",
+      sampleRateHz
+    };
+  }
+  if (lower.includes("-16bit-") && lower.endsWith("-pcm")) {
+    return {
+      channels: 1,
+      container: "raw",
+      encoding: "pcm_s16le",
+      sampleRateHz
+    };
+  }
+  if (lower.includes("-8bit-") && lower.endsWith("-pcm")) {
+    return {
+      channels: 1,
+      container: "raw",
+      encoding: "pcm_s8",
+      sampleRateHz
+    };
+  }
+  throw new Error(`Unrecognized Azure raw format "${format}". Expected -pcm/-mulaw/-alaw suffix.`);
+};
+var resolveBaseUrl = (config) => {
+  if (config.baseUrl)
+    return config.baseUrl.replace(/\/$/, "");
+  if (!config.region) {
+    throw new Error('@absolutejs/voice-azure requires either baseUrl or region (e.g. "eastus").');
+  }
+  return `https://${config.region}.tts.speech.microsoft.com`;
+};
+var resolveEndpointPath = (config) => {
+  const path = config.endpointPath ?? DEFAULT_ENDPOINT_PATH;
+  return path.startsWith("/") ? path : `/${path}`;
+};
+var buildHeaders = (config, outputFormat) => {
+  const headers = {
+    "Content-Type": "application/ssml+xml",
+    "User-Agent": config.userAgent ?? DEFAULT_USER_AGENT,
+    "X-Microsoft-OutputFormat": outputFormat
+  };
+  if ("token" in config && config.token) {
+    headers["Authorization"] = `Bearer ${config.token}`;
+  } else if ("subscriptionKey" in config && config.subscriptionKey) {
+    headers["Ocp-Apim-Subscription-Key"] = config.subscriptionKey;
+  }
+  return headers;
+};
+var buildProsodyAttributes = (prosody) => {
+  if (!prosody)
+    return "";
+  const parts = [];
+  if (prosody.rate)
+    parts.push(`rate="${escapeAttr(prosody.rate)}"`);
+  if (prosody.pitch)
+    parts.push(`pitch="${escapeAttr(prosody.pitch)}"`);
+  if (prosody.volume)
+    parts.push(`volume="${escapeAttr(prosody.volume)}"`);
+  return parts.length === 0 ? "" : ` ${parts.join(" ")}`;
+};
+var buildSsmlPayload = (config, text) => {
+  const language = config.language ?? DEFAULT_LANGUAGE;
+  const escapedText = escapeXml(text);
+  const styleDegreeAttribute = config.voiceStyle && typeof config.styleDegree === "number" ? ` styledegree="${String(config.styleDegree)}"` : "";
+  const styledInner = config.voiceStyle ? `<mstts:express-as style="${escapeAttr(config.voiceStyle)}"${styleDegreeAttribute}>${escapedText}</mstts:express-as>` : escapedText;
+  const prosodyAttributes = buildProsodyAttributes(config.prosody);
+  const innerWithProsody = prosodyAttributes ? `<prosody${prosodyAttributes}>${styledInner}</prosody>` : styledInner;
+  const mstssNs = config.voiceStyle ? ` xmlns:mstts="http://www.w3.org/2001/mstts"` : "";
+  return `<speak version="1.0" xml:lang="${escapeAttr(language)}"${mstssNs}>` + `<voice name="${escapeAttr(config.voice)}">${innerWithProsody}</voice></speak>`;
+};
+var buildTtsUrl = (config) => new URL(`${resolveBaseUrl(config)}${resolveEndpointPath(config)}`);
+var azureTTS = (config) => {
+  if (!(("subscriptionKey" in config) && config.subscriptionKey) && !(("token" in config) && config.token)) {
+    throw new Error("@absolutejs/voice-azure requires either subscriptionKey or token for authentication.");
+  }
+  if (!config.voice) {
+    throw new Error('@absolutejs/voice-azure requires a voice name (e.g. "en-US-JennyNeural").');
+  }
+  resolveBaseUrl(config);
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const outputFormat = config.outputFormat ?? DEFAULT_OUTPUT_FORMAT;
+  const audioFormat = resolveAudioFormat(outputFormat);
+  return {
+    kind: "tts",
+    open: () => {
+      const listeners = createListenerMap();
+      const activeControllers = new Set;
+      let closed = false;
+      return {
+        close: async (reason) => {
+          if (closed)
+            return;
+          closed = true;
+          for (const controller of activeControllers) {
+            controller.abort(reason);
+          }
+          await emit(listeners, "close", {
+            reason,
+            recoverable: false,
+            type: "close"
+          });
+        },
+        on: (event, handler) => {
+          listeners[event].add(handler);
+          return () => {
+            listeners[event].delete(handler);
+          };
+        },
+        send: async (text) => {
+          if (closed)
+            return;
+          const trimmed = text.trim();
+          if (!trimmed)
+            return;
+          const controller = new AbortController;
+          activeControllers.add(controller);
+          try {
+            const target = buildTtsUrl(config);
+            const response = await fetchImpl(target, {
+              ...h2IfHttps(target),
+              body: buildSsmlPayload(config, trimmed),
+              headers: buildHeaders(config, outputFormat),
+              method: "POST",
+              signal: controller.signal
+            });
+            if (!response.ok || !response.body) {
+              const bodyText = await response.text().catch(() => "");
+              throw new Error(`Azure TTS returned ${String(response.status)} ${response.statusText}${bodyText ? `: ${bodyText.slice(0, 200)}` : ""}`);
+            }
+            const reader = response.body.getReader();
+            try {
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done || !value)
+                  break;
+                await emit(listeners, "audio", {
+                  chunk: value,
+                  format: audioFormat,
+                  receivedAt: Date.now(),
+                  type: "audio"
+                });
+              }
+            } finally {
+              reader.releaseLock();
+            }
+          } catch (error) {
+            if (error.name === "AbortError")
+              return;
+            await emit(listeners, "error", {
+              error: error instanceof Error ? error : new Error(resolveErrorMessage(error)),
+              recoverable: false,
+              type: "error"
+            });
+          } finally {
+            activeControllers.delete(controller);
+          }
+        }
+      };
+    }
+  };
+};
+export {
+  azureTTS
+};

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+export type AzureTTSOutputFormat = 'audio-16khz-32kbitrate-mono-mp3' | 'audio-16khz-64kbitrate-mono-mp3' | 'audio-16khz-128kbitrate-mono-mp3' | 'audio-24khz-48kbitrate-mono-mp3' | 'audio-24khz-96kbitrate-mono-mp3' | 'audio-24khz-160kbitrate-mono-mp3' | 'audio-48khz-96kbitrate-mono-mp3' | 'audio-48khz-192kbitrate-mono-mp3' | 'raw-8khz-8bit-mono-alaw' | 'raw-8khz-8bit-mono-mulaw' | 'raw-8khz-16bit-mono-pcm' | 'raw-16khz-16bit-mono-pcm' | 'raw-22050hz-16bit-mono-pcm' | 'raw-24khz-16bit-mono-pcm' | 'raw-44100hz-16bit-mono-pcm' | 'raw-48khz-16bit-mono-pcm' | (string & {});
+export type AzureTTSAuth = {
+    subscriptionKey: string;
+    token?: never;
+} | {
+    subscriptionKey?: never;
+    token: string;
+};
+export type AzureTTSProsody = {
+    pitch?: string;
+    rate?: string;
+    volume?: string;
+};
+export type AzureTTSOptions = AzureTTSAuth & {
+    baseUrl?: string;
+    endpointPath?: string;
+    fetch?: typeof fetch;
+    language?: string;
+    outputFormat?: AzureTTSOutputFormat;
+    prosody?: AzureTTSProsody;
+    region?: string;
+    styleDegree?: number;
+    userAgent?: string;
+    voice: string;
+    voiceStyle?: string;
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@absolutejs/voice-azure",
+	"version": "0.0.1-beta.1",
+	"description": "Azure Speech (Cognitive Services) adapter for @absolutejs/voice — Neural TTS shipped, streaming STT next",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/absolutejs/voice-adapters.git",
+		"directory": "azure"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"license": "CC BY-NC 4.0",
+	"author": "Alex Kahn",
+	"scripts": {
+		"build": "rm -rf dist && bun build ./src/index.ts --outdir dist --target bun --external @absolutejs/voice && tsc --emitDeclarationOnly --project tsconfig.json",
+		"format": "prettier --write \"./**/*.{js,ts,json,md}\"",
+		"release": "bun run format && bun run build && bun publish --access public",
+		"test": "bun test",
+		"typecheck": "bun run tsc --noEmit"
+	},
+	"dependencies": {
+		"@absolutejs/voice": "0.0.22-beta.471"
+	},
+	"devDependencies": {
+		"@types/bun": "1.3.9",
+		"typescript": "^5.9.3"
+	}
+}