speech - PythonIDE Docs

文字转语音（TTS）：朗读文本、暂停/恢复、查询可用语音。

边界：适合朗读结果、无障碍提示、学习卡片。短音效用 sound；语音识别用 speech_recognition。AppUI 回调里保持 wait=False，否则界面会被阻塞。

#模块概览

项	说明
导入	`import speech`
适合做什么	朗读文本、多语言播报、无障碍反馈
调用时机	放在按钮回调；长文本必须提供停止入口
推荐顺序	先 `stop()` 清队列 → `say(..., wait=False)` → 需要时 `pause`/`resume`
语言标签	BCP-47，如 `zh-CN`、`en-US`

#快速开始

下面脚本用中文朗读，并列出前几个可用语音：

python

import speech

speech.say("你好，PythonIDE", language="zh-CN", wait=True)

voices = speech.available_voices()
print("可用语音数:", len(voices))
if voices:
    print("示例:", voices[:3])

#AppUI 示例

朗读控制放在按钮回调；AppUI 里使用 wait=False，并提供停止/暂停入口。

python

import appui
import speech

state = appui.State(
    text="你好，欢迎使用 PythonIDE",
    language="zh-CN",
    status="未朗读",
    voice_count="—",
)


def update_text(value):
    state.text = value


def update_language(value):
    state.language = value


def refresh_voices():
    voices = speech.available_voices()
    state.voice_count = str(len(voices))


def speak():
    text = state.text.strip()
    if not text:
        state.status = "请输入要朗读的文本"
        return
    speech.stop()
    speech.say(text, language=state.language, rate=0.5, wait=False)
    state.status = "朗读中"


def pause_speech():
    speech.pause()
    state.status = "已暂停"


def resume_speech():
    speech.resume()
    state.status = "朗读中"


def stop_speech():
    speech.stop()
    state.status = "已停止"


def check_speaking():
    state.status = "朗读中" if speech.is_speaking() else "空闲"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("文本", [
                appui.TextField("内容", text=state.text, on_change=update_text),
                appui.Picker(
                    "语言",
                    selection=state.language,
                    options=["zh-CN", "en-US", "ja-JP"],
                    on_change=update_language,
                ),
            ]),
            appui.Section("控制", [
                appui.Button("朗读", action=speak)
                .button_style("bordered_prominent"),
                appui.Button("暂停", action=pause_speech),
                appui.Button("继续", action=resume_speech),
                appui.Button("停止", action=stop_speech, role="destructive"),
                appui.Button("检查状态", action=check_speaking),
                appui.Button("刷新语音列表", action=refresh_voices),
            ]),
            appui.Section("状态", [
                appui.LabeledContent("状态", value=state.status),
                appui.LabeledContent("可用语音", value=state.voice_count),
            ]),
        ]).navigation_title("语音朗读")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`say(text, language, rate, pitch, volume, wait)`	朗读文本
`stop()`	立即停止
`pause()` / `resume()`	暂停 / 恢复
`is_speaking()`	是否正在朗读 → `bool`
`available_voices()`	可用语音标识列表

#朗读

say(text, language=None, rate=0.5, pitch=1.0, volume=1.0, wait=False)

python

import speech

speech.say("Hello", language="en-US", wait=False)
speech.say("你好", language="zh-CN", rate=0.5, volume=1.0)

参数	说明
`text`	要朗读的文本
`language`	BCP-47 标签，如 `zh-CN`；`None` 用系统默认
`rate`	语速 0.0–1.0
`pitch`	音调 0.5–2.0
`volume`	音量 0.0–1.0
`wait`	`True` 阻塞到读完；AppUI 里用 `False`

开始新朗读前建议先 stop()，避免多段语音排队。

#播放控制

python

speech.pause()
speech.resume()
speech.stop()
if speech.is_speaking():
    print("正在朗读")

离开页面或切换内容时调用 stop()。

#语音列表

available_voices() — 返回设备可用语音标识列表，适合设置页；不要在 body() 里每次刷新都调用。

python

voices = speech.available_voices()
print(len(voices), voices[:5])

#常见错误

错误写法	后果	修正
AppUI 里 `wait=True`	界面阻塞	使用 `wait=False`
用 `speech` 播放音效	能力不匹配	使用 sound
新朗读前不 `stop()`	多段语音重叠排队	先 `stop()` 再 `say()`
长文本无停止按钮	用户无法打断	提供「停止」按钮

#相关文档

文档	用途
sound	短音效与本地音频
speech_recognition	语音转文字
原生能力入口	MiniApp 场景配方

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。