earshot-cli 0.1.0__py3-none-any.whl

earshot/models.py

@@ -0,0 +1,72 @@
+"""模型自动获取:缺失时首次运行自动下载(MacWhisper/Ollama 式体验)。
+
+源默认走 hf-mirror(国内可达),可用 HF_ENDPOINT 覆盖。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+
+DEFAULT_ENDPOINT = "https://hf-mirror.com"
+SENSE_VOICE_REPO = "csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17"
+SILERO_VAD_REPO = "onnx-community/silero-vad"
+
+# 相对路径 -> (HF 仓库, 仓库内文件)
+MODEL_FILES: dict[str, tuple[str, str]] = {
+    "asr/model.int8.onnx": (SENSE_VOICE_REPO, "model.int8.onnx"),
+    "asr/tokens.txt": (SENSE_VOICE_REPO, "tokens.txt"),
+    "vad/silero_vad.onnx": (SILERO_VAD_REPO, "onnx/model.onnx"),
+}
+
+
+def missing_models(model_root: Path) -> list[str]:
+    """列出缺失的模型相对路径。"""
+    return [rel for rel in MODEL_FILES if not (model_root / rel).is_file()]
+
+
+def ensure_models(model_root: Path, endpoint: str | None = None) -> bool:
+    """确保模型齐全,缺失则下载。
+
+    Args:
+        model_root: 模型根目录。
+        endpoint: HF 端点,默认 hf-mirror,可 ``HF_ENDPOINT`` 覆盖。
+
+    Returns:
+        是否发生了下载。
+
+    Raises:
+        RuntimeError: 下载失败(网络不可达等)。
+    """
+    import os
+
+    base = endpoint or os.environ.get("HF_ENDPOINT") or DEFAULT_ENDPOINT
+    downloaded = False
+    for rel in missing_models(model_root):
+        repo, remote = MODEL_FILES[rel]
+        dest = model_root / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        url = f"{base}/{repo}/resolve/main/{remote}"
+        print(f"↓ 下载模型 {rel}(首次运行自动补齐,之后不再下载)")
+        try:
+            mb = 1 << 20
+            with httpx.stream("GET", url, follow_redirects=True, timeout=60.0) as resp:
+                resp.raise_for_status()
+                total = int(resp.headers.get("content-length") or 0)
+                done = 0
+                with dest.with_suffix(dest.suffix + ".part").open("wb") as f:
+                    for chunk in resp.iter_bytes(chunk_size=mb):
+                        f.write(chunk)
+                        done += len(chunk)
+                        if total:
+                            print(f"\r  {done // mb}/{total // mb} MB", end="", flush=True)
+            dest.with_suffix(dest.suffix + ".part").replace(dest)
+            downloaded = True
+            print()
+        except httpx.HTTPError as e:
+            for suffix in ("", ".part"):
+                Path(str(dest) + suffix).unlink(missing_ok=True)
+            msg = f"模型下载失败: {rel}({e})。可设 HF_ENDPOINT=https://huggingface.co 重试,或手动放置到 {model_root}"
+            raise RuntimeError(msg) from e
+    return downloaded

earshot/subtitle.py

@@ -0,0 +1,207 @@
+"""B站字幕直拉:yt-dlp 提取元信息与字幕轨 → Segment 列表。
+
+高信噪比路线:听录会混入环境噪音/被打断,字幕来自平台已生成文本,无此问题。
+支持 .bcc/.json(B站)与 .srt/.vtt 格式;AI 字幕(ai-zh)通常需要登录态
+(--cookies-from-browser)。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from earshot.transcribe import Segment
+
+# 人工字幕优先于 AI 字幕;同组内先列者优先
+PREFERRED_LANGS = ("zh-CN", "zh-Hans", "zh", "ai-zh")
+PARSABLE_EXTS = ("bcc", "json", "srt", "vtt")
+
+_SRT_TIME = re.compile(r"(?P<h>\d{2}):(?P<m>\d{2}):(?P<s>\d{2})[.,](?P<ms>\d{3})")
+
+
+class SubtitleError(RuntimeError):
+    """字幕获取失败(无字幕/网络/解析)。"""
+
+
+@dataclass(frozen=True, slots=True)
+class VideoMeta:
+    """视频元信息(写进笔记脚注)。
+
+    Attributes:
+        title: 视频标题。
+        uploader: UP主/作者。
+        duration_s: 视频时长(秒,缺失为 0)。
+        url: 原始链接(回溯用)。
+        subtitle_lang: 实际采用的字幕语言(如 zh-CN / ai-zh)。
+    """
+
+    title: str
+    uploader: str
+    duration_s: float
+    url: str
+    subtitle_lang: str
+    chapter_starts: list[float] = field(default_factory=list)  # 章节起点(秒),按章节分段
+
+
+@dataclass(frozen=True, slots=True)
+class _Track:
+    """一条字幕轨:url 与 data 二选一(yt-dlp 对B站已下载转内联 data)。"""
+
+    lang: str
+    ext: str
+    url: str = ""
+    data: str = ""
+
+
+def choose_subtitle(tracks: list[_Track]) -> _Track | None:
+    """按语言优先级与格式可解析性选字幕轨(纯函数)。
+
+    人工 zh 字幕 > ai-zh;同语言内 bcc/json 优先于 srt/vtt。
+    """
+    by_lang: dict[str, list[_Track]] = {}
+    for t in tracks:
+        if t.ext in PARSABLE_EXTS and (t.url or t.data):
+            by_lang.setdefault(t.lang, []).append(t)
+    for lang in PREFERRED_LANGS:
+        candidates = by_lang.get(lang)
+        if candidates:
+            for ext in ("bcc", "json", "srt", "vtt"):
+                for t in candidates:
+                    if t.ext == ext:
+                        return t
+            return candidates[0]
+    return None
+
+
+def parse_subtitle(content: str, ext: str) -> list[Segment]:
+    """解析字幕内容为 Segment 列表(纯函数)。
+
+    Args:
+        content: 字幕文件文本。
+        ext: bcc/json(B站 JSON 体)或 srt/vtt。
+
+    Returns:
+        按时间排序、非空文本的 Segment 列表。
+
+    Raises:
+        SubtitleError: 格式无法解析。
+    """
+    if ext in ("bcc", "json"):
+        try:
+            body = json.loads(content).get("body") or []
+        except ValueError as e:
+            msg = f"bcc/json 字幕解析失败: {e}"
+            raise SubtitleError(msg) from e
+        bcc_segments = [
+            Segment(start_s=float(item["from"]), end_s=float(item["to"]), text=str(item["content"]).strip())
+            for item in body
+            if item.get("content")
+        ]
+        return bcc_segments
+    # srt / vtt
+    segments: list[Segment] = []
+    blocks = content.replace("\r\n", "\n").split("\n\n")
+    for block in blocks:
+        lines = [ln for ln in block.split("\n") if ln.strip()]
+        times = [ln for ln in lines if "-->" in ln]
+        if not times:
+            continue
+        m_start = _SRT_TIME.search(times[0])
+        m_end = _SRT_TIME.search(times[0], times[0].find("-->") + 3)
+        text = " ".join(ln.strip() for ln in lines if "-->" not in ln and not ln.strip().isdigit())
+        if m_start and m_end and text:
+            segments.append(
+                Segment(
+                    start_s=_to_seconds(m_start),
+                    end_s=_to_seconds(m_end),
+                    text=text,
+                )
+            )
+    if not segments:
+        msg = f"srt/vtt 字幕解析失败(无有效块): ext={ext}"
+        raise SubtitleError(msg)
+    return segments
+
+
+def _to_seconds(m: re.Match[str]) -> float:
+    return int(m["h"]) * 3600 + int(m["m"]) * 60 + int(m["s"]) + int(m["ms"]) / 1000.0
+
+
+def fetch_video_note(url: str, cookies_browser: str | None = None) -> tuple[VideoMeta, list[Segment]]:
+    """拉取视频字幕,返回 (元信息, Segment 列表)。
+
+    Args:
+        url: 视频链接(B站等 yt-dlp 支持的平台)。
+        cookies_browser: 浏览器名(chrome/safari/firefox/edge),拉 ai-zh AI 字幕
+            通常需要登录态;None 则匿名尝试。
+
+    Raises:
+        SubtitleError: 提取失败或无可用字幕。
+    """
+    import yt_dlp  # noqa: PLC0415 延迟导入:不用 video 命令时不加载
+
+    opts: dict[str, Any] = {
+        "quiet": True,
+        "no_warnings": True,
+        "skip_download": True,
+        "noplaylist": True,
+        # yt-dlp 契约:不设 writesubtitles,提取器根本不会调字幕接口(info["subtitles"] 恒空)
+        "writesubtitles": True,
+        "writeautomaticsub": True,
+        "subtitleslangs": list(PREFERRED_LANGS) + ["zh-Hant", "en"],
+    }
+    if cookies_browser:
+        opts["cookiesfrombrowser"] = (cookies_browser,)
+    try:
+        info = yt_dlp.YoutubeDL(opts).extract_info(url, download=False)
+    except Exception as e:  # yt_dlp 异常族庞大,统一收口
+        msg = f"yt-dlp 提取失败: {e}"
+        raise SubtitleError(msg) from e
+    if not info:
+        msg = "yt-dlp 未返回视频信息"
+        raise SubtitleError(msg)
+
+    tracks: list[_Track] = []
+    for subs_field in ("subtitles", "automatic_captions"):
+        for lang, subs in (info.get(subs_field) or {}).items():
+            for s in subs:
+                tracks.append(
+                    _Track(
+                        lang=lang,
+                        ext=str(s.get("ext") or "srt"),
+                        url=str(s.get("url") or ""),
+                        data=str(s.get("data") or ""),
+                    )
+                )
+    track = choose_subtitle(tracks)
+    if track is None:
+        hints = []
+        if not cookies_browser:
+            hints.append("试试 --cookies-from-browser chrome(AI 字幕通常需要登录态)")
+        hints.append("若字幕是烧在画面里的硬字幕(播放器右下角无 CC 开关),字幕轨本来就不存在,请改用 earshot listen 听录")
+        msg = f"无可用中文字幕。{' ; '.join(hints)}"
+        raise SubtitleError(msg)
+    if track.data:  # yt-dlp 已下载并转好格式(B站 ai-zh 即此路径)
+        content = track.data
+    else:
+        try:
+            resp = httpx.get(track.url, timeout=60.0, follow_redirects=True, headers={"User-Agent": "Mozilla/5.0"})
+            resp.raise_for_status()
+        except httpx.HTTPError as e:
+            msg = f"字幕下载失败({track.lang}/{track.ext}): {e}"
+            raise SubtitleError(msg) from e
+        content = resp.text
+    segments = parse_subtitle(content, track.ext)
+    meta = VideoMeta(
+        title=str(info.get("title") or url),
+        uploader=str(info.get("uploader") or info.get("channel") or "-"),
+        duration_s=float(info.get("duration") or 0),
+        url=url,
+        subtitle_lang=track.lang,
+        chapter_starts=[float(c["start_time"]) for c in (info.get("chapters") or []) if "start_time" in c],
+    )
+    return meta, segments

earshot/transcribe.py

@@ -0,0 +1,220 @@
+"""本地转写引擎:silero VAD 切段 + SenseVoice 离线解码。
+
+sherpa-onnx 延迟导入 —— compose 等纯逻辑模块与单测不依赖模型栈。
+"""
+
+from __future__ import annotations
+
+import wave
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+SAMPLE_RATE = 16000
+VAD_WINDOW = 512  # silero 要求 512 样本/窗(16k 下 32ms)
+MAX_SPEECH_RUN_S = 55.0  # 连续无停顿语音强制切段,防 VAD 60s buffer 溢出
+MIN_SILENCE_S = 0.45  # 短于此的静音不算说完(挡住句中停顿)
+PARAGRAPH_FEED_EVERY_S = 5.0  # 进度回调最小间隔
+
+
+class TranscribeError(RuntimeError):
+    """本地转写失败(模型缺失 / 配置 / 解码错误)。"""
+
+
+@dataclass(frozen=True, slots=True)
+class Segment:
+    """一段连续语音的转写结果。
+
+    Attributes:
+        start_s: 段起点(秒,相对音频开头)。
+        end_s: 段终点(秒)。
+        text: 转写文本。
+    """
+
+    start_s: float
+    end_s: float
+    text: str
+
+
+class LocalTranscriber:
+    """VAD 切段 + SenseVoice 批量识别,输入须为 16k mono wav。"""
+
+    def __init__(self, model_root: Path) -> None:
+        """加载 ASR/VAD 模型。
+
+        Args:
+            model_root: 模型根目录,须含 ``asr/model.int8.onnx``、``asr/tokens.txt``、
+                ``vad/silero_vad.onnx``(scripts/download_models.sh 产物)。
+
+        Raises:
+            TranscribeError: 模型缺失或初始化失败。
+        """
+        asr_model = model_root / "asr" / "model.int8.onnx"
+        tokens = model_root / "asr" / "tokens.txt"
+        vad_model = model_root / "vad" / "silero_vad.onnx"
+        for p in (asr_model, tokens, vad_model):
+            if not p.is_file():
+                msg = f"模型缺失: {p}(先跑 scripts/download_models.sh,或设 EARSHOT_MODEL_ROOT 指向已有模型)"
+                raise TranscribeError(msg)
+
+        import sherpa_onnx  # noqa: PLC0415 延迟导入:纯逻辑模块/单测不拉模型栈
+
+        try:
+            self._recognizer: Any = sherpa_onnx.OfflineRecognizer.from_sense_voice(
+                model=str(asr_model),
+                tokens=str(tokens),
+                use_itn=True,
+            )
+            self._vad_model_config: Any = sherpa_onnx.VadModelConfig()
+            self._vad_model_config.silero_vad.model = str(vad_model)
+            self._vad_model_config.silero_vad.threshold = 0.5
+            self._vad_model_config.silero_vad.min_silence_duration = MIN_SILENCE_S
+            self._vad_model_config.silero_vad.min_speech_duration = 0.15
+            self._vad_model_config.silero_vad.window_size = VAD_WINDOW
+            self._vad_model_config.sample_rate = SAMPLE_RATE
+            if not self._vad_model_config.validate():
+                msg = "VAD 配置校验失败"
+                raise TranscribeError(msg)
+        except TranscribeError:
+            raise
+        except Exception as e:  # sherpa 抛的均为未类型化异常
+            msg = f"初始化本地转写失败: {e}"
+            raise TranscribeError(msg) from e
+
+    def transcribe(self, wav: Path, on_progress: Any = None) -> list[Segment]:
+        """转写整个 wav 文件。
+
+        Args:
+            wav: 16k mono wav(earshot.extract.to_wav16k 产物)。
+            on_progress: 可选回调 ``on_progress(fraction)``,fraction ∈ [0,1]。
+
+        Returns:
+            按时间排序的 Segment 列表。
+
+        Raises:
+            TranscribeError: wav 格式不符或解码失败。
+        """
+        samples = read_wav16k_mono(wav)
+        return self.transcribe_samples(samples, on_progress)
+
+    def transcribe_samples(self, samples: np.ndarray, on_progress: Any = None) -> list[Segment]:
+        """转写内存样本(16k float32 mono)。"""
+        return run_live(
+            vad=self._new_vad(),
+            chunks=iter([samples]),
+            decode=self._decode,
+            on_progress=on_progress,
+            total_samples=len(samples),
+        )
+
+    def _new_vad(self) -> Any:
+        """新建一个 VAD 状态机(有状态,每次转写须新建)。"""
+        import sherpa_onnx  # noqa: PLC0415
+
+        return sherpa_onnx.VoiceActivityDetector(self._vad_model_config, buffer_size_in_seconds=60)
+
+    def _decode(self, samples: np.ndarray) -> str:
+        """单段离线解码,返回去空白文本。"""
+        try:
+            stream = self._recognizer.create_stream()
+            stream.accept_waveform(SAMPLE_RATE, samples)
+            self._recognizer.decode_stream(stream)
+            return str(stream.result.text).strip()
+        except Exception as e:
+            msg = f"解码失败: {e}"
+            raise TranscribeError(msg) from e
+
+
+def run_live(
+    vad: Any,
+    chunks: Iterator[np.ndarray],
+    decode: Callable[[np.ndarray], str],
+    on_segment: Callable[[Segment], None] | None = None,
+    on_progress: Any = None,
+    total_samples: int | None = None,
+    max_speech_run_s: float = MAX_SPEECH_RUN_S,
+) -> list[Segment]:
+    """VAD 切段 + 逐段解码核心:批量转写与实时旁听共用。
+
+    Args:
+        vad: sherpa VoiceActivityDetector(状态机,每次调用须新建)。
+        chunks: 16k mono float32 音频块迭代器,逐块喂入。
+        decode: 单段样本 -> 文本。
+        on_segment: 每段解码完成即回调(实时字幕用)。
+        on_progress: 进度回调(需 total_samples;实时模式无总量则不回调)。
+        total_samples: 音频总样本数(进度计算用,实时模式为 None)。
+        max_speech_run_s: 连续无闭段语音超过该秒数强制闭段 —— 批量为防 VAD
+            buffer 溢出(55s),实时为字幕滚动预算(10s):连续口播停顿全部低于
+            min_silence 阈值时,VAD 永不自然闭段,字幕要等收尾 flush 才出。
+
+    Returns:
+        按时间排序的 Segment 列表。
+    """
+    segments: list[Segment] = []
+    fed = 0  # 已喂样本数(绝对时间锚点)
+    last_pop = 0  # 上次弹出段时的已喂样本数
+    next_progress = PARAGRAPH_FEED_EVERY_S * SAMPLE_RATE
+
+    def drain() -> None:
+        nonlocal last_pop
+        while not vad.empty():
+            seg = vad.front
+            seg_samples = np.asarray(seg.samples, dtype=np.float32)
+            text = decode(seg_samples)
+            if text:
+                start = seg.start / SAMPLE_RATE
+                segment = Segment(start_s=start, end_s=start + len(seg_samples) / SAMPLE_RATE, text=text)
+                segments.append(segment)
+                if on_segment is not None:
+                    on_segment(segment)
+            vad.pop()
+            last_pop = fed
+
+    carry = np.empty(0, dtype=np.float32)
+    for chunk in chunks:
+        buf = (
+            np.concatenate([carry, np.asarray(chunk, dtype=np.float32)])
+            if carry.size
+            else np.asarray(chunk, dtype=np.float32)
+        )
+        n_windows = len(buf) // VAD_WINDOW
+        for w in range(n_windows):
+            vad.accept_waveform(buf[w * VAD_WINDOW : (w + 1) * VAD_WINDOW])
+            fed += VAD_WINDOW
+            drain()
+            if bool(vad.is_speech_detected()) and (fed - last_pop) / SAMPLE_RATE > max_speech_run_s:
+                vad.flush()  # 强制闭段:连续语音超预算(批量=防溢出,实时=字幕滚动)
+                drain()
+        carry = buf[n_windows * VAD_WINDOW :]
+        if on_progress is not None and total_samples and fed >= next_progress:
+            on_progress(fed / total_samples)
+            next_progress = fed + PARAGRAPH_FEED_EVERY_S * SAMPLE_RATE
+    if carry.size:
+        vad.accept_waveform(carry)
+        fed += carry.size
+    vad.flush()
+    drain()
+    if on_progress is not None and total_samples:
+        on_progress(1.0)
+    return segments
+
+
+def read_wav16k_mono(wav: Path) -> np.ndarray:
+    """读 wav 为 16k mono float32 样本。
+
+    Raises:
+        TranscribeError: 非法 wav 或采样率/声道不符。
+    """
+    try:
+        with wave.open(str(wav), "rb") as w:
+            if w.getframerate() != SAMPLE_RATE or w.getnchannels() != 1:
+                msg = f"须为 16k mono wav(实际 {w.getframerate()}Hz/{w.getnchannels()}ch): {wav}"
+                raise TranscribeError(msg)
+            pcm = np.frombuffer(w.readframes(w.getnframes()), dtype="<i2")
+    except wave.Error as e:
+        msg = f"不是合法 wav: {wav}({e})"
+        raise TranscribeError(msg) from e
+    return pcm.astype(np.float32) / 32768.0

earshot/transcribe_cloud.py

@@ -0,0 +1,76 @@
+"""云端转写:复用 exomind 服务端 /transcribe/upload + /transcribe/status(dashscope)。"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import httpx
+
+from earshot.config import Settings
+
+POLL_INTERVAL_S = 3.0
+DEFAULT_TIMEOUT_S = 900.0
+UPLOAD_TIMEOUT_S = 120.0
+
+
+class CloudTranscribeError(RuntimeError):
+    """云端转写失败(未配置凭据 / 上传失败 / 转写失败 / 超时)。"""
+
+
+def transcribe_cloud(wav: Path, settings: Settings, timeout_s: float = DEFAULT_TIMEOUT_S) -> str:
+    """上传 wav 并轮询至转写完成。
+
+    Args:
+        wav: 音频文件(16k wav;服务端另收 .aac/.mp3/.m4a)。
+        settings: 含 exomind_base_url / api_key 的配置。
+        timeout_s: 轮询总预算。
+
+    Returns:
+        转写全文。
+
+    Raises:
+        CloudTranscribeError: 任一环节失败。
+    """
+    if not settings.exomind_api_key:
+        msg = "未配置 exomind 凭据(先 `exomind login` 生成 ~/.exomind/config.json,或设 EXOMIND_API_KEY)"
+        raise CloudTranscribeError(msg)
+    base = settings.exomind_base_url
+    headers = {"Authorization": f"Bearer {settings.exomind_api_key}"}
+
+    try:
+        with wav.open("rb") as f:
+            resp = httpx.post(
+                f"{base}/transcribe/upload",
+                files={"file": (wav.name, f, "audio/wav")},
+                headers=headers,
+                timeout=UPLOAD_TIMEOUT_S,
+            )
+    except httpx.HTTPError as e:
+        msg = f"上传失败: {e}"
+        raise CloudTranscribeError(msg) from e
+    if resp.status_code != 200:
+        msg = f"上传被拒({resp.status_code}): {resp.text[:300]}"
+        raise CloudTranscribeError(msg)
+    task_id = resp.json().get("task_id")
+    if not task_id:
+        msg = f"响应缺 task_id: {resp.text[:300]}"
+        raise CloudTranscribeError(msg)
+
+    deadline = time.monotonic() + timeout_s
+    while time.monotonic() < deadline:
+        try:
+            r = httpx.get(f"{base}/transcribe/status", params={"task_id": task_id}, headers=headers, timeout=30.0)
+        except httpx.HTTPError as e:
+            msg = f"轮询失败: {e}"
+            raise CloudTranscribeError(msg) from e
+        payload = r.json()
+        status = payload.get("status")
+        if status == "done":
+            return str(payload.get("text") or "")
+        if status == "failed":
+            msg = f"转写失败: {payload.get('error', '未知错误')}"
+            raise CloudTranscribeError(msg)
+        time.sleep(POLL_INTERVAL_S)
+    msg = f"转写超时({timeout_s:.0f}s),task_id={task_id}"
+    raise CloudTranscribeError(msg)