讯飞语音转写

基于 PyQt6 + 讯飞录音文件转写大模型 API 的桌面端播客/音频转文字工具。

支持音频信息查看、自定义时间范围裁剪转写、说话人分离、领域优化，结果可导出为 TXT 文件。

项目地址：https://github.com/LT-IENG/xfyun-speech-transcription （这是某公司面试时的测试项目）

演示视频

产品演示文档见文章末尾

功能概览

音频文件信息 — 加载音频后自动显示时长、采样率、声道、格式、文件大小等
时间范围转写 — 支持设定起止时间，仅转写音频的指定片段
说话人分离 — 支持自动识别说话人数量，或手动指定人数
领域优化 — 针对不同场景（金融、医疗、教育、游戏等）优化识别准确率
深色 / 浅色主题 — 一键切换，自动记忆偏好
结果导出 — 转写文本按段落展示，支持一键导出 TXT 或复制到剪贴板

截图

运行 python main.py 后即可看到完整界面：左侧磨砂玻璃侧边栏 + 右侧三张卡片（音频信息、转写设置、进度与结果）

环境要求

依赖	版本	说明
Python	≥ 3.9	推荐 3.11+
ffmpeg	任意较新版本	需加入系统 PATH，供 pydub 调用

Python 依赖

pip install -r requirements.txt

包	用途
PyQt6	GUI 框架
pydub	音频处理（读取时长、裁剪片段）
requests	HTTP 请求（调用讯飞 API）
audioop-lts	Python 3.13+ 兼容（audioop 已从标准库移除）
pyinstaller	EXE 打包（仅构建时需）

快速开始

1. 获取 API 凭据

前往讯飞开放平台注册并申请”录音文件转写大模型”服务，获取：

APPID
Access Key ID（APIKey）
Access Key Secret（APISecret）

2. 配置 API 凭据

将 api_config.example.json 复制为 api_config.json，填入你的凭据：

{
    "api": {
        "upload_url": "https://office-api-ist-dx.iflyaisol.com/v2/upload",
        "result_url": "https://office-api-ist-dx.iflyaisol.com/v2/getResult",
        "app_id": "你的APPID",
        "access_key_id": "你的ACCESS_KEY_ID",
        "access_key_secret": "你的ACCESS_KEY_SECRET",
        ...
    }
}

也可以在应用内通过 ⚙️ API 设置 面板直接填写和保存。

api_config.json 已被 .gitignore 忽略，不会提交到版本管理。

3. 安装 ffmpeg

Windows: 从 ffmpeg.org 下载，将 bin/ 加入系统 PATH
macOS: brew install ffmpeg
Linux: sudo apt install ffmpeg

4. 运行

python main.py

5. 打包为 EXE（可选）

build.bat

输出文件：dist/讯飞语音转写.exe

项目结构

program2/
├── main.py                       # 应用入口
├── api_config.example.json       # API 配置模板（可提交 git）
├── api_config.json               # API 配置（已忽略，不提交 git）
├── requirements.txt              # Python 依赖
├── build.bat                     # PyInstaller 打包脚本
├── .gitignore
├── assets/
│   └── p1.ico                    # 应用图标
└── src/
    ├── __init__.py
    ├── config.py                 # 配置管理（api_config.json + QSettings）
    ├── api_client.py             # 讯飞 API 客户端（HMAC-SHA1 签名）
    ├── worker.py                 # QThread 后台工作线程
    ├── audio_utils.py            # 音频工具（时长、裁剪、片段）
    └── ui/
        ├── __init__.py
        ├── main_window.py        # 主窗口（侧边栏 + 卡片布局）
        ├── styles.py             # 深色/浅色主题定义与 QSS 生成
        └── widgets.py            # 自定义控件（GlassCard、SidebarButton 等）

模块说明

模块	职责
`main.py`	创建 QApplication，设置全局字体/主题/异常钩子，启动主窗口
`src/config.py`	`ConfigManager` — API 凭据读写 `api_config.json`，UI 偏好读写 `QSettings`
`src/api_client.py`	`XfyunASRClient` — 按讯飞官方规范实现 HMAC-SHA1 签名、文件上传、轮询获取转写结果
`src/worker.py`	`TranscriptionWorker(QThread)` — 将阻塞的 API 调用移至后台，通过信号通知 UI
`src/audio_utils.py`	基于 pydub 的音频工具函数：获取时长/信息、裁剪片段、随机截取
`src/ui/main_window.py`	`MainWindow` — 完整 UI 布局与交互逻辑
`src/ui/styles.py`	深色/浅色主题色板定义，运行时动态生成 QSS 文件
`src/ui/widgets.py`	磨砂玻璃卡片、渐变按钮、侧边栏、主题切换按钮等自定义控件

技术要点

API 签名

按照讯飞官方规范，使用 HMAC-SHA1 对请求参数签名：

1. 将参数按 key 字母序排序
2. 拼接为 key1=value1&key2=value2 格式（urlencode）
3. 使用 access_key_secret 对拼接串做 HMAC-SHA1
4. Base64 编码后放入 X-Appkey-Signature Header

音频处理

使用 pydub (ffmpeg 封装) 处理音频：

支持格式：mp3 / wav / m4a / flac / ogg / aac / opus / wma 等
可精确裁剪指定时间段的音频片段发送给 API
裁剪后的临时文件在转写完成后自动清理

许可证

MIT License — 详见 LICENSE 文件。

致谢

科大讯飞开放平台 — 语音转写 API 服务
PyQt6 — Python GUI 框架
pydub — 音频处理库

讯飞语音转写-自制桌面端播客/音频转文字工具