@usercase/mcp 0.2.11-next.0 → 0.2.11-next.1

package/mcp/hub.js

@@ -25,6 +25,7 @@ const ws = require("./workspace.js");
 const signin = require("../src/browser/signin.js");
 const { openRealChrome } = require("../src/browser/real-chrome.js");
 const study = require("../src/browser/study.js");
+const voice = require("../src/browser/voice.js");
 const report = require("./report.js");
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -49,7 +50,9 @@ function trace(rec, o) {
     fs.appendFileSync(TRACE, JSON.stringify({ at: Date.now(), person: rec && rec.person ? rec.person.id : null, ...o }) + "\n");
   } catch {}
 }
-const STUDY_ACTIVE = new Set(["consent", "loading", "testing", "timeout", "survey", "next", "submit"]);
+/** 음성 설문이 끝나고 위젯이 간 곳 — 여기면 마지막 말은 인사다 */
+const VOICE_OVER = new Set(["testing", "next", "submit", "loading", "done", "complete", "idle"]);
+const STUDY_ACTIVE = new Set(["consent", "mic", "loading", "testing", "timeout", "survey", "ai", "next", "submit"]);
 
 /**
  * 가상 사용자 표시 이름. 서버가 이 이름으로 가상 사용자 답을 진짜 답과 갈라 센다
@@ -459,7 +462,7 @@ class Hub {
     const sdk = await rec.visit.begin();
     // 리서치 참여 — 초대 수락·녹화 동의까지는 참여하기로 한 사람이 늘 하는 것이라 도구가 한다
     if (research) {
-      rec.study = { research, answers: [], tasks: [], skipped: [], lastTask: null, over: false, surveyAt: null };
+      rec.study = { research, answers: [], tasks: [], skipped: [], lastTask: null, over: false, surveyAt: null, heardFrom: 0 };
       const j = await study.join(page);
       if (!j.ok) {
         await this.finish(rec, { study: { research, failed: j.why } });
@@ -482,6 +485,11 @@ class Hub {
         "You agreed to take part, so you stay with the study until its tasks are done — you do not leave the site in the middle of it over a small thing. The study may ask you a few questions along the way; answer them with answer_card.",
         "If you get stuck on a task, do what a person does: keep looking for it — try other menus and pages, go back, scroll through lists, try what you have not tried yet. Studies usually offer a way to give up on a task after a while; when the panel offers it and you would give up, take it and go on to the next task. Leave in the middle only if you really would — something about you or your moment makes you stop.",
       );
+    // AI 모더레이터 리서치 — 마이크를 받아 갔다(voice.js). 목소리가 말을 걸고, 방문자는 소리 내어 답한다
+    if (research && (await page.evaluate(() => !!(window.__ucVoice && window.__ucVoice.used())).catch(() => false)))
+      lines.push(
+        "This study has a voice: you allowed your microphone, and a voice may talk to you during the study (you see its words as a caption). When it asks you something, you answer out loud — with answer_card.",
+      );
     if (!sdk.ready) lines.push("(note for whoever runs this: the Usercase SDK did not start on this page — this visit may not be recorded)");
     lines.push("", await this.screen(rec));
     return { id, text: lines.join("\n") };
@@ -558,6 +566,17 @@ class Hub {
         await study.waitState(page, ["testing", "survey", "submit", "done"], 15000);
         continue;
       }
+      // AI 모더레이터가 소리로 묻는 중(음성 후속설문). 물음이 들리면 방문자가 소리 내어 답한다
+      if (s.state === "ai") {
+        const q = await this.voiceQuestion(rec);
+        if (q) {
+          rec.studyPending = { kind: "voice", q, task: st.lastTask };
+          return { card: renderVoiceQuestion(q, st.lastTask) };
+        }
+        s = study.isSurveyUrl(page.url()) ? null : await study.readStudy(page);
+        if (!s || s.state === "ai") break;
+        continue;
+      }
       if (s.state === "submit" || s.state === "loading") {
         await study.waitState(page, ["done", "complete", "testing", "survey", "next", "idle", "invite"], 120000);
         continue;
@@ -581,6 +600,14 @@ class Hub {
       }
       st.lastTaskKey = key;
       st.lastTask = s.task.title;
+      // 과제 중에 모더레이터가 한 말(음성 리서치) — 사람도 듣는다
+      // 아직 말하는 중인 줄은 다음 화면에서 — 자막이 늘어나며 이어지는 동안 읽으면 말이 반쯤 잘린다
+      const h = await voice.heard(page, st.heardFrom);
+      if (h && h.closed) {
+        st.heardFrom += h.closed;
+        const said = `(The study's voice said: ${h.lines.slice(0, h.closed).map((l) => `"${l.text}"`).join(" ")})`;
+        note = note ? `${note}\n${said}` : said;
+      }
       // 패널에는 지금 과제에 머문 시간이 보인다(SDK 알약의 타이머) — 방문자도 같은 걸 본다
       const onTaskMs = Date.now() - rec.startedAt - st.tasks[st.tasks.length - 1].at;
       st.canSkip = !!s.task.skip;
@@ -602,6 +629,55 @@ class Hub {
     return null;
   }
 
+  /**
+   * 모더레이터가 소리로 묻는 것(자막). 아직 답하지 않은 새 말이 들릴 때까지 기다린다 — 말이 이어지면 다 들은 뒤.
+   * 위젯이 묻는 상태(ai)를 벗어나거나 한참 조용하면 null
+   */
+  async voiceQuestion(rec, ms = 25000) {
+    const st = rec.study;
+    const page = rec.page;
+    let h = null;
+    for (let t = 0; t < ms; t += 300) {
+      h = await voice.heard(page, st.heardFrom);
+      if (!h) return null;
+      // 설문 전에(과제 중에) 한 말은 묻는 말이 아니다 — 지나간다. 안 그러면 인사에 답하고 답이 한 칸씩 밀린다(11/04 실험실)
+      let skip = 0;
+      while (skip < h.lines.length && h.lines[skip].state !== "ai" && (skip < h.closed || !h.speaking)) skip++;
+      if (skip) {
+        if (TRACE) trace(rec, { ev: "voice_skip", lines: h.lines.slice(0, skip).map((l) => `${l.state}: ${l.text.slice(0, 80)}`) });
+        st.heardFrom += skip;
+        h = await voice.heard(page, st.heardFrom);
+        if (!h) return null;
+      }
+      if (h.lines.length && h.lines[0].state === "ai") break;
+      const s = await study.readStudy(page);
+      if (!s || s.state !== "ai") return null;
+      await sleep(300);
+    }
+    if (!h || !h.lines.length || h.lines[0].state !== "ai") return null;
+    // 말을 다 들을 때까지(자막이 내려갈 때까지). 서버는 질문을 말하기 시작할 때부터 답을 기다리니 너무 오래는 못 듣는다
+    for (let t = 0; t < 10000 && h.speaking; t += 300) {
+      await sleep(300);
+      h = (await voice.heard(page, st.heardFrom)) || h;
+    }
+    // 마지막 인사("고마워요")로 설문이 끝나면 위젯이 곧 묻는 상태를 벗어난다 — 그건 답할 말이 아니다
+    // 끝났다고 보는 건 위젯이 분명히 다음으로 간 때만 — 못 읽었거나 잠깐 바뀌는 중이면 묻는 말로 둔다.
+    // "아니면 끝" 으로 봤더니 진짜 질문을 넘겨 서버가 답 없이 다음으로 갔다(11/04 실험실 p2132)
+    let after = null;
+    for (let t = 0; t < 1500; t += 300) {
+      await sleep(300);
+      after = await study.readStudy(page);
+      if (after && VOICE_OVER.has(after.state)) break;
+    }
+    const text = h.lines.map((l) => l.text).join(" ");
+    if (TRACE) trace(rec, { ev: "voice_q", text: text.slice(0, 120), after: after ? after.state : null });
+    if (after && VOICE_OVER.has(after.state)) {
+      st.heardFrom = h.total;
+      return null;
+    }
+    return { text, upTo: h.total };
+  }
+
   /** 과제 질문·시간 초과 창에 답한다. 참여하기로 한 사람이라 닫지 않는다 — 비워 두고 넘기는 건 된다(필수가 아니면) */
   async studyAnswer(rec, decision) {
     const p = rec.studyPending;
@@ -610,6 +686,31 @@ class Hub {
     // 손이 고른 답으로 가는 시간. 읽고 정하는 건 AI 가 이미 했다(11/02: 1.2~3.7초를 또 기다렸다)
     await sleep(300 + Math.random() * 500);
     let said;
+    if (p.kind === "voice") {
+      // 소리 내어 답한다. 모더레이터가 말을 마칠 때까지 기다린다 — 끼어들지 않는다
+      st.heardFrom = p.q.upTo;
+      const words = decision.action === "other" ? String(decision.otherText || "").trim() : "";
+      for (let t = 0; t < 20000; t += 300) {
+        const h = await voice.heard(page, st.heardFrom);
+        if (!h || !h.speaking) break;
+        await sleep(300);
+      }
+      let answer = null;
+      if (words) {
+        try {
+          await voice.speak(page, words, { seed: rec.person.id });
+          answer = words;
+          said = `You said: "${words}"`;
+        } catch (e) {
+          said = `You tried to answer out loud, but no sound came out (${String(e.message).split("\n")[0]}).`;
+        }
+      } else said = "You stayed quiet and did not answer.";
+      st.answers.push({ task: p.task, question: p.q.text, answer, why: decision.why, spoken: true });
+      rec.studyPending = null;
+      rec.visit.history.push(`The study's voice asked "${p.q.text}" — ${said}`);
+      await sleep(600);
+      return [said, "", await this.screen(rec)].join("\n");
+    }
     if (p.kind === "timeout") {
       const skip = decision.action === "choose" && decision.choiceIndex === 1;
       await study.press(page, skip ? "timeoutSkip" : "keepGoing").catch(() => {});
@@ -1062,6 +1163,18 @@ function renderStudyQuestion(q, task) {
   return L.join("\n");
 }
 
+/** AI 모더레이터가 소리로 묻는다(음성 리서치) */
+function renderVoiceQuestion(q, task) {
+  return [
+    "## The study's voice is asking you something, out loud",
+    `This is part of the study you agreed to take part in${task ? ` (it comes after the task "${task}")` : ""}. A voice speaks to you, and its words show as a caption:`,
+    "",
+    `"${q.text}"`,
+    "",
+    "Answer out loud, as yourself, with answer_card: bothered true, action other, and in other_text exactly what you say — spoken words in the language of the voice, the way this person talks, in one go (a short pause ends your answer). It waits for you only a few seconds, so answer right away. Close only if you would stay quiet.",
+  ].join("\n");
+}
+
 /** 과제에 시간이 오래 걸리면 패널이 묻는다 */
 function renderStudyTimeout(t, task) {
   return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.11-next.0",
+  "version": "0.2.11-next.1",
   "description": "Virtual users that browse your website and tell you what they thought — an MCP server for Claude Code",
   "license": "UNLICENSED",
   "homepage": "https://usercase.io",

package/src/browser/open.js

@@ -11,6 +11,7 @@
  */
 
 const { markAgent, withAgentUA } = require("./card.js");
+const { installVoice } = require("./voice.js");
 
 /** HTTPS 사이트에서 localhost SDK·소켓을 부르려면 사설망 제한을 꺼야 한다. 로컬 SDK 로 돌릴 때만 필요하다 */
 const LOCAL_NETWORK_ARGS = ["--disable-features=LocalNetworkAccessChecks,PrivateNetworkAccessSendPreflights,PrivateNetworkAccessRespectPreflightResults"];
@@ -54,6 +55,8 @@ async function openVisit(browser, devices, { agent, site, guard, device = "deskt
   await guard.apply(ctx, { onOffsite, onWrite, onExternal });
   // **반드시 guard 뒤.** markAgent 의 비밀값 route 가 마지막에 걸려야 먼저 돈다
   await markAgent(ctx, agent, { siteOrigin: site, persona, research, debugCards, hideDevOverlay: guard.local });
+  // 리서치 참여자는 목소리를 가진다 — AI 모더레이터 리서치가 마이크를 달라면 우리 목소리를 준다(voice.js)
+  if (research) await installVoice(ctx);
   return ctx;
 }
 

package/src/browser/study.js

@@ -8,7 +8,8 @@
  * 질문에 무엇을 답하는지, 포기할지는 방문자가 정한다.
  *
  * 화면 구성(earningbirds-core layouts/Widget.ts · components/frost/*):
- *   #eb-pill[data-state] — idle·invite·consent·loading·testing·timeout·survey·next·submit·done …
+ *   #eb-pill[data-state] — idle·invite·consent·mic·loading·testing·timeout·survey·ai·next·submit·done …
+ *   mic: #eb-mic-start(음성 리서치의 마이크 확인) · ai: AI 모더레이터가 소리로 묻는 중(자막은 voice.js 가 읽는다)
  *   #eb-frost(.eb-visible 이면 열림) > #eb-frost-body
  *   testing: .eb-frost-testing .eb-gf-section(진행) .eb-gf-flat-title(과제) .eb-gf-flat-sub(설명) #eb-task-lefttime-text #eb-test-skip
  *   timeout: .eb-frost-timeout #eb-timeout-continue #eb-timeout-skip
@@ -152,7 +153,21 @@ async function join(page, { inviteMs = 25000 } = {}) {
     await sleep(1500 + Math.random() * 2500);
     await page.locator("#eb-plugin #eb-consent-agree").click({ timeout: 5000 }).catch(() => {});
   }
-  const s = await waitState(page, ["testing", "survey", "done"], 40000);
+  let s = await waitState(page, ["mic", "testing", "survey", "done"], 40000);
+  // AI 모더레이터(음성) 리서치는 동의 뒤 마이크 확인 화면이 있다. 마이크는 voice.js 가 준 우리 목소리다 —
+  // 연결됐다고 뜨면 사람처럼 잠깐 보고 시작을 누른다. Gemini 를 여는 데 시간이 걸려 시작까지 넉넉히 기다린다
+  if (s && s.state === "mic") {
+    const ready = await page
+      .locator("#eb-plugin #eb-mic-start:not([disabled])")
+      .first()
+      .waitFor({ timeout: 15000 })
+      .then(() => true)
+      .catch(() => false);
+    if (!ready) return { ok: false, why: "the study's microphone check did not accept the virtual user's microphone" };
+    await sleep(1200 + Math.random() * 1800);
+    await page.locator("#eb-plugin #eb-mic-start").first().click({ timeout: 5000 }).catch(() => {});
+    s = await waitState(page, ["testing", "survey", "done"], 60000);
+  }
   if (!s || s.state !== "testing") return { ok: false, why: `the research did not start (the study panel is at "${s ? s.state || "?" : "nothing"}")` };
   return { ok: true, study: s };
 }

package/src/browser/voice.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * 가상 사용자의 목소리 — AI 모더레이터(음성) 리서치에 참여할 때.
+ *
+ * 사람 참여자와 같은 길로 간다: SDK 는 마이크를 받고, 그 마이크로 들어온 소리를 Gemini·서버 음성 인식이 듣는다.
+ * - 귀: 모더레이터가 하는 말은 위젯 자막(.eb-ai-caption-text, core components/widget/Widget.ts)으로 뜬다. 그것을 읽는다
+ * - 입: 페이지의 마이크 요청(getUserMedia)이 진짜 마이크 대신 우리가 만든 오디오 줄(MediaStreamDestination)을 받는다.
+ *   할 말은 이 컴퓨터에 깔린 음성(Windows 음성 · macOS say · espeak)으로 wav 를 만들어 그 줄로 튼다 — 바깥 서비스·비용 없음
+ *
+ * 리서치 참여 방문에만 건다(open.js). 음성을 안 쓰는 리서치는 마이크를 부르지 않으니 아무 일도 없다.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFile } = require("child_process");
+
+/** 페이지가 뜨기 전에 심는다. 마이크·권한·장치 목록을 우리 오디오 줄로 바꾸고, 모더레이터 자막을 적어 둔다 */
+const PAGE_SCRIPT = `(() => {
+  if (window.__ucVoice) return;
+  const md = navigator.mediaDevices;
+  if (!md || !md.getUserMedia) return;
+  let ac = null;
+  let dest = null;
+  const line = () => {
+    if (!ac) {
+      ac = new (window.AudioContext || window.webkitAudioContext)();
+      dest = ac.createMediaStreamDestination();
+    }
+    if (ac.state === "suspended") ac.resume().catch(() => {});
+    return dest;
+  };
+  const MIC = { deviceId: "usercase-voice", groupId: "usercase-voice", kind: "audioinput", label: "Microphone" };
+  MIC.toJSON = () => ({ deviceId: MIC.deviceId, groupId: MIC.groupId, kind: MIC.kind, label: MIC.label });
+  const enumerate = md.enumerateDevices ? md.enumerateDevices.bind(md) : async () => [];
+  md.enumerateDevices = async () => {
+    const list = await enumerate().catch(() => []);
+    return [MIC, ...list.filter((d) => d.kind !== "audioinput")];
+  };
+  const gum = md.getUserMedia.bind(md);
+  md.getUserMedia = async (c) => {
+    if (c && c.audio && !c.video) {
+      const d = line();
+      // 받는 쪽이 트랙을 멈춰도(stop) 원본 줄은 살아 있게 복제해 준다
+      return new MediaStream(d.stream.getAudioTracks().map((t) => t.clone()));
+    }
+    return gum(c);
+  };
+  if (navigator.permissions && navigator.permissions.query) {
+    const query = navigator.permissions.query.bind(navigator.permissions);
+    navigator.permissions.query = (p) =>
+      p && p.name === "microphone"
+        ? Promise.resolve({ name: "microphone", state: "granted", onchange: null, addEventListener() {}, removeEventListener() {} })
+        : query(p);
+  }
+  // 모더레이터 자막. 보이는 동안이 말하는 동안이다. 글이 늘어나며 이어지면(스트리밍 자막) 한 줄로 친다
+  const heard = [];
+  let shownText = "";
+  let speaking = false;
+  setInterval(() => {
+    const host = document.getElementById("eb-plugin");
+    const root = (host && host.shadowRoot) || document;
+    const box = root.querySelector(".eb-ai-caption.eb-ai-caption-visible .eb-ai-caption-text");
+    const t = box ? (box.innerText || box.textContent || "").replace(/\\s+/g, " ").trim() : "";
+    speaking = !!t;
+    if (!t || t === shownText) return;
+    // 그 말이 나올 때 위젯 상태 — ai 면 소리로 묻는 설문(답을 기다린다), 그 밖(과제 중)은 그냥 하는 말이다
+    const pill = root.querySelector("#eb-pill");
+    const state = (pill && pill.getAttribute("data-state")) || "";
+    const last = heard[heard.length - 1];
+    if (last && shownText && t.startsWith(shownText)) {
+      last.text = t;
+      last.at = Date.now();
+    } else heard.push({ n: heard.length, text: t, at: Date.now(), state });
+    shownText = t;
+  }, 200);
+  window.__ucVoice = {
+    used: () => !!ac,
+    // closed: 다 말한 줄 수(from 부터). 말하는 중인 마지막 줄은 아직 늘어날 수 있다
+    heard: (from) => {
+      const lines = heard.slice(from || 0);
+      return { speaking, lines, total: heard.length, closed: speaking && lines.length ? lines.length - 1 : lines.length };
+    },
+    say: async (b64) => {
+      const d = line();
+      if (ac.state !== "running") await ac.resume().catch(() => {});
+      const bin = atob(b64);
+      const buf = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) buf[i] = bin.charCodeAt(i);
+      const audio = await ac.decodeAudioData(buf.buffer);
+      const src = ac.createBufferSource();
+      src.buffer = audio;
+      src.connect(d);
+      await new Promise((r) => {
+        src.onended = r;
+        src.start();
+      });
+      return audio.duration;
+    },
+  };
+})();`;
+
+/** 방문 컨텍스트에 목소리를 건다. 페이지보다 먼저 */
+async function installVoice(ctx) {
+  await ctx.addInitScript({ content: PAGE_SCRIPT });
+}
+
+/** 글의 언어. 이 컴퓨터 음성을 고르는 데만 쓴다 */
+function langOf(text) {
+  const s = String(text || "");
+  if (/[가-힣]/.test(s)) return "ko";
+  if (/[぀-ヿ]/.test(s)) return "ja";
+  if (/[一-鿿]/.test(s)) return "zh";
+  if (/[Ѐ-ӿ]/.test(s)) return "ru";
+  return "en";
+}
+
+const run = (cmd, args, ms = 30000) =>
+  new Promise((resolve, reject) =>
+    execFile(cmd, args, { timeout: ms, windowsHide: true, maxBuffer: 4 << 20 }, (err, stdout, stderr) =>
+      err ? reject(new Error(String(stderr || err.message).trim().split("\n")[0])) : resolve(String(stdout)),
+    ),
+  );
+
+/** 사람마다 같은 목소리 — 같은 언어 음성이 여럿이면 사람 번호로 하나를 고정해 고른다 */
+const pickIndex = (seed, n) => {
+  let h = 0;
+  for (const c of String(seed || "")) h = (h * 31 + c.charCodeAt(0)) >>> 0;
+  return n ? h % n : 0;
+};
+
+async function synthWindows(textFile, out, lang, seed) {
+  const ps = [
+    "$ErrorActionPreference='Stop'",
+    "Add-Type -AssemblyName System.Speech",
+    "$s = New-Object System.Speech.Synthesis.SpeechSynthesizer",
+    `$v = @($s.GetInstalledVoices() | Where-Object { $_.Enabled -and $_.VoiceInfo.Culture.Name -like '${lang}*' })`,
+    `if ($v.Count -gt 0) { $s.SelectVoice($v[${pickIndex(seed, 97)} % $v.Count].VoiceInfo.Name) }`,
+    `$s.SetOutputToWaveFile('${out.replace(/'/g, "''")}')`,
+    `$s.Speak([IO.File]::ReadAllText('${textFile.replace(/'/g, "''")}', [Text.Encoding]::UTF8))`,
+    "$s.Dispose()",
+  ].join("; ");
+  await run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", ps]);
+}
+
+async function synthMac(textFile, out, lang, seed) {
+  // say -v '?' : "Yuna   ko_KR   # 안녕하세요" — 그 언어 음성 이름들
+  let voice = null;
+  try {
+    const names = (await run("say", ["-v", "?"]))
+      .split("\n")
+      .map((l) => l.match(/^(.+?)\s+([a-z]{2})[_-][A-Z]{2}\s+#/))
+      .filter((m) => m && m[2] === lang)
+      .map((m) => m[1].trim());
+    if (names.length) voice = names[pickIndex(seed, names.length)];
+  } catch {
+    // 목록을 못 읽으면 기본 음성
+  }
+  await run("say", [...(voice ? ["-v", voice] : []), "--file-format=WAVE", "--data-format=LEI16@22050", "-o", out, "-f", textFile]);
+}
+
+async function synthLinux(textFile, out, lang) {
+  for (const cmd of ["espeak-ng", "espeak"]) {
+    try {
+      await run(cmd, ["-v", lang, "-w", out, "-f", textFile]);
+      return;
+    } catch (e) {
+      if (!/ENOENT|not found/i.test(e.message)) throw e;
+    }
+  }
+  throw new Error("no speech voice on this computer (install espeak-ng)");
+}
+
+/**
+ * 문장 사이 쉼을 줄인다. 서버 음성 인식은 0.7초 조용하면 답이 끝난 것으로 친다(server voiceConfig speechEndTimeoutSec) —
+ * 이 컴퓨터 음성은 문장마다 그보다 길게 쉬어서 두 문장째가 잘린다. 16비트 PCM wav 만 고친다(그 밖은 그대로)
+ */
+function tightenPauses(wav, { maxGapSec = 0.3, floor = 400 } = {}) {
+  if (wav.length < 44 || wav.toString("ascii", 0, 4) !== "RIFF" || wav.toString("ascii", 8, 12) !== "WAVE") return wav;
+  let off = 12;
+  let fmt = null;
+  while (off + 8 <= wav.length) {
+    const id = wav.toString("ascii", off, off + 4);
+    const size = wav.readUInt32LE(off + 4);
+    if (id === "fmt ") fmt = { channels: wav.readUInt16LE(off + 10), rate: wav.readUInt32LE(off + 12), bits: wav.readUInt16LE(off + 22) };
+    if (id === "data") {
+      if (!fmt || fmt.bits !== 16) return wav;
+      const frame = 2 * fmt.channels;
+      const start = off + 8;
+      const end = Math.min(wav.length, start + size);
+      const maxGap = Math.round(maxGapSec * fmt.rate) * frame;
+      const out = [];
+      let run = 0; // 이어진 조용한 바이트
+      for (let i = start; i + frame <= end; i += frame) {
+        let loud = false;
+        for (let c = 0; c < fmt.channels; c++) if (Math.abs(wav.readInt16LE(i + 2 * c)) > floor) loud = true;
+        run = loud ? 0 : run + frame;
+        if (run <= maxGap) out.push(wav.subarray(i, i + frame));
+      }
+      const data = Buffer.concat(out);
+      const head = Buffer.from(wav.subarray(0, start));
+      head.writeUInt32LE(data.length, off + 4);
+      head.writeUInt32LE(head.length - 8 + data.length, 4);
+      return Buffer.concat([head, data]);
+    }
+    off += 8 + size + (size & 1);
+  }
+  return wav;
+}
+
+/** 할 말을 이 컴퓨터 음성으로 wav 로. @returns Buffer */
+async function synth(text, { seed } = {}) {
+  const lang = langOf(text);
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "usercase-voice-"));
+  const textFile = path.join(dir, "say.txt");
+  const out = path.join(dir, "say.wav");
+  try {
+    fs.writeFileSync(textFile, String(text), "utf8");
+    if (process.platform === "win32") await synthWindows(textFile, out, lang, seed);
+    else if (process.platform === "darwin") await synthMac(textFile, out, lang, seed);
+    else await synthLinux(textFile, out, lang);
+    const wav = fs.readFileSync(out);
+    if (wav.length < 100) throw new Error("the voice made no sound");
+    return tightenPauses(wav);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** 소리 내어 말한다 — 끝까지 틀고 돌아온다. @returns 말한 초 */
+async function speak(page, text, opts = {}) {
+  const wav = await synth(text, opts);
+  return page.evaluate((b64) => window.__ucVoice.say(b64), wav.toString("base64"));
+}
+
+/** 모더레이터가 한 말(자막). from 번째 줄부터. 페이지가 아직 안 심겼으면 null */
+async function heard(page, from = 0) {
+  return page.evaluate((f) => (window.__ucVoice ? window.__ucVoice.heard(f) : null), from).catch(() => null);
+}
+
+module.exports = { installVoice, speak, synth, heard, langOf, tightenPauses, PAGE_SCRIPT };