托福口语练习速查手册：5个Python脚本搞定录音分析

官方文档动辄几百页，翻到头疼还抓不住重点？别慌。直接上速查手册，用5个Python脚本把托福口语练习的核心功能拆得明明白白。

项目目标：把“听”变成“看”

很多人练托福口语，卡在哪？卡在不清楚自己到底说得好不好。语速快慢、发音准不准、逻辑连不连贯，光靠耳朵听，全凭感觉。

这个项目不搞花里胡哨。目标很直接：

录音转文本：把你说的英语变成文字，看看词汇量够不够。
语速统计：托福口语建议语速在150-180词/分钟，超了或慢了都扣分。
停顿检测：卡壳超过2秒，系统自动标记，帮你找“嗯”“啊”的位置。
评分估算：基于语音识别置信度，给个大概分数区间。
对比复盘：把这次录音和上次对比，看进步在哪。

不需要你懂语音算法。调用现成API，写几行胶水代码，就能跑起来。

目录结构：清晰到离谱

别把代码堆在一个文件里。那是新手才干的活。

toefl-speech-practice/
├── main.py              # 入口文件，启动整个流程
├── config.py            # 配置文件，API Key放这里
├── utils/
│   ├── recorder.py      # 录音模块，调用麦克风
│   ├── transcriber.py   # 转写模块，调用Whisper API
│   ├── analyzer.py      # 分析模块，算语速、停顿
│   └── reporter.py      # 报告模块，生成HTML/PDF
├── audio/               # 存放录音文件
├── results/             # 存放分析报告
├── requirements.txt     # 依赖包列表
└── README.md            # 使用说明

关键点：config.py 里放API Key，千万别硬编码在代码里。掘金技术社区有个开发者分享，他就是因为把Key提交到GitHub，被刷了200美金账单。血的教训。

核心代码实现：逐行拆解

1. 录音模块：30秒搞定

# utils/recorder.py
import pyaudio
import wave
import timeclass Recorder:def __init__(self, chunk=1024, rate=44100, channels=1, seconds=30):self.chunk = chunkself.rate = rateself.channels = channelsself.seconds = secondsself.frames = []def record(self):"""启动录音，返回音频数据"""print(f"开始录音，时长{self.seconds}秒...")p = pyaudio.PyAudio()# 打开麦克风输入流stream = p.open(format=pyaudio.paInt16,channels=self.channels,rate=self.rate,input=True,frames_per_buffer=self.chunk)start_time = time.time()while time.time() - start_time < self.seconds:data = stream.read(self.chunk)self.frames.append(data)# 关闭流，释放资源stream.stop_stream()stream.close()p.terminate()return b''.join(self.frames)def save_wav(self, audio_data, filename="recording.wav"):"""保存为WAV文件"""with wave.open(filename, 'wb') as wf:wf.setnchannels(self.channels)wf.setsampwidth(2)  # 16-bitwf.setframerate(self.rate)wf.writeframes(audio_data)print(f"音频已保存: {filename}")

逐行讲解：

pyaudio 是跨平台的音频I/O库，比sounddevice稳定。
frames_per_buffer 设为1024，平衡延迟和CPU占用。
time.time() 计算实际耗时，比固定读取次数更准确，防止时钟漂移。
一定要调用 p.terminate()，否则Windows上会残留进程。

2. 转写模块：调用OpenAI Whisper

# utils/transcriber.py
import openai
from config import OPENAI_API_KEYclass Transcriber:def __init__(self):openai.api_key = OPENAI_API_KEYdef transcribe(self, audio_path):"""调用Whisper API，返回文本和时间戳"""with open(audio_path, "rb") as f:# 使用whisper-1模型，支持英文result = openai.audio.transcriptions.create(model="whisper-1",file=f,response_format="verbose_json",timestamp_granularities=["segment"])return result

避坑指南：

response_format 必须设为 verbose_json，才能拿到每个词的时间戳。普通格式只有纯文本，没法算停顿。
Whisper对长音频支持有限，单次超过30分钟会失败。托福口语每题1分钟，完全够用。
免费额度用完就停，别等账单来了才哭。

3. 分析模块：语速和停顿

# utils/analyzer.py
import reclass Analyzer:def analyze(self, transcription_result):"""计算语速、停顿、词汇量"""segments = transcription_result.get('segments', [])words = transcription_result.get('text', '').split()duration = segments[-1]['end'] if segments else 0# 1. 语速（词/分钟）wpm = (len(words) / duration) * 60 if duration > 0 else 0# 2. 停顿检测：相邻segment间隔超过2秒pauses = []for i in range(len(segments) - 1):gap = segments[i+1]['start'] - segments[i]['end']if gap > 2.0:pauses.append({'time': segments[i]['end'],'duration': gap,'context': segments[i]['text'] + " [PAUSE] " + segments[i+1]['text']})# 3. 词汇量（去重）unique_words = set([w.lower().strip('.,!?') for w in words if len(w) > 1])return {'word_count': len(words),'unique_words': len(unique_words),'wpm': round(wpm, 1),'pauses': pauses,'total_pauses': len(pauses)}

逻辑拆解：

语速公式：总词数 / 总时长 * 60。简单粗暴，但有效。
停顿阈值设为2秒。托福评分标准里，超过2秒的停顿会被视为“犹豫”，影响流利度分数。
词汇量去重时，去掉标点和单字母词（如“a”“I”），否则虚高。

4. 报告生成：HTML可视化

# utils/reporter.py
import json
from datetime import datetimeclass Reporter:def generate_html(self, analysis_data, transcription_text, output_path):"""生成HTML报告，高亮停顿位置"""html = f"""<html><head><title>托福口语分析报告</title></head><body><h1>分析时间: {datetime.now().strftime('%Y-%m-%d %H:%M')}</h1><h2>核心指标</h2><ul><li>总词数: {analysis_data['word_count']}</li><li>独特词汇: {analysis_data['unique_words']}</li><li>语速: {analysis_data['wpm']} WPM (建议150-180)</li><li>停顿次数: {analysis_data['total_pauses']}</li></ul><h2>停顿详情</h2><table border="1"><tr><th>时间点</th><th>时长</th><th>上下文</th></tr>"""for pause in analysis_data['pauses']:html += f"<tr><td>{pause['time']:.1f}s</td><td>{pause['duration']:.1f}s</td><td>{pause['context']}</td></tr>\n"html += f"""</table><h2>完整文本</h2><p>{transcription_text}</p></body></html>"""with open(output_path, 'w', encoding='utf-8') as f:f.write(html)print(f"报告已生成: {output_path}")

运行与测试：别信“理论上可行”

第一步：装依赖

pip install pyaudio openai

Windows用户注意：pyaudio 需要安装 PortAudio。去官网下载 .whl 文件，或者用 pip install pyaudio --only-binary :all:。

第二步：配置API Key

# config.py
OPENAI_API_KEY = "sk-你的Key"

第三步：跑起来

# main.py
from utils.recorder import Recorder
from utils.transcriber import Transcriber
from utils.analyzer import Analyzer
from utils.reporter import Reporterdef main():# 1. 录音recorder = Recorder(seconds=30)audio_data = recorder.record()recorder.save_wav(audio_data, "audio/test.wav")# 2. 转写transcriber = Transcriber()result = transcriber.transcribe("audio/test.wav")text = result.get('text', '')# 3. 分析analyzer = Analyzer()analysis = analyzer.analyze(result)# 4. 生成报告reporter = Reporter()reporter.generate_html(analysis, text, "results/report.html")# 5. 打印摘要print(f"\n===== 摘要 =====")print(f"语速: {analysis['wpm']} WPM")print(f"停顿: {analysis['total_pauses']} 次")print(f"词汇量: {analysis['unique_words']}")if __name__ == "__main__":main()

测试要点：

第一次跑，先录10秒，看流程通不通。
检查 results/report.html 能否在浏览器打开。
故意卡壳几次，看停顿检测准不准。

常见问题：

录音无声：检查系统默认输入设备，pyaudio 用的是系统默认。
API超时：网络不稳，加个重试机制。for i in range(3): try: ... except: time.sleep(2)。
语速异常：检查 duration 是否取到了最后一个segment的结束时间，别用录音时长。

优化扩展：从能用到了好用

基础版跑通后，想再进一步？

1. 本地部署Whisper OpenAI API按量收费，练多了心疼。用 faster-whisper 本地跑，CPU也能处理，速度够快。

pip install faster-whisper

from faster_whisper import WhisperModel
model = WhisperModel("small", device="cpu", compute_type="int8")
segments, info = model.transcribe("audio/test.wav")

2. 加入发音评估 speechbrain 库可以评估单个单词的发音准确性。把转写文本和音频对齐，逐词打分。

3. 数据库存储历史 用SQLite存每次分析结果，画趋势图。看自己语速是变快了还是变慢了。

import sqlite3
conn = sqlite3.connect('toefl.db')
conn.execute('''CREATE TABLE IF NOT EXISTS records(id INTEGER PRIMARY KEY, date TEXT, wpm REAL, pauses INT, words INT)''')

4. 移动端适配 用 flask 包个Web界面，手机也能录、也能看报告。

5. 对比功能 选两次录音，并排显示文本，高亮差异部分。看自己是不是总在某些地方卡壳。