@broberg/ai-sdk 0.45.0 → 0.46.0

package/README.md

@@ -81,6 +81,43 @@ const { data } = await ai.contracts.extract({
 // also: ai.contracts.{ mockup, design, classify, rerank }
 ```
 
+## Read-aloud: what was actually SPOKEN is not your `text`
+
+`ai.tts({ pronunciations })` rewrites your text before the provider ever sees it —
+`broberg.ai` becomes four spoken words. So **`text` is a retelling of the audio**, and a
+word-highlighter built on `text` alone will drift at every rewritten word.
+
+Two fields close that gap:
+
+```ts
+const { audio, wordTimings, ssml } = await ai.tts({
+  text, voice, wordTimings: true, pronunciations,
+  override: { provider: "azure" },
+});
+wordTimings.words      // [{ text, startMs, endMs, sourceStart, sourceEnd }]
+wordTimings.unaligned  // spoken words we could NOT place — never a guessed offset
+ssml                   // the EXACT markup we sent, verbatim — your ground truth
+```
+
+`sourceStart`/`sourceEnd` index **your original text**, because Azure reports audio time
+only and carries no text offset at all; the link back to the manuscript is derived here.
+`ssml` exists so you can check that derivation instead of trusting it — it is the string
+we sent, not a rebuild (filed by a consumer who could not verify what was spoken, F055.4).
+It is `undefined` on routes that build no markup; an empty string would be a different claim.
+
+**Two matcher rules that surprise people**, both measured in `pronunciations`:
+
+- **Case-insensitive.** `ai`, `Ai` and `AI` all match a rule for `AI`.
+- **A word touching a hyphen keeps its spelling.** `broberg.ai-drevet` is NOT rewritten
+  unless that entry sets `matchInCompounds: true` — the rule that keeps `mail` out of
+  `e-mail`. A consumer deriving their own expected-word list got exactly these two
+  occurrences wrong before the field existed.
+
+**Word timings need Azure's BATCH route**, a different call shape (submit → poll → ZIP),
+and that route requires the resource's custom subdomain — the regional host answers 401
+with a valid key, blaming the key. Set `AZURE_SPEECH_RESOURCE`; without it `wordTimings`
+fails before the call, naming the fix.
+
 ## Providers & tiers
 
 Adapters: **Anthropic** (HTTP + `claude -p` subprocess), **OpenAI**, **Google

package/dist/index.d.ts

@@ -555,6 +555,17 @@ interface PodcastResult {
      *  — Azure reports only audio time, so the link back to the manuscript is derived
      *  here. `unaligned` names any spoken word that could not be placed. */
     wordTimings?: AlignedWordTimings;
+    /** F055.4 — the EXACT markup we sent the provider, verbatim, not rebuilt.
+     *
+     *  Why it exists: the text you passed is not what was spoken. A pronunciation
+     *  dictionary rewrites it, so `text` is a RETELLING of the audio — and without this
+     *  field a consumer cannot check our retelling any more than we could check theirs.
+     *  cms filed exactly that (11 September 2026) while we were asking them for markup
+     *  only we could produce.
+     *
+     *  UNDEFINED when the route builds no markup (ElevenLabs routes by voice, not SSML).
+     *  An empty string would say "we sent empty markup", which is a different claim. */
+    ssml?: string;
     usage: Usage;
 }
 
@@ -2385,8 +2396,17 @@ declare function azureAdapter(config?: {
     sttPricePerMin?: number;
     /** STT base URL override (e.g. a resource custom domain). */
     sttBaseUrl?: string;
-    /** Resource name → custom-domain STT host `{resource}.cognitiveservices.azure.com`
-     *  (or env AZURE_SPEECH_RESOURCE). Without it, STT uses the regional host. */
+    /** Resource name → custom-domain host `{resource}.cognitiveservices.azure.com`
+     *  (or env AZURE_SPEECH_RESOURCE).
+     *
+     *  **STT works without it** — the regional host is a legitimate route for
+     *  `speechtotext/transcriptions` and is the tested default (F029).
+     *
+     *  **BATCH SYNTHESIS REQUIRES IT.** Every example in Microsoft's batch-synthesis
+     *  docs uses the resource host; the regional host is shown nowhere, and cms measured
+     *  it answering 401 with a valid key (F055.3). Without this set, `wordTimings` fails
+     *  before the call rather than spending your time on Azure's "invalid subscription
+     *  key or wrong API endpoint" — which names the key first and sends you the wrong way. */
     resource?: string;
     /** Fast-transcription api-version (overrides the GA default). */
     sttApiVersion?: string;
@@ -2514,8 +2534,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.45.0";
-declare const SDK_TAG: "@broberg/ai-sdk@0.45.0";
+declare const VERSION: "0.46.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.46.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.

package/dist/index.js

@@ -1836,11 +1836,14 @@ function azureAdapter(config = {}) {
     }
     return classifyRegionName(region());
   }
-  function sttBaseUrl() {
-    if (config.sttBaseUrl) return config.sttBaseUrl.replace(/\/$/, "");
+  function sttHost() {
+    if (config.sttBaseUrl) return { url: config.sttBaseUrl.replace(/\/$/, ""), source: "explicit" };
     const resource = config.resource ?? process.env.AZURE_SPEECH_RESOURCE;
-    if (resource) return `https://${resource}.cognitiveservices.azure.com`;
-    return `https://${region()}.api.cognitive.microsoft.com`;
+    if (resource) return { url: `https://${resource}.cognitiveservices.azure.com`, source: "resource" };
+    return { url: `https://${region()}.api.cognitive.microsoft.com`, source: "regional-fallback" };
+  }
+  function sttBaseUrl() {
+    return sttHost().url;
   }
   function priceFor(chars, model) {
     const usage = freshUsage({
@@ -1874,6 +1877,7 @@ function azureAdapter(config = {}) {
   async function tts(req) {
     if (req.wordTimings) return ttsBatch(req);
     const format = req.format ?? DEFAULT_FORMAT;
+    const ssml = buildSsml(req);
     const res = await fetchImpl(
       `https://${region()}.tts.speech.microsoft.com/cognitiveservices/v1`,
       {
@@ -1883,7 +1887,7 @@ function azureAdapter(config = {}) {
           "Content-Type": "application/ssml+xml",
           "X-Microsoft-OutputFormat": format
         },
-        body: buildSsml(req)
+        body: ssml
       }
     );
     if (!res.ok) {
@@ -1891,10 +1895,17 @@ function azureAdapter(config = {}) {
       throw new Error(`azure tts ${res.status}: ${body.slice(0, 300)}`);
     }
     const audio = new Uint8Array(await res.arrayBuffer());
-    return { audio, mimeType: "audio/mpeg", usage: priceFor(req.text.length, req.spec.model) };
+    return { audio, mimeType: "audio/mpeg", ssml, usage: priceFor(req.text.length, req.spec.model) };
   }
   async function ttsBatch(req) {
-    const host = sttBaseUrl();
+    const ssml = buildSsml(req);
+    const picked = sttHost();
+    if (picked.source === "regional-fallback") {
+      throw new Error(
+        `azure batch synthesis (wordTimings) needs the resource's custom subdomain, not the regional host ${picked.url}. Set AZURE_SPEECH_RESOURCE (or config.resource) to your Speech resource name so the call goes to {resource}.cognitiveservices.azure.com, and make sure custom subdomain is enabled on that resource. Azure answers 401 here with a VALID key, and its message blames the key \u2014 measured by cms 11 September 2026.`
+      );
+    }
+    const host = picked.url;
     const api = "api-version=2024-04-01";
     const id = `wt-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
     const headers = { "Ocp-Apim-Subscription-Key": key(), "Content-Type": "application/json" };
@@ -1903,7 +1914,7 @@ function azureAdapter(config = {}) {
       headers,
       body: JSON.stringify({
         inputKind: "SSML",
-        inputs: [{ content: buildSsml(req) }],
+        inputs: [{ content: ssml }],
         properties: {
           wordBoundaryEnabled: true,
           // ONE audio file and ONE word list for the whole text. Without it a chunked
@@ -1963,6 +1974,7 @@ function azureAdapter(config = {}) {
       // Batch defaults to riff PCM, not mp3 — saying audio/mpeg here would be a lie the
       // browser would act on.
       mimeType: req.format?.includes("mp3") ? "audio/mpeg" : "audio/wav",
+      ssml,
       // Aligned against the ORIGINAL text, with the dictionary, so the offsets index the
       // manuscript rather than the SSML we sent.
       wordTimings: alignWordTimings(req.text, boundaries, { pronunciations: req.pronunciations }),
@@ -3325,8 +3337,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.45.0";
-var SDK_TAG = "@broberg/ai-sdk@0.45.0";
+var VERSION = "0.46.0";
+var SDK_TAG = "@broberg/ai-sdk@0.46.0";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {