{"id":"52e1b761-47da-4a81-8632-9d2aca8813b5","entityType":"agent","slug":"clawhub-xuxuclassmate-whisper-voice-transcription","name":"Whisper Voice Transcription (whisper.cpp)","canonicalUrl":"https://www.xpersona.co/agent/clawhub-xuxuclassmate-whisper-voice-transcription","canonicalPath":"/agent/clawhub-xuxuclassmate-whisper-voice-transcription","generatedAt":"2026-10-13T11:34:54.484Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T23:25:29.190Z","emptyReason":null},"description":"Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical. Skill: Whisper Voice Transcription (whisper.cpp) Owner: xuxuclassmate Summary: Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical. Tags: audio:1.1.1, chinese:1.1.0, latest:1.1.1, media:1.1.1, speech-to-text:1.1.1, stt:1.1.1, transcription:1.1.1, voice:1.1.1, voice-transcription:1.0.0, whisper:1.1.1 Version history: v1.1.1 | 2026-04-22T0","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 977 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17ev136gszam5rsp8hcgkksex83gbfy:whisper-voice-transcription","sourceUrl":"https://clawhub.ai/xuxuclassmate/whisper-voice-transcription","homepage":"https://clawhub.ai/xuxuclassmate/skills/whisper-voice-transcription","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/xuxuclassmate/whisper-voice-transcription","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/xuxuclassmate/skills/whisper-voice-transcription","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical. Skill: Whisper Voice Trans"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:25:29.190Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:25:29.190Z","emptyReason":null},"stars":null,"forks":null,"downloads":977,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.1.1","tractionLabel":"977 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T23:25:29.113Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T23:25:29.190Z","lastCrawledAt":"2026-10-11T23:25:29.113Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T23:25:29.113Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.1","createdAt":"2026-04-22T05:44:05.082Z","changelog":"Translate the guide to English and tighten the instructions around official downloads and scoped audio-file discovery.","fileCount":3,"zipByteSize":2456},{"version":"1.1.0","createdAt":"2026-04-18T06:42:26.326Z","changelog":"安全修复：移除非官方镜像域名，改用官方GitHub/HuggingFace源；移除系统特定路径；添加安全建议章节","fileCount":2,"zipByteSize":3563},{"version":"1.0.0","createdAt":"2026-04-18T06:10:06.025Z","changelog":"Initial publish: whisper.cpp + large-v3 本地语音转录方案，支持中文语音转文字","fileCount":2,"zipByteSize":4736}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17ev136gszam5rsp8hcgkksex83gbfy:whisper-voice-transcription","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-13T11:34:54.484Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xuxuclassmate-whisper-voice-transcription/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T23:25:29.190Z","emptyReason":null},"readme":"Skill: Whisper Voice Transcription (whisper.cpp)\n\nOwner: xuxuclassmate\n\nSummary: Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical.\n\nTags: audio:1.1.1, chinese:1.1.0, latest:1.1.1, media:1.1.1, speech-to-text:1.1.1, stt:1.1.1, transcription:1.1.1, voice:1.1.1, voice-transcription:1.0.0, whisper:1.1.1\n\nVersion history:\n\nv1.1.1 | 2026-04-22T05:44:05.082Z | user\n\nTranslate the guide to English and tighten the instructions around official downloads and scoped audio-file discovery.\n\nv1.1.0 | 2026-04-18T06:42:26.326Z | user\n\n安全修复：移除非官方镜像域名，改用官方GitHub/HuggingFace源；移除系统特定路径；添加安全建议章节\n\nv1.0.0 | 2026-04-18T06:10:06.025Z | user\n\nInitial publish: whisper.cpp + large-v3 本地语音转录方案，支持中文语音转文字\n\nArchive index:\n\nArchive v1.1.1: 3 files, 2456 bytes\n\nFiles: skill-card.md (2178b), SKILL.md (1816b), _meta.json (146b)\n\nFile v1.1.1:SKILL.md\n\n---\nname: whisper-voice-transcription\ndescription: Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical.\ntags: [speech-to-text, stt, voice, transcription, whisper, audio]\nversion: 1.1.1\n---\n\n# Whisper Voice Transcription with whisper.cpp\n\n## When to use\n\n- You want local speech-to-text without sending audio to a third party.\n- You need a fallback workflow when a built-in transcription tool fails.\n- You want an operator guide for compiling and running `whisper.cpp`.\n\n## Prerequisites\n\n- `git`\n- `cmake`\n- a C or C++ compiler\n- `ffmpeg`\n\n## Build steps\n\n```bash\ngit clone --depth 1 https://github.com/ggerganov/whisper.cpp.git ~/whisper.cpp\ncd ~/whisper.cpp\ncmake -B build -DCMAKE_BUILD_TYPE=Release\ncmake --build build -j4\n```\n\nDownload a model from the official `ggerganov/whisper.cpp` releases or Hugging Face repository and place it under `~/whisper.cpp/models/`.\n\n## Standard transcription flow\n\n```bash\nffmpeg -y -i input_audio.ogg -ar 16000 -ac 1 -f wav /tmp/voice.wav\n~/whisper.cpp/build/bin/whisper-cli \\\n  -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n  -f /tmp/voice.wav \\\n  -l auto \\\n  --no-timestamps\n```\n\n## Fallback workflow\n\nIf a higher-level tool fails, first locate the exact cache or upload path used by that tool. Search only within the expected application cache directory instead of scanning the entire home directory.\n\n## Cloud fallback\n\nIf local transcription is too slow or unavailable, use an approved speech API and tell the user that audio will leave the machine.\n\n## Guardrails\n\n- Download binaries and models only from official sources.\n- Verify hashes when possible.\n- Do not search unrelated directories for audio files.\n- Be explicit when using a cloud provider because that changes the privacy model.\n\nFile v1.1.1:_meta.json\n\n{\n  \"ownerId\": \"kn7a6qzk16ny6zj2a6ge10exrn82q9qp\",\n  \"slug\": \"whisper-voice-transcription\",\n  \"version\": \"1.1.1\",\n  \"publishedAt\": 1776836645082\n}\n\nFile v1.1.1:skill-card.md\n\n## Description:\n\nBuild and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[xuxuclassmate](https://clawhub.ai/user/xuxuclassmate)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, engineers, and operators use this skill to build whisper.cpp, prepare audio, run local speech-to-text transcription, and choose an approved cloud fallback when local transcription is not practical.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Building third-party code from a moving upstream branch can change the behavior or trust boundary of local transcription over time.\n\nMitigation: Pin whisper.cpp to a known release or commit before building and review updates before adopting them.\n\nRisk: Downloaded transcription models may be tampered with or may not match the intended source.\n\nMitigation: Download models only from official sources and verify hashes when available.\n\nRisk: Using a fixed temporary audio path can expose private audio or leave sensitive files behind.\n\nMitigation: Use a unique private temporary file for each transcription and remove it after use.\n\nRisk: Cloud transcription fallback sends audio outside the local machine.\n\nMitigation: Use cloud fallback only with user acceptance and an approved speech API.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/xuxuclassmate/skills/whisper-voice-transcription)\n- [whisper.cpp](https://github.com/ggerganov/whisper.cpp)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [None]\n\n## Skill Version(s):\n\n1.1.1 (source: artifact frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.1.0: 2 files, 3563 bytes\n\nFiles: SKILL.md (6460b), _meta.json (146b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: whisper-voice-transcription\ndescription: 语音消息转文字（STT）完整方案 — whisper.cpp（C++本地，首选）+ 云端API兜底。含安装、模型下载、使用流程和踩坑记录。\ntags: [speech-to-text, stt, voice, transcription, whisper, audio, chinese]\n---\n\n# 语音转文字（Speech-to-Text）方案\n\n## 🎯 主方案：whisper.cpp（本地离线转录）\n\n> 纯 C++ 实现的 Whisper 语音识别，无需 Python 虚拟环境，支持离线使用。\n\n### 前置依赖\n\n| 依赖 | 用途 | 安装方式 |\n|------|------|---------|\n| `g++` / `gcc` / `make` | 编译 whisper.cpp | 系统包管理器 |\n| `cmake` (≥3.14) | 构建系统 | [CMake 官网](https://cmake.org/download/) 或包管理器 |\n| `ffmpeg` | 音频格式转换 | 系统包管理器 |\n| `git` | 克隆源码 | 系统包管理器 |\n\n### 安装步骤\n\n#### Step 1: 克隆 whisper.cpp 源码\n\n```bash\ngit clone --depth 1 https://github.com/ggerganov/whisper.cpp.git ~/whisper.cpp\ncd ~/whisper.cpp\n```\n\n> 💡 如果 GitHub 访问慢，可使用 HuggingFace 镜像或 Git 代理。**请始终验证下载文件的完整性（SHA256 校验）。**\n\n#### Step 2: 编译\n\n```bash\ncmake -B build -DCMAKE_BUILD_TYPE=Release\nmake -C build -j$(nproc)\n```\n\n编译产物在 `~/whisper.cpp/build/bin/`：\n- `whisper-cli` — 命令行转录工具 ✅ 主要用这个\n- `whisper-server` — HTTP 服务端\n- `whisper-quantize` — 模型量化工具\n\n#### Step 3: 下载模型\n\n从 [HuggingFace](https://huggingface.co/ggerganov/whisper.cpp/tree/main) 下载 ggml 格式模型到 `~/whisper.cpp/models/`：\n\n| 模型 | 大小 | 准确度 | 速度 | 推荐场景 |\n|------|------|--------|------|---------|\n| **ggml-large-v3.bin** ⭐ | ~3GB | 最高 | 较慢 | **默认推荐，生产使用** |\n| ggml-base.bin | ~142MB | 中等 | 最快 | 快速测试/调试 |\n| ggml-small.bin | ~466MB | 较好 | 中等 | 平衡选择 |\n\n> ⚠️ **安全提醒**：仅从官方 HuggingFace 仓库 (`ggerganov/whisper.cpp`) 下载模型文件。下载后建议校验 SHA256 哈希。\n\n#### Step 4: 验证安装\n\n```bash\n~/whisper.cpp/build/bin/whisper-cli --help\n# 应显示版本信息和用法\n```\n\n---\n\n## 🔧 标准转录流程\n\n### 两步走：预处理 + 转录\n\n```bash\n# Step 1: ffmpeg 预处理 — 任意音频格式 → 16kHz mono wav\nffmpeg -i <输入音频文件> -ar 16000 -ac 1 -f wav /tmp/voice.wav -y\n\n# Step 2: whisper-cli 转录\n~/whisper.cpp/build/bin/whisper-cli \\\n    -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n    -f /tmp/voice.wav -l zh --no-timestamps\n```\n\n### 一键脚本封装\n\n```bash\ntranscribe() {\n    local input=\"$1\"\n    local wav=\"/tmp/whisper_$(date +%s).wav\"\n    ffmpeg -y -i \"$input\" -ar 16000 -ac 1 -f wav \"$wav\" 2>/dev/null || { echo \"ffmpeg转换失败\"; return 1; }\n    ~/whisper.cpp/build/bin/whisper-cli \\\n        -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n        -f \"$wav\" -l zh --no-timestamps 2>/dev/null\n}\n# 用法: transcribe your_audio.ogg\n```\n\n### 参数说明\n\n| 参数 | 含义 | 推荐值 |\n|------|------|--------|\n| `-m` | 模型路径 | `ggml-large-v3.bin`（最准）/ `ggml-base.bin`（快速） |\n| `-f` | 音频文件路径 | 必须是 wav 格式 |\n| `-l` | 语言 | `zh`(中文), `en`(英文), `auto`(自动检测) |\n| `--no-timestamps` | 不输出时间戳 | 推荐加上，输出更干净 |\n| `-t` | 线程数 | 默认4，可根据 CPU 核心数调大加速 |\n\n---\n\n## 🔄 Hermes 内置转录失败时的回退流程\n\n当 Hermes 内置语音转录报错时，可用此方案手动转录：\n\n### Step 1: 定位语音文件\n\n语音文件通常在 Hermes 的音频缓存目录中。查找最近的音频文件：\n\n```bash\n# 查找最近 5 分钟内修改的音频文件（路径因配置而异）\nfind ~ -type f -mmin -5 \\( -name \"*.ogg\" -o -name \"*.mp3\" -o -name \"*.wav\" \\) 2>/dev/null\n```\n\n> ⚠️ 请根据实际 Hermes 配置调整搜索路径。常见位置包括 `~/.hermes/cache/audio/` 或平台特定缓存目录。\n\n### Step 2: 转录\n\n```bash\n# 将 <找到的音频文件路径> 替换为实际路径\nffmpeg -y -i <音频文件> -ar 16000 -ac 1 -f wav /tmp/voice.wav 2>/dev/null\n~/whisper.cpp/build/bin/whisper-cli \\\n    -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n    -f /tmp/voice.wav -l zh --no-timestamps 2>/dev/null\n```\n\n---\n\n## ☁️ 备选方案：云端 API\n\n当本地算力不足或需要更高准确度时，可使用云端 ASR 服务：\n\n| 服务 | 模型 | 费用 | 特点 |\n|------|------|------|------|\n| [OpenAI Whisper API](https://platform.openai.com/docs/guides/speech-to-text) | whisper-1 | 按量付费 | 准确度高，官方API |\n| [Groq Whisper](https://console.groq.com/) | whisper-large-v3 | 免费额度 | 速度快，免费层可用 |\n| [SiliconFlow SenseVoice](https://cloud.siliconflow.cn) | SenseVoiceSmall | 注册送额度 | 中文优化好 |\n| [DeepSeek](https://platform.deepseek.com/) | - | 极低价格 | 性价比高 |\n\n> 💡 使用云端 API 需要相应平台的 API Key，并确保网络可达。\n\n---\n\n## ⚠️ 注意事项与最佳实践\n\n### 安全建议\n\n1. **仅从官方源下载**：whisper.cpp 仅从 GitHub (`ggerganov/whisper.cpp`) 获取，模型仅从 HuggingFace 官方仓库获取\n2. **校验下载完整性**：大文件下载后应验证 SHA256 哈希\n3. **不要从未知镜像下载可执行文件**：非官方镜像可能篡改文件内容\n4. **权限最小化**：whisper-cli 只需读权限访问模型文件和音频文件\n\n### 性能优化\n\n- 使用 `large-v3` 模型获得最佳中文准确度\n- 增加 `-t` 线程数加速（不超过 CPU 核心数）\n- 音频预处理固定为 16kHz mono 可获得最佳效果\n\n### 常见问题\n\n| 问题 | 原因 | 解决方法 |\n|------|------|---------|\n| 编译失败 | 缺少 cmake 或编译工具 | 安装 build-essential / cmake |\n| 转录乱码/空白 | 音频格式不支持 | 先用 ffmpeg 转 wav |\n| 速度太慢 | 模型太大/CPU太弱 | 换 base 模型或用云端 API |\n| 中文准确度差 | 用了小模型 | 升级到 large-v3 模型 |\n\n---\n\n## 方案对比\n\n| 维度 | whisper.cpp (本地) | 云端 API |\n|------|-------------------|----------|\n| 依赖 | gcc/cmake/ffmpeg | 网络 + API Key |\n| 隐私 | ✅ 本地处理，数据不出机器 | ❌ 音频上传至第三方 |\n| 费用 | 免费（自备算力） | 按 API 调用量计费 |\n| 延迟 | 取决于本地算力 | 取决于网络 |\n| 离线可用 | ✅ 是 | ❌ 否 |\n| 中文准确度 | high (large-v3) | 通常最高 |\n\nFile v1.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7a6qzk16ny6zj2a6ge10exrn82q9qp\",\n  \"slug\": \"whisper-voice-transcription\",\n  \"version\": \"1.1.0\",\n  \"publishedAt\": 1776494546326\n}\n\nArchive v1.0.0: 2 files, 4736 bytes\n\nFiles: SKILL.md (9509b), _meta.json (146b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: whisper-voice-transcription\ndescription: 语音消息转文字（STT）完整方案 — whisper.cpp（C++本地，首选）+ 云端API兜底。含安装、模型下载、使用流程和踩坑记录。\n---\n\n# 语音转文字（Speech-to-Text）方案\n\n## 🎯 当前主方案：whisper.cpp + large-v3（已部署 ✅）\n\n> **用户明确要求使用 whisper.cpp**，纯 C++ 实现，无需 Python 虚拟环境。\n\n### 环境状态\n\n| 组件 | 状态 | 路径 |\n|------|------|------|\n| **whisper-cli** | ✅ 已编译 | `~/whisper.cpp/build/bin/whisper-cli` |\n| **large-v3 模型** | ✅ 已下载 (2.95GB) | `~/whisper.cpp/models/ggml-large-v3.bin` |\n| **base 模型** | ✅ 已下载 (141MB) | `~/whisper.cpp/models/ggml-base.bin` |\n| **cmake** | ✅ v3.31.4 | `~/local/bin/cmake` |\n| **ffmpeg** | ✅ v7.1.3 | `/usr/bin/ffmpeg` |\n\n### 标准转录流程（两步走）\n\n```bash\n# Step 1: ffmpeg 预处理 — 任意格式 → 16kHz mono wav\nffmpeg -i <输入音频> -ar 16000 -ac 1 -f wav /tmp/voice.wav -y 2>/dev/null\n\n# Step 2: whisper-cli 转录（中文，最准）\n~/whisper.cpp/build/bin/whisper-cli \\\n    -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n    -f /tmp/voice.wav -l zh --no-timestamps 2>/dev/null\n```\n\n### 一键脚本封装\n\n```bash\ntranscribe() {\n    local input=\"$1\"\n    local wav=\"/tmp/whisper_$(date +%s).wav\"\n    ffmpeg -y -i \"$input\" -ar 16000 -ac 1 -f wav \"$wav\" 2>/dev/null || { echo \"ffmpeg转换失败\"; return 1; }\n    ~/whisper.cpp/build/bin/whisper-cli \\\n        -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n        -f \"$wav\" -l zh --no-timestamps 2>/dev/null\n}\n# 用法: transcribe /opt/data/cache/audio/audio_xxx.ogg\n```\n\n### 常用参数说明\n\n| 参数 | 含义 | 推荐值 |\n|------|------|--------|\n| `-m` | 模型路径 | `models/ggml-large-v3.bin`（最准）/ `ggml-base.bin`（快速） |\n| `-f` | 音频文件 | 必须是 wav 格式（用 ffmpeg 预处理） |\n| `-l` | 语言 | `zh`(中文), `en`(英文), `auto`(自动) |\n| `--no-timestamps` | 不输出时间戳 | 推荐加上 |\n| `-t` | 线程数 | 默认4，可调大加速 |\n\n### 模型选择指南\n\n| 模型 | 大小 | 准确度 | 速度(11秒音频) | 场景 |\n|------|------|--------|----------------|------|\n| **large-v3** ⭐ | 2.95GB | 最高 | ~30-60s | **默认推荐** |\n| base | 141MB | 中等 | ~5s | 快速测试 |\n| small | ~466MB | 较好 | ~15s | 平衡选择 |\n| medium | ~1.5GB | 很好 | ~30s | 高质量需求 |\n\n### 实测准确率对比（同一段11秒中文语音）\n\n| 模型 | 转录结果 | 评价 |\n|------|---------|------|\n| base | \"那就是对地区为现任因为我在本地教授是好的包括那个偶尔文若茨也是好的\" | ❌ 多处错误 |\n| **large-v3** | \"那就是这地区被限制了因为我在本地调用的时候是好的包括那个open rules也是好的\" | ✅ **语义通顺** |\n\n---\n\n## 📦 安装与部署（从零开始）\n\n### 前置条件检查\n\n```bash\nwhich g++ gcc make && echo \"✅ 编译工具就绪\" || echo \"❌ 缺编译工具\"\nwhich cmake && echo \"✅ cmake就绪\" || echo \"⚠️ 需要安装cmake\"\n```\n\n### Step 1: 克隆源码（必须用镜像）\n\n```bash\nrm -rf ~/whisper.cpp\ngit clone --depth 1 https://ghfast.top/https://github.com/ggerganov/whisper.cpp.git ~/whisper.cpp\n```\n\n> ❌ 直连 GitHub 可能超时。✅ 用 ghfast.top 镜像加速。\n\n### Step 2: 安装 cmake（如系统没有）\n\n**⚠️ 大坑：不要下载 .sh 安装脚本！** 非交互环境下解压会失败。\n\n**正确做法：下载预编译 tar.gz 包**\n\n```bash\npython3 -c \"\nimport urllib.request, os\nurl = 'https://ghfast.top/https://github.com/Kitware/CMake/releases/download/v3.31.4/cmake-3.31.4-linux-x86_64.tar.gz'\ndest = '/tmp/cmake-prebuilt.tar.gz'\nurllib.request.urlretrieve(url, dest)\nprint(f'Done: {os.path.getsize(dest)//1024//1024}MB')\n\"\n\nmkdir -p ~/local\ntar xzf /tmp/cmake-prebuilt.tar.gz -C ~/local --strip-components=1\n~/local/bin/cmake --version\n```\n\n### Step 3: 编译 whisper.cpp\n\n```bash\nexport PATH=\"$HOME/local/bin:$PATH\"\ncd ~/whisper.cpp\ncmake -B build -DCMAKE_BUILD_TYPE=Release   # ~2秒\nmake -C build -j$(nproc)                      # ~60秒\n```\n\n编译产物在 `~/whisper.cpp/build/bin/`：\n- `whisper-cli` — 命令行转录工具 ✅ 主要用这个\n- `whisper-server` — HTTP 服务端\n- `whisper-quantize` — 模型量化工具\n- `whisper-vad-speech-segments` — 语音活动检测\n\n### Step 4: 下载 ggml 模型\n\n**⚠️ 官方脚本依赖 wget/curl，环境可能没有！** 用 Python 代替：\n\n#### 小模型（<500MB）— 直接下载\n\n```bash\npython3 -c \"\nimport urllib.request, os\nurl = 'https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-base.bin'\ndest = os.path.expanduser('~/whisper.cpp/models/ggml-base.bin')\nurllib.request.urlretrieve(url, dest)\nprint(f'Done: {os.path.getsize(dest)/1024/1024:.1f}MB')\n\"\n```\n\n#### 大模型（≥1GB）— 必须用断点续传脚本！\n\n**⚠️ 大文件直接下载容易 SSL 握手超时！**\n\n```bash\npython3 << 'PYEOF'\nimport urllib.request, os, sys, time\n\nmodel_url = 'https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin'\ndest = os.path.expanduser('~/whisper.cpp/models/ggml-large-v3.bin')\n\ndownloaded = 0\nif os.path.exists(dest):\n    downloaded = os.path.getsize(dest)\n    print(f'Resuming from {downloaded/1024/1024:.1f}MB...')\n\nreq = urllib.request.Request(model_url, headers={'User-Agent': 'Mozilla/5.0'})\nif downloaded > 0:\n    req.add_header('Range', f'bytes={downloaded}-')\n\nmax_retries = 5\nfor attempt in range(max_retries):\n    try:\n        print(f'Attempt {attempt+1}/{max_retries}...')\n        response = urllib.request.urlopen(req, timeout=60)\n        total_str = response.headers.get('Content-Range', response.headers.get('Content-Length', ''))\n        if 'bytes' in total_str:\n            total = int(total_str.split('/')[-1])\n        else:\n            total = int(total_str) + downloaded\n        print(f'Total size: {total/1024/1024:.1f}MB')\n        mode = 'ab' if downloaded > 0 else 'wb'\n        with open(dest, mode) as f:\n            while True:\n                chunk = response.read(2*1024*1024)\n                if not chunk: break\n                f.write(chunk)\n                downloaded += len(chunk)\n                if downloaded % (50*1024*1024) < 2*1024*1024:\n                    print(f'  Progress: {downloaded/1024/1024:.1f}MB / {total/1024/1024:.1f}MB ({downloaded*100//total}%)')\n        print(f'DONE! {os.path.getsize(dest)/1024/1024:.1f}MB')\n        break\n    except Exception as e:\n        print(f'Error: {e}')\n        if attempt < max_retries - 1:\n            time.sleep(3)\n            downloaded = os.path.getsize(dest) if os.path.exists(dest) else 0\n            req = urllib.request.Request(model_url, headers={\n                'User-Agent': 'Mozilla/5.0',\n                'Range': f'bytes={downloaded}-',\n            })\nelse:\n    print('All retries failed!')\n    sys.exit(1)\nPYEOF\n```\n\n> 💡 所有模型下载必须用 hf-mirror.com 镜像站，直连 huggingface.co 会 Network unreachable。\n\n---\n\n## 🔄 Hermes 内置转录失败时的回退流程\n\n当内置语音转录报错时：\n\n### Step 1: 找到语音文件\n\n```bash\nfind /opt/data/cache/audio -type f -mmin -5 2>/dev/null\n# 典型输出: /opt/data/cache/audio/audio_xxx.ogg\n```\n\n### Step 2: 用 whisper.cpp 转录\n\n```bash\nffmpeg -y -i /opt/data/cache/audio/audio_xxx.ogg -ar 16000 -ac 1 -f wav /tmp/voice.wav 2>/dev/null\n~/whisper.cpp/build/bin/whisper-cli -m ~/whisper.cpp/models/ggml-large-v3.bin -f /tmp/voice.wav -l zh --no-timestamps 2>/dev/null\n```\n\n---\n\n## ☁️ 备选方案：云端 API\n\n当本地模型不够用时：\n\n| 服务 | 费用 | 状态 | 备注 |\n|------|------|------|------|\n| SiliconFlow SenseVoice | 注册送额度 | ⚠️ 余额不足 | Key有效，国内直连 |\n| Groq Whisper | 完全免费 | ❌ 403 Forbidden | 需验证邮箱 |\n| OpenRouter | 按量付费 | ❌ 401 Unauthorized | Key可能无效 |\n\n### SiliconFlow API（余额恢复后可用）\n\nKey 存储在 `~/.hermes/api-config.json`，使用方式：\n\n```bash\n# 从配置文件读取 Key\nAPI_KEY=$(python3 -c \"import json; c=json.load(open('$HOME/.hermes/api-config.json')); print(c['siliconflow']['key'])\")\ncurl -X POST https://api.siliconflow.cn/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $API_KEY\" \\\n  -F \"file=@audio.ogg\" \\\n  -F \"model=FunAudioLLM/SenseVoiceSmall\" \\\n  -F \"language=zh\"\n```\n\n---\n\n## ⚠️ 踩坑记录\n\n### 1. cmake .sh 安装脚本不可用\n- 症状：`cd: can't cd to ~/local`\n- 原因：shell 脚本用 `~` 展开失败\n- 解决：下载 tar.gz 预编译包，手动解压\n\n### 2. 大文件下载 SSL 超时\n- 症状：`SSL handshake timeout`\n- 解决：用带 Range header 的断点续传脚本，2MB chunks，5次重试\n\n### 3. HuggingFace Hub 不通\n- 症状：`Network is unreachable`\n- 解决：所有 HF 地址替换为 `hf-mirror.com`\n\n### 4. GitHub 直连慢/超时\n- 解决：用 `ghfast.top` 镜像代理\n\n### 5. 无 curl/wget 环境\n- 解决：全部用 `python3 urllib.request` 替代\n\n---\n\n## 方案对比总览\n\n| 维度 | whisper.cpp (当前首选) | faster-whisper (Python) | 云端API |\n|------|----------------------|------------------------|---------|\n| 依赖 | gcc/cmake | Python+uv+venv | 网络 |\n| 安装复杂度 | 中（需编译） | 低（pip install） | 无 |\n| 内存占用 | 低 (~模型大小) | ~1-2GB | 无 |\n| 中文准确度 | high (large-v3) | medium-high | 最高 |\n| 离线可用 | 是 | 是 | 否 |\n| 用户偏好 | **首选** | 已卸载 | 备选 |\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7a6qzk16ny6zj2a6ge10exrn82q9qp\",\n  \"slug\": \"whisper-voice-transcription\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1776492606025\n}","readmeExcerpt":"Skill: Whisper Voice Transcription (whisper.cpp) Owner: xuxuclassmate Summary: Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical. Tags: audio:1.1.1, chinese:1.1.0, latest:1.1.1, media:1.1.1, speech-to-text:1.1.1, stt:1.1.1, transcription:1.1.1, voice:1.1.1, voice-transcription:1.0.0, whisper:1.1.1 Version history: v1.1.1 | 2026-04-22T0","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"git clone --depth 1 https://github.com/ggerganov/whisper.cpp.git ~/whisper.cpp\ncd ~/whisper.cpp\ncmake -B build -DCMAKE_BUILD_TYPE=Release\ncmake --build build -j4"},{"language":"bash","snippet":"ffmpeg -y -i input_audio.ogg -ar 16000 -ac 1 -f wav /tmp/voice.wav\n~/whisper.cpp/build/bin/whisper-cli \\\n  -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n  -f /tmp/voice.wav \\\n  -l auto \\\n  --no-timestamps"},{"language":"bash","snippet":"git clone --depth 1 https://github.com/ggerganov/whisper.cpp.git ~/whisper.cpp\ncd ~/whisper.cpp"},{"language":"bash","snippet":"cmake -B build -DCMAKE_BUILD_TYPE=Release\nmake -C build -j$(nproc)"},{"language":"bash","snippet":"~/whisper.cpp/build/bin/whisper-cli --help\n# 应显示版本信息和用法"},{"language":"bash","snippet":"# Step 1: ffmpeg 预处理 — 任意音频格式 → 16kHz mono wav\nffmpeg -i <输入音频文件> -ar 16000 -ac 1 -f wav /tmp/voice.wav -y\n\n# Step 2: whisper-cli 转录\n~/whisper.cpp/build/bin/whisper-cli \\\n    -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n    -f /tmp/voice.wav -l zh --no-timestamps"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: whisper-voice-transcription\ndescription: Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical.\ntags: [speech-to-text, stt, voice, transcription, whisper, audio]\nversion: 1.1.1\n---\n\n# Whisper Voice Transcription with whisper.cpp\n\n## When to use\n\n- You want local speech-to-text without sending audio to a third party.\n- You need a fallback workflow when a built-in transcription tool fails.\n- You want an operator guide for compiling and running `whisper.cpp`.\n\n## Prerequisites\n\n- `git`\n- `cmake`\n- a C or C++ compiler\n- `ffmpeg`\n\n## Build steps\n\n```bash\ngit clone --depth 1 https://github.com/ggerganov/whisper.cpp.git ~/whisper.cpp\ncd ~/whisper.cpp\ncmake -B build -DCMAKE_BUILD_TYPE=Release\ncmake --build build -j4\n```\n\nDownload a model from the official `ggerganov/whisper.cpp` releases or Hugging Face repository and place it under `~/whisper.cpp/models/`.\n\n## Standard transcription flow\n\n```bash\nffmpeg -y -i input_audio.ogg -ar 16000 -ac 1 -f wav /tmp/voice.wav\n~/whisper.cpp/build/bin/whisper-cli \\\n  -m ~/whisper.cpp/models/ggml-large-v3.bin \\\n  -f /tmp/voice.wav \\\n  -l auto \\\n  --no-timestamps\n```\n\n## Fallback workflow\n\nIf a higher-level tool fails, first locate the exact cache or upload path used by that tool. Search only within the expected application cache directory instead of scanning the entire home directory.\n\n## Cloud fallback\n\nIf local transcription is too slow or unavailable, use an approved speech API and tell the user that audio will leave the machine.\n\n## Guardrails\n\n- Download binaries and models only from official sources.\n- Verify hashes when possible.\n- Do not search unrelated directories for audio files.\n- Be explicit when using a cloud provider because that changes the privacy model."},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7a6qzk16ny6zj2a6ge10exrn82q9qp\",\n  \"slug\": \"whisper-voice-transcription\",\n  \"version\": \"1.1.1\",\n  \"publishedAt\": 1776836645082\n}"},{"path":"skill-card.md","content":"## Description:\n\nBuild and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[xuxuclassmate](https://clawhub.ai/user/xuxuclassmate)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, engineers, and operators use this skill to build whisper.cpp, prepare audio, run local speech-to-text transcription, and choose an approved cloud fallback when local transcription is not practical.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Building third-party code from a moving upstream branch can change the behavior or trust boundary of local transcription over time.\n\nMitigation: Pin whisper.cpp to a known release or commit before building and review updates before adopting them.\n\nRisk: Downloaded transcription models may be tampered with or may not match the intended source.\n\nMitigation: Download models only from official sources and verify hashes when available.\n\nRisk: Using a fixed temporary audio path can expose private audio or leave sensitive files behind.\n\nMitigation: Use a unique private temporary file for each transcription and remove it after use.\n\nRisk: Cloud transcription fallback sends audio outside the local machine.\n\nMitigation: Use cloud fallback only with user acceptance and an approved speech API.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/xuxuclassmate/skills/whisper-voice-transcription)\n- [whisper.cpp](https://github.com/ggerganov/whisper.cpp)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [None]\n\n## Skill Version(s):\n\n1.1.1 (source: artifact frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical. Skill: Whisper Voice Transcription (whisper.cpp) Owner: xuxuclassmate Summary: Build and use whisper.cpp for local speech-to-text workflows, with optional cloud fallback when local transcription is not practical. Tags: audio:1.1.1, chinese:1.1.0, latest:1.1.1, media:1.1.1, speech-to-text:1.1.1, stt:1.1.1, transcription:1.1.1, voice:1.1.1, voice-transcription:1.0.0, whisper:1.1.1 Version history: v1.1.1 | 2026-04-22T0","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":916,"uniquenessScore":51,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:25:29.190Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T23:25:29.190Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-13T11:34:54.484Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}