本地音视频转文字

概述

本地语音转文字 · Local Speech to Text

一句话定位：音频视频丢进来，逐字稿和台账长出来——五角色流水线把「装环境 → 转 wav → 出逐字稿 → 记台账」全链路接管，全程本地处理，数据不出本机。

始终使用与用户相同的语言回复。

定位与角色

角色卡在 references/ 下（role-orchestrator / role-installer / role-audio / role-transcriber / role-stats），派发时按角色卡首行的声明格式来。

能力矩阵

已固化的三个实战坑

适用人群与触发场景

• 每天有会议录音、访谈、播客、课程视频要出文字稿，并想按日期沉淀成档案的人。
• 触发场景：用户说「把这个录音转成文字」「帮我把这批视频转写一下」「看看这个月转了多少」「把昨天的会议纪要出个逐字稿」；或直接丢文件过来。

平台支持

首次拿到本技能（换机器/换平台）先跑安装员体检：

python3 scripts/doctor.py --check-only     # Windows: py -3 scriptsdoctor.py --check-only

安装 / 卸载（可选，默认装到用户技能目录）：

python3 scripts/install.py                 # 安装
python3 scripts/install.py --check         # 检查是否已装
python3 scripts/install.py --uninstall     # 卸载

快速开始

1. 首次使用：请用户给一个工作根目录的绝对路径（如 ~/Documents/asr-archive），然后登记：

   python3 scripts/lst.py init --root <用户指定的绝对路径>

以后所有档案、台账都放在该目录；每次会话先跑 lst.py root 复述确认（未登记时先问，不要猜）。

1. 首次（或换机器）：派安装员 doctor.py 三查三装，全绿再开工。
2. 日常转写：走「总管编排 → 音频处理员 → 文字输出员 → 统计员」四步（见下），或总管直接一键：

   python3 scripts/lst.py run <文件1> <文件2> --date 2026-10-07

协作流程（总管按此编排）

第一步 · 总管编排

• 确认根目录（首次必问）→ init；环境没验过先派安装员。
• 收齐三件事：文件路径清单 + 业务日期（默认今天）+ 模型偏好（默认 small）。
• 依次派发下面三个角色；每步验收退出码，失败按排障处理，不静默重试超过 2 次。

第二步 · 音频处理员

python3 scripts/lst.py ingest <文件…> --date 2026-10-07   # 收料复制进 raw/
python3 scripts/lst.py convert --date 2026-10-07          # 转标准 wav 进 audio/

• 相同文件自动跳过，同名不同内容自动 -2 后缀；失败记 failed 不拖垮整批。
• 默认带响度归一化：先测原片 LUFS，偏离 -16 LUFS 超过 1.5 LU 才归一化（已知合格的原片不折腾，--no-norm 可关，--lufs 换目标）。
• 产出：audio/<名称>.16000hz.wav + 台账里的时长、原片响度、是否归一化。

第三步 · 文字输出员

python3 scripts/lst.py transcribe --date 2026-10-07 [--model small] [--language zh]

• 只转 converted 状态的文件；产出 asr/<名称>.txt（头部元信息 + [00:01:23] 段落 时间戳，--plain 出纯文本）。
• 简体：未指定语言时先做 30 秒探测，是中文就自动挂 initial_prompt 引导简体（--prompt 自定义、--no-prompt 关闭）。
• 标点：输出自动做半角→全角修正（千分位/小数/时间码/网址受保护，--keep-ascii-punct 保留原样）。
• 长音频：超 15 分钟自动按静音点切 240 秒/段（也可 --chunk 240 手动），段失败自动降级重试，只丢一段不丢整片。
• 台账自动回写：asr 路径、状态 done、开始/结束时间、处理耗时、字数、处理备注。

第四步 · 统计员

python3 scripts/lst.py stats --date 2026-10-07   # 当日明细页 + 台账（不带 --date 重建全部）

• 产出 statics/2026-10-07/day.html 与 statics/ledger.html；有素材没统计的日期在日历上标「待统计」（不给死链）。
• 两条命令都退出码 0 才算完成。

目录约定（根目录由用户首次指定）

ROOT/
  2026-10-07/
    raw/      用户提供的原始文件（复制进来，原件不动）
    audio/    16000Hz/16bit wav
    asr/      逐字稿 txt
  statics/
    2026-10-07/  day.json（唯一数据源）+ day.html（当日明细页）
    ledger.html  台账日历页（年月切换、总计数、处理总时长）

命令速查

行为契约（总管监督）

• 先定目录：用户未给根目录绝对路径时，第一步永远是问，禁止默认塞到临时目录；登记后一直沿用，每次会话先 root 复述确认。
• 先装后跑：没验证过环境不派业务角色；安装员复查全绿才算就绪。
• 原件不动：用户文件只复制进 raw/，永不移动/删除原件；raw/ 副本也不手删（重做靠 --force）。
• 数据是唯一真相：day.json 是台账唯一数据源，页面全部由脚本生成；禁止手改 HTML、禁止手写逐字稿、禁止手工补统计数来"补交差"。
• 逐字稿不加工：模型原样输出，不润色、不摘要；要加工是用户后续的事。
• 失败如实记录：报错写进台账 error 字段并如实上报，绝不静默重试超过 2 次、绝不生成空壳页面。
• 日期归日期：--date 是业务日期，用户没指定就默认今天，不自作主张归到别的日期。
• 待统计不装死：有素材没 day.json 的日期，日历标「待统计」不可点击；补跑流程后标记自动消失。
• 页脚不可删改：所有页面底部固定一张品牌图片（data URI 内联），不带任何品牌文字；改模板时不要把文字加回去。
• 日历格子尺寸一律相同：台账日历用 table-layout:fixed 七列等宽 + 每格定高容器（td > .cell 定高 + overflow:hidden），改样式不要去掉这两条。
• 各角色不越界：总管不碰业务、安装员不碰文件、音频处理员不转写、文字输出员不改音、统计员不补数。

排障

FAQ

见 references/faq.md（含模型选择、镜像加速、失败重试、页面外发、零脚本模式等常见问题）。

English Summary

Local Speech to Text — a five-role, fully local audio/video transcription pipeline with a calendar ledger. Roles: an Orchestrator (scheduling and reporting only; asks the user for a workspace root directory on first use and keeps using it), an Installer (checks & installs FFmpeg, faster-whisper, and the Whisper model via Tsinghua PyPI mirror with HF-mirror fallback), an Audio Operator (copies sources into raw/ and converts everything to standard 16000 Hz / 16-bit mono WAV via FFmpeg), a Transcriber (faster-whisper transcription into timestamped plain-text transcripts under asr/), and a Statistician (writes per-day day.json and builds two self-contained HTML pages). Archive layout: ROOT/YYYY-MM-DD/{raw,audio,asr} plus ROOT/statics/ holding the ledger page (a month-switchable calendar showing per-month totals — file count and processed audio duration — plus cumulative totals, where data days link to their day page and unprocessed days are flagged "待统计" instead of dead links) and day pages (per-file rows linking to the source file, converted WAV and transcript, with audio duration, start/end times, processing time and status). Every page footer carries only the inlined data-URI QR image — no brand text. Three real-world pitfalls are solved in code: Chinese output defaults to Traditional characters (the skill auto-detects the language and prepends an initial_prompt forcing Simplified Chinese, then converts half-width punctuation to full-width while protecting thousands separators, decimals, timecodes and URLs); long recordings crash mid-run (audio over 15 minutes is split on silence points into ~240 s chunks and each failed chunk automatically retries in degraded mode, so one bad chunk no longer sinks a two-hour file); quiet source audio drops sentences (each file is measured for loudness and normalized to -16 LUFS via loudnorm only when it deviates more than 1.5 LU, with the measured value recorded in the ledger). CLI: lst.py init/root/ingest/convert/transcribe/stats/run/selftest + doctor.py + install.py. Works on Windows (py -3), macOS, Linux and HarmonyOS (Linux-compat detection). Everything stays on-device — no uploads. Single-file failures never break the batch — errors are recorded in the ledger and retried automatically on re-run; redo requires explicit --force. CLI: lst.py init/root/ingest/convert/transcribe/stats/run/selftest + doctor.py + install.py. Works on Windows (py -3), macOS, Linux and HarmonyOS (Linux-compat detection). Everything stays on-device — no uploads.

品牌：瑆皓科技 · 技术支持