earshot-cli 0.1.0__py3-none-any.whl

earshot/compose.py

@@ -0,0 +1,195 @@
+"""转写段 → Markdown 笔记:分段、标题、元信息脚注、outbox 落盘。"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from earshot.transcribe import Segment
+
+PARAGRAPH_GAP_S = 2.5  # 段间隔超过此值即换段(自然段)
+PARAGRAPH_MAX_CHARS = 400  # 单段上限,超出在句号处拆(口播字幕无长停顿时的兜底)
+SENTENCE_MAX_CHARS = 60  # 句长预算:连续无句号超过该字数,强制断句
+TITLE_MAX_CHARS = 40
+
+SOURCE_LABELS = {"listen": "旁听录音", "audio": "音频文件", "video": "视频字幕"}
+
+
+@dataclass(frozen=True, slots=True)
+class NoteMeta:
+    """笔记元信息(渲染进脚注)。
+
+    Attributes:
+        started_at: 录音开始时间。
+        duration_s: 音频时长(秒)。
+        device: 采集设备名(audio 文件模式为 ``-``)。
+        source: ``listen`` 或 ``audio``。
+        note: 来源备注(如"B站·xx视频"),可为空。
+    """
+
+    started_at: datetime
+    duration_s: float
+    device: str
+    source: str
+    note: str
+    source_url: str = ""  # 原文链接(video 路线=视频 URL),投递时传服务端作 source_url 留痕
+
+
+def group_paragraphs(
+    segments: list[Segment],
+    gap_s: float = PARAGRAPH_GAP_S,
+    chapter_breaks: list[float] | None = None,
+) -> list[list[Segment]]:
+    """聚段为自然段:章节边界 > 时间间隔 > 长度兜底。
+
+    Args:
+        segments: 时间排序的转写段。
+        gap_s: 相邻段时间间隔超过该值则分段。
+        chapter_breaks: 视频章节起点(秒,B站章节标记),跨过即强制换段。
+
+    Returns:
+        段的列表(每个元素是一个自然段);单段不超过 PARAGRAPH_MAX_CHARS 字(句号处拆)。
+    """
+    chapters = sorted(chapter_breaks or [])
+    paragraphs: list[list[Segment]] = []
+    for seg in segments:
+        make_new = not paragraphs or seg.start_s - paragraphs[-1][-1].end_s > gap_s
+        if not make_new and chapters and paragraphs:
+            prev_start = paragraphs[-1][0].start_s  # 现段起点跨过章节边界而本段首未跨 → 新段
+            make_new = any(prev_start < cb <= seg.start_s for cb in chapters)
+        if make_new:
+            paragraphs.append([seg])
+        else:
+            paragraphs[-1].append(seg)
+
+    result: list[list[Segment]] = []
+    for para in paragraphs:
+        if sum(len(s.text) for s in para) <= PARAGRAPH_MAX_CHARS:
+            result.append(para)
+            continue
+        current: list[Segment] = []
+        current_chars = 0
+        for s in para:  # 超长段在句号处拆(口播字幕无长停顿时的兜底)
+            current.append(s)
+            current_chars += len(s.text)
+            if current_chars >= PARAGRAPH_MAX_CHARS and s.text.rstrip().endswith(("。", "?", "!", "！", "？")):
+                result.append(current)
+                current = []
+                current_chars = 0
+        if current:
+            result.append(current)
+    return result
+
+
+SENTENCE_END_GAP_S = 0.8  # 段间隔超过此值视为一句话说完
+_PUNCT_ENDINGS = "。！？；，、,.!?;:"
+
+
+def add_punctuation(segments: list[Segment]) -> list[Segment]:
+    """按时间轴给无标点转写恢复标点(B站 AI 字幕原文无标点;SenseVoice 已有,自动跳过)。
+
+    规则:段尾已有标点不动;与下段时间间隔大→句号(问句语气词→问号),小→逗号;末段补句号。
+    句长预算:连续无句号超过 SENTENCE_MAX_CHARS 字时强制断句(口播字幕行间隔密集,
+    固定间隔阈值会漏断,产生超长逗号串)。
+
+    Args:
+        segments: 时间排序的转写段。
+
+    Returns:
+        补齐标点的新 Segment 列表(原列表不改)。
+    """
+    out: list[Segment] = []
+    chars_since_period = 0
+    for i, seg in enumerate(segments):
+        text = seg.text.strip()
+        if not text:
+            continue
+        chars_since_period += len(text)
+        if text[-1] in _PUNCT_ENDINGS:
+            if text[-1] in "。！？!?":
+                chars_since_period = 0
+        elif i + 1 < len(segments):
+            gap = segments[i + 1].start_s - seg.end_s
+            if gap > SENTENCE_END_GAP_S or chars_since_period >= SENTENCE_MAX_CHARS:
+                text += "？" if text[-1] in ("吗", "呢", "吧") else "。"
+                chars_since_period = 0
+            else:
+                text += "，"
+        else:
+            text += "？" if text[-1] in ("吗", "呢", "吧") else "。"
+            chars_since_period = 0
+        out.append(Segment(start_s=seg.start_s, end_s=seg.end_s, text=text))
+    return out
+
+
+def derive_title(segments: list[Segment], override: str | None = None) -> str:
+    """标题:``--title`` 覆盖优先,否则取首个非空段截断。
+
+    Returns:
+        标题文本;无任何内容时返回 ``"(无语音内容)"``。
+    """
+    if override:
+        return override.strip()
+    first = next((s.text.strip() for s in segments if s.text.strip()), "")
+    first = first.rstrip(_PUNCT_ENDINGS)
+    if not first:
+        return "(无语音内容)"
+    if len(first) > TITLE_MAX_CHARS:
+        return first[:TITLE_MAX_CHARS].rstrip() + "…"
+    return first
+
+
+def format_duration(seconds: float) -> str:
+    """时长人性化:``1时02分03秒`` / ``12分34秒`` / ``45秒``。"""
+    total = max(0, int(round(seconds)))
+    h, rem = divmod(total, 3600)
+    m, s = divmod(rem, 60)
+    if h:
+        return f"{h}时{m:02d}分{s:02d}秒"
+    if m:
+        return f"{m}分{s:02d}秒"
+    return f"{s}秒"
+
+
+def slugify(title: str) -> str:
+    """标题 → 文件名安全片段(保留中文/字母/数字,其余折叠为 ``-``)。"""
+    slug = re.sub(r"[^\w一-鿿]+", "-", title).strip("-")
+    slug = slug[:30].strip("-")
+    return slug or "note"
+
+
+def render_markdown(meta: NoteMeta, paragraphs: list[str], title: str) -> str:
+    """渲染完整 Markdown 笔记。
+
+    Args:
+        meta: 元信息。
+        paragraphs: 已拼接好的自然段文本列表。
+        title: 笔记标题(同时用于投递侧 ``--title``)。
+
+    Returns:
+        Markdown 字符串,含元信息脚注。
+    """
+    source_label = SOURCE_LABELS.get(meta.source, meta.source)
+    lines = [f"# {title}", ""]
+    for para in paragraphs:  # Markdown 相邻行会合并同段,段落间必须空行
+        lines.append(para)
+        lines.append("")
+    lines += [
+        "",
+        "---",
+        "",
+        f"- 来源: {source_label}",
+        f"- 开始: {meta.started_at.strftime('%Y-%m-%d %H:%M:%S')}",
+        f"- 时长: {format_duration(meta.duration_s)}",
+        f"- 设备: {meta.device}",
+    ]
+    if meta.note:
+        lines.append(f"- 备注: {meta.note}")
+    return "\n".join(lines).strip() + "\n"
+
+
+def outbox_path(outbox: Path, started_at: datetime, title: str) -> Path:
+    """outbox 文件路径:``YYYYMMDD-HHMMSS-<slug>.md``。"""
+    return outbox / f"{started_at.strftime('%Y%m%d-%H%M%S')}-{slugify(title)}.md"

earshot/config.py

@@ -0,0 +1,88 @@
+"""配置加载:earshot 数据目录、模型根目录、exomind 凭据。
+
+优先级:环境变量 > ``~/.exomind/config.json`` > 默认值。
+exomind 凭据与 exomind CLI 共用(``~/.exomind/config.json``),云引擎与投递不用重复登录。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+EARSHOT_HOME_ENV = "EARSHOT_HOME"
+EARSHOT_MODEL_ROOT_ENV = "EARSHOT_MODEL_ROOT"
+EXOMIND_API_KEY_ENV = "EXOMIND_API_KEY"
+EXOMIND_BASE_URL_ENV = "EXOMIND_BASE_URL"
+
+DEFAULT_EXOMIND_BASE_URL = "https://exomind-api.ai-as.cn"
+EXOMIND_CONFIG_FILENAME = ".exomind/config.json"
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """运行时配置快照。
+
+    Attributes:
+        home: earshot 数据目录(outbox 留档、tmp 录音)。
+        model_root: 模型根目录,内含 ``asr/`` 与 ``vad/``。
+        exomind_base_url: exomind API 地址(云引擎 + 投递)。
+        exomind_api_key: API key,未配置时为空串(仅本地模式可用)。
+    """
+
+    home: Path
+    model_root: Path
+    exomind_base_url: str
+    exomind_api_key: str
+
+    @property
+    def outbox(self) -> Path:
+        """转写笔记留档目录。"""
+        return self.home / "outbox"
+
+
+def load_settings(
+    env: dict[str, str] | None = None,
+    exomind_config_path: Path | None = None,
+) -> Settings:
+    """解析配置。
+
+    Args:
+        env: 环境变量映射,默认取 ``os.environ``(测试注入用)。
+        exomind_config_path: exomind 配置文件路径,默认 ``~/.exomind/config.json``。
+
+    Returns:
+        Settings 快照。
+    """
+    env = dict(os.environ) if env is None else env
+    exo = load_exomind_config(exomind_config_path)
+    home = Path(env.get(EARSHOT_HOME_ENV, str(Path.home() / ".earshot")))
+    model_root = Path(env.get(EARSHOT_MODEL_ROOT_ENV, str(home / "models")))
+    base_url = env.get(EXOMIND_BASE_URL_ENV) or exo.get("base_url") or DEFAULT_EXOMIND_BASE_URL
+    api_key = env.get(EXOMIND_API_KEY_ENV) or exo.get("api_key") or ""
+    return Settings(
+        home=home,
+        model_root=model_root,
+        exomind_base_url=base_url.rstrip("/"),
+        exomind_api_key=api_key,
+    )
+
+
+def load_exomind_config(path: Path | None = None) -> dict[str, str]:
+    """读取 exomind CLI 的配置文件,不存在或损坏时返回空 dict。
+
+    Args:
+        path: 配置文件路径,默认 ``~/.exomind/config.json``。
+
+    Returns:
+        只含 ``base_url`` / ``api_key`` 等字符串键的 dict。
+    """
+    cfg_path = path if path is not None else Path.home() / EXOMIND_CONFIG_FILENAME
+    try:
+        raw = json.loads(cfg_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(raw, dict):
+        return {}
+    return {k: v for k, v in raw.items() if isinstance(v, str)}

earshot/deliver.py

@@ -0,0 +1,219 @@
+"""投递层:exomind API(直连,免 CLI)/ exomind CLI / webhook / 不投递,可插拔。"""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from earshot.config import Settings
+
+EXOMIND_ORIGIN = "earshot"
+EXOMIND_PENDING_EXIT_CODE = 3  # exomind CLI 契约:3 = 已提交、后台仍在抽取,不是失败
+DELIVER_TIMEOUT_S = 600.0
+INGEST_POLL_INTERVAL_S = 2.0
+INGEST_POLL_BUDGET_S = 120.0
+
+
+@dataclass(frozen=True, slots=True)
+class DeliveryResult:
+    """投递结果。
+
+    Attributes:
+        status: ``delivered`` / ``pending`` / ``skipped`` / ``failed``。
+        detail: 给用户看的一句话说明。
+    """
+
+    status: str
+    detail: str
+
+
+def build_exomind_args(
+    md_path: Path,
+    title: str,
+    tags: list[str],
+    origin: str = EXOMIND_ORIGIN,
+) -> list[str]:
+    """组装 exomind ingest 命令行(纯函数,wire 契约由单测钉死)。"""
+    args = ["exomind", "ingest", "--file", str(md_path), "--origin", origin]
+    if title:
+        args += ["--title", title]
+    for tag in tags:
+        args += ["--tag", tag]
+    return args
+
+
+def deliver_exomind(
+    md_path: Path,
+    title: str,
+    tags: list[str],
+    runner: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+) -> DeliveryResult:
+    """经 exomind CLI 投递(复用其异步 job、轮询与 client_key 幂等)。
+
+    Args:
+        md_path: 笔记文件。
+        title: 标题(透传 ``--title``)。
+        tags: 标签列表。
+        runner: subprocess 运行器(测试注入用)。
+
+    Returns:
+        DeliveryResult,``pending`` 对应 CLI exit 3(已提交未完成)。
+    """
+    cmd = build_exomind_args(md_path, title, tags)
+    try:
+        proc = runner(cmd, capture_output=True, text=True, timeout=DELIVER_TIMEOUT_S)
+    except FileNotFoundError:
+        return DeliveryResult("failed", "未找到 exomind CLI(npm i -g exomind,或改用 --deliver webhook/none)")
+    except subprocess.TimeoutExpired:
+        return DeliveryResult("failed", f"exomind CLI 超时({DELIVER_TIMEOUT_S:.0f}s)")
+    out_lines = (proc.stdout or "").strip().splitlines()
+    tail = out_lines[-1] if out_lines else ""
+    if proc.returncode == 0:
+        return DeliveryResult("delivered", tail or "已投递进知识库")
+    if proc.returncode == EXOMIND_PENDING_EXIT_CODE:
+        return DeliveryResult("pending", "已提交,后台抽取中(exomind 会幂等续查回执)")
+    err = (proc.stderr or "").strip().splitlines()
+    detail = err[-1] if err else tail or f"exomind CLI 退出码 {proc.returncode}"
+    return DeliveryResult("failed", detail)
+
+
+def deliver_webhook(
+    url: str,
+    title: str,
+    content_md: str,
+    tags: list[str],
+    origin: str = EXOMIND_ORIGIN,
+    poster: Callable[[str, dict[str, str | list[str]]], None] | None = None,
+) -> DeliveryResult:
+    """POST JSON 到任意 webhook,适配非 exomind 知识库。
+
+    Args:
+        url: webhook 地址。
+        title: 标题。
+        content_md: Markdown 正文。
+        tags: 标签。
+        origin: 来源标识。
+        poster: 发送函数(测试注入用),抛异常即视为失败。
+
+    Returns:
+        DeliveryResult。
+    """
+
+    def _post(target: str, payload: dict[str, str | list[str]]) -> None:
+        resp = httpx.post(target, json=payload, timeout=30.0)
+        resp.raise_for_status()
+
+    send = poster or _post
+    payload: dict[str, str | list[str]] = {"origin": origin, "title": title, "content": content_md, "tags": tags}
+    try:
+        send(url, payload)
+    except Exception as e:  # httpx 异常族不稳定,统一收口
+        return DeliveryResult("failed", f"webhook 投递失败: {e}")
+    return DeliveryResult("delivered", f"已 POST 到 {url}")
+
+
+def client_key_for(content: str) -> str:
+    """内容幂等键:与服务端两层幂等(优先级最高)对齐,重复投递不会入库两次。"""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+def _as_count(value: Any) -> int:
+    """回执计数兼容:服务端字段时而为个数(int)、时而为列表,统一取数。"""
+    if isinstance(value, int):
+        return value
+    if isinstance(value, list):
+        return len(value)
+    return 0
+
+
+def deliver_exomind_api(
+    md_path: Path,
+    title: str,
+    tags: list[str],
+    settings: Settings,
+    poster: Callable[[str, dict[str, Any], dict[str, str]], dict[str, Any]] | None = None,
+    getter: Callable[[str, dict[str, str], dict[str, str]], dict[str, Any]] | None = None,
+    poll_interval_s: float = INGEST_POLL_INTERVAL_S,
+    poll_budget_s: float = INGEST_POLL_BUDGET_S,
+    source_url: str | None = None,
+) -> DeliveryResult:
+    """直连 exomind HTTP API 投递(免装 exomind CLI)。
+
+    走 POST /ingest/async + GET /ingest/status,与 CLI 同契约:
+    秒回 job_id → 轮询至 done/failed;超预算视为 pending(内容已入库,抽取仍在跑)。
+
+    Args:
+        md_path: 笔记文件。
+        title: 标题。
+        tags: 标签。
+        settings: 含 base_url / api_key 的配置。
+        poster: ``(url, payload, headers) -> 响应 dict``(测试注入)。
+        getter: ``(url, params, headers) -> 响应 dict``(测试注入)。
+        poll_interval_s / poll_budget_s: 轮询节奏与总预算。
+        source_url: 原文链接(video 路线);content+url 并存时服务端仅作出处留痕,不抓取。
+
+    Returns:
+        DeliveryResult。
+    """
+    if not settings.exomind_api_key:
+        return DeliveryResult("failed", "无 exomind 凭据(调用方应回退 CLI)")
+
+    def _post(url: str, payload: dict[str, Any], headers: dict[str, str]) -> dict[str, Any]:
+        resp = httpx.post(url, json=payload, headers=headers, timeout=60.0)
+        resp.raise_for_status()
+        return dict(resp.json())
+
+    def _get(url: str, params: dict[str, str], headers: dict[str, str]) -> dict[str, Any]:
+        resp = httpx.get(url, params=params, headers=headers, timeout=30.0)
+        resp.raise_for_status()
+        return dict(resp.json())
+
+    post = poster or _post
+    get = getter or _get
+    base = settings.exomind_base_url
+    headers = {"Authorization": f"Bearer {settings.exomind_api_key}"}
+
+    content = md_path.read_text(encoding="utf-8")
+    payload: dict[str, Any] = {"content": content, "origin": EXOMIND_ORIGIN, "client_key": client_key_for(content)}
+    if title:
+        payload["title"] = title
+    if tags:
+        payload["tags"] = tags
+    if source_url:
+        payload["url"] = source_url
+    try:
+        resp = post(f"{base}/ingest/async", payload, headers)
+    except Exception as e:
+        return DeliveryResult("failed", f"提交 ingest 失败: {e}")
+    job_id = resp.get("job_id")
+    if not job_id:
+        return DeliveryResult("failed", f"响应缺 job_id: {str(resp)[:200]}")
+
+    deadline = time.monotonic() + poll_budget_s
+    try:
+        while time.monotonic() < deadline:
+            try:
+                st = get(f"{base}/ingest/status", {"job_id": str(job_id)}, headers)
+            except Exception as e:
+                return DeliveryResult("failed", f"查询回执失败(job_id={job_id}): {e}")
+            status = st.get("status")
+            if status == "done":
+                n_entities = _as_count(st.get("entities"))
+                n_pages = _as_count(st.get("created_pages"))
+                n_updated = _as_count(st.get("updated_pages"))
+                detail = f"已入库:实体 {n_entities} 个,页面 +{n_pages}/更{n_updated}(job_id={job_id})"
+                return DeliveryResult("delivered", detail)
+            if status == "failed":
+                return DeliveryResult("failed", f"服务端抽取失败: {st.get('error', '未知')}(job_id={job_id})")
+            time.sleep(poll_interval_s)
+    except KeyboardInterrupt:
+        # Ctrl-C = 不等回执了;内容已提交,服务端 job 会继续跑完
+        return DeliveryResult("pending", f"已提交,不再等待回执(job_id={job_id})")
+    return DeliveryResult("pending", f"已提交,后台抽取中(job_id={job_id})")

earshot/extract.py

@@ -0,0 +1,88 @@
+"""ffmpeg 工具:任意音视频 → 16k mono wav(ASR 统一入口格式)。"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import wave
+from pathlib import Path
+
+FFMPEG = "ffmpeg"
+TARGET_SAMPLE_RATE = 16000
+
+
+class ExtractError(RuntimeError):
+    """ffmpeg 抽音轨失败。"""
+
+
+def ffmpeg_exe() -> str | None:
+    """定位 ffmpeg:优先系统 PATH,其次 imageio-ffmpeg wheel 内置二进制。
+
+    Returns:
+        ffmpeg 可执行文件路径,两级都无则 None。
+    """
+    found = shutil.which(FFMPEG)
+    if found:
+        return found
+    try:
+        import imageio_ffmpeg  # noqa: PLC0415 延迟导入:装了系统 ffmpeg 就不必加载
+
+        return str(imageio_ffmpeg.get_ffmpeg_exe())
+    except Exception:  # imageio_ffmpeg 缺失或平台无二进制
+        return None
+
+
+def ffmpeg_available() -> bool:
+    """ffmpeg 是否可用(系统或内置 wheel 任一)。"""
+    return ffmpeg_exe() is not None
+
+
+def to_wav16k(src: Path, dst: Path) -> None:
+    """抽音轨并重采样为 16k mono wav。
+
+    Args:
+        src: 输入任意音视频文件(ffmpeg 支持即行)。
+        dst: 输出 wav 路径。
+
+    Raises:
+        ExtractError: ffmpeg 缺失或执行失败。
+    """
+    exe = ffmpeg_exe()
+    if exe is None:
+        msg = "未找到 ffmpeg(系统 PATH 与 imageio-ffmpeg 内置均无;重装 earshot 依赖)"
+        raise ExtractError(msg)
+    cmd = [
+        exe,
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-y",
+        "-i",
+        str(src),
+        "-vn",
+        "-ac",
+        "1",
+        "-ar",
+        str(TARGET_SAMPLE_RATE),
+        "-f",
+        "wav",
+        str(dst),
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=600)  # noqa: S603
+    if proc.returncode != 0:
+        msg = f"ffmpeg 失败({proc.returncode}): {(proc.stderr or '').strip()[:500]}"
+        raise ExtractError(msg)
+
+
+def wav_duration(path: Path) -> float:
+    """读 wav 时长(秒)。
+
+    Raises:
+        ExtractError: 文件不是合法 wav。
+    """
+    try:
+        with wave.open(str(path), "rb") as w:
+            return w.getnframes() / float(w.getframerate())
+    except wave.Error as e:
+        msg = f"不是合法 wav: {path}({e})"
+        raise ExtractError(msg) from e

earshot/live.py

@@ -0,0 +1,76 @@
+"""实时旁听:录音线程边录边喂,后台线程 VAD 切段+解码,段闭合即出字幕。
+
+录音不中断、转写不阻塞:两者经队列解耦,SenseVoice 单段解码远快于实时,
+后台线程永远追得上。
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+from collections.abc import Callable, Iterator
+from typing import Any
+
+import numpy as np
+
+from earshot.transcribe import Segment, TranscribeError, run_live
+
+LIVE_CAPTION_MAX_RUN_S = 10.0  # 字幕滚动预算:连续语音超过该秒数强制闭段出字幕
+
+
+class LiveSession:
+    """边录边转会话:push 喂 16k 音频块,finalize 收尾并返回全部 Segment。
+
+    Args:
+        transcriber: 已初始化的 LocalTranscriber(提供 VAD 工厂与解码器)。
+        on_text: 每段文本就绪即回调(实时字幕;回调里别做慢活,会拖住解码线程)。
+    """
+
+    def __init__(self, transcriber: Any, on_text: Callable[[str], None] | None = None) -> None:
+        self._transcriber = transcriber
+        self._on_text = on_text
+        self._q: queue.Queue[np.ndarray | None] = queue.Queue()
+        self._segments: list[Segment] = []
+        self._err: BaseException | None = None
+        self._thread = threading.Thread(target=self._consume, daemon=True)
+
+    def start(self) -> None:
+        """启动后台解码线程。"""
+        self._thread.start()
+
+    def push(self, samples: np.ndarray) -> None:
+        """喂一块 16k mono float32 样本(录音线程调用,非阻塞)。"""
+        self._q.put(samples)
+
+    def finalize(self, timeout_s: float = 300.0) -> list[Segment]:
+        """收尾:喂入结束哨兵,等尾部音频解码完,返回全部 Segment。
+
+        Raises:
+            TranscribeError: 后台线程曾出错。
+        """
+        self._q.put(None)
+        self._thread.join(timeout_s)
+        if self._err is not None:
+            msg = f"实时转写线程出错: {self._err}"
+            raise TranscribeError(msg) from self._err
+        return self._segments
+
+    def _consume(self) -> None:
+        try:
+            self._segments = run_live(
+                vad=self._transcriber._new_vad(),
+                chunks=self._iter_queue(),
+                decode=self._transcriber._decode,
+                on_segment=lambda seg: self._on_text(seg.text) if self._on_text else None,
+                max_speech_run_s=LIVE_CAPTION_MAX_RUN_S,  # 连续口播停顿<min_silence 时也保证字幕滚动
+            )
+        except BaseException as e:  # 线程内不可抛,存起来由 finalize 抛
+            self._err = e
+
+    def _iter_queue(self) -> Iterator[np.ndarray]:
+        """队列 -> 迭代器,收到哨兵即结束。"""
+        while True:
+            item = self._q.get()
+            if item is None:
+                return
+            yield item