企业官网建设流程全解析

快速修好 AsrTools 常见报错：语音转文字任务故障排查指南

【免费下载链接】AsrTools✨ AsrTools: Smart Voice-to-Text Tool | Efficient Batch Processing | User-Friendly Interface | No GPU Required | Supports SRT/TXT Output | Turn your audio into accurate text in an instant!项目地址: https://gitcode.com/gh_mirrors/as/AsrTools

你点了“开始处理”，任务列表卡了几秒，然后弹出一个红色的“错误”，文件夹里也没有字幕文件——这是大多数人用 AsrTools 时最先碰到的情况。AsrTools 是一款无需 GPU 的语音转文字工具，能批量处理音频、视频文件，输出 SRT、TXT、ASS 三种字幕。下面按你实际看到的报错，逐个告诉你怎么定位、怎么修。

🔴 修好任务列表里的红色“错误”

主界面长这样：左边选引擎和格式，中间是批量转写的任务列表，状态列会显示“处理中 / 已处理 / 错误”。

报错写着“确保安装 ffmpeg”

现象：选视频文件（mp4、mov、ts 等）处理时出错。 原因：视频要先用 ffmpeg 抽成音频再转写，ffmpeg 没装就走到这一步。 解决：装好 ffmpeg 后，把它的 bin 目录加入系统 PATH，然后打开一个新终端验证：

ffmpeg -version

这条命令用来确认 ffmpeg 已安装且在 PATH 里，能打印版本号就说明配置成功。

报错写着“Unsupported sound format”

现象：提示音频格式不支持，并附上你的文件后缀名。 原因：转写后端只收 flac、m4a、mp3、wav 这几种，支持列表定义在bk_asr/BaseASR.py里。 解决：先用 ffmpeg 把音频转成 mp3 再拖进列表：

ffmpeg -i 原文件.aac -ac 1 新文件.mp3

报错写着“File not found”

现象：文件明明在列表里，却说找不到。 原因：文件在添加后被移动、重命名或删除了。 解决：把文件放回原位置，或用右键菜单“删除任务”后重新拖入。

🖥️ 修好 GUI 打不开、中文路径崩溃

中文或带空格的路径下界面崩溃

现象：运行python asr_gui.py时闪退，或提示 Qt 平台插件加载失败，路径里有中文、空格时尤其明显。 原因：PyQt5 的 Qt 平台插件路径没被正确解析。 解决：新版asr_gui.py开头已经设置好了QT_QPA_PLATFORM_PLUGIN_PATH。如果你用的是旧版本或自己写了入口脚本，在启动前补上这段环境变量：

import os, sys os.environ['QT_QPA_PLATFORM_PLUGIN_PATH'] = os.path.join( sys.prefix, 'Lib', 'site-packages', 'PyQt5', 'Qt5', 'plugins')

启动时提示 ModuleNotFoundError

现象：报错缺少requests、PyQt5或qfluentwidgets。 原因：依赖没装全，源码运行的核心依赖只有 requests，界面额外需要两个 GUI 库。 解决：按项目依赖文件安装，然后启动：

pip install -r requirements.txt python asr_gui.py

🌐 修好任务卡住、“无法连接到互联网”

启动即提示“无法连接到互联网”

现象：刚启动就弹网络错误，或者任务长时间无响应后失败。 原因：转写是走云端接口的，本地网络或代理挡住了请求。 解决：先确认浏览器能正常上网；如果你开了代理，给 AsrTools 的运行环境配置好代理变量（或临时关掉代理再试）；公司内网通常需要给相关域名放通出口。如果上一步没生效，多半是代理只代理了浏览器没代理终端，两个环境要分别设置。

选了 Whisper 引擎报错

现象：引擎下拉框选 Whisper，开始处理后立刻失败。 原因：这个引擎目前还没实现，代码里直接抛了未实现异常。 解决：引擎换成 B、J、K 三个接口之一再开始处理。

📄 找到生成的字幕文件、用好缓存

处理完了却找不到字幕

现象：状态是“已处理”，但目录里没看到新文件。 原因：字幕写在源文件旁边，文件名与源文件相同，只换后缀为 .srt、.txt 或 .ass，取决于你在界面上选的“导出格式”。 解决：在任务行上右键选“打开文件目录”最快。提醒一句：TXT 是纯文本没有时间轴，要带时间轴就选 SRT 或 ASS。

重复转写同一个文件，出来的还是旧结果

现象：改了源文件内容，再处理一遍结果却没变。 原因：转写结果按文件内容做了缓存，命中缓存就直接复用旧结果。缓存文件在系统临时目录下的bk_asr/asr_cache.json，逻辑见bk_asr/BaseASR.py。 解决：删掉这个缓存文件再重新处理即可。缓存超过 10MB 时程序也会自动清掉。

想同时处理更多文件

现象：批量任务排队久，想跑快一点。 原因：默认只开 3 个并发线程，数值在asr_gui.py的max_threads里。 解决：按 CPU 核心数调大它，比如 4 核机器调到 4，调完重启程序生效。

⚡ 用速查表快速定位报错

错误速查

还是修不好的话

在干净的虚拟环境里重试一遍，能排除大部分环境层面的干扰：

python -m venv asr_env pip install -r requirements.txt

如果依旧报错，把完整错误信息提交到项目的 issue 区，附上操作系统、Python 版本和出错文件类型，会方便很多。

【免费下载链接】AsrTools✨ AsrTools: Smart Voice-to-Text Tool | Efficient Batch Processing | User-Friendly Interface | No GPU Required | Supports SRT/TXT Output | Turn your audio into accurate text in an instant!项目地址: https://gitcode.com/gh_mirrors/as/AsrTools