MetaNote 本地化增强版

基于 Marstaos/MetaNote 的深度优化与功能增强

本项目源自原作者优秀的笔记生成工具，我在此基础上进行了大量修改，旨在提升易用性、性能并使其完全离线可用（语音识别部分）。

✨ v1.0-local-asr (macOS ARM64 预编译版)

这是 MetaNote 本地化增强版的第一个 Release，主要特点：

• 🚀 预编译 whisper.cpp：针对 macOS ARM64 编译，直接可用，无需自行编译。
• 📝 完整增强功能：本地 ASR、分段笔记生成、界面修复、相对路径配置等（详见下方）。
• ⚙️ 动态库已处理：代码中已自动设置 DYLD_LIBRARY_PATH，一般无需手动干预。

⚠️ 注意事项

• 本版本仅适用于 macOS ARM64（Apple Silicon）系统。
• 若遇到动态库找不到的错误，可手动设置环境变量（见上文）。
• 包含 whisper.cpp 的预编译二进制，版权归其原作者所有，相关许可证文件已附带。

🗓️ 后续计划

下一个版本将提供通用源码包，支持多平台自行编译。
✨ 主要新增功能与改进

1. 🚀 本地 ASR 引擎（核心亮点）

将原项目的云端 ASR 服务替换为 whisper.cpp，实现完全本地化语音识别，无需联网，保护隐私。
针对 Apple M4/M系列芯片 进行了优化，充分利用 GPU 加速，转录速度大幅提升。
在 Streamlit 配置界面中增加了本地模式切换，方便配置可执行文件和模型路径。
2. 📝 超长视频支持（分段笔记生成）

彻底解决了 API Token 限制问题：当视频转录文本过长时，自动进行智能分段，每段分别调用大模型生成笔记，最后合并为完整文档。
完整保留所有内容，不再粗暴截断，尤其适合处理数小时的课程视频。
3. 🛠️ 修复与优化

修复 Streamlit 界面错误：解决了因函数返回值缺失导致的 TypeError: 'NoneType' object is not subscriptable 界面崩溃问题。
修复 ANSI 乱码：在 asr_client.py 中增加了 ANSI 转义序列清理功能，确保生成的 Markdown 笔记中不再出现 �[38;5;160m 等乱码字符。
完善错误处理：为本地 ASR 添加了详细的文件缺失检查和友好的错误提示。
4. 🎯 易用性提升

路径配置优化：将配置文件 config.yaml 中的 whisper_cli_path、model_path、output_dir 等关键路径改为相对路径，使整个项目文件夹可以随意移动而无需重新配置。
新增音频转换脚本：提供了 convert_audio_to_metanote.sh 脚本，可一键将纯音频文件（如 MP3、M4A）转换为带静态画面的 MP4，完美适配 MetaNote 的视频处理流程。
🐛 已知问题

分段笔记生成时，每部分都会包含所有关键帧信息，可能导致最终笔记中图片重复出现。（计划后续优化为按时间戳精确分配）
qwen-max 模型在处理极长文本时仍需保守分段（当前每段约15000字符），未来可根据实际模型能力动态调整。

本地 ASR 配置（whisper.cpp）

🔧 本地 ASR 配置（whisper.cpp）

本项目已将原云端 ASR 替换为完全离线的 whisper.cpp，并针对 Apple M 系列芯片（如 M1/M2/M4）进行了优化。你需要自行编译 whisper.cpp 并下载模型文件。

1. 编译 whisper.cpp

进入项目根目录下的 ai_models 文件夹（若不存在则创建），然后克隆并编译 whisper.cpp：

bash

进入 ai_models 目录（位于项目根目录）

cd ai_models

克隆 whisper.cpp 仓库

git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp

创建构建目录并编译

mkdir build && cd build

配置 CMake（启用 Metal 加速，适用于 Apple Silicon）

cmake .. -DGGML_METAL=ON

编译（使用 4 个并行任务）

cmake --build . --config Release -j 4
编译完成后，可执行文件 whisper-cli 将位于 build/bin/ 目录下。

2. 下载模型文件

whisper.cpp 需要使用 GGML 格式的模型文件。你可以从 Hugging Face 下载预转换好的模型（推荐）：

bash

回到 whisper.cpp 根目录

cd ..

使用自带脚本下载 base 模型（约 142 MB）

./models/download-ggml-model.sh base
该脚本会自动将 ggml-base.bin 下载到 models/ 目录。其他可选模型包括 tiny、small、medium、large，可根据你的硬件性能选择（模型越大，识别越准，但速度越慢）。

如果你无法运行脚本，也可以手动下载：Hugging Face whisper.cpp 模型库，将下载的 .bin 文件放入 models/ 目录。

3. 验证路径配置

本项目已默认配置好相对路径，确保以下位置正确：

whisper-cli 路径：../ai_models/whisper.cpp/build/bin/whisper-cli
模型文件路径：../ai_models/whisper.cpp/models/ggml-base.bin
如果你的实际路径不同，请修改 config.yaml 文件：

yaml
asr:
whisper_cli_path: 你的实际路径/whisper-cli
model_path: 你的实际路径/ggml-base.bin
4. 测试 ASR 是否正常

你可以直接运行以下命令测试 whisper.cpp 是否工作：

bash
../ai_models/whisper.cpp/build/bin/whisper-cli
-m ../ai_models/whisper.cpp/models/ggml-base.bin
-f 你的测试音频.wav -l zh -otxt
如果输出带时间戳的转录文本，说明配置成功。

5. 常见问题排查

5.1 动态库找不到（dyld: Library not loaded）

如果你在运行 whisper-cli 时遇到类似 Library not loaded: @rpath/libggml.dylib 的错误，是因为动态库路径未正确设置。本项目已在代码中自动处理（在 asr_client.py 中设置了 DYLD_LIBRARY_PATH），一般无需手动干预。若仍有问题，可尝试手动设置环境变量后再运行程序：

bash
export DYLD_LIBRARY_PATH=$(pwd)/ai_models/whisper.cpp/build/src:$(pwd)/ai_models/whisper.cpp/build/ggml/src:$(pwd)/ai_models/whisper.cpp/build/ggml/src/ggml-metal:$DYLD_LIBRARY_PATH
streamlit run app.py
5.2 模型文件缺失

如果提示模型文件不存在，请确认模型已下载至正确的 models/ 目录，并检查 config.yaml 中的路径是否正确。

📦 纯音频文件支持（可选）

如果你需要处理的只有录音文件（如 MP3、M4A），可以使用提供的转换脚本生成一个带静态画面的 MP4 文件，再上传给 MetaNote 处理：

bash
cd MetaNote-main
./convert_audio_to_metanote.sh 你的音频.mp3
脚本会在同一目录生成 你的音频_for_metanote.mp4，上传此文件即可正常处理。

🎯 最后

完成以上配置后，运行 streamlit run app.py，在界面中确认 ASR 服务状态为“就绪”，然后就可以上传视频生成笔记了。所有输出文件将保存在 temp/output/ 目录下。

如果仍有问题，欢迎在 Issues 中提出。
📦 如何使用

确保已安装 whisper.cpp 并编译好 whisper-cli，下载好 ggml-base.bin 等模型文件。
git clone 本仓库。
根据你的实际路径修改 config.yaml 中的 ASR 相关配置（或通过 Streamlit 界面设置）。
运行 streamlit run app.py。
（可选）对于纯音频文件，先运行 ./convert_audio_to_metanote.sh your_audio.mp3 生成伪视频。
🙏 致谢

特别感谢原作者 Marstaos 创建的 MetaNote 项目，为本工具提供了坚实的基础。本版本的所有修改旨在探索本地化和增强功能，若原作者有任何意见或建议，欢迎联系。