@broberg/ai-sdk 0.45.1 → 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;
 }
 
@@ -2523,8 +2534,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.45.1";
-declare const SDK_TAG: "@broberg/ai-sdk@0.45.1";
+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

@@ -1877,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`,
       {
@@ -1886,7 +1887,7 @@ function azureAdapter(config = {}) {
           "Content-Type": "application/ssml+xml",
           "X-Microsoft-OutputFormat": format
         },
-        body: buildSsml(req)
+        body: ssml
       }
     );
     if (!res.ok) {
@@ -1894,9 +1895,10 @@ 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 ssml = buildSsml(req);
     const picked = sttHost();
     if (picked.source === "regional-fallback") {
       throw new Error(
@@ -1912,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
@@ -1972,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 }),
@@ -3334,8 +3337,8 @@ var aiConfigSchema = z.object({
 });
 
 // src/version.ts
-var VERSION = "0.45.1";
-var SDK_TAG = "@broberg/ai-sdk@0.45.1";
+var VERSION = "0.46.0";
+var SDK_TAG = "@broberg/ai-sdk@0.46.0";
 
 // src/cost/sinks/upmetrics.ts
 function upmetricsSink(config) {