earshot-cli 0.1.0__tar.gz

earshot_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: uv sync
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+      - name: Type check
+        run: uv run mypy
+      - name: Test
+        run: uv run pytest

earshot_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Trusted Publishing(OIDC):PyPI 侧注册 pending publisher 后免长期 token。
+# 注册路径:pypi.org/manage/account/publishing → owner=helloworldtang
+# repo=earshot workflow=publish.yml environment=pypi project=earshot-cli
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  id-token: write  # OIDC
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: uv build
+      - name: Publish
+        run: uv publish

earshot_cli-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# 模型与录音产物(不进仓)
+models/
+*.wav
+*.m4a
+*.mp3
+*.aac

earshot_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jackie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

earshot_cli-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: earshot-cli
+Version: 0.1.0
+Summary: 旁听剪藏:跨平台桌面端系统声录制 → 本地转写 → 投递知识库(默认 ExoMind,可插拔)
+Project-URL: Homepage, https://github.com/helloworldtang/earshot
+Project-URL: Repository, https://github.com/helloworldtang/earshot
+Project-URL: Issues, https://github.com/helloworldtang/earshot/issues
+Author: Jackie
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asr,bilibili,cli,knowledge-base,sensevoice,subtitle,transcription
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: imageio-ffmpeg>=0.5
+Requires-Dist: numpy>=1.26
+Requires-Dist: onnxruntime<1.29,>=1.28.0
+Requires-Dist: sherpa-onnx>=1.13.8
+Requires-Dist: soundcard>=0.4.3
+Requires-Dist: soxr>=0.5
+Requires-Dist: yt-dlp>=2025.1
+Description-Content-Type: text/markdown
+
+# earshot
+
+旁听剪藏:**听到的,都能进知识库。**
+
+听 B站/视频号/播客/讲座时开着它,听完 `Ctrl-C`,录音自动转写为 Markdown 并投递到你的知识库(默认 [ExoMind 知识飞轮](https://exomind.ai-as.cn),可插拔任意 webhook)。纯端侧转写,无限流、零 API 费用。
+
+```
+系统声音 ──录制──> 16k wav ──silero VAD 切段──> SenseVoice 端侧识别(实时字幕) ──> Markdown ──> 投递(exomind / webhook / 仅存档)
+视频链接 ──yt-dlp──> 平台字幕(ai-zh/CC) ────────────────────────────┘(高信噪比路线)
+```
+
+## 安装(开箱即用)
+
+```bash
+uv tool install earshot-cli   # 或 pipx install earshot-cli;安装后命令名是 earshot
+earshot doctor                # 环境自检
+```
+
+源码安装请**锁版本 tag**,不要引滚动的 `main`(消费方 `uv sync`/`pip install` 会隐性升级到未审阅代码;升级应当是显式改版本号的决策):
+
+```bash
+uv tool install "earshot-cli @ https://github.com/helloworldtang/earshot/archive/refs/tags/v0.1.0.tar.gz"
+```
+
+- **零系统依赖**:ffmpeg 已随 Python wheel 内置([imageio-ffmpeg](https://pypi.org/project/imageio-ffmpeg),MoviePy 同款),无需 brew/apt。
+- **模型首次运行自动下载**:SenseVoice int8 + silero VAD(~230MB,默认走 hf-mirror,`HF_ENDPOINT` 可覆盖),装完不再下。
+- **投递免装 CLI**:默认直连 ExoMind HTTP API(复用 `~/.exomind/config.json` 凭据);没有凭据但有 exomind CLI 时自动回退;也支持任意 webhook。
+
+### 平台采集矩阵
+
+| 平台 | 系统声采集 | 额外步骤 |
+|---|---|---|
+| Windows | WASAPI loopback(原生) | 无 |
+| Linux | PulseAudio/PipeWire `.monitor` | 无 |
+| macOS | 无原生环回 | 见下方「macOS 三级台阶」,零配置即可用 |
+
+#### macOS 三级台阶(按门槛从低到高)
+
+1. **零配置·录屏路线**:听 Mac 上的内容时 `Cmd+Shift+5` 录屏(自带系统声),
+   听完 `earshot audio 录屏.mp4` —— 不装任何东西,今天就能用。
+2. **零配置·麦录兜底**:直接 `earshot listen`,未配置环回时自动退回内置麦克风
+   外放收音(豆包同款,音质一般但可用)。
+3. **一次性设置·内录(音质无损)**:`brew install blackhole-2ch`,在「音频 MIDI 设置」
+   新建**多输出设备**(BlackHole 2ch + 扬声器)并设为系统输出 —— 边听边录,终身受用。
+   装好后 earshot 自动选中,无需 `--device`。
+
+> macOS 下默认逻辑 = 取「当前默认扬声器的同名输入设备」;把多输出设备设为默认输出即可被自动选中。也可 `--device` 指定。
+
+## 使用
+
+```bash
+# 旁听模式:开录 → 听(实时字幕滚动) → Ctrl-C 完成 → 预览确认 → 投递
+earshot listen
+earshot listen --note "B站·xxx第3期"
+
+# B站等视频链接直拉字幕(高信噪比:无环境噪音/打断;AI 字幕需登录态)
+earshot video "https://www.bilibili.com/video/BVxxxx" --cookies-from-browser chrome
+
+# 已有音视频文件(录屏 mp4 / 语音 m4a / 播客 mp3)
+earshot audio recording.mp4 --title "通勤听书笔记" --deliver none
+
+# 补投/重投 outbox 里的笔记(如环境问题当时没投出去)
+earshot deliver ~/.earshot/outbox/20261030-xxxx.md
+
+# 列出采集设备 / 环境自检 / 清理过期留档
+earshot devices
+earshot doctor
+earshot clean --days 30
+```
+
+常用参数:`--title`(默认取首句截断40字)、`--tag`(可多次)、`--note`(来源备注写入脚注)、
+`--engine server`(改走云端 dashscope 转写,复用 `~/.exomind/config.json` 凭据)、
+`--deliver webhook --webhook <url>`(投递到任意知识库,POST JSON `{origin,title,content,tags}`)、
+`--deliver none`(只落 `~/.earshot/outbox/` 存档)。
+
+笔记留档:`~/.earshot/outbox/YYYYMMDD-HHMMSS-<标题>.md`。
+
+### 文件生命周期
+
+| 位置 | 内容 | 生命周期 |
+|---|---|---|
+| `~/.earshot/tmp/*.wav` | 录音中间产物 | 转写投递成功后**自动删除**(失败保留供排查) |
+| `~/.earshot/outbox/*.md` | 转写笔记留档 | **永久保留**(审计/重投兜底),`earshot clean --days 30` 手动清理 |
+
+投递前会先在终端**预览识别内容**,回车投递、`q` 放弃(笔记仍留档);`--yes` 跳过确认。等待服务端回执时 Ctrl-C = 不再等待(内容已提交,job 在服务端继续)。
+
+## 设计要点
+
+- **声音是最后的通用接口**:不依赖任何平台的开放性(B站字幕 API、视频号加密……都不碰),换平台零成本。
+- **端侧优先**:SenseVoice-small int8 纯 CPU 转写,1 小时音频约 1-2 分钟,无"服务用户多请稍后"。
+- **投递可插拔**:exomind CLI(复用其异步 job、轮询、client_key 幂等)/ webhook / 仅存档。
+- **平台差异只允许存在于 `capture.py`**:换采集方案不动上层。
+
+## 开发
+
+```bash
+uv sync                      # 含 dev 组(ruff/mypy/pytest)
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+测试不依赖模型与声卡;`tests/test_extract.py` 需要本机 ffmpeg(无则自动跳过)。
+
+## License
+
+MIT

earshot_cli-0.1.0/README.md

@@ -0,0 +1,107 @@
+# earshot
+
+旁听剪藏:**听到的,都能进知识库。**
+
+听 B站/视频号/播客/讲座时开着它,听完 `Ctrl-C`,录音自动转写为 Markdown 并投递到你的知识库(默认 [ExoMind 知识飞轮](https://exomind.ai-as.cn),可插拔任意 webhook)。纯端侧转写,无限流、零 API 费用。
+
+```
+系统声音 ──录制──> 16k wav ──silero VAD 切段──> SenseVoice 端侧识别(实时字幕) ──> Markdown ──> 投递(exomind / webhook / 仅存档)
+视频链接 ──yt-dlp──> 平台字幕(ai-zh/CC) ────────────────────────────┘(高信噪比路线)
+```
+
+## 安装(开箱即用)
+
+```bash
+uv tool install earshot-cli   # 或 pipx install earshot-cli;安装后命令名是 earshot
+earshot doctor                # 环境自检
+```
+
+源码安装请**锁版本 tag**,不要引滚动的 `main`(消费方 `uv sync`/`pip install` 会隐性升级到未审阅代码;升级应当是显式改版本号的决策):
+
+```bash
+uv tool install "earshot-cli @ https://github.com/helloworldtang/earshot/archive/refs/tags/v0.1.0.tar.gz"
+```
+
+- **零系统依赖**:ffmpeg 已随 Python wheel 内置([imageio-ffmpeg](https://pypi.org/project/imageio-ffmpeg),MoviePy 同款),无需 brew/apt。
+- **模型首次运行自动下载**:SenseVoice int8 + silero VAD(~230MB,默认走 hf-mirror,`HF_ENDPOINT` 可覆盖),装完不再下。
+- **投递免装 CLI**:默认直连 ExoMind HTTP API(复用 `~/.exomind/config.json` 凭据);没有凭据但有 exomind CLI 时自动回退;也支持任意 webhook。
+
+### 平台采集矩阵
+
+| 平台 | 系统声采集 | 额外步骤 |
+|---|---|---|
+| Windows | WASAPI loopback(原生) | 无 |
+| Linux | PulseAudio/PipeWire `.monitor` | 无 |
+| macOS | 无原生环回 | 见下方「macOS 三级台阶」,零配置即可用 |
+
+#### macOS 三级台阶(按门槛从低到高)
+
+1. **零配置·录屏路线**:听 Mac 上的内容时 `Cmd+Shift+5` 录屏(自带系统声),
+   听完 `earshot audio 录屏.mp4` —— 不装任何东西,今天就能用。
+2. **零配置·麦录兜底**:直接 `earshot listen`,未配置环回时自动退回内置麦克风
+   外放收音(豆包同款,音质一般但可用)。
+3. **一次性设置·内录(音质无损)**:`brew install blackhole-2ch`,在「音频 MIDI 设置」
+   新建**多输出设备**(BlackHole 2ch + 扬声器)并设为系统输出 —— 边听边录,终身受用。
+   装好后 earshot 自动选中,无需 `--device`。
+
+> macOS 下默认逻辑 = 取「当前默认扬声器的同名输入设备」;把多输出设备设为默认输出即可被自动选中。也可 `--device` 指定。
+
+## 使用
+
+```bash
+# 旁听模式:开录 → 听(实时字幕滚动) → Ctrl-C 完成 → 预览确认 → 投递
+earshot listen
+earshot listen --note "B站·xxx第3期"
+
+# B站等视频链接直拉字幕(高信噪比:无环境噪音/打断;AI 字幕需登录态)
+earshot video "https://www.bilibili.com/video/BVxxxx" --cookies-from-browser chrome
+
+# 已有音视频文件(录屏 mp4 / 语音 m4a / 播客 mp3)
+earshot audio recording.mp4 --title "通勤听书笔记" --deliver none
+
+# 补投/重投 outbox 里的笔记(如环境问题当时没投出去)
+earshot deliver ~/.earshot/outbox/20261030-xxxx.md
+
+# 列出采集设备 / 环境自检 / 清理过期留档
+earshot devices
+earshot doctor
+earshot clean --days 30
+```
+
+常用参数:`--title`(默认取首句截断40字)、`--tag`(可多次)、`--note`(来源备注写入脚注)、
+`--engine server`(改走云端 dashscope 转写,复用 `~/.exomind/config.json` 凭据)、
+`--deliver webhook --webhook <url>`(投递到任意知识库,POST JSON `{origin,title,content,tags}`)、
+`--deliver none`(只落 `~/.earshot/outbox/` 存档)。
+
+笔记留档:`~/.earshot/outbox/YYYYMMDD-HHMMSS-<标题>.md`。
+
+### 文件生命周期
+
+| 位置 | 内容 | 生命周期 |
+|---|---|---|
+| `~/.earshot/tmp/*.wav` | 录音中间产物 | 转写投递成功后**自动删除**(失败保留供排查) |
+| `~/.earshot/outbox/*.md` | 转写笔记留档 | **永久保留**(审计/重投兜底),`earshot clean --days 30` 手动清理 |
+
+投递前会先在终端**预览识别内容**,回车投递、`q` 放弃(笔记仍留档);`--yes` 跳过确认。等待服务端回执时 Ctrl-C = 不再等待(内容已提交,job 在服务端继续)。
+
+## 设计要点
+
+- **声音是最后的通用接口**:不依赖任何平台的开放性(B站字幕 API、视频号加密……都不碰),换平台零成本。
+- **端侧优先**:SenseVoice-small int8 纯 CPU 转写,1 小时音频约 1-2 分钟,无"服务用户多请稍后"。
+- **投递可插拔**:exomind CLI(复用其异步 job、轮询、client_key 幂等)/ webhook / 仅存档。
+- **平台差异只允许存在于 `capture.py`**:换采集方案不动上层。
+
+## 开发
+
+```bash
+uv sync                      # 含 dev 组(ruff/mypy/pytest)
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+测试不依赖模型与声卡;`tests/test_extract.py` 需要本机 ffmpeg(无则自动跳过)。
+
+## License
+
+MIT

earshot_cli-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "earshot-cli"
+version = "0.1.0"
+description = "旁听剪藏:跨平台桌面端系统声录制 → 本地转写 → 投递知识库(默认 ExoMind,可插拔)"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Jackie" }]
+keywords = ["transcription", "asr", "sensevoice", "bilibili", "subtitle", "knowledge-base", "cli"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: Chinese (Simplified)",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=1.26",
+    "sherpa-onnx>=1.13.8",
+    # 上界钉死:sherpa-onnx 的 Linux wheel 链接 onnxruntime VERS_1.28.2 符号版本,
+    # 1.29+ 会在 import 时报 version `VERS_1.28.2' not found(macOS 不受影响,同钉为一致)
+    "onnxruntime>=1.28.0,<1.29",
+    "soundcard>=0.4.3",
+    "httpx>=0.27",
+    # 平台 wheel 内置 ffmpeg 二进制(~60MB):系统没装 ffmpeg 也能跑(MoviePy 同款做法)
+    "imageio-ffmpeg>=0.5",
+    # 实时字幕:录音流 48k→16k 在线重采样(流式,不能等录完再重采样)
+    "soxr>=0.5",
+    # video 命令:提取B站等平台的元信息与字幕轨(纯 Python,自包含)
+    "yt-dlp>=2025.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/helloworldtang/earshot"
+Repository = "https://github.com/helloworldtang/earshot"
+Issues = "https://github.com/helloworldtang/earshot/issues"
+
+[project.scripts]
+earshot = "earshot.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.11",
+    "pytest>=8.3",
+    "ruff>=0.7",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/earshot"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src", "tests"]
+# sherpa-onnx / soundcard 未随 wheel 提供 py.typed —— 与其假装,不如显式忽略
+[[tool.mypy.overrides]]
+module = ["sherpa_onnx.*", "soundcard.*", "onnxruntime.*", "imageio_ffmpeg.*", "soxr.*", "yt_dlp.*"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["tests.*"]
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

earshot_cli-0.1.0/scripts/download_models.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# 拉取 earshot 本地转写模型(int8 优先,不进仓)。
+#
+# 产物布局(earshot 默认读 ~/.earshot/models,可用 EARSHOT_MODEL_ROOT 覆盖):
+#   models/asr/model.int8.onnx   SenseVoice-small int8(zh/en/ja/ko/yue,含标点+ITN)
+#   models/asr/tokens.txt
+#   models/vad/silero_vad.onnx
+#
+# 源:HF(默认走 hf-mirror,本机实测 GitHub release 直连不通)。
+# 用法: ./scripts/download_models.sh [目标目录,默认 ~/.earshot/models]
+#       可 HF_ENDPOINT=https://huggingface.co 覆盖
+set -euo pipefail
+
+HF="${HF_ENDPOINT:-https://hf-mirror.com}"
+ROOT="${1:-$HOME/.earshot/models}"
+
+ASR_REPO="csukuangfj/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17"
+VAD_REPO="onnx-community/silero-vad"
+
+fetch() {  # fetch <repo> <remote-file> <dest-relpath>
+  local repo="$1" remote="$2" dest="$ROOT/$3"
+  mkdir -p "$(dirname "$dest")"
+  if [ -f "$dest" ]; then echo "skip  $3 (已存在)"; return; fi
+  echo "get   $3"
+  curl -L --fail --retry 3 -o "$dest.part" "$HF/$repo/resolve/main/$remote"
+  mv "$dest.part" "$dest"
+}
+
+# ASR:SenseVoice int8(model ~230MB + tokens)
+fetch "$ASR_REPO" model.int8.onnx asr/model.int8.onnx
+fetch "$ASR_REPO" tokens.txt       asr/tokens.txt
+
+# VAD:silero
+fetch "$VAD_REPO" onnx/model.onnx  vad/silero_vad.onnx
+
+echo "done: $ROOT"
+du -sh "$ROOT"/* 2>/dev/null || true

earshot_cli-0.1.0/src/earshot/__init__.py

@@ -0,0 +1,7 @@
+"""earshot:旁听剪藏 —— 听到的都能进知识库。
+
+跨平台桌面端:系统声环回录制(macOS 需 BlackHole)→ 端侧 VAD+ASR 转写
+→ 组装 Markdown → 投递(默认 exomind CLI,可插拔 webhook)。
+"""
+
+__version__ = "0.1.0"

earshot_cli-0.1.0/src/earshot/capture.py

@@ -0,0 +1,148 @@
+"""系统声环回采集(soundcard):平台差异只允许存在于此模块。
+
+- Windows: WASAPI loopback,免驱
+- Linux: PulseAudio ``.monitor``,免驱
+- macOS: 无原生环回,需安装 BlackHole 并(建议用多输出设备)设为输出
+"""
+
+from __future__ import annotations
+
+import platform
+import warnings
+import wave
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+# soundcard 在 macOS import 时必发一条"不支持环回"警告,属已知事实(BlackHole 方案的前提),
+# 压掉以免吓到用户 —— 必须在 import soundcard 之前过滤
+warnings.filterwarnings("ignore", message=".*loopback recording functionality.*", category=Warning)
+import soundcard as sc  # noqa: E402
+
+SAMPLE_RATE = 48000  # 环回设备主流采样率;重采样交给 ffmpeg
+BLOCK_FRAMES = 4800  # 100ms/块,兼顾电平刷新频率与 CPU
+BLACKHOLE_HINT = "blackhole"
+
+
+def list_capture_devices() -> list[tuple[str, bool]]:
+    """列出全部输入设备。
+
+    Returns:
+        ``(设备名, 是否环回)`` 列表。
+    """
+    return [(m.name, bool(m.isloopback)) for m in sc.all_microphones(include_loopback=True)]
+
+
+def blackhole_missing_hint() -> str | None:
+    """macOS 上未发现 BlackHole 设备时的安装指引,其他平台返回 None。"""
+    if platform.system() != "Darwin":
+        return None
+    names = " ".join(name for name, _ in list_capture_devices()).lower()
+    if BLACKHOLE_HINT in names:
+        return None
+    return (
+        "未检测到 BlackHole。安装: brew install blackhole-2ch;"
+        "再在「音频 MIDI 设置」建多输出设备(BlackHole+扬声器)并设为系统输出,"
+        "即可边听边录。"
+    )
+
+
+def pick_loopback(hint: str | None = None) -> Any:
+    """选采集设备:默认取当前默认扬声器的同名环回/输入设备。
+
+    Args:
+        hint: 设备名子串,大小写不敏感;None 时走默认逻辑。
+
+    Returns:
+        soundcard 的 Mic 对象。
+
+    Raises:
+        LookupError: 找不到匹配设备。
+    """
+    mics = sc.all_microphones(include_loopback=True)
+    if hint:
+        low = hint.lower()
+        for m in mics:
+            if low in m.name.lower():
+                return m
+        msg = f"未找到匹配「{hint}」的输入设备(earshot devices 查看)"
+        raise LookupError(msg)
+    speaker = sc.default_speaker()
+    for m in mics:
+        if m.name == speaker.name:  # macOS:BlackHole 输出即同名输入;Win/Linux:同名环回
+            return m
+    msg = f"默认扬声器「{speaker.name}」没有可采集的环回设备。{blackhole_missing_hint() or ''}"
+    raise LookupError(msg)
+
+
+def pick_device(hint: str | None = None) -> tuple[Any, str]:
+    """选采集设备,带麦录兜底(零门槛优先于零音质损失)。
+
+    优先级:hint 匹配 > 默认扬声器环回 > 任意环回 > 默认麦克风(外放收音,豆包同款)。
+
+    Args:
+        hint: 设备名子串;None 走默认回退链。
+
+    Returns:
+        ``(mic, mode_label)``,mode_label 用于向用户说明当前采集方式。
+
+    Raises:
+        LookupError: 全链条找不到可用设备。
+    """
+    try:
+        return pick_loopback(hint), "环回内录(音质无损)"
+    except LookupError:
+        if hint:
+            raise  # 显式指定的设备找不到,不擅自换
+    for m in sc.all_microphones(include_loopback=True):
+        if m.isloopback:
+            return m, f"环回内录(音质无损,设备:{m.name})"
+    mic = sc.default_microphone()
+    if mic is None:
+        msg = "未找到任何可用输入设备(earshot devices 查看)"
+        raise LookupError(msg)
+    fallback = f"麦克风收音(外放收音,豆包同款;配 BlackHole 可内录)设备:{mic.name}"
+    return mic, fallback
+
+
+def record_to_wav(
+    mic: Any,
+    out_wav: Path,
+    on_level: Callable[[float], None] | None = None,
+    on_audio: Callable[[np.ndarray], None] | None = None,
+) -> float:
+    """录制到 wav(pcm16/48k/mono),Ctrl-C 停止。
+
+    Args:
+        mic: pick_device 返回的设备。
+        out_wav: 输出路径。
+        on_level: 可选电平回调(rms,0~1 区间参考),用于终端电平条。
+        on_audio: 可选音频块回调(float32 mono),实时转写经此喂入。
+
+    Returns:
+        实际录制时长(秒)。
+    """
+    total_frames = 0
+    with wave.open(str(out_wav), "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(SAMPLE_RATE)
+        try:
+            with mic.recorder(samplerate=SAMPLE_RATE) as rec:
+                while True:
+                    data = rec.record(numframes=BLOCK_FRAMES)
+                    mono = data.mean(axis=1) if data.ndim > 1 else np.asarray(data, dtype=np.float32)
+                    if mono.size == 0:
+                        continue
+                    if on_level is not None:
+                        on_level(float(np.sqrt(np.mean(np.square(mono)))))
+                    if on_audio is not None:
+                        on_audio(mono)
+                    pcm16 = (np.clip(mono, -1.0, 1.0) * 32767.0).astype("<i2")
+                    w.writeframes(pcm16.tobytes())
+                    total_frames += mono.size
+        except KeyboardInterrupt:
+            pass  # Ctrl-C = "点完成"
+    return total_frames / SAMPLE_RATE