mcpField
A
audify

audify

github.com/jpcaparas创意与媒体5678 次安装1 天前更新
代码仓库

关于 audify

audify 是一项将可朗读的 URL、文件或文本清理后，通过 Gemini 3.1 Flash TTS 合成为语音的技能，面向需要音频版本内容的用户。输出文件夹包含 MP3、清理后的文本和清单；不适合朗读的内容会停止处理。

主要功能

  1. 01清理文本以适合朗读
  2. 02使用 Gemini 3.1 Flash TTS 合成
  3. 03支持 URL、文件和原始文本
  4. 04输出 MP3、文本和清单
  5. 05按块合成并重试失败片段
  6. 06检查内容是否适合朗读

适用场景

  1. 01将网页文章转换为 MP3
  2. 02把本地文档制作成语音
  3. 03从标准输入合成原始文本
  4. 04在合成前检查内容适用性

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jpcaparas/skills --skill audify

安装后在 Claude Code 中输入/audify确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AGENTS.md
metadata.json
README.md
skill-card.prompt.md
agents/
openai.yaml
assets/
.gitkeep
evals/
evals.json
references/
api.md
configuration.md
gotchas.md
patterns.md
scripts/
audify.py
probe_gemini_tts.py
test_audify_unit.py
test_skill.py
validate.py
templates/
sample-input.md

详细介绍

audify

将易读的资源整理成适合旁白朗读的文本，使用 Gemini 3.1 Flash TTS 进行语音合成，并写入带时间戳的输出文件夹，其中包含 MP3、清理后的文本稿和清单。

已根据 2026 年 4 月 15 日更新的 Gemini API 语音生成文档，以及 2026 年 4 月 16 日发布的 Google Cloud 博客文章进行验证。

决策树

你要处理哪种输入？

  • 应该听读的 URL、Markdown 文件、HTML 文件、DOCX、纯文本文件或原始文本

    • 运行 python3 scripts/audify.py ...

  • 主要由代码、日志、表格、压缩后的 JSON 或其他不适合朗读的内容构成的资源

    • 不要强行进行 TTS，直接说明该内容不适合作为朗读对象。

  • 声音或语气存在实质性歧义的请求

    • 合成前先简短询问一个问题。
    • 使用：“我应该使用哪种声音和表达方式？如果你不在意，我会使用 Kore，采用清晰、中性的旁白风格。”

  • 用户不在意风格细节的请求

    • 默认使用 Kore，并采用清晰、中性的语气。

  • 包含多个分块或大型清理后文本稿的较长任务

    • 事先告知用户，多分块 TTS 可能需要几分钟，而且期间可能会有静默等待。
    • 不要在每次短暂轮询时都播报进度。最好先发送一条预期说明，然后等待分块进度或任务完成。

  • 缺少 GEMINI_API_KEY、gemini-3.1-flash-tts-preview 不可用、缺少 ffmpeg，或读取尝试次数已用尽

    • 说明具体缺少的前置条件，然后停止。

快速参考

任务命令阅读
将 URL 转换为 MP3 包python3 scripts/audify.py "https://example.com/"references/patterns.md
将本地文件转换为 MP3 包python3 scripts/audify.py --file templates/sample-input.md --voice Kore --nuance "Warm documentary narrator"references/patterns.md
从 stdin 读取原始文本cat templates/sample-input.md | python3 scripts/audify.py --stdinreferences/patterns.md
仅检查内容是否适合朗读python3 scripts/audify.py --url "https://example.com/" --check-onlyreferences/patterns.md
实时模型与合成探测python3 scripts/probe_gemini_tts.py --mode allreferences/api.md

阅读指南

如果用户需要……阅读
原始 Gemini REST 格式、支持的模型、声音和失败代码references/api.md
环境变量、密钥设置、ffmpeg 和前置条件检查references/configuration.md
URL/文件/文本工作流、输出包布局和提问规则references/patterns.md
失败处理、重试，以及 audify 应停止的原因references/gotchas.md

操作规则

  1. 将 SKILL.md 视为入口，并严格限定工具选择：生产运行使用 scripts/audify.py，实时验证使用 scripts/probe_gemini_tts.py。
  2. 先清理，再合成。进行 TTS 前，移除标记、HTML、代码围栏和裸 URL，让朗读稿尽量贴近可读文本，而非传输格式。
  3. 尽可能保留人类可读文本。保留可见的锚文本、标题、段落内容和行内文本；删除仅用于结构组织而非朗读的模板内容。
  4. 如果源内容不适合朗读，就停止。不要仅仅因为代码转储、日志、堆栈跟踪、原始表格或二进制数据块能解码为文本，就把它们读出来。
  5. 如果已耗尽读取尝试，就停止。不要在获取失败或文件无法解码时，悄悄退而求其次，编造摘要。
  6. 长时间运行前，先说明运行预期。对于多块 TTS，告知用户合理的时间范围，例如“通常需要 2-6 分钟”，并说明各块完成之间出现静默是正常现象。
  7. 不要频繁催促用户查看进度。发送初始预期说明后，仅在有重要状态变化时（例如块进度、重试或最终完成）才报告。
  8. 大块内容暂时失败时，自动拆分后再放弃。使用更小的块边界重试，同时保持相同的语音、语气、模型和输出格式。

输出约定

默认情况下，scripts/audify.py 会在当前工作目录下创建 audify-output/<timestamp>-<slug>/。

该文件夹包含：

  • 默认生成的 audio.mp3
  • 包含最终朗读稿的 cleaned.txt
  • 包含来源、语音、语气、分块和重试元数据的 manifest.json
  • 封装器输出 JSON 和状态流中的运行预期
  • 大块内容拆分成更小块重试时的备用分块元数据

不需要 MP3 转换时，使用 --format wav。

注意事项

  1. Gemini TTS 返回的是 PCM，而非 MP3：Gemini API 返回 Base64 编码的 PCM 音频。此技能会使用本地 ffmpeg 转换，因此默认 MP3 流程缺少 ffmpeg 时会直接终止。
  2. Gemini 3.1 Flash TTS 可能会出现暂时性的 500 错误：Google 文档提到，模型偶尔会输出文本 token 而非音频 token。封装器会通过退避重试暂时性故障。
  3. 含糊的提示词可能被拒绝或被朗读出来：封装器会使用明确的“仅合成语音”前言，以及带标签的 TRANSCRIPT 部分，避免把指令当成旁白。
  4. 语音和提示词可能不协调：Google 提醒，角色设定与语音差异过大时，听感可能会不自然。用户要求特定人设时，请确保所选语音和语气方向一致。
  5. HTML 提取只能尽力而为：在结构混乱的页面上，博客界面元素、导航文本或法律页脚文本仍可能混入。如果清理后的预览不正确，请停止并要求用户缩小来源范围。
  6. 长时间静默不等于失败：多块运行可能会在 Gemini 调用和本地 MP3 转换中耗费几分钟。不要把每段 30 秒的静默都当成问题。
  7. 单个大块仍可能暂时失败：发生这种情况时，封装器应只将该块拆分成更小的部分，然后使用相同的语音、语气、模型和格式继续处理，而不是要求用户从头手动重跑。

辅助脚本

  • scripts/audify.py 是处理 URL、文件、stdin 和原始文本输入的生产封装器。
  • scripts/probe_gemini_tts.py 会针对模型发现和短文本合成运行安全的实时探测。
  • scripts/test_audify_unit.py 涵盖清理器、分块、DOCX 提取和终止启发式规则。
  • scripts/validate.py 会检查结构、交叉引用和遗留的模板占位符。
  • scripts/test_skill.py 会运行结构检查、单元测试；如果存在 GEMINI_API_KEY，还会运行实时冒烟探测。

评论

支持 Markdown