scribe — 本地录音转写

音频/视频 → 带时间戳文字稿。全本地、常驻服务、Agent 可自动调用。

快速使用（Skill 自包含，无需外部项目）

# 首次安装（新机器/新环境，一次）——建 venv + 装 funasr/torch + 下载模型 897MB
python3 scripts/setup.py

# 启动服务（常驻，http://localhost:8399）
python3 scripts/start.py --detach

# Agent 调用（上传转写 + 下载留存，一条命令）
python3 scripts/scribe.py 会议录音.m4a --diarize --format all --out ~/输出目录

三种入口（同一服务）

Agent 调用闭环（核心用法）

用户丢录音文件
  → python3 scripts/scribe.py <文件> [--diarize] [--format txt|srt|json|all] [--out DIR]
      → ① 检测服务没起 → 自动启动并等待就绪（≤180s）
      → ② POST /api/transcribe 上传 → 转写
      → ③ GET /api/download 下载产物 → 存到 --out
  → Agent 读 TXT/JSON 做会议纪要/存档/知识库留存

API（Agent 直接调用也行）

GET  /api/health         # 服务状态（ok/base_dir/disk_free_gb/模型信息）
POST /api/transcribe     # multipart: file=音频; query: ?diarize=true（说话人标记）
GET  /api/download/{项目}/{文件}.txt|srt|json   # 下载产物
GET  /api/projects       # 历史转写项目
GET  /api/projects/{项目}/files   # 项目产物列表
DELETE /api/projects/{项目}       # 删除项目（不可恢复）
WS   /ws/live            # 实时录音转写（浏览器用）

首次环境搭建（唯一前置）

cd ~/.exflower/skills/scribe
python3 scripts/setup.py
# 做什么: ① 建 .venv + 装依赖（funasr/torch/fastapi，5-15 分钟）
#         ② 下载模型 SenseVoice-Small 897MB + FSMN-VAD + CAM++（modelscope 国内源）
#         ③ 验证环境就绪

• .venv 绑定 CPU 架构：换机器/换架构重跑 setup.py（模型和代码通用）
• 模型走 modelscope（阿里，国内快）；断网可重跑续传
• 服务端无 OCR 平台分支，纯 CPU 推理 Mac/Windows 均可

执行要点（为什么这么做）

1. 服务常驻而非每次现转：模型加载 3-15 秒，之后秒级响应——start.py 拉起后一直挂着（日志 data/server.log）
2. scribe.py 自动管理服务：没起就 spawn + 轮询 health，Agent 无需关心服务状态
3. diarize 是 query 参数（?diarize=true），不是 form 字段（FastAPI 坑，已踩）
4. 产物三格式：TXT（带时间戳句子）/ SRT（字幕）/ JSON（结构化 sentences 含起止秒）
5. 转写质量：SenseVoice 中文强；英文词偶发不准（"AI"→"爱"）——重要英文术语建议画面/人工校对
6. 实时录音逐句落盘：每闭合一句立即追加写入项目目录 txt，崩溃/断电/关页不丢已转内容（断线再兜底补全量 srt/json）

已知坑（详见 references/已知坑.md）

• Python 3.9 注解要 from __future__ import annotations
• CAM++ "Loading remote code failed" 是无害警告（回退内置类，实测加载成功）
• TTS 合成音频声纹区分度低，说话人聚类可能归并；真人音频区分可靠
• 上传临时文件/缓存钉在 skill 内 data/（不写系统盘）

系统依赖