@ai-matrx/media 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @ai-matrx/media
 
+## 0.15.0 — THE one speech engine (`/speech`) + ReadAloudButton compact size
+
+- New `@ai-matrx/media/speech`: `speak()`, the app-wide playback queue (`enqueuePlayback`,
+  `pausePlayback`, `resumePlayback`, `skipPlayback`, `playPlaybackItem`, `removePlaybackItem`,
+  `clearPlayback`, `subscribePlayback`, …), the playback lock (`claimPlayback` / `releasePlayback`),
+  the Cartesia streaming lane (`connectCartesiaTts`, `cartesiaAdapter`, `ProviderSessionError`),
+  `SinkAwarePlayer` + output-device routing, and the iOS/WebKit unlock (`primeAudioOutput`,
+  `installAudioUnlockListeners`) — moved from matrx-frontend's audio system, which is the reference.
+  A host wires it once: `configureSpeech({ getCartesiaToken, resolveVoiceSettings,
+  reportProviderFailure?, notifyError?, beforeStart?, describeStartRefusal?, onEngage?, adapters?,
+  defaultEngine?, completeRequest?, resolvePronunciations?, invalidateCartesiaToken? })`.
+- `@ai-matrx/media/react`: `useSpeech`, `useReadAloud(text)` (the read-aloud button's whole wiring:
+  `status`, `error`, `onPress`), `usePlaybackSnapshot`, `readAloudStatusOf` — over the same queue
+  instance (`/react` imports `/speech`, never a bundled copy).
+- New dependency `@cartesia/cartesia-js` ^4.2.0.
+- Consumer action: delete the app's own queue / lock / Cartesia connection / player / unlock and
+  import them from `/speech`; call `configureSpeech` once at start-up.
+
+- `ReadAloudButton` `size?: "default" | "compact"` (`ReadAloudButtonSize` exported): "compact" is the
+  message-footer cell (32px box, 28px pill — the tap system's group geometry) instead of the 38px
+  default box. Geometry only; it wins over `variant`.
+- Consumer action: a message footer that drew the old 24px speaker passes `size="compact"`.
+
+## 0.14.0 — Read-aloud lives here (speech text, languages, button, language picker)
+
+- `@ai-matrx/media/voices`: `parseMarkdownToText` (+ `normalizeSpeechAbbreviations`,
+  `normalizeSpeechBlanks`, `COMMON_ABBREVIATION_EXPANSIONS`, `SpeechPronunciation`) — THE one
+  markdown → spoken-text conversion (tables read as a sentence, initialisms letter by letter,
+  pronunciations), moved from matrx-frontend; `READ_ALOUD_LANGUAGES` / `readAloudLanguage` — the
+  website's 15 voice languages plus the extension's Persian, each with its own name.
+- `@ai-matrx/media/react`: `ReadAloudButton` (one look for idle / connecting / playing / paused /
+  failed; the host's engine reports `status` and handles `onPress`) and
+  `ReadAloudLanguagePicker` (controlled quick picker).
+- New sibling deps: `@ai-matrx/content-ir` (table + code-span rules), `@ai-matrx/tap-target`.
+- Consumer action: replace an app copy of the speech parser / speaker button / language picker
+  with these; render `ReadAloudButton` inside a `TooltipProvider` (every app shell has one).
+
 
 
 ## 0.13.0 — DB types come from @ai-matrx/data/types

package/dist/react.cjs

@@ -56,6 +56,8 @@ __export(react_exports, {
   PenToolIcon: () => PenToolIcon,
   PlayIcon: () => PlayIcon,
   PlusIcon: () => PlusIcon,
+  ReadAloudButton: () => ReadAloudButton,
+  ReadAloudLanguagePicker: () => ReadAloudLanguagePicker,
   SearchIcon: () => SearchIcon,
   Settings2Icon: () => Settings2Icon,
   Share2Icon: () => Share2Icon,
@@ -68,7 +70,11 @@ __export(react_exports, {
   VolumeXIcon: () => VolumeXIcon,
   XIcon: () => XIcon,
   cn: () => cn,
-  useMediaDropzone: () => useMediaDropzone
+  readAloudStatusOf: () => readAloudStatusOf,
+  useMediaDropzone: () => useMediaDropzone,
+  usePlaybackSnapshot: () => usePlaybackSnapshot,
+  useReadAloud: () => useReadAloud,
+  useSpeech: () => useSpeech
 });
 module.exports = __toCommonJS(react_exports);
 
@@ -2531,4 +2537,198 @@ function MediaLightbox({
     }
   );
 }
+
+// src/react/read-aloud-button.tsx
+var import_buttons = require("@ai-matrx/tap-target/buttons");
+var import_jsx_runtime9 = require("react/jsx-runtime");
+function ReadAloudButton({
+  status,
+  onPress,
+  error,
+  disabled = false,
+  variant: requestedVariant,
+  size = "default",
+  className,
+  label = "Read aloud"
+}) {
+  const variant = size === "compact" ? "group" : requestedVariant;
+  if (status === "playing") {
+    return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(import_buttons.PauseTapButton, { variant, onClick: onPress, disabled, ariaLabel: "Pause", className });
+  }
+  if (status === "error") {
+    return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+      import_buttons.TriangleAlertTapButton,
+      {
+        variant,
+        onClick: onPress,
+        disabled,
+        ariaLabel: error || "Read aloud failed. Press to try again.",
+        className
+      }
+    );
+  }
+  const loading = status === "loading";
+  return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+    import_buttons.Volume2TapButton,
+    {
+      variant,
+      onClick: onPress,
+      disabled: disabled || loading,
+      ariaLabel: loading ? "Connecting\u2026" : status === "paused" ? "Resume" : label,
+      className
+    }
+  );
+}
+
+// src/react/use-speech.ts
+var import_react17 = require("react");
+var import_speech = require("@ai-matrx/media/speech");
+var cached = (0, import_speech.getPlaybackSnapshot)();
+function subscribe(onChange) {
+  return (0, import_speech.subscribePlayback)((snapshot) => {
+    cached = snapshot;
+    onChange();
+  });
+}
+var read = () => cached;
+function usePlaybackSnapshot() {
+  return (0, import_react17.useSyncExternalStore)(subscribe, read, read);
+}
+function useSpeech({ adoptText, ...request } = {}) {
+  const { items, currentId } = usePlaybackSnapshot();
+  const [itemId, setItemId] = (0, import_react17.useState)(null);
+  const adoptedId = !itemId && adoptText && currentId ? items.find(
+    (i) => i.id === currentId && i.text === adoptText && (i.status === "playing" || i.status === "paused" || i.status === "loading")
+  )?.id ?? null : null;
+  const effectiveId = itemId ?? adoptedId;
+  const { engine, voice, purpose, processMarkdown = true, label, dictionarySurfaceKey, language, speed } = request;
+  const speak = (0, import_react17.useCallback)(
+    (text) => {
+      const { id } = (0, import_speech.speak)({
+        text,
+        engine,
+        voice,
+        purpose,
+        processMarkdown,
+        label,
+        dictionarySurfaceKey,
+        language,
+        speed
+      });
+      setItemId(id);
+      return id;
+    },
+    [engine, voice, purpose, processMarkdown, label, dictionarySurfaceKey, language, speed]
+  );
+  const item = effectiveId ? items.find((i) => i.id === effectiveId) : void 0;
+  const status = item?.status ?? null;
+  return {
+    speak,
+    status,
+    error: item?.error ?? null,
+    itemId,
+    isMine: effectiveId !== null && effectiveId === currentId,
+    pause: import_speech.pausePlayback,
+    resume: import_speech.resumePlayback,
+    skip: import_speech.skipPlayback,
+    remove: import_speech.removePlaybackItem,
+    playItem: import_speech.playPlaybackItem
+  };
+}
+function readAloudStatusOf(status) {
+  if (status === "playing") return "playing";
+  if (status === "paused") return "paused";
+  if (status === "loading" || status === "queued") return "loading";
+  if (status === "error") return "error";
+  return "idle";
+}
+function useReadAloud(text, options = {}) {
+  const { speak, status, error, pause, resume } = useSpeech({ adoptText: text, ...options });
+  const state = readAloudStatusOf(status);
+  const onPress = (0, import_react17.useCallback)(() => {
+    if (state === "loading") return;
+    if (state === "playing") void pause();
+    else if (state === "paused") void resume();
+    else if (text.trim()) speak(text);
+  }, [state, text, speak, pause, resume]);
+  return { status: state, error, onPress, speak };
+}
+
+// src/react/read-aloud-language-picker.tsx
+var import_design_system = require("@ai-matrx/design-system");
+var import_lucide_react = require("lucide-react");
+var import_react18 = require("react");
+
+// src/voices/read-aloud-languages.ts
+var READ_ALOUD_LANGUAGES = [
+  { code: "en", englishName: "English", nativeName: "English" },
+  { code: "es", englishName: "Spanish", nativeName: "Espa\xF1ol" },
+  { code: "fr", englishName: "French", nativeName: "Fran\xE7ais" },
+  { code: "de", englishName: "German", nativeName: "Deutsch" },
+  { code: "it", englishName: "Italian", nativeName: "Italiano" },
+  { code: "pt", englishName: "Portuguese", nativeName: "Portugu\xEAs" },
+  { code: "zh", englishName: "Chinese", nativeName: "\u4E2D\u6587" },
+  { code: "ja", englishName: "Japanese", nativeName: "\u65E5\u672C\u8A9E" },
+  { code: "ko", englishName: "Korean", nativeName: "\uD55C\uAD6D\uC5B4" },
+  { code: "ru", englishName: "Russian", nativeName: "\u0420\u0443\u0441\u0441\u043A\u0438\u0439" },
+  { code: "hi", englishName: "Hindi", nativeName: "\u0939\u093F\u0928\u094D\u0926\u0940" },
+  { code: "nl", englishName: "Dutch", nativeName: "Nederlands" },
+  { code: "pl", englishName: "Polish", nativeName: "Polski" },
+  { code: "sv", englishName: "Swedish", nativeName: "Svenska" },
+  { code: "tr", englishName: "Turkish", nativeName: "T\xFCrk\xE7e" },
+  { code: "fa", englishName: "Persian", nativeName: "\u0641\u0627\u0631\u0633\u06CC" }
+];
+function readAloudLanguage(code) {
+  return READ_ALOUD_LANGUAGES.find((l) => l.code === code) ?? READ_ALOUD_LANGUAGES[0];
+}
+
+// src/react/read-aloud-language-picker.tsx
+var import_jsx_runtime10 = require("react/jsx-runtime");
+function ReadAloudLanguagePicker({ value, onChange, className }) {
+  const [open, setOpen] = (0, import_react18.useState)(false);
+  const selected = readAloudLanguage(value);
+  return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_design_system.Popover, { open, onOpenChange: setOpen, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(import_design_system.PopoverTrigger, { asChild: true, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
+      import_design_system.Button,
+      {
+        variant: "ghost",
+        size: "icon",
+        className: cn("size-7 text-muted-foreground", className),
+        title: `Voice language: ${selected.englishName}`,
+        "aria-label": `Voice language, currently ${selected.englishName}`,
+        children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(import_lucide_react.Languages, { className: "size-3.5" })
+      }
+    ) }),
+    /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_design_system.PopoverContent, { className: "max-h-80 w-56 overflow-y-auto p-1", align: "end", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("div", { className: "px-2.5 py-1.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground", children: "Voice language" }),
+      READ_ALOUD_LANGUAGES.map((option) => {
+        const isSelected = option.code === selected.code;
+        return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
+          "button",
+          {
+            type: "button",
+            role: "menuitemradio",
+            "aria-checked": isSelected,
+            onClick: () => {
+              onChange(option.code);
+              setOpen(false);
+            },
+            className: cn(
+              "flex w-full items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left transition-colors hover:bg-accent",
+              isSelected && "bg-accent"
+            ),
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("span", { className: "min-w-0 flex-1", children: [
+                /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { className: "block text-sm", children: option.nativeName }),
+                option.nativeName !== option.englishName ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("span", { className: "block text-[11px] text-muted-foreground", children: option.englishName }) : null
+              ] }),
+              isSelected ? /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(import_lucide_react.Check, { className: "size-3.5 shrink-0 text-primary" }) : null
+            ]
+          },
+          option.code
+        );
+      })
+    ] })
+  ] });
+}
 //# sourceMappingURL=react.cjs.map