Voice Assistant 项目文档精读：8 大模块驱动的 Python 语音助手架构与实现解析

Voice Assistant 项目文档精读：8 大模块驱动的 Python 语音助手架构与实现解析

【免费下载链接】PythonMy Python Examples项目地址: https://gitcode.com/gh_mirrors/py/Python

导读

本文以仓库中 VoiceAssistant/DOCUMENTATION.md 为骨架，结合VoiceAssistant/Project_Basic_struct目录下的全部源码，系统拆解一个由8 个 Python 模块组合而成的语音助手项目：从唤醒词 "Hello Python" 激活、语音录制与识别（Google Speech Recognition）、语音合成朗读（pyttsx3 + SAPI5），到 Google/Wikipedia 搜索、Word/PDF 文档朗读、语音听写等完整功能链路。读完本文，你将掌握该项目的模块划分、每个模块的公开函数与核心参数、主程序的命令分发逻辑，以及实际运行时的前置依赖与已知边界（如 OneDrive 目录限制、文件扩展名要求）。

一、项目总览：8 个模块如何协作

文档开篇即说明：主包中共有 8 个文件（模块），分别是：

从源码看，8 个模块并非彼此孤立：VoiceAssistant_main.py通过from speakListen import *、from websiteWork import *等一次性导入所有能力；而websiteWork.py、textRead.py、menu.py又反向从speakListen.py导入hear()与speak()，因此speakListen.py 是整个项目的语音能力中枢。所有模块的组合调用链如下图所示：

VoiceAssistant_main.py（命令分发） ├── speakListen.py（speak / hear / short_hear / long_hear / greet / recognizing） ├── websiteWork.py（google_search / wiki_search） ├── textRead.py（ms_word / pdf_read / doubleslash / print_index / print_n_speak_index / search_in_toc / book_details） ├── dictator.py（big_text） ├── menu.py（print_menu） ├── speechtotext.py（stt） └── TextTospeech.py（tts）

二、VoiceAssistant_main.py：主入口与命令分发

文档强调：这是主文件，运行它可以获得语音助手的全部能力。其运行流程在源码 VoiceAssistant_main.py 中清晰可见：

2.1 唤醒阶段

程序启动后，先打印提示语Say "Hello Python" to activate the Voice Assistant!，随后进入while True循环，用short_hear()（默认录制 5 秒）持续监听。当识别文本中包含"hello python"时调用greet("start")打招呼，并调用print_menu()显示任务菜单。

2.2 命令分发阶段

菜单显示后，进入内层循环，通过hear()（默认录制 9 秒）接收命令，并基于子串匹配（in判断）分发任务。源码中实际匹配的关键词与对应功能如下：

每个任务执行后都会通过time.sleep(4)至time.sleep(10)预留缓冲时间，避免上一次任务的语音输出被误识别为下一条命令。任务完成后，助手会语音询问Do you want to continue? if yes then say YES else say CLOSE PYTHON，再次通过hear()接收答复：说yes则重新打印菜单，说close则调用greet("end")并退出。

2.3 程序终止

• 常规退出：说出"close python"（或任意包含close的命令），程序调用greet("end")说再见后退出。
• 强制退出：文档明确说明，Windows 与 Linux 下均可使用Ctrl + C组合键强制终止。
• 未识别兜底：当命令无法匹配任何关键词时，程序会打印并朗读I could'nt understand what you just said!。

值得注意：外层唤醒循环中if "close" in q也被置于"hello python"判断之前，因此唤醒状态下说出close同样会直接退出——这是文档未展开但源码确认的边界行为。

三、speakListen.py：语音中枢模块

这是被其他模块复用最多的核心模块，位于 speakListen.py。文档列出的 5 个函数在源码中均有对应实现。

3.1 引擎初始化

模块加载时即完成 TTS 引擎初始化（speakListen.py）：

python = pyttsx3.init("sapi5") # 引擎名设置为 "python" voices = python.getProperty("voices") python.setProperty("voice", voices[1].id) # 选择第 2 个语音 python.setProperty("rate", 140) # 语速 140 字/分

• pyttsx3.init("sapi5")显式指定Microsoft SAPI5驱动——这正是文档中所说的 "Microsoft SAPI5 has provided the voice"。
• rate = 140是语速参数，数值越大语速越快，可在此处按需调整。
• 全局python引擎实例被speak()反复使用。

3.2 speak(text)

将参数text（字符串）朗读出来，核心实现只有两行（speakListen.py）：

python.say(text) python.runAndWait()

3.3 hear() / long_hear() / short_hear()

三个识别函数结构高度一致，差别仅在录音时长，共同依赖speech_recognition库：

三个函数共享同一套识别器参数（以 speakListen.py 为例）：

• r.pause_threshold = 1：停顿超过 1 秒即视为语句结束；
• r.energy_threshold = 300：最小输入能量阈值（低于该值视为环境噪音）；
• r.dynamic_energy_threshold = True：允许动态调整能量阈值以适应环境；
• speech = r.record(source, duration=9)：从默认麦克风录制指定时长音频；
• r.recognize_google(speech)：调用Google Speech Recognition API将音频转成英文文本（en-IN）。

识别失败（except Exception）时统一返回字符串"None"，调用方通过判断query != "None"决定是否执行后续操作——这是全项目通用的失败哨兵值。

3.4 recognizing()

一个用rich库的Progress渲染的 "Recognizing..." 加载进度条（speakListen.py），每 0.01 秒推进 1 个单位，模拟识别过程的可视反馈。

3.5 greet(g)

基于datetime库按当前小时生成时段问候（speakListen.py）：

• g = "start"/"s"：h > 12 and h < 17说 "Good Afternoon"，h < 12说 "Good Morning"，h >= 17说 "Good Evening"，最后统一追加"I am Python, How may i help you ?"；
• g = "quit"/"end"/"over"/"e"：朗读"Thank you!. Good Bye !"。

四、websiteWork.py：网页搜索模块

该模块处理项目的 "搜索网络" 任务，依赖wikipedia与webbrowser两个标准/第三方库，源码位于 websiteWork.py。

4.1 google_search()

流程为：语音询问"What do you want me to search on Google?"→hear()录制查询词 → 拼接到搜索 URLhttps://www.google.co.in/search?q=后，通过webbrowser.open()在默认浏览器中打开搜索结果（websiteWork.py）。若识别结果为"None"，则打印并朗读提示无法理解。

4.2 wiki_search()

相比 Google 搜索多了一步摘要播报（websiteWork.py）：

1. 语音询问要搜索的词或句子；
2. wikipedia.summary(query, sentences=2)获取2 句话的摘要，打印并朗读；
3. 再次语音询问"Do you want me to open the Wikipedia page?"；
4. 回答包含yes/okay/ok/es等近似词时，用webbrowser.open("https://en.wikipedia.org/wiki/" + query)打开维基页面；
5. 异常时打印"Couldn't find"兜底。

五、textRead.py：文档朗读模块

这是文档中篇幅最大的模块，负责文件处理与文本转语音，源码位于 textRead.py，依赖docx（python-docx）、fitz（PyMuPDF）、rich与colorama。

5.1 ms_word()：朗读 Word 文档

流程（textRead.py）：语音提示并等待input()输入文档位置 →doubleslash()处理路径 →docx.Document(file_loc)打开文档 → 遍历doc.paragraphs拼接全文 → 打印并speak()朗读。定位失败时打印黄色错误提示，提醒检查扩展名。

5.2 pdf_read()：PDF/电子书朗读

这是功能最丰富的函数（textRead.py），文档明确列出其4 种阅读模式，与源码一一对应：

pdf_read()的启动阶段还会做三件事：

1. 通过pdf.metadata读取作者、标题，用book_details()生成书籍信息表格并语音播报标题/作者/总页数；
2. 询问是否打印索引：说1/only print走print_index()，说2/speak走print_n_speak_index()（打印并朗读索引）；
3. 每页文本中的制表符\t会被替换为空格后再输出。

5.3 doubleslash(location)

文档特别说明此函数是为 Windows 用户设计的：当用户从资源管理器复制路径时，路径中往往是单个反斜杠\，直接作为字符串会引发转义序列问题。源码实现为text.replace("\\", "\\\\")（textRead.py），即把每个\替换为\\，从而安全传入docx.Document()/fitz.open()。

5.4 索引相关函数

• print_index(toc)：按名称 ---- 页码的格式打印目录，每个条目用-填充对齐（textRead.py）；
• print_n_speak_index(toc)：在打印的同时对每个条目调用speak()；
• search_in_toc(toc, key, totalpg)（文档未列、源码补充）：遍历目录嵌套列表，命中课程名后返回其起始页与下一个条目的起始页作为结束页，若是最后一个条目则以totalpg为结束页；未命中返回(None, None)。

toc的数据结构取自pdf.get_toc()，即 PyMuPDF 返回的嵌套列表：toc[i][1]为主题名、toc[i][2]为页码——与文档描述完全一致。

5.5 book_details(author, title, total_pages)

用rich库的Table生成三列（Sr. No. / Property / Value）的书籍信息表（textRead.py），分别展示 Title、Author、Pages。

5.6 重要边界（文档原文强调）

助手会询问待朗读文件的路径；如果文件位于 OneDrive 文件夹或任何受保护的第三方文件夹中，将无法检测到该文件。此外，不提供扩展名会直接报错。

文档给出的示例：

• 目录为folder_loc，其中有 Word 文件abc与 PDF 文件fgh；
• 输入folder_loc\abc或folder_loc\fgh（无扩展名）→ 报错；
• 输入folder_loc\abc.docx或folder_loc\fgh.pdf（带扩展名）→ 正常朗读。

这与ms_word()/pdf_read()源码中的except Exception兜底逻辑吻合：扩展名缺失时docx.Document()或fitz.open()抛异常，随后打印黄色提示。

六、dictator.py：听写模块

正如文档所说，该模块 "像一个听写员"，把说出的话转成文本。核心函数big_text()（dictator.py）封装了long_hear()：

1. 先语音询问"By default, I will record your voice for 60 seconds. Do you want to change this default timing?"，并提示回答 Yes / No；
2. 回答包含yes/es/ye/s时，通过input()让用户输入自定义秒数；否则保持默认60 秒；
3. 播报"I will record for {duration_time} seconds!"后调用long_hear(duration_time)完成录制；
4. 最后用colorama的Fore.LIGHTCYAN_EX高亮打印识别文本。

也就是说，默认录制 60 秒，但用户可指定任意时长，与文档描述完全对应。

七、menu.py：任务菜单模块

print_menu()（menu.py）在说出 "Hello Python" 激活后由主程序调用，用rich库的Table渲染任务与命令对照表，表格三列为 Sr. No. / Task / Command，共 7 行：

注意：菜单展示的 "命令" 是面向用户的自然语言提示，实际分发时主程序按第 2.2 节的关键词做子串匹配（如菜单写Python close，代码中实际匹配"close"子串），两者并不要求逐字一致。

八、两个独立辅助模块

文档将speechtotext.py与TextTospeech.py也计入 8 个模块之列：

• speechtotext.py：独立的轻量语音转文本函数stt()（speechtotext.py），创建全局sr.Recognizer()，录制 5 秒音频后经recognize_google()转为文本并打印。
• TextTospeech.py：基于 Windows 的win32com实现tts()（TextTospeech.py），通过win32com.client.Dispatch("SAPI.SpVoice")朗读用户输入的句子。该函数由主程序中"text to speech"命令触发（speakListen使用 pyttsx3，而此模块走 SAPI 直连，是两条并行的 TTS 通路）。

九、运行前置条件与启动方式

9.1 依赖安装

依据 VoiceAssistant/PRE-REQUISITES.md，通过终端运行时需先安装以下 Python 库（pip install或pip3 install）：

colorama rich pyttsx3 DateTime SpeechRecognition docx # python-docx fitz # PyMuPDF gTTS playsound pywin32 # win32com（Windows） wikipedia webbrowser # Python 标准库

9.2 启动命令

源码位于 VoiceAssistant/Project_Basic_struct 目录。依据 VoiceAssistant/GUIDE.md，在终端进入该目录后运行：

python VoiceAssistant_main.py

启动后按提示说出"Hello Python"激活，随后按菜单命令逐项使用即可。文档与 README 还提供了打包为.exe的发行方式（将可执行文件放在 VoiceAssistant 文件夹内运行）。

9.3 使用边界小结

• 语音识别走 Google Speech Recognition API，需要联网；
• TTS 引擎依赖 Microsoft SAPI5（Windows 环境），TextTospeech.py依赖 win32com，整体更适配 Windows；
• 文件朗读要求给出带扩展名的完整路径，且文件不能位于 OneDrive 等受保护/第三方目录；
• 程序退出推荐语音命令 "close python"，强退用 Ctrl + C。

十、小结：从文档到源码的完整闭环

DOCUMENTATION.md以 8 个模块为主线勾勒了语音助手的全貌，而源码进一步印证并补充了大量实现细节：speakListen.py是语音能力中枢（SAPI5 引擎、9/5/60 秒三档录音、"None"失败哨兵值）；textRead.py承载了最复杂的文档朗读逻辑（4 种 PDF 阅读模式 + 索引打印 +doubleslash路径处理）；VoiceAssistant_main.py用子串匹配完成命令分发，并内置 "YES/CLOSE PYTHON" 的继续/退出会话流。对于希望扩展该项目的开发者，可以从替换recognize_google（如换成本地识别引擎）、调整rate语速、或为pdf_read()增加更多阅读模式等方向入手，结合本仓库源码继续深化。

【免费下载链接】PythonMy Python Examples项目地址: https://gitcode.com/gh_mirrors/py/Python