--- name: "piper-tts-engine-free" description: "基于 Piper 的本地离线文字转语音工具，零云端调用、零 API 费用，适合个人单条语音生成。Use when 需要API集成、接口对接、Webhook配置、系统连接时使用。不适用于逆向工程闭源API。适用于独立开发者、企业团队和自动化工作流场景。支持中文交互，无需复杂配置即开即用。输出结果可直接使用，减少二次加工成本。" license: Proprietary allowed-tools: read exec compatibility: "Requires LLM with tool-use capability" metadata: displayName: "本地语音合成免费版" version: "1.0.0" summary: "基于 Piper 的本地离线文字转语音工具，零云端调用、零 API 费用，适合个人单条语音生成。" tags: - "语音合成" - "本地TTS" - "离线语音" - "文字转语音" - "个人效率" source: "SkillHub" converted_at: "2026-07-22T17:58:36" tools: - exec - read - write --- # 本地语音合成 免费版 ## 概述 免费版本地语音合成工具基于 Piper 引擎，为个人用户提供完全离线的文字转语音能力。无需云端 API、无需 API Key、零费用，安装后即可在本地生成高质量语音。生成的 MP3 文件可作为语音消息投递至 Telegram、Discord 等渠道。本版本适合个人开发者、内容创作者与无障碍辅助场景。 与专业版相比，免费版聚焦单条文本合成与预置音色选择，不包含批量合成、自定义音色训练、SSML 标记与 API 服务化等高级能力。但两者的核心合成命令完全一致，便于后续平滑升级。 ## 核心能力 | 能力 | 说明 | | --- | --- | | 本地离线合成 | 完全在本地运行，不依赖任何云端服务 | | 单条文本合成 | 将一段文本转换为 MP3 语音文件 | | 预置音色 | 提供多个预置音色（英语为主） | | 快速生成 | 合成速度约 0.5-1 秒，远快于云端 TTS | | 语音消息投递 | 生成的 MP3 可作为原生语音消息发送 | | 零配置 | 安装后无需 API Key 即可使用 | **技术实现要点**：核心能力基于`input_params`参数与`output_format`配置实现,支持创建/查询/修改/删除等操作模式,通过`config_options`进行运行时配置。 ### 核心功能执行 用`input_params`参数进行配置。 **输出**: 返回核心功能执行的执行结果,包含操作状态和输出数据。 - 执行此能力时使用`input_params`参数,支持创建/查询/导出操作 ### 参数配置与调用 用`config_options`参数进行配置。 **输出**: 返回参数配置与调用的执行结果,包含操作状态和输出数据。 - 执行此能力时使用`config_options`参数,支持修改/重置/导入操作 ### 结果处理与输出 用`output_format`参数进行配置。 **输出**: 返回结果处理与输出的执行结果,包含操作状态和输出数据。 - 执行此能力时使用`output_format`参数,支持导出/保存/转换操作 **能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：Piper、的本地离线文字转、语音工具、零云端调用、适合个人单条语音、面向个人用户的本、地离线文字转语音、多音色选择、离线运行、适用场景、个人语音消息生成、离线朗读、无障碍辅助、内容创作配音、差异化、免费版聚焦单条文、本合成与基础音色、不含批量合成与自、定义音色训练、适用关键词、语音合成、文字转语音、voice等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。 ## 使用场景 ### 场景一：个人语音消息生成 用户希望将一段文字转为语音消息发送给好友。 ```bash # 生成语音 scripts/piper-speak.sh "嘿，今天天气不错，要不要一起出去走走？" # 示例 # MP3 路径: ~/.piper/output/20260718_153000.mp3 ``` 将输出路径填入回复，以语音消息形式投递： ```text [[audio_as_voice]] ``` ### 场景二：内容创作配音 博主为短视频生成英文旁白，避免真人录音。 ```bash # 生成英文旁白 scripts/piper-speak.sh "Welcome to my channel. Today we will explore the future of AI." en_US-ryan-high # 输出 # MP3 路径: ~/.piper/output/20260718_153100.mp3 ``` ### 场景三：无障碍朗读辅助 将长文本转为语音，方便视障用户或通勤时收听。 ```bash # 朗读一段文章摘要 scripts/piper-speak.sh "本文介绍了向量数据库的核心原理与典型应用场景，包括相似度检索、推荐系统与语义搜索。" ``` ## 不适用场景 以下场景本地语音合成免费版不适合处理： - 加密文件破解 - 损坏文件修复 - 物理介质数据恢复 ## 触发条件 需要文件处理、文档转换、格式互转、内容提取时使用。不适用于非本工具能力范围的需求。 ## 快速开始 1. 运行安装脚本，自动安装 Piper 引擎与默认音色。 ```bash scripts/setup-piper.sh ``` 安装脚本会： - 通过 pip 安装 `piper-tts` - 下载默认音色 `en_US-kusal-medium` - 配置输出目录 `~/.piper/output/` 2. 生成领先条语音。 ```bash scripts/piper-speak.sh "Hello, this is my first voice message." ``` 3. 获取 MP3 路径并投递。 ```text [[audio_as_voice]] MEDIA:/path/to/output.mp3 ``` ## 配置示例 免费版配置通过环境变量或脚本参数控制。 ```bash # ~/.piper/config.sh export PIPER_VOICE="en_US-kusal-medium" # 默认音色 export PIPER_OUTPUT_DIR="$HOME/.piper/output" # 输出目录 export PIPER_SPEED="1.0" # 语速（0.5-2.0） ``` **可用预置音色** | 音色名称 | 语言 | 风格 | 推荐用途 | | --- | --- | --- | --- | | `en_US-kusal-medium` | 美式英语 | 清晰男声（默认） | 通用场景 | | `en_US-ryan-high` | 美式英语 | 高质量男声 | 内容创作 | | `en_US-hfc_male-medium` | 美式英语 | 自然男声 | 日常对话 | | `en_GB-northern_english_male-medium` | 英式英语 | 英国男声 | 英式内容 | 下载更多音色： ```bash scripts/setup-piper.sh --voice en_US-ryan-high scripts/setup-piper.sh --voice en_GB-northern_english_male-medium ``` ## 优选实践 - **按需合成**：不要设置 `messages.tts.auto: "always"`，这会使每条回复都变慢。保持按需触发。 - **音色选择**：内容创作推荐 `en_US-ryan-high`（高质量），日常使用推荐 `en_US-kusal-medium`（速度快）。 - **文本长度**：单条合成建议不超过 500 字，过长文本建议分段合成后拼接。 - **语速调整**：通过 `PIPER_SPEED` 环境变量调整，1.0 为正常速度，1.2 适合快节奏内容。 - **输出管理**：定期清理 `~/.piper/output/` 目录，避免磁盘空间占用过多。 - **离线运行**：安装完成后完全离线，无需网络连接，适合无网环境使用。 - **平台兼容**：支持 macOS（Apple Silicon + Intel）与 Linux，需 Python 3.9+。 ## 常见问题 ### 依赖详情 Piper 需要 Python 3.9+。运行 `python3 --version` 检查版本，若低于 3.9 请先升级 Python。 ### Q2：合成的语音有杂音或断续？ - 检查文本中是否包含特殊字符，尝试去除 emoji 与特殊符号。 - 确认音色模型完整下载，重新运行 `scripts/setup-piper.sh --voice <音色名>`。 - 长文本建议分段合成。 ### Q3：免费版支持中文语音吗？ 免费版预置音色以英语为主。如需中文语音合成，可尝试下载社区中文音色模型，或升级至专业版获取多语言支持。 ### Q4：可以在 Windows 上使用吗？ 免费版主要支持 macOS 与 Linux。Windows 用户建议通过 WSL（Windows Subsystem for Linux）运行，或升级至专业版获取原生 Windows 支持。 ### Q5：合成的 MP3 如何发送到 Telegram？ 在 Agent 回复中使用 `[[audio_as_voice]]` 标记加上 `MEDIA:`，即可作为原生语音消息投递至 Telegram 等渠道。 ### 已知限制 没有。免费版完全本地运行，无任何使用次数或频率限制。合成速度取决于本地硬件性能。 ### Q7：如何调整语速？ 通过环境变量 `PIPER_SPEED` 设置，范围 0.5（慢速）到 2.0（快速），默认 1.0。 ```bash scripts/piper-speak.sh "这是一段加速语音" ``` ## 依赖说明 ### 运行环境 - **Agent 平台**：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等） - **操作系统**：macOS（Apple Silicon + Intel）/ Linux - **运行时**：Python 3.9+ - **网络**：仅安装时需要下载音色模型，运行时完全离线 ### 第三方依赖 | 依赖项 | 类型 | 是否必需 | 获取方式 | | :------- | :----- | :--------- | :--------- | | Python 3.9+ | 运行时 | 必需 | python.org 官方下载 | | piper-tts | Python 包 | 必需 | `pip install piper-tts`（安装脚本自动处理） | | 音色模型 | 模型文件 | 必需 | 安装脚本自动下载默认音色 | | LLM API | API | 必需 | 由 Agent 内置 LLM 提供 | | onnxruntime | Python 包 | 必需 | `pip install onnxruntime`（自动安装） | ### API Key 配置 - 免费版无需任何 API Key。 - 完全本地离线运行，不调用任何云端服务。 ### 可用性分类 - **分类**：MD+EXEC（纯 Markdown 指令，部分功能需要 exec 命令行执行能力） - **说明**：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 执行任务。免费版为单条合成功能子集，核心合成命令与专业版完全兼容。 ## 错误处理 | 错误场景 | 原因 | 处理方式 | |---------|------|---------| | 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 | | 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 | | 网络错误 | 连接超时或不可达 | 执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案 | ## 示例 ### 基本用法 **输出**：返回执行结果,包含操作状态和输出数据 ```text 用户: 执行核心功能 Skill: 正在执行核心功能... Skill: 执行完成,结果如下: 操作成功 ``` ## 安全注意事项 | 风险类型 | 防范措施 | |----------|---------| | API密钥泄露 | 通过环境变量配置，禁止硬编码到代码或配置文件中 | | 命令执行风险 | 仅执行白名单命令，避免拼接用户输入到命令行参数中 | | 网络通信安全 | 使用HTTPS协议，验证SSL证书有效性 | | 敏感数据暴露 | 输出结果中不包含密钥、令牌等敏感信息 | 使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。