会议记录这件事很多团队都卡在同一个地方会上聊得热火朝天会后整理笔记却要花掉双倍时间。有人用付费会议软件自带的转写功能又担心会议内容被上传到云端。最近看到 “Show HN” 上有人发布了一个叫 Loofah 的工具定位非常清晰——把会议录音自动转写成文字直接落地成一个本地 Markdown 知识库Vault。这正好踩中了我的兴趣点本地优先、纯文本存储、方便检索。本文就沿着这条思路完整拆解“会议音频 → 本地 Markdown Vault”的整个技术链路并给出一个可以照抄的 Python 实现。不管你是经常开会但不爱记笔记的后端开发还是想给团队搭一套隐私友好的会议知识库这篇文章都能直接用上。我们不做概念复读直接讲清楚原理、代码、配置和坑。1. 背景与核心概念1.1 会议转录工具解决了什么问题会议转录工具的核心任务只有一个把音频里的口语内容变成可检索的文字。听起来简单实际上包含一条完整链路音频采集、降噪处理、语音识别、文字整理、结构化存储。过去我们做会议记录无非是边听边打字或者录音后再回放。前者漏掉大量细节后者回放浪费时间。转录工具的价值在于它让“整理会议纪要”这件事从人工行为变成自动化流水线并且输出的是结构化文本方便后续检索、归档和分享。1.2 什么是本地 Markdown VaultVault 是笔记软件圈子里的常见叫法特指一个以本地目录为核心的笔记集合里面所有笔记都是纯文本 Markdown 文件。最有代表性的工具是 Obsidian它本身不绑定云端全部数据都保存在你指定的文件夹里。用 Markdown Vault 存会议转录内容有四个明显优势纯文本格式不依赖特定软件任何编辑器都能打开。支持双链可以在会议记录里直接[[链接到]]相关项目文档。Git 友好整个知识库可以通过 Git 做版本管理。本地存储隐私可控不需要担心会议内容被第三方平台处理。1.3 Loofah 的定位从 “Show HN: Loofah, meeting transcription into a local Markdown vault” 这个标题看Loofah 是一个“把会议转录直接落成本地 Markdown 知识库”的工具。这种工具的想象力不在于语音识别本身而在于后面那半段如何把转录文本加工成一张干净、有结构、可长期复用的笔记。这其实才是普通人做会议记录时真正缺的东西。1.4 与云端转录方案的区别市面上很多会议软件自带转录功能比如 Zoom 的 Cloud Recording、飞书妙记、腾讯会议转写。但这类服务有一个共同特点音频默认上传到云端处理。对企业来说这可能构成合规风险对个人开发者来说免费额度通常也有限。Loofah 这类“本地转录工具”则把语音识别放在本地执行音频文件不出本机转录结果直接以 Markdown 形式落到你指定的目录。它的代价是需要自己配环境、装语音模型好处是数据完全可控而且笔记格式完全由自己定义。明白了这些我们就能开始动手了。2. 系统架构与核心流程2.1 整体 Pipeline我先用文字画一下这个系统的完整流水线方便你在大脑里建立整体认知会议录音MP3/WAV/M4A ↓ 音频预处理格式转换、采样率统一、分片 ↓ 语音识别Whisper / 本地语音模型 ↓ 原始转录文本带时间戳 ↓ 结构化整理生成标题、摘要、章节、待办 ↓ Markdown 渲染frontmatter 正文 ↓ 写入本地 Vault按日期/主题组织文件2.2 核心组件拆解整个系统可以拆成五个核心模块音频输入层负责读取录音文件支持常见格式。预处理层统一采样率、声道必要时切割长音频。识别层调用语音模型输出带时间戳的文本。结构化层对原始转录内容做后处理提取会议标题、摘要、决策、待办事项。输出层按预设模板生成 Markdown写入 Vault 目录。2.3 技术选型为什么选择 Whisper语音识别模型选择上目前最主流的是 OpenAI 开源的 Whisper 系列模型。它支持多语言对中文识别效果不错能在本地 CPU/GPU 上运行完全符合“本地优先”的定位。Whisper 不是 SaaS 接口而是一套开源模型权重通过 Python 库调用即可。如果机器没有 GPU可以用tiny或base模型如果追求精度可以换medium甚至large。这是 Loofah 类工具能落地的技术基础。3. 环境准备与依赖安装3.1 运行环境本文示例以常见环境为例重点演示配置思路版本需要根据你的项目实际情况调整。推荐环境如下macOS 12 / Ubuntu 20.04 / Windows 10WSL 更稳Python 3.9FFmpegOpenAI Whisper 开源模型3.2 安装 FFmpegWhisper 处理音频时依赖 FFmpeg 做解码所以这一步必须先装好。macOS 安装方式brew install ffmpegUbuntu/Debian 安装方式sudo apt update sudo apt install ffmpegWindows 用户可以从 FFmpeg 官网下载可执行文件并把bin目录加入系统 PATH。安装完成后在终端执行下面命令验证ffmpeg -version如果能正常输出版本信息说明安装成功。3.3 创建 Python 虚拟环境为项目单独创建虚拟环境是一个好习惯避免污染全局 Python 环境。mkdir loofah-demo cd loofah-demo python3 -m venv venv source venv/bin/activateWindows 下激活命令是venv\Scripts\activate3.4 安装 Whisper 和相关依赖pip install openai-whisper装完后可以验证一下whisper --help如果正常输出帮助信息说明 Whisper 安装成功。另外还要安装一个用于处理 Markdown frontmatter 的库pip install python-frontmatter3.5 模型选择建议Whisper 官方提供多种参数规模的模型模型显存需求速度准确率tiny约 1 GB最快较低base约 1 GB快一般small约 2 GB中等较好medium约 5 GB慢很好large约 10 GB最慢最好对中文会议记录我建议至少从small开始尝试。tiny和base对中文口语的处理能力比较弱会出现较多同音字错误。如果机器配置允许medium是一个准确率与速度均衡的选择。模型不需要手动下载第一次调用时 Whisper 会自动下载到本地缓存目录。4. 核心功能模块实现4.1 音频预处理音频预处理的目的有三个统一格式、统一采样率、降低背景噪音带来的识别误差。Whisper 内部会自动把输入音频重采样成 16kHz但我们在外部做一次格式统一可以避免某些异常音频格式导致的解码失败。下面是用 FFmpeg 把任意格式转成 Whisper 更友好的 WAV 文件的命令ffmpeg -i input.m4a -ar 16000 -ac 1 -c:a pcm_s16le output.wav参数说明-ar 16000采样率设为 16kHz。-ac 1合并为单声道。-c:a pcm_s16le使用 PCM 16 位小端编码也就是 WAV 标准格式。这种音频格式在语音识别任务里是通用做法很多语音工具都以 16kHz 单声道作为标准输入。4.2 语音识别转写调用 Whisper 转写音频的代码非常简洁。在写完整项目之前先看一个最小片段import whisper model whisper.load_model(small) result model.transcribe(output.wav, languagezh, verboseFalse) for segment in result[segments]: print(segment[start], segment[end], segment[text])这段代码干了三件事加载small模型。转写output.wav指定语言为中文。遍历segments打印每一段文本的起始时间、结束时间和文字内容。segments是 Whisper 返回的时间戳分段后面生成 Markdown 时这些时间戳是我们的重点素材。4.3 生成结构化 Markdown转录结果本身只是纯文本直接丢进 Vault 也能用但可读性很差。所以我们要做一层结构整理生成 YAML frontmatter记录会议日期、会议主题、参与人、标签。提取摘要简单场景下可以取识别文本的前几句话。按时间戳分段把长文本拆成带时间标记的小段落。待办事项识别找包含“待办”“后续”“需要跟进”等关键词的句子。Markdown frontmatter 是 Obsidian 识别元数据的方式写在文件开头用---包裹--- title: 周会 - 后端架构评审 date: 2025-04-10 tags: - 会议记录 - 后端 attendees: - 张三 - 李四 ---5. 完整实战案例现在把上面的模块组合成一个完整的命令行工具。这个工具就是仿照 Loofah 思路的简化实现输入录音文件输出一条结构化 Markdown 笔记到本地 Vault。5.1 项目结构loofah-demo/ ├── venv/ ├── transcribe.py └── vault/ └── meetings/vault/meetings/目录就是我们本地 Markdown Vault 里的会议归档区。5.2 完整代码文件路径loofah-demo/transcribe.py#!/usr/bin/env python3 # -*- coding: utf-8 -*- 会议转录工具将录音文件转写为 Markdown 笔记写入本地 Vault。 用法: python transcribe.py 录音文件.m4a --title 周会-后端架构评审 依赖: openai-whisper python-frontmatter import argparse import re import subprocess import sys from datetime import datetime from pathlib import Path import frontmatter import whisper VAULT_DIR Path(__file__).parent / vault / meetings KEYWORDS_TODO [待办, 后续, 需要跟进, TODO, 接下来要] def convert_audio(input_path: Path, output_path: Path) - None: 将任意音频转成 16kHz 单声道 WAV便于 Whisper 处理。 cmd [ ffmpeg, -y, -i, str(input_path), -ar, 16000, -ac, 1, -c:a, pcm_s16le, str(output_path), ] subprocess.run(cmd, checkTrue, capture_outputTrue) def transcribe(audio_path: Path, model_name: str small) - dict: 使用 Whisper 转写音频返回完整结果。 print(f[INFO] 加载语音模型: {model_name}) model whisper.load_model(model_name) print(f[INFO] 开始转写: {audio_path}) result model.transcribe(str(audio_path), languagezh, verboseFalse) return result def format_timestamp(seconds: float) - str: 将秒数转换为 HH:MM:SS 格式。 hours int(seconds // 3600) minutes int((seconds % 3600) // 60) secs int(seconds % 60) return f{hours:02d}:{minutes:02d}:{secs:02d} def extract_abstract(segments: list) - str: 从转录结果中提取摘要简单策略拼接前 3 段文本前 80 字。 text .join(seg[text].strip() for seg in segments[:3]) return text[:80] ... if len(text) 80 else text def extract_todos(segments: list) - list: 通过关键词匹配提取待办事项。 todos [] for seg in segments: text seg[text].strip() if any(k in text for k in KEYWORDS_TODO): timestamp format_timestamp(seg[start]) todos.append(f- [ ] ({timestamp}) {text}) return todos def build_markdown( title: str, audio_name: str, result: dict, ) - str: 构建 Markdown 内容包含 frontmatter 与正文。 segments result[segments] abstract extract_abstract(segments) todos extract_todos(segments) now datetime.now() meeting_date now.strftime(%Y-%m-%d) tags [会议记录, 转录] post frontmatter.Post() post[title] title post[date] meeting_date post[source] audio_name post[tags] tags post[abstract] abstract content_lines [ ## 摘要, , abstract, , ## 内容, , ] for seg in segments: ts_start format_timestamp(seg[start]) ts_end format_timestamp(seg[end]) text seg[text].strip() content_lines.append(f### [{ts_start} - {ts_end}]) content_lines.append() content_lines.append(text) content_lines.append() if todos: content_lines.extend([## 待办事项, ]) content_lines.extend(todos) content_lines.append() post.content \n.join(content_lines) return frontmatter.dumps(post) def save_note(markdown_text: str, title: str) - Path: 将 Markdown 写入 Vault 目录文件名带日期前缀。 VAULT_DIR.mkdir(parentsTrue, exist_okTrue) safe_title re.sub(r[\\/:*?|], _, title) today datetime.now().strftime(%Y%m%d) file_path VAULT_DIR / f{today}-{safe_title}.md # 如果文件已存在自动加后缀避免覆盖 counter 1 while file_path.exists(): file_path VAULT_DIR / f{today}-{safe_title}-{counter}.md counter 1 file_path.write_text(markdown_text, encodingutf-8) print(f[OK] 笔记已保存: {file_path}) return file_path def main(): parser argparse.ArgumentParser(description会议转录工具输出 Markdown 到本地 Vault) parser.add_argument(audio, help录音文件路径) parser.add_argument(--title, requiredTrue, help会议标题) parser.add_argument(--model, defaultsmall, helpWhisper 模型名称) args parser.parse_args() audio_path Path(args.audio) if not audio_path.exists(): print(f[ERROR] 文件不存在: {audio_path}) sys.exit(1) temp_wav audio_path.with_suffix(.wav) print(f[INFO] 预处理音频: {audio_path}) convert_audio(audio_path, temp_wav) result transcribe(temp_wav, model_nameargs.model) markdown_text build_markdown(args.title, audio_path.name, result) save_note(markdown_text, args.title) if __name__ __main__: main()这段代码能直接跑下面解释几个关键设计convert_audio()通过 FFmpeg 子进程统一音频格式。transcribe()加载 Whisper 模型并执行识别返回完整结果对象。format_timestamp()将 Whisper 返回的秒数格式化成HH:MM:SS。extract_todos()通过关键词粗略提取待办实际项目中可以换成更聪明的规则或调用 LLM。save_note()写入 Markdown 时做文件重名保护不会覆盖已有笔记。5.3 运行与验证准备一个会议录音文件meeting.m4a执行python transcribe.py meeting.m4a --title 周会-后端架构评审 --model small如果一切正常你会看到类似下面的输出[INFO] 预处理音频: meeting.m4a [INFO] 加载语音模型: small [INFO] 开始转写: meeting.wav [OK] 笔记已保存: /path/to/loofah-demo/vault/meetings/20250410-周会-后端架构评审.md5.4 预期输出示例生成的 Markdown 文件内容大致长这样--- title: 周会-后端架构评审 date: 2025-04-10 source: meeting.m4a tags: - 会议记录 - 转录 abstract: 我们今天主要讨论订单服务拆分方案整体分成三个部分... --- ## 摘要 我们今天主要讨论订单服务拆分方案整体分成三个部分... ## 内容 ### [00:00:12 - 00:00:35] 好的我们开始今天的会议主要议题是订单服务拆分。 ### [00:00:36 - 00:01:20] 目前核心问题是订单表数据量太大单表已经超过两千万行。 ### [00:01:22 - 00:02:10] 我建议按订单状态做分表历史数据走归档这样查询性能会有明显提升。 ## 待办事项 - [ ] (00:02:15) 待办张三下周三之前输出分表方案文档。 - [ ] (00:03:02) 后续李四确认数据库迁移工具选型。把这个文件放进 Obsidian Vault 后可以立刻用双链、标签、全文搜索来管理会议记录。6. 常见问题与排查思路6.1 常见问题速查表问题现象常见原因解决思路报错FileNotFoundError: ffmpegFFmpeg 未安装或未加入 PATH执行ffmpeg -version检查安装把 ffmpeg 所在目录加入 PATH转写结果全是英文或乱码未指定languagezh在model.transcribe()中显式指定语言中文识别同音字错误多模型太小如tiny/base换small或medium模型长音频内存溢出单次转写太长的音频模型显存不足切片转写或换更大显存机器第一次运行下载模型很慢模型权重需要从外网下载提前下载模型设置HF_ENDPOINT镜像如可行Vault 里看不到新笔记Obsidian 没开启自动刷新在 Obsidian 设置中开启自动刷新或重启 Obsidian生成的 frontmatter 不生效python-frontmatter输出格式问题检查post[tags]是否为列表确保标签格式正确6.2 转写结果为空如果转写完成后segments为空通常有两种可能第一种是音频本身没有有效人声。可以用播放器确认录音内容或者用 FFmpeg 统计音频音量ffmpeg -i meeting.wav -af volumedetect -f null -第二种是音频格式异常Whisper 解码后得到的是静音。解决方法是重新检查预处理环节确保 WAV 文件采样率是 16kHz、声道数是 1。6.3 模型下载慢或失败Whisper 第一次运行时会自动下载模型权重体积从几百 MB 到几个 GB 不等。如果你的网络环境不稳定很容易下载失败。解决办法是手动提前下载在 Python 中运行whisper.load_model(small)等待下载完成后模型会缓存在本地。之后再运行脚本就不用重新下载了。6.4 时间戳与内容对不上如果发现转写文本的时间戳和音频实际内容偏差较大可以尝试在transcribe()中设置fp16False。某些 GPU 环境下半精度推理会导致时间戳错位result model.transcribe(str(audio_path), languagezh, fp16False)7. 最佳实践与工程建议7.1 隐私与安全本地转录最大的优势就是隐私但我们仍然要维护这个优势不要把录音文件和转录结果自动同步到云盘除非加密后再同步。会议内容可能包含敏感信息建议在 Vault 目录中加.gitignore避免误提交到公开 Git 仓库。如果需要团队共享优先选择内网 Git 服务而不是公网仓库。7.2 文件组织与命名Vault 的文件组织直接影响长期可用性。推荐按下面的目录结构整理vault/ ├── meetings/ │ ├── 2025-04-10-周会-后端架构评审.md │ └── 2025-04-12-周会-订单服务拆分.md ├── projects/ └── templates/会议笔记统一以日期-标题命名排序直观而且不会因为重名互相覆盖。7.3 定期做摘要与归档原始转录文本往往很长全部堆在 Vault 里会让检索变得困难。建议在转录完成后定期把关键决策、问题、待办提炼到项目文档中原始转录保留在meetings/目录项目文档只保留引用链接。Obsidian 的双链语法在这里非常有用可以在项目文档中这样引用关于订单分表方案详见 [[2025-04-10-周会-后端架构评审]]7.4 增量与幂等设计如果你准备把转录工具接入定时任务一定要考虑幂等性。即同一个录音文件重复执行不应该产生多个重复笔记。生产项目中可以按文件哈希存储在写入前先检查指纹import hashlib def file_md5(path: Path) - str: return hashlib.md5(path.read_bytes()).hexdigest()将文件 MD5 写入 frontmatter下次处理前先判断是否已存在相同source_md5。7.5 识别质量优化方向目前这个工具用的是纯 Whisper 识别口语化内容多、多人同时说话的场景下效果一般。后续可以从三个方向优化使用更大的模型做基础识别再用 LLM 做结构化整理。引入说话人识别区分不同说话人的段落。使用更强大的提示词指导模型输出更规整的会议摘要。这一步可以根据自己的算力和需求逐步演进不必一次性全部实现。8. 总结与下一步学习路线通过这篇文章我们从零实现了一个类似 Loofah 的本地会议转录工具核心链路包括FFmpeg 音频预处理、Whisper 语音识别、Python 后处理、Markdown 写入本地 Vault。整条链路完全在本地运行会议内容不会上传到任何第三方平台。这只是一个最简版本但它已经具备了几个重要能力时间戳分段、自动摘要、待办提取、文件重名保护、Markdown frontmatter 支持。对于一个够用的会议记录工具来说核心骨架已经完整。下一步如果你要继续深入可以从这几个方向选一个学习 Whisper 的更多参数比如initial_prompt、temperature提升专业场景下的识别准确率。学习 Obsidian 插件开发把转录工具直接集成到 Obsidian 面板中。学习向量检索把会议记录嵌入后做语义查询让知识库真正“可问答”。动手跑一遍上面的代码再拿你自己一场真实会议的录音试一下你会直观感受到“会议记录自动归档”带来的效率提升。如果这篇文章对你有帮助可以先收藏后面配置或排错时直接翻出来对照。