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 个文件模块分别是序号模块文件核心职责1VoiceAssistant_main.py主入口封装其余 7 个模块2speakListen.py语音合成speak与语音识别hear 系列3websiteWork.pyGoogle / Wikipedia 网页搜索4textRead.pyMS Word.docx与 PDF 文档朗读5dictator.py听写模式将长语音转为文本6menu.py打印任务菜单rich 表格7speechtotext.py独立短时语音转文本8TextTospeech.py基于 Windows SAPI 的文本朗读从源码看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.pyspeak / hear / short_hear / long_hear / greet / recognizing ├── websiteWork.pygoogle_search / wiki_search ├── textRead.pyms_word / pdf_read / doubleslash / print_index / print_n_speak_index / search_in_toc / book_details ├── dictator.pybig_text ├── menu.pyprint_menu ├── speechtotext.pystt └── TextTospeech.pytts二、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判断分发任务。源码中实际匹配的关键词与对应功能如下语音关键词源码匹配触发的函数对应任务text to speechtts()朗读用户输入的文本search on google/search google/googlegoogle_search()Google 搜索search on wikipedia/search wikipedia/wikipediawiki_search()Wikipedia 搜索wordms_word()朗读 Word 文档bookpdf_read()朗读 PDF 书籍speech to textbig_text()听写语音转文本每个任务执行后都会通过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 couldnt understand what you just said!。值得注意外层唤醒循环中if close in q也被置于hello python判断之前因此唤醒状态下说出close同样会直接退出——这是文档未展开但源码确认的边界行为。三、speakListen.py语音中枢模块这是被其他模块复用最多的核心模块位于 speakListen.py。文档列出的 5 个函数在源码中均有对应实现。3.1 引擎初始化模块加载时即完成 TTS 引擎初始化speakListen.pypython 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.pypython.say(text) python.runAndWait()3.3 hear() / long_hear() / short_hear()三个识别函数结构高度一致差别仅在录音时长共同依赖speech_recognition库函数默认录音时长用途hear()9 秒主命令识别long_hear(duration_time)60 秒可传参覆盖长语音听写short_hear(duration_time)5 秒可传参覆盖唤醒词监听三个函数共享同一套识别器参数以 speakListen.py 为例r.pause_threshold 1停顿超过 1 秒即视为语句结束r.energy_threshold 300最小输入能量阈值低于该值视为环境噪音r.dynamic_energy_threshold True允许动态调整能量阈值以适应环境speech r.record(source, duration9)从默认麦克风录制指定时长音频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.pyg start/sh 12 and h 17说 Good Afternoonh 12说 Good Morningh 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语音询问要搜索的词或句子wikipedia.summary(query, sentences2)获取2 句话的摘要打印并朗读再次语音询问Do you want me to open the Wikipedia page?回答包含yes/okay/ok/es等近似词时用webbrowser.open(https://en.wikipedia.org/wiki/ query)打开维基页面异常时打印Couldnt find兜底。五、textRead.py文档朗读模块这是文档中篇幅最大的模块负责文件处理与文本转语音源码位于 textRead.py依赖docxpython-docx、fitzPyMuPDF、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 种阅读模式与源码一一对应选项语音关键词源码匹配行为1. 读单页single/one/1 page等pdf.load_page(pgno - 1)后get_text(text)打印并朗读2. 读页范围range/multiple输入起止页码for i in range(start-1, end)逐页朗读3. 读一课lessonlesson输入课程名经search_in_toc()在目录中定位起止页后朗读4. 读全书whole/complete从第 0 页循环到total_pages全部朗读pdf_read()的启动阶段还会做三件事通过pdf.metadata读取作者、标题用book_details()生成书籍信息表格并语音播报标题/作者/总页数询问是否打印索引说1/only print走print_index()说2/speak走print_n_speak_index()打印并朗读索引每页文本中的制表符\t会被替换为空格后再输出。5.3 doubleslash(location)文档特别说明此函数是为 Windows 用户设计的当用户从资源管理器复制路径时路径中往往是单个反斜杠\直接作为字符串会引发转义序列问题。源码实现为text.replace(\\, \\\\)textRead.py即把每个\替换为\\从而安全传入docx.Document()/fitz.open()。5.4 索引相关函数print_index(toc)按名称 ---- 页码的格式打印目录每个条目用-填充对齐textRead.pyprint_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()先语音询问By default, I will record your voice for 60 seconds. Do you want to change this default timing?并提示回答 Yes / No回答包含yes/es/ye/s时通过input()让用户输入自定义秒数否则保持默认60 秒播报I will record for {duration_time} seconds!后调用long_hear(duration_time)完成录制最后用colorama的Fore.LIGHTCYAN_EX高亮打印识别文本。也就是说默认录制 60 秒但用户可指定任意时长与文档描述完全对应。七、menu.py任务菜单模块print_menu()menu.py在说出 Hello Python 激活后由主程序调用用rich库的Table渲染任务与命令对照表表格三列为 Sr. No. / Task / Command共 7 行序号任务命令1Speak Text entered by Usertext to speech2Search anything on GoogleSearch on Google3Search anything on WikipediaSearch on Wikipedia4Read a MS Word(docx) documentRead MS Word document5Convert speech to textConvert speech to text6Read a book(PDF)Read a book7Quit the programPython close注意菜单展示的 命令 是面向用户的自然语言提示实际分发时主程序按第 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 installcolorama rich pyttsx3 DateTime SpeechRecognition docx # python-docx fitz # PyMuPDF gTTS playsound pywin32 # win32comWindows 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 SAPI5Windows 环境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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考