local-audio-transcriber

Local Audio Transcriber

把用户提供的本地录音、音频或视频文件转成文字。核心目标是：用户发来音频后，直接返回转写文本；同时在本地保存 Markdown 文稿和 SRT 字幕。

适用边界

• 适用：.m4a、.mp3、.wav、.aac、.flac、.ogg、.opus、.mp4、.mov、.mkv 等已有文件
• 适用：会议录音、访谈录音、课程音频、播客片段、视频提取文字、字幕生成
• 不适用：现场临时录音、麦克风采集、实时听写，除非用户另行明确要求
• 默认本地处理，不上传音频到云端

工作流程

1. 确认用户提供的是可访问的本地音频/视频文件路径或附件。
2. 先判断机器类型和可用引擎：

python3 - <<'PY'
import platform, sys
print(sys.platform, platform.machine())
try:
    import mlx.core as mx
    print("mlx", mx.default_device())
except Exception as e:
    print(type(e).__name__ + ": " + str(e))
PY

3. Apple Silicon（M1/M2/M3/M4）优先安装并使用 MLX，本地调用 Apple GPU/统一内存：

python3.13 -m venv /tmp/local-audio-transcriber-mlx
/tmp/local-audio-transcriber-mlx/bin/python -m pip install -U pip mlx-whisper

4. 非 Apple Silicon、CUDA 机器或 MLX 不可用时，再使用 faster-whisper：

python3 -m pip install -U faster-whisper

5. 运行转写脚本，中文录音优先指定 --language zh；不确定语言时省略语言参数：

/tmp/local-audio-transcriber-mlx/bin/python {skill_dir}/scripts/transcribe.py "input.m4a" --language zh --print-text

6. 向用户直接发送转写文本。文本很长时，优先交付本地文件路径，并贴出开头和关键说明。
7. 默认只保存 .md 和 .srt 文件；不要生成 txt、json 或 vtt。

常用命令

# Apple Silicon 中文长录音：优先使用 MLX + Apple GPU + turbo-q4
/tmp/local-audio-transcriber-mlx/bin/python {skill_dir}/scripts/transcribe.py "recording.m4a" --language zh --print-text

# 明确指定 MLX 和模型
/tmp/local-audio-transcriber-mlx/bin/python {skill_dir}/scripts/transcribe.py "recording.m4a" --engine mlx --model mlx-community/whisper-large-v3-turbo-q4 --language zh --print-text

# 非 Apple Silicon / CUDA / CPU：使用 faster-whisper
python3 {skill_dir}/scripts/transcribe.py "recording.m4a" --engine faster-whisper --model small --language zh --print-text

# 自动识别语言，生成 Markdown 和 SRT
python3 {skill_dir}/scripts/transcribe.py "video.mp4" --print-text

# 多个文件批量转写到指定目录
python3 {skill_dir}/scripts/transcribe.py *.m4a --language zh --output-dir ./transcripts

# faster-whisper 质量更高但更慢
python3 {skill_dir}/scripts/transcribe.py "meeting.m4a" --engine faster-whisper --model medium --language zh --print-text

参数取舍

• Apple Silicon 默认引擎：mlx，默认模型：mlx-community/whisper-large-v3-turbo-q4
• 非 Apple Silicon 默认引擎：faster-whisper，默认模型：small
• 中文长录音、多人直播、专有名词较多：优先 whisper-large-v3-turbo-q4
• whisper-large-v3-turbo-q4 是量化模型，适合 M1 16GB 这类统一内存机器；首次运行会下载模型，之后走本地缓存
• OpenAI Whisper 的 --device mps 在 M1 上可能极慢；本地 Apple GPU 路线优先用 MLX，不优先用 PyTorch MPS
• 长录音默认关闭 condition_on_previous_text，避免 Whisper 在中文口语录音里进入重复幻觉循环
• 只有明确需要跨段一致性且没有重复风险时，才加 --condition-on-previous-text
• faster-whisper 长会议、嘈杂环境或多人访谈：可用 --model medium
• CPU 环境：默认 int8，更省内存
• CUDA 环境：脚本会尽量自动使用 float16
• 口语录音：默认开启 VAD 静音过滤；如切分异常，使用 --no-vad-filter
• 如果 MLX small 出现明显错词，优先升级到 whisper-large-v3-turbo-q4，不要只靠后处理硬校对
• 初始提示词可以帮助专有名词，但如果配合上下文续写出现重复，立即关闭 --condition-on-previous-text

输出要求

• 用户明确要“转文字”时，最终回复应包含转写正文，不要只给文件路径。
• 用户要“整理成会议纪要/文章/字幕”时，先完成转写，再按用户目标继续加工。
• 转写文件只保留 Markdown 和 SRT 两种格式，不生成 txt/json/vtt。
• 对隐私敏感录音，只说明本地处理和输出位置，不复述无关敏感信息。

故障处理

• ModuleNotFoundError: faster_whisper：运行 python3 -m pip install -U faster-whisper
• ModuleNotFoundError: mlx_whisper：在虚拟环境中运行 /tmp/local-audio-transcriber-mlx/bin/python -m pip install -U mlx-whisper
• macOS 系统 Python 提示 externally-managed-environment：不要加 --break-system-packages，改用 python3.13 -m venv /tmp/local-audio-transcriber-mlx
• mlx 默认设备不是 Device(gpu, 0)：说明 MLX/Metal 没走通，降级到 faster-whisper 或检查系统环境
• 音频无法解码：建议安装或更新 ffmpeg，或让用户换成 .m4a/.mp3/.wav
• 转写很慢：改用 --model small 或 --model base
• Apple Silicon 转写很慢：确认不是 OpenAI Whisper --device mps，优先使用本脚本 --engine mlx
• 中文被识别成其他语言：加 --language zh
• 字幕时间轴不准：尝试 --model medium，或关闭 VAD：--no-vad-filter
• 出现“同一句话无限重复”：重跑并确保没有开启 --condition-on-previous-text，必要时换 whisper-large-v3-turbo-q4