Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: read replies aloud without markdown symbols (#12598)

Aziz Muminovf21633e117de
diff --git a/studio/frontend/package-lock.json b/studio/frontend/package-lock.json
index 8c8dd512394..1d764d2288b 100644
--- a/studio/frontend/package-lock.json
+++ b/studio/frontend/package-lock.json
@@ -47,6 +47,7 @@
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"cmdk": "^1.1.1",
+ "decode-named-character-reference": "1.3.0",
"dexie": "^4.3.0",
"fflate": "0.8.3",
"js-yaml": "^4.3.2",
diff --git a/studio/frontend/package.json b/studio/frontend/package.json
index 4d1549e56d5..12a434f48ba 100644
--- a/studio/frontend/package.json
+++ b/studio/frontend/package.json
@@ -62,6 +62,7 @@
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"cmdk": "^1.1.1",
+ "decode-named-character-reference": "1.3.0",
"dexie": "^4.3.0",
"fflate": "0.8.3",
"js-yaml": "^4.3.2",
diff --git a/studio/frontend/src/features/chat/adapters/studio-speech-synthesis-adapter.ts b/studio/frontend/src/features/chat/adapters/studio-speech-synthesis-adapter.ts
index 74ac725bdcb..472a09dba75 100644
--- a/studio/frontend/src/features/chat/adapters/studio-speech-synthesis-adapter.ts
+++ b/studio/frontend/src/features/chat/adapters/studio-speech-synthesis-adapter.ts
@@ -9,6 +9,7 @@ import { encryptProviderApiKey } from "../api/providers-api";
import { getExternalProviderApiKey } from "../external-providers";
import { stripSearchImageTokens } from "../search-images/search-images";
import { useExternalProvidersStore } from "../stores/external-providers-store";
+import { markdownToSpeechText } from "../utils/speech-text";
/** Voice for a stored voiceURI. "default" resolves to the voice the platform marks as its
* default, so the "System default" choice means what it says instead of falling back to a
@@ -465,8 +466,7 @@ export class StudioSpeechSynthesisAdapter implements SpeechSynthesisAdapter {
}
speak(spokenText: string): SpeechSynthesisAdapter.Utterance {
- // Renderer markup: without this the reader says the token id out loud.
- const text = stripSearchImageTokens(spokenText);
+ const text = markdownToSpeechText(stripSearchImageTokens(spokenText));
const subscribers = new Set<() => void>();
const handleEnd = (
diff --git a/studio/frontend/src/features/chat/utils/speech-text.ts b/studio/frontend/src/features/chat/utils/speech-text.ts
new file mode 100644
index 00000000000..f5a72de712a
--- /dev/null
+++ b/studio/frontend/src/features/chat/utils/speech-text.ts
@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { decodeNamedCharacterReference } from "decode-named-character-reference";
+import type { Nodes, Root, RootContent } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { mathFromMarkdown } from "mdast-util-math";
+import { gfm } from "micromark-extension-gfm";
+import { math } from "micromark-extension-math";
+import { defaultRehypePlugins } from "streamdown";
+import { normalizeEscapedInlineMath } from "../../../lib/escaped-inline-math.ts";
+import { preprocessLaTeX } from "../../../lib/latex.ts";
+
+// Tags the chat renders; any other `<tag>` (`Vec<T>`, `<script>`) stays on the page as text.
+const SCHEMA_TAGS = new Set(
+ (defaultRehypePlugins.sanitize as [unknown, { tagNames?: string[] }])[1]
+ .tagNames,
+);
+// Elements that start a new line on the page; other schema tags join their text (`H<sub>2</sub>O`).
+const LINE_TAGS = new Set(
+ "br p div li ul ol dl dt dd tr table thead tbody tfoot blockquote pre hr section details summary h1 h2 h3 h4 h5 h6".split(
+ " ",
+ ),
+);
+
+/** The words a markdown reply shows, for read-aloud: voices speak raw markup ("asterisk asterisk", #12547). */
+export function markdownToSpeechText(markdown: string): string {
+ let root: Root;
+ try {
+ // Same preprocessing as the chat renderer, else "$5 and $10" parses as math and loses its "$".
+ root = fromMarkdown(preprocessLaTeX(normalizeEscapedInlineMath(markdown)), {
+ extensions: [gfm(), math({ singleDollarTextMath: true })],
+ mdastExtensions: [gfmFromMarkdown(), mathFromMarkdown()],
+ });
+ } catch {
+ return markdown;
+ }
+ const out: string[] = [];
+ const notes: string[] = [];
+ for (const node of root.children) {
+ // Footnotes render after the reply, so they are read there too.
+ collectBlocks(
+ node,
+ node.type === "footnoteDefinition" ? notes : out,
+ false,
+ );
+ }
+ return [...out, ...notes].filter((block) => block.length > 0).join("\n");
+}
+
+function collectBlocks(
+ node: RootContent,
+ out: string[],
+ inList: boolean,
+): void {
+ switch (node.type) {
+ case "paragraph":
+ out.push(inList ? sentence(inline(node)) : inline(node).trim());
+ return;
+ // Full stop = the pause the layout gives the eye; else lines run together when spoken.
+ case "heading":
+ out.push(sentence(inline(node)));
+ return;
+ case "code":
+ case "math":
+ out.push(node.value);
+ return;
+ case "table":
+ for (const row of node.children) {
+ out.push(sentence(row.children.map(inline).join(", ")));
+ }
+ return;
+ // The sanitizer unwraps raw HTML, so its text shows on the page.
+ case "html":
+ out.push(
+ htmlText(node.value)
+ .split("\n")
+ .map((line) => line.replace(/\s+/g, " ").trim())
+ .filter(Boolean)
+ .join("\n"),
+ );
+ return;
+ case "thematicBreak":
+ case "definition":
+ case "yaml":
+ return;
+ case "listItem":
+ for (const child of node.children) collectBlocks(child, out, true);
+ return;
+ default:
+ if ("children" in node) {
+ for (const child of node.children) {
+ collectBlocks(child as RootContent, out, inList);
+ }
+ }
+ }
+}
+
+function inline(node: Nodes): string {
+ switch (node.type) {
+ case "text":
+ case "inlineCode":
+ case "inlineMath":
+ return node.value;
+ case "break":
+ return "\n";
+ case "image":
+ case "imageReference":
+ return node.alt ?? "";
+ case "html":
+ return htmlText(node.value);
+ case "footnoteReference":
+ return "";
+ default:
+ return "children" in node ? node.children.map(inline).join("") : "";
+ }
+}
+
+function htmlText(html: string): string {
+ return html
+ .replace(/<!--[\s\S]*?-->/g, "")
+ .replace(
+ /<\/?([a-z][^\s/<>]*)(?:[^<>"']|"[^"]*"|'[^']*')*>/gi,
+ (tag, name: string) => {
+ const lower = name.toLowerCase();
+ if (!SCHEMA_TAGS.has(lower)) return tag;
+ if (lower === "td" || lower === "th") return " ";
+ return LINE_TAGS.has(lower) ? "\n" : "";
+ },
+ )
+ .replace(/&(#x[\da-f]+|#\d+|[a-z][a-z\d]*);/gi, (ref, body: string) => {
+ if (body[0] !== "#") return decodeNamedCharacterReference(body) || ref;
+ const hex = body[1] === "x" || body[1] === "X";
+ const code = Number.parseInt(body.slice(hex ? 2 : 1), hex ? 16 : 10);
+ return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : ref;
+ });
+}
+
+function sentence(text: string): string {
+ const trimmed = text.trim();
+ if (!trimmed || /[.!?:;,…]$/.test(trimmed)) return trimmed;
+ return `${trimmed}.`;
+}
diff --git a/studio/frontend/tests/read-aloud-studio-voice.test.ts b/studio/frontend/tests/read-aloud-studio-voice.test.ts
index 59ca2e6815e..d95315ad043 100644
--- a/studio/frontend/tests/read-aloud-studio-voice.test.ts
+++ b/studio/frontend/tests/read-aloud-studio-voice.test.ts
@@ -47,6 +47,9 @@ function load(
"../search-images/search-images": {
stripSearchImageTokens: (text: string) => text,
},
+ "../utils/speech-text": {
+ markdownToSpeechText: (text: string) => text,
+ },
"../stores/external-providers-store": {
useExternalProvidersStore: { getState: () => ({}) },
},
diff --git a/studio/frontend/tests/speech-text.test.ts b/studio/frontend/tests/speech-text.test.ts
new file mode 100644
index 00000000000..9e392f9c4e1
--- /dev/null
+++ b/studio/frontend/tests/speech-text.test.ts
@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { markdownToSpeechText } from "../src/features/chat/utils/speech-text.ts";
+
+test("read-aloud does not speak emphasis markers (#12547)", () => {
+ assert.equal(
+ markdownToSpeechText(
+ "This is **bold**, *italic*, __also bold__ and ~~gone~~.",
+ ),
+ "This is bold, italic, also bold and gone.",
+ );
+});
+
+test("headings, bullets and numbered items lose their symbols but keep a pause", () => {
+ const spoken = markdownToSpeechText(
+ "## Steps\n\n- Install the package\n- Run `unsloth studio`\n\n1. First\n2. Second!",
+ );
+ assert.equal(
+ spoken,
+ "Steps.\nInstall the package.\nRun unsloth studio.\nFirst.\nSecond!",
+ );
+ assert.doesNotMatch(spoken, /[#*`]|^\s*[-\d]/m);
+});
+
+test("links and images read as their text, not their URLs", () => {
+ assert.equal(
+ markdownToSpeechText(
+ "See [the docs](https://unsloth.ai/docs) and ![a cat](cat.png).",
+ ),
+ "See the docs and a cat.",
+ );
+});
+
+test("code keeps its content but drops the fences", () => {
+ assert.equal(
+ markdownToSpeechText("Run this:\n\n```bash\npip install unsloth\n```"),
+ "Run this:\npip install unsloth",
+ );
+});
+
+test("blockquotes, rules, tables and html are read as plain text", () => {
+ assert.equal(
+ markdownToSpeechText(
+ "> quoted **line**\n\n---\n\n| Model | Size |\n| --- | --- |\n| Qwen | 7B |\n\n<br>",
+ ),
+ "quoted line\nModel, Size.\nQwen, 7B.",
+ );
+});
+
+test("math is read from its source and plain text passes through unchanged", () => {
+ assert.equal(
+ markdownToSpeechText("Euler: $e^{i\\pi}+1=0$"),
+ "Euler: e^{i\\pi}+1=0",
+ );
+ assert.equal(markdownToSpeechText("Just a sentence."), "Just a sentence.");
+ assert.equal(
+ markdownToSpeechText("It costs $5 and $10 today."),
+ "It costs $5 and $10 today.",
+ );
+ assert.equal(markdownToSpeechText("Inline \\(x^2\\)"), "Inline x^2");
+ assert.equal(markdownToSpeechText(""), "");
+});
+
+test("text inside raw HTML and footnotes is read, as the page shows it", () => {
+ assert.equal(
+ markdownToSpeechText(
+ "<details><summary>More</summary>\n\nHidden <b>text</b>\n\n</details>\n\nSee note[^1].\n\n[^1]: The note.\n\nEnd.",
+ ),
+ "More\nHidden text\nSee note.\nEnd.\nThe note.",
+ );
+ assert.equal(
+ markdownToSpeechText("<div>Visible answer</div>\n<!-- note -->"),
+ "Visible answer",
+ );
+});
+
+test("tags the page shows as text are read, and entities read as their characters", () => {
+ assert.equal(
+ markdownToSpeechText("Use <placeholder> here, a Vec<T>, and <b>bold</b>."),
+ "Use <placeholder> here, a Vec<T>, and bold.",
+ );
+ assert.equal(
+ markdownToSpeechText("<div>AT&amp;T &lt; 5 &#33; &#x41;</div>"),
+ "AT&T < 5 ! A",
+ );
+});
+
+test("raw HTML reads as the chat shows it: quoted attributes, literal tags, named entities", () => {
+ assert.equal(
+ markdownToSpeechText('<div aria-label="a > b">visible</div>'),
+ "visible",
+ );
+ assert.equal(
+ markdownToSpeechText(
+ "<div>The <small> tag and <script>alert(1)</script></div>",
+ ),
+ "The <small> tag and <script>alert(1)</script>",
+ );
+ assert.equal(
+ markdownToSpeechText("<div>caf&eacute; &copy; &hellip;</div>"),
+ "café © …",
+ );
+});
+
+test("HTML tags keep the word boundaries the page shows", () => {
+ assert.equal(markdownToSpeechText("hello<br>world"), "hello\nworld");
+ assert.equal(
+ markdownToSpeechText("| a<br>b | c |\n|---|---|\n| 1 | 2 |"),
+ "a\nb, c.\n1, 2.",
+ );
+ assert.equal(markdownToSpeechText("<div>H<sub>2</sub>O</div>"), "H2O");
+});
diff --git a/studio/frontend/tests/tts-custom-connections-disabled.test.ts b/studio/frontend/tests/tts-custom-connections-disabled.test.ts
index 525d63339ca..2ffb9b693c4 100644
--- a/studio/frontend/tests/tts-custom-connections-disabled.test.ts
+++ b/studio/frontend/tests/tts-custom-connections-disabled.test.ts
@@ -12,6 +12,7 @@ import { loadWithStubs } from "./helpers/module-stubs.ts";
import { readSrc } from "./helpers/kit.ts";
type Adapter = {
+ StudioSpeechSynthesisAdapter: new () => { speak: (text: string) => unknown };
generateCustomTtsAudio: (
text: string,
signal?: AbortSignal,
@@ -44,12 +45,14 @@ function load(
voice = "af_sky",
encrypt = async (key: string) => `enc(${key})`,
beforeAuthenticatedRetry,
+ toSpeech = (text: string) => text,
}: {
providers?: StubProvider[];
legacyKey?: string;
voice?: string;
encrypt?: (key: string) => Promise<string>;
beforeAuthenticatedRetry?: () => void;
+ toSpeech?: (text: string) => string;
} = {},
): {
adapter: Adapter;
@@ -89,6 +92,9 @@ function load(
"../search-images/search-images": {
stripSearchImageTokens: (text: string) => text,
},
+ "../utils/speech-text": {
+ markdownToSpeechText: toSpeech,
+ },
"../stores/external-providers-store": {
useExternalProvidersStore: {
getState: () => ({
@@ -160,6 +166,15 @@ test("custom TTS defaults a blank voice for strict OpenAI-compatible endpoints",
assert.equal(JSON.parse(posted[0]).voice, "alloy");
});
+test("read-aloud sends the speech text, not the markdown source (#12547)", async () => {
+ const { adapter, posted } = load(true, {
+ toSpeech: (text) => `spoken(${text})`,
+ });
+ new adapter.StudioSpeechSynthesisAdapter().speak("**Done.**");
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ assert.equal(JSON.parse(posted[0]).messages[0].content, "spoken(**Done.**)");
+});
+
test("custom TTS rejects a deleted provider even when Voice settings is unmounted", async () => {
const { adapter, posted, clearedProviderIds } = load(true, { providers: [] });
await assert.rejects(