语音转文字神器：pi-skills的transcribe如何用Groq Whisper API快速生成带标点转录-平芜编程栈

语音转文字神器：pi-skills的transcribe如何用Groq Whisper API快速生成带标点转录

【免费下载链接】pi-skillsSkills for pi coding agent (compatible with Claude Code and Codex CLI)项目地址: https://gitcode.com/gh_mirrors/pi/pi-skills

pi-skills的transcribe技能是一个基于 Groq Whisper API 的语音转文字（Speech-to-Text）技能：一条命令把音频文件转成带标点、大小写正确的纯文本，支持 m4a、mp3、wav、ogg、flac、webm 六种格式。整个技能只有一个 shell 脚本，零依赖（只需 curl 和一个 API Key），同时兼容 pi coding agent、Claude Code 和 Codex CLI。

为什么值得用这个语音转文字技能？

很多人第一次听说 pi-skills，它其实是一个开源的 AI 编程智能体"技能包"仓库，里面打包了 8 个实用技能：网页搜索、浏览器自动化、Google 日历/云盘/邮件 CLI、语音转文字、VS Code 集成和 YouTube 字幕抓取。

其中的 transcribe 技能解决了日常一个高频痛点——把会议录音、播客、语音消息快速变成可搜索的文本。它有几个明显优势：

⚡极快：走 Groq 的whisper-large-v3-turbo模型，云端推理速度远快于本地跑 Whisper
✒️带标点：输出自带标点符号和正确的大小写，不是干巴巴的字块
🪶极简：核心逻辑就 transcribe.sh 这一个 30 来行的脚本
🤖智能体友好：以 SKILL.md 格式编写，AI 编程智能体可以理解并自动引导你完成配置

文件	作用
transcribe/SKILL.md	技能说明，告诉 AI 智能体如何配置和使用
transcribe/transcribe.sh	实际的转写脚本，调用 Groq Whisper API
README.md	整个 pi-skills 的安装说明和技能清单

快速上手：三步装好 transcribe

第一步：克隆仓库

git clone https://gitcode.com/gh_mirrors/pi/pi-skills

第二步：准备 Groq API Key

脚本依赖GROQ_API_KEY环境变量。如果没有 Groq 账号，到 console.groq.com 注册并创建一个 API Key，然后选一种方式配置：

方式 A：写入 shell 配置文件（推荐长期使用）

export GROQ_API_KEY="<你的api-key>" # 加入 ~/.zshrc 或 ~/.bashrc source ~/.zshrc # 让配置立即生效

方式 B：在技能目录放一个 config 文件

脚本会优先加载同目录下的config文件（见 transcribe.sh 的 source 逻辑），所以也可以：

echo 'GROQ_API_KEY="你的key"' > pi-skills/transcribe/config

第三步：直接使用

./pi-skills/transcribe/transcribe.sh 会议录音.m4a

转录结果会直接打印到终端（stdout），纯文本、带标点、首字母大写，方便管道处理：

./transcribe.sh 笔记.wav | pbcopy # 转写完直接复制到剪贴板

支持哪些格式？有什么限制？

根据 SKILL.md 的说明：

🎵支持格式：m4a、mp3、wav、ogg、flac、webm（基本覆盖手机、录音笔、浏览器录制的常见格式）
📦文件大小上限：25MB（Groq 的接口限制，长录音建议先分段）
📄输出：纯文本（plain text），带标点和正确大小写

原理拆解：脚本到底做了什么？

把 transcribe.sh 从头读一遍，逻辑非常清晰，一共四步：

加载配置：如果技能目录下存在config文件就 source 进来，方便不污染环境变量
参数校验：没传音频文件路径时，打印用法Usage: transcribe.sh <audio-file>（transcribe.sh）
Key 检查：GROQ_API_KEY未设置时给出明确报错，并提示如何创建 config 文件（transcribe.sh）
发起请求：用 curl 把音频上传到 Groq 的 OpenAI 兼容端点（transcribe.sh）：

curl -s -X POST "https://api.groq.com/openai/v1/audio/transcriptions" \ -H "Authorization: Bearer $GROQ_API_KEY" \ -F "file=@${AUDIO_FILE}" \ -F "model=whisper-large-v3-turbo" \ -F "response_format=text"

关键点在于model=whisper-large-v3-turbo（Groq 平台上速度最快的 Whisper 变体）和response_format=text（只返回纯文本，不含 JSON 包装）。因为端点是 OpenAI 兼容的/v1/audio/transcriptions，如果你有自己的 OpenAI Key，把 URL 和 Key 换掉即可无缝替换。

在 AI 智能体中使用 transcribe

这个技能的价值不仅在于命令行，更在于它是一份标准的SKILL.md：pi-coding-agent、Claude Code、Codex CLI 等智能体读取后，会主动引导你完成配置——检查GROQ_API_KEY是否已设置、没有就带你一步步申请并写入 shell 配置文件（SKILL.md 的 Setup 一节就是写给智能体看的指令）。

不同智能体的安装位置参考 README.md：

pi-coding-agent：git clone到~/.pi/agent/skills/pi-skills
Codex CLI：克隆到~/.codex/skills/pi-skills
Claude Code：只递归一层查找 SKILL.md，需要把transcribe目录软链到~/.claude/skills/下

装好之后，你只需要对智能体说"帮我把这个录音转成文字"，它就会自己跑脚本、处理错误并返回结果。

常见问题排查 🛠️

现象	原因与解决
`Error: GROQ_API_KEY not set`	Key 未生效，重新`source ~/.zshrc`或改用 config 文件
`Error: File not found`	音频路径不对，建议用绝对路径
上传失败/413	文件超过 25MB 上限，先用 ffmpeg 分段或转码压缩
输出为空	检查网络能否访问 api.groq.com，Key 是否有转录额度

写在最后：不止语音转文字

transcribe 是 pi-skills 里最"即插即用"的技能之一——MIT 协议开源（见 LICENSE），脚本短到五分钟就能读完并改成自己的版本。如果你还有现成的 YouTube 视频想要文字稿，仓库里的 youtube-transcript 技能可以按视频 ID 或链接直接抓取带时间戳的字幕，和 transcribe 正好互补：一个管本地音频，一个管在线视频，组合起来就是完整的文字化工作流 📝

【免费下载链接】pi-skillsSkills for pi coding agent (compatible with Claude Code and Codex CLI)项目地址: https://gitcode.com/gh_mirrors/pi/pi-skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考