{"id":"88acb06d-81cb-4f51-9bb7-9b379f5fc8bd","entityType":"agent","slug":"clawhub-moroiser-stt-recognizer","name":"STT Recognizer | STT 识别器","canonicalUrl":"https://www.xpersona.co/agent/clawhub-moroiser-stt-recognizer","canonicalPath":"/agent/clawhub-moroiser-stt-recognizer","generatedAt":"2026-10-12T09:31:53.099Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T20:28:26.639Z","emptyReason":null},"description":"语音转文字（Speech-to-Text / STT）工具。 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字， 或通过 OpenAI 兼容 API 进行云端转写。 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。 适用平台：Linux / Windows... Skill: STT Recognizer | STT 识别器 Owner: moroiser Summary: 语音转文字（Speech-to-Text / STT）工具。 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字， 或通过 OpenAI 兼容 API 进行云端转写。 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。 适用平台：Linux / Windows... Tags: latest:1.0.8 Version history: v1.0.8 | 2026-04-29T14:09:00.715Z | user 1. Fix all internal path references and display names to match the renamed stt-recognizer slug. 修复所有内部路径引用和展示名，统一为新命名的 stt-rec","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 997 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1708w2t7w31qf7b0gsy7kamnx83gqa6:stt-recognizer","sourceUrl":"https://clawhub.ai/moroiser/stt-recognizer","homepage":"https://clawhub.ai/moroiser/skills/stt-recognizer","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/moroiser/stt-recognizer","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/moroiser/skills/stt-recognizer","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"语音转文字（Speech-to-Text / STT）工具。 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字， 或通过 OpenAI 兼容 API 进行云端转写。 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。 适用平台：Linux / Windows... "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:28:26.639Z","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-11T20:28:26.639Z","emptyReason":null},"stars":null,"forks":null,"downloads":997,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.8","tractionLabel":"997 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:28:26.620Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T20:28:26.639Z","lastCrawledAt":"2026-10-11T20:28:26.620Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T20:28:26.620Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.8","createdAt":"2026-04-29T14:09:00.715Z","changelog":"1. Fix all internal path references and display names to match the renamed stt-recognizer slug. 修复所有内部路径引用和展示名，统一为新命名的 stt-recognizer。","fileCount":8,"zipByteSize":15526},{"version":"1.0.7","createdAt":"2026-04-29T14:01:24.679Z","changelog":"1. Rename the skill from speech-transcriber to stt-recognizer and update the bilingual display name. 将技能从 speech-transcriber 重命名为 stt-recognizer，并更新中英文双语展示名。","fileCount":7,"zipByteSize":14255},{"version":"1.0.6","createdAt":"2026-04-12T10:00:45.262Z","changelog":"Fix repeated model downloads: add correct cache path to model search paths and fix find_model() to locate directories instead of files. 修复重复下载：添加正确的模型搜索路径，修复 find_model() 定位模型目录而非文件。","fileCount":7,"zipByteSize":14244},{"version":"1.0.5","createdAt":"2026-04-12T09:36:12.336Z","changelog":"Fix output paths from stt/ to speech-transcriber/ to match documentation","fileCount":7,"zipByteSize":13994},{"version":"1.0.4","createdAt":"2026-04-12T09:24:54.007Z","changelog":"1. Restructure directories: project and model cache now use skill-name convention. 优化目录结构，项目目录和模型缓存统一使用技能同名规范。 2. Update SKILL.md: paths unified to ~/.cache/huggingface/modules/speech-transcriber/. 更新 SKILL.md，路径统一为缓存位置。 3. Download script updated: default to small model. 下载脚本更新，默认下载 small 模型。 4. Clean up residual files and models directories. 清理残留旧文件和目录。","fileCount":7,"zipByteSize":13840},{"version":"1.0.3","createdAt":"2026-04-06T03:48:12.239Z","changelog":"Fix display name to Speech Transcriber | 语音转录器. Remove broken symlink and fix shell=True security issue. 修复显示名称；移除坏符号链接；修复安全问题。","fileCount":11,"zipByteSize":882055},{"version":"1.0.2","createdAt":"2026-04-06T03:45:18.632Z","changelog":"Remove broken symlink models/model.bin that caused embedding failures. Fix subprocess.run(shell=True) in record_audio.py for security compliance. 移除导致Embedding失败的坏符号链接；修复 subprocess.run(shell=True) 安全问题。","fileCount":11,"zipByteSize":882056},{"version":"1.0.1","createdAt":"2026-04-06T03:38:05.397Z","changelog":"Fix subprocess.run(shell=True) in record_audio.py for security compliance. 修复 record_audio.py 中 subprocess.run(shell=True) 调用，提升安全性。","fileCount":10,"zipByteSize":880940}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1708w2t7w31qf7b0gsy7kamnx83gqa6:stt-recognizer","setupComplexity":"medium","setupSteps":["Python environment detected. Create a strict virtual environment (`python -m venv .venv`) before installing dependencies to prevent system-level package conflicts.","Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","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-moroiser-stt-recognizer/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/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-12T09:31:53.096Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-moroiser-stt-recognizer/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-11T20:28:26.639Z","emptyReason":null},"readme":"Skill: STT Recognizer | STT 识别器\n\nOwner: moroiser\n\nSummary: 语音转文字（Speech-to-Text / STT）工具。 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字， 或通过 OpenAI 兼容 API 进行云端转写。 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。 适用平台：Linux / Windows...\n\nTags: latest:1.0.8\n\nVersion history:\n\nv1.0.8 | 2026-04-29T14:09:00.715Z | user\n\n1. Fix all internal path references and display names to match the renamed stt-recognizer slug. 修复所有内部路径引用和展示名，统一为新命名的 stt-recognizer。\n\nv1.0.7 | 2026-04-29T14:01:24.679Z | user\n\n1. Rename the skill from speech-transcriber to stt-recognizer and update the bilingual display name. 将技能从 speech-transcriber 重命名为 stt-recognizer，并更新中英文双语展示名。\n\nv1.0.6 | 2026-04-12T10:00:45.262Z | user\n\nFix repeated model downloads: add correct cache path to model search paths and fix find_model() to locate directories instead of files. 修复重复下载：添加正确的模型搜索路径，修复 find_model() 定位模型目录而非文件。\n\nv1.0.5 | 2026-04-12T09:36:12.336Z | user\n\nFix output paths from stt/ to speech-transcriber/ to match documentation\n\nv1.0.4 | 2026-04-12T09:24:54.007Z | user\n\n1. Restructure directories: project and model cache now use skill-name convention. 优化目录结构，项目目录和模型缓存统一使用技能同名规范。\n2. Update SKILL.md: paths unified to ~/.cache/huggingface/modules/speech-transcriber/. 更新 SKILL.md，路径统一为缓存位置。\n3. Download script updated: default to small model. 下载脚本更新，默认下载 small 模型。\n4. Clean up residual files and models directories. 清理残留旧文件和目录。\n\nv1.0.3 | 2026-04-06T03:48:12.239Z | user\n\nFix display name to Speech Transcriber | 语音转录器. Remove broken symlink and fix shell=True security issue. 修复显示名称；移除坏符号链接；修复安全问题。\n\nv1.0.2 | 2026-04-06T03:45:18.632Z | user\n\nRemove broken symlink models/model.bin that caused embedding failures. Fix subprocess.run(shell=True) in record_audio.py for security compliance. 移除导致Embedding失败的坏符号链接；修复 subprocess.run(shell=True) 安全问题。\n\nv1.0.1 | 2026-04-06T03:38:05.397Z | user\n\nFix subprocess.run(shell=True) in record_audio.py for security compliance. 修复 record_audio.py 中 subprocess.run(shell=True) 调用，提升安全性。\n\nv1.0.0 | 2026-04-05T10:18:02.512Z | user\n\nInitial release: Local speech-to-text with Whisper/faster-whisper and OpenAI API support. 首发版本：支持本地 Whisper 和 API 语音转文字。\n\nArchive index:\n\nArchive v1.0.8: 8 files, 15526 bytes\n\nFiles: _meta.json (133b), requirements.txt (1672b), scripts/download_models.sh (2393b), scripts/record_and_transcribe.py (5416b), scripts/record_audio.py (8293b), scripts/transcribe.py (12474b), skill-card.md (2297b), SKILL.md (10412b)\n\nFile v1.0.8:SKILL.md\n\n---\nname: STT Recognizer | STT 识别器\ndescription: |\n 语音转文字（Speech-to-Text / STT）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# STT Recognizer | STT 识别器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 文件结构\n\n```\n技能目录（发布用）：\n~/.openclaw/workspace/skills/stt-recognizer/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音\n ├── transcribe.py # 转写\n └── record_and_transcribe.py # 一键录音+转写\n\n项目目录（运行时数据）：\n~/.openclaw/workspace/projects/stt-recognizer/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n\n模型缓存（统一命名，技能专属）：\n~/.cache/huggingface/modules/stt-recognizer/\n├── small/ # small 模型（464MB，默认使用）\n└── base/ # base 模型（约 142MB，可选）\n```\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\npip install -r requirements.txt --break-system-packages\n```\n\n### 2. 下载模型\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/stt-recognizer/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/stt-recognizer/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/stt-recognizer/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型统一存放在缓存位置，**按技能命名目录**，清晰不混乱：\n\n```\n~/.cache/huggingface/modules/stt-recognizer/\n├── small/ # small 模型（464MB，当前使用）\n└── base/ # base 模型（约 142MB）\n\n# 模型文件结构示例：\n~/.cache/huggingface/modules/stt-recognizer/small/\n├── model.bin # 462MB（实际模型）\n├── tokenizer.json # 2.2MB\n├── config.json # 2.4KB\n└── vocabulary.txt # 450KB\n```\n\n### 下载模型\n\n首次使用需下载 Whisper 模型（存放在 HuggingFace 缓存，不占技能目录）：\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. `~/.cache/huggingface/modules/` ← 主要位置\n3. `~/.openclaw/workspace/projects/stt-recognizer/models/` ← 工作区备份\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/stt-recognizer/` 目录下：\n\n```\n~/.openclaw/workspace/projects/stt-recognizer/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n\n# 安装依赖\ncd ~/.openclaw/workspace/skills/stt-recognizer\npip install -r requirements.txt --break-system-packages\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n### 技能目录（发布用）\n\n```\nstt-recognizer/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音脚本\n ├── transcribe.py # 转写脚本\n └── record_and_transcribe.py # ⭐ 一键录音+转写\n```\n\n### 项目目录（运行时数据）\n\n```\n~/.openclaw/workspace/projects/stt-recognizer/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n```\n\n### 模型缓存\n\n```\n~/.cache/huggingface/modules/stt-recognizer/\n├── small/ # small 模型\n└── base/ # base 模型\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.8:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.8\",\n \"publishedAt\": 1777471740715\n}\n\nFile v1.0.8:skill-card.md\n\n## Description:\n\nSpeech-to-text skill that records microphone audio and transcribes audio files locally with Whisper/faster-whisper or through an OpenAI-compatible API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[moroiser](https://clawhub.ai/user/moroiser)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and end users can record speech or submit audio files for transcription, choosing local Whisper inference or an OpenAI-compatible API based on privacy, hardware, and connectivity needs.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can record microphone audio and upload audio to an OpenAI-compatible API, which may expose sensitive speech.\n\nMitigation: Get explicit user consent, prefer local transcription for sensitive audio, use only trusted HTTPS endpoints or intentional localhost endpoints, and delete recordings and transcripts when no longer needed.\n\nRisk: Dependency installation guidance uses broad version ranges and includes --break-system-packages.\n\nMitigation: Install in a virtual environment and pin or lock dependencies before operational use.\n\nRisk: API keys can be passed through command-line options and may be exposed through shell history or process listings.\n\nMitigation: Avoid passing API keys on the command line; use a secret manager or protected environment configuration and rotate keys if exposure is suspected.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/moroiser/skills/stt-recognizer)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Shell commands, Configuration, Files, Guidance]\n\n**Output Format:** [Markdown guidance with bash commands; runtime outputs include WAV recordings and text transcription files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Transcriptions may be saved as txt, srt, or vtt files; recorded audio and transcripts can remain on disk until deleted.]\n\n## Skill Version(s):\n\n1.0.8 (source: server release metadata and artifact _meta.json)\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\nFile v1.0.8:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)\n\nArchive v1.0.7: 7 files, 14255 bytes\n\nFiles: _meta.json (133b), requirements.txt (1672b), scripts/download_models.sh (2409b), scripts/record_and_transcribe.py (5420b), scripts/record_audio.py (8301b), scripts/transcribe.py (12498b), SKILL.md (10496b)\n\nFile v1.0.7:SKILL.md\n\n---\nname: STT Recognizer | STT 识别器\ndescription: |\n 语音转文字（Speech-to-Text / STT）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# STT Recognizer | STT 识别器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 文件结构\n\n```\n技能目录（发布用）：\n~/.openclaw/workspace/skills/speech-transcriber/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音\n ├── transcribe.py # 转写\n └── record_and_transcribe.py # 一键录音+转写\n\n项目目录（运行时数据）：\n~/.openclaw/workspace/projects/speech-transcriber/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n\n模型缓存（统一命名，技能专属）：\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型（464MB，默认使用）\n└── base/ # base 模型（约 142MB，可选）\n```\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt --break-system-packages\n```\n\n### 2. 下载模型\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/speech-transcriber/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/speech-transcriber/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/speech-transcriber/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型统一存放在缓存位置，**按技能命名目录**，清晰不混乱：\n\n```\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型（464MB，当前使用）\n└── base/ # base 模型（约 142MB）\n\n# 模型文件结构示例：\n~/.cache/huggingface/modules/speech-transcriber/small/\n├── model.bin # 462MB（实际模型）\n├── tokenizer.json # 2.2MB\n├── config.json # 2.4KB\n└── vocabulary.txt # 450KB\n```\n\n### 下载模型\n\n首次使用需下载 Whisper 模型（存放在 HuggingFace 缓存，不占技能目录）：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. `~/.cache/huggingface/modules/` ← 主要位置\n3. `~/.openclaw/workspace/projects/speech-transcriber/models/` ← 工作区备份\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/speech-transcriber/` 目录下：\n\n```\n~/.openclaw/workspace/projects/speech-transcriber/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n\n# 安装依赖\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt --break-system-packages\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n### 技能目录（发布用）\n\n```\nspeech-transcriber/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音脚本\n ├── transcribe.py # 转写脚本\n └── record_and_transcribe.py # ⭐ 一键录音+转写\n```\n\n### 项目目录（运行时数据）\n\n```\n~/.openclaw/workspace/projects/speech-transcriber/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n```\n\n### 模型缓存\n\n```\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型\n└── base/ # base 模型\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.7:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.7\",\n \"publishedAt\": 1777471284679\n}\n\nFile v1.0.7:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)\n\nArchive v1.0.6: 7 files, 14244 bytes\n\nFiles: _meta.json (133b), requirements.txt (1672b), scripts/download_models.sh (2409b), scripts/record_and_transcribe.py (5420b), scripts/record_audio.py (8301b), scripts/transcribe.py (12498b), SKILL.md (10484b)\n\nFile v1.0.6:SKILL.md\n\n---\nname: speech-transcriber\ndescription: |\n 语音转文字（Speech-to-Text）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# Speech Transcriber | 语音转录器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 文件结构\n\n```\n技能目录（发布用）：\n~/.openclaw/workspace/skills/speech-transcriber/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音\n ├── transcribe.py # 转写\n └── record_and_transcribe.py # 一键录音+转写\n\n项目目录（运行时数据）：\n~/.openclaw/workspace/projects/speech-transcriber/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n\n模型缓存（统一命名，技能专属）：\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型（464MB，默认使用）\n└── base/ # base 模型（约 142MB，可选）\n```\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt --break-system-packages\n```\n\n### 2. 下载模型\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/speech-transcriber/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/speech-transcriber/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/speech-transcriber/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型统一存放在缓存位置，**按技能命名目录**，清晰不混乱：\n\n```\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型（464MB，当前使用）\n└── base/ # base 模型（约 142MB）\n\n# 模型文件结构示例：\n~/.cache/huggingface/modules/speech-transcriber/small/\n├── model.bin # 462MB（实际模型）\n├── tokenizer.json # 2.2MB\n├── config.json # 2.4KB\n└── vocabulary.txt # 450KB\n```\n\n### 下载模型\n\n首次使用需下载 Whisper 模型（存放在 HuggingFace 缓存，不占技能目录）：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. `~/.cache/huggingface/modules/` ← 主要位置\n3. `~/.openclaw/workspace/projects/speech-transcriber/models/` ← 工作区备份\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/speech-transcriber/` 目录下：\n\n```\n~/.openclaw/workspace/projects/speech-transcriber/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n\n# 安装依赖\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt --break-system-packages\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n### 技能目录（发布用）\n\n```\nspeech-transcriber/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音脚本\n ├── transcribe.py # 转写脚本\n └── record_and_transcribe.py # ⭐ 一键录音+转写\n```\n\n### 项目目录（运行时数据）\n\n```\n~/.openclaw/workspace/projects/speech-transcriber/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n```\n\n### 模型缓存\n\n```\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型\n└── base/ # base 模型\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.6:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.6\",\n \"publishedAt\": 1775988045262\n}\n\nFile v1.0.6:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)\n\nArchive v1.0.5: 7 files, 13994 bytes\n\nFiles: _meta.json (133b), requirements.txt (1672b), scripts/download_models.sh (2409b), scripts/record_and_transcribe.py (5420b), scripts/record_audio.py (8301b), scripts/transcribe.py (11355b), SKILL.md (10734b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: speech-transcriber\ndescription: |\n 语音转文字（Speech-to-Text）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# Speech Transcriber | 语音转录器 🎤\n\n---\n\n## 更新日志\n\n### v1.0.5\n- 修复：代码中的路径从 `stt/` 改为 `speech-transcriber/`，与文档一致\n\n### v1.0.4\n- 优化：目录结构统一，使用技能同名规范\n- 完善：SKILL.md 结构优化，补充模型管理说明\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 文件结构\n\n```\n技能目录（发布用）：\n~/.openclaw/workspace/skills/speech-transcriber/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音\n ├── transcribe.py # 转写\n └── record_and_transcribe.py # 一键录音+转写\n\n项目目录（运行时数据）：\n~/.openclaw/workspace/projects/speech-transcriber/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n\n模型缓存（统一命名，技能专属）：\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型（464MB，默认使用）\n└── base/ # base 模型（约 142MB，可选）\n```\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt --break-system-packages\n```\n\n### 2. 下载模型\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/speech-transcriber/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/speech-transcriber/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/speech-transcriber/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型统一存放在缓存位置，**按技能命名目录**，清晰不混乱：\n\n```\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型（464MB，当前使用）\n└── base/ # base 模型（约 142MB）\n\n# 模型文件结构示例：\n~/.cache/huggingface/modules/speech-transcriber/small/\n├── model.bin # 462MB（实际模型）\n├── tokenizer.json # 2.2MB\n├── config.json # 2.4KB\n└── vocabulary.txt # 450KB\n```\n\n### 下载模型\n\n首次使用需下载 Whisper 模型（存放在 HuggingFace 缓存，不占技能目录）：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. `~/.cache/huggingface/modules/` ← 主要位置\n3. `~/.openclaw/workspace/projects/speech-transcriber/models/` ← 工作区备份\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/speech-transcriber/` 目录下：\n\n```\n~/.openclaw/workspace/projects/speech-transcriber/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n\n# 安装依赖\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt --break-system-packages\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n### 技能目录（发布用）\n\n```\nspeech-transcriber/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音脚本\n ├── transcribe.py # 转写脚本\n └── record_and_transcribe.py # ⭐ 一键录音+转写\n```\n\n### 项目目录（运行时数据）\n\n```\n~/.openclaw/workspace/projects/speech-transcriber/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n```\n\n### 模型缓存\n\n```\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型\n└── base/ # base 模型\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.5:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.5\",\n \"publishedAt\": 1775986572336\n}\n\nFile v1.0.5:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)\n\nArchive v1.0.4: 7 files, 13840 bytes\n\nFiles: _meta.json (133b), requirements.txt (1672b), scripts/download_models.sh (2409b), scripts/record_and_transcribe.py (5405b), scripts/record_audio.py (8271b), scripts/transcribe.py (11310b), SKILL.md (10484b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: speech-transcriber\ndescription: |\n 语音转文字（Speech-to-Text）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# Speech Transcriber | 语音转录器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 文件结构\n\n```\n技能目录（发布用）：\n~/.openclaw/workspace/skills/speech-transcriber/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音\n ├── transcribe.py # 转写\n └── record_and_transcribe.py # 一键录音+转写\n\n项目目录（运行时数据）：\n~/.openclaw/workspace/projects/speech-transcriber/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n\n模型缓存（统一命名，技能专属）：\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型（464MB，默认使用）\n└── base/ # base 模型（约 142MB，可选）\n```\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt --break-system-packages\n```\n\n### 2. 下载模型\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/speech-transcriber/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/speech-transcriber/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/speech-transcriber/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型统一存放在缓存位置，**按技能命名目录**，清晰不混乱：\n\n```\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型（464MB，当前使用）\n└── base/ # base 模型（约 142MB）\n\n# 模型文件结构示例：\n~/.cache/huggingface/modules/speech-transcriber/small/\n├── model.bin # 462MB（实际模型）\n├── tokenizer.json # 2.2MB\n├── config.json # 2.4KB\n└── vocabulary.txt # 450KB\n```\n\n### 下载模型\n\n首次使用需下载 Whisper 模型（存放在 HuggingFace 缓存，不占技能目录）：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. `~/.cache/huggingface/modules/` ← 主要位置\n3. `~/.openclaw/workspace/projects/speech-transcriber/models/` ← 工作区备份\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/speech-transcriber/` 目录下：\n\n```\n~/.openclaw/workspace/projects/speech-transcriber/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n\n# 安装依赖\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt --break-system-packages\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n### 技能目录（发布用）\n\n```\nspeech-transcriber/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音脚本\n ├── transcribe.py # 转写脚本\n └── record_and_transcribe.py # ⭐ 一键录音+转写\n```\n\n### 项目目录（运行时数据）\n\n```\n~/.openclaw/workspace/projects/speech-transcriber/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n```\n\n### 模型缓存\n\n```\n~/.cache/huggingface/modules/speech-transcriber/\n├── small/ # small 模型\n└── base/ # base 模型\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.4:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.4\",\n \"publishedAt\": 1775985894007\n}\n\nFile v1.0.4:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)\n\nArchive v1.0.3: 11 files, 882055 bytes\n\nFiles: _meta.json (133b), download_models.sh (2329b), models/config.json (2370b), models/tokenizer.json (2203239b), models/vocabulary.txt (459861b), requirements.txt (1672b), scripts/download_models.sh (2329b), scripts/record_and_transcribe.py (5405b), scripts/record_audio.py (8271b), scripts/transcribe.py (11310b), SKILL.md (8251b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: speech-transcriber\ndescription: |\n 语音转文字（Speech-to-Text）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# Speech Transcriber | 语音转录器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt\n```\n\n### 2. 下载模型\n\n```bash\n# 下载 faster-whisper 模型（推荐）\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/stt/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/stt/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/stt/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型存放在 skill 目录的 `models/` 文件夹中（便携设计）：\n\n```\n~/.openclaw/workspace/skills/speech-transcriber/models/\n└── (模型文件)\n```\n\n### 下载模型\n\n```bash\n# 下载指定大小的模型\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. skill 的 `models/` 目录\n3. `~/.cache/huggingface/modules/`\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/stt/` 目录下：\n\n```\n~/.openclaw/workspace/projects/stt/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n```\nspeech-transcriber/\n├── SKILL.md # 本文档\n├── requirements.txt # Python 依赖\n├── scripts/\n│ ├── record_audio.py # 录音脚本\n│ ├── transcribe.py # 转写脚本\n│ ├── record_and_transcribe.py # ⭐ 一键录音+转写\n│ └── download_models.sh # 模型下载脚本\n└── models/ # 模型目录（需单独下载）\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.3:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.3\",\n \"publishedAt\": 1775447292239\n}\n\nFile v1.0.3:models/config.json\n\n{\n \"alignment_heads\": [\n [\n 5,\n 3\n ],\n [\n 5,\n 9\n ],\n [\n 8,\n 0\n ],\n [\n 8,\n 4\n ],\n [\n 8,\n 7\n ],\n [\n 8,\n 8\n ],\n [\n 9,\n 0\n ],\n [\n 9,\n 7\n ],\n [\n 9,\n 9\n ],\n [\n 10,\n 5\n ]\n ],\n \"lang_ids\": [\n 50259,\n 50260,\n 50261,\n 50262,\n 50263,\n 50264,\n 50265,\n 50266,\n 50267,\n 50268,\n 50269,\n 50270,\n 50271,\n 50272,\n 50273,\n 50274,\n 50275,\n 50276,\n 50277,\n 50278,\n 50279,\n 50280,\n 50281,\n 50282,\n 50283,\n 50284,\n 50285,\n 50286,\n 50287,\n 50288,\n 50289,\n 50290,\n 50291,\n 50292,\n 50293,\n 50294,\n 50295,\n 50296,\n 50297,\n 50298,\n 50299,\n 50300,\n 50301,\n 50302,\n 50303,\n 50304,\n 50305,\n 50306,\n 50307,\n 50308,\n 50309,\n 50310,\n 50311,\n 50312,\n 50313,\n 50314,\n 50315,\n 50316,\n 50317,\n 50318,\n 50319,\n 50320,\n 50321,\n 50322,\n 50323,\n 50324,\n 50325,\n 50326,\n 50327,\n 50328,\n 50329,\n 50330,\n 50331,\n 50332,\n 50333,\n 50334,\n 50335,\n 50336,\n 50337,\n 50338,\n 50339,\n 50340,\n 50341,\n 50342,\n 50343,\n 50344,\n 50345,\n 50346,\n 50347,\n 50348,\n 50349,\n 50350,\n 50351,\n 50352,\n 50353,\n 50354,\n 50355,\n 50356,\n 50357\n ],\n \"suppress_ids\": [\n 1,\n 2,\n 7,\n 8,\n 9,\n 10,\n 14,\n 25,\n 26,\n 27,\n 28,\n 29,\n 31,\n 58,\n 59,\n 60,\n 61,\n 62,\n 63,\n 90,\n 91,\n 92,\n 93,\n 359,\n 503,\n 522,\n 542,\n 873,\n 893,\n 902,\n 918,\n 922,\n 931,\n 1350,\n 1853,\n 1982,\n 2460,\n 2627,\n 3246,\n 3253,\n 3268,\n 3536,\n 3846,\n 3961,\n 4183,\n 4667,\n 6585,\n 6647,\n 7273,\n 9061,\n 9383,\n 10428,\n 10929,\n 11938,\n 12033,\n 12331,\n 12562,\n 13793,\n 14157,\n 14635,\n 15265,\n 15618,\n 16553,\n 16604,\n 18362,\n 18956,\n 20075,\n 21675,\n 22520,\n 26130,\n 26161,\n 26435,\n 28279,\n 29464,\n 31650,\n 32302,\n 32470,\n 36865,\n 42863,\n 47425,\n 49870,\n 50254,\n 50258,\n 50358,\n 50359,\n 50360,\n 50361,\n 50362\n ],\n \"suppress_ids_begin\": [\n 220,\n 50257\n ]\n}\n\nFile v1.0.3:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)\n\nArchive v1.0.2: 11 files, 882056 bytes\n\nFiles: _meta.json (133b), download_models.sh (2329b), models/config.json (2370b), models/tokenizer.json (2203239b), models/vocabulary.txt (459861b), requirements.txt (1672b), scripts/download_models.sh (2329b), scripts/record_and_transcribe.py (5405b), scripts/record_audio.py (8271b), scripts/transcribe.py (11310b), SKILL.md (8251b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: speech-transcriber\ndescription: |\n 语音转文字（Speech-to-Text）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# Speech Transcriber | 语音转录器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt\n```\n\n### 2. 下载模型\n\n```bash\n# 下载 faster-whisper 模型（推荐）\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/stt/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/stt/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/stt/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型存放在 skill 目录的 `models/` 文件夹中（便携设计）：\n\n```\n~/.openclaw/workspace/skills/speech-transcriber/models/\n└── (模型文件)\n```\n\n### 下载模型\n\n```bash\n# 下载指定大小的模型\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. skill 的 `models/` 目录\n3. `~/.cache/huggingface/modules/`\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/stt/` 目录下：\n\n```\n~/.openclaw/workspace/projects/stt/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n```\nspeech-transcriber/\n├── SKILL.md # 本文档\n├── requirements.txt # Python 依赖\n├── scripts/\n│ ├── record_audio.py # 录音脚本\n│ ├── transcribe.py # 转写脚本\n│ ├── record_and_transcribe.py # ⭐ 一键录音+转写\n│ └── download_models.sh # 模型下载脚本\n└── models/ # 模型目录（需单独下载）\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.2:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1775447118632\n}\n\nFile v1.0.2:models/config.json\n\n{\n \"alignment_heads\": [\n [\n 5,\n 3\n ],\n [\n 5,\n 9\n ],\n [\n 8,\n 0\n ],\n [\n 8,\n 4\n ],\n [\n 8,\n 7\n ],\n [\n 8,\n 8\n ],\n [\n 9,\n 0\n ],\n [\n 9,\n 7\n ],\n [\n 9,\n 9\n ],\n [\n 10,\n 5\n ]\n ],\n \"lang_ids\": [\n 50259,\n 50260,\n 50261,\n 50262,\n 50263,\n 50264,\n 50265,\n 50266,\n 50267,\n 50268,\n 50269,\n 50270,\n 50271,\n 50272,\n 50273,\n 50274,\n 50275,\n 50276,\n 50277,\n 50278,\n 50279,\n 50280,\n 50281,\n 50282,\n 50283,\n 50284,\n 50285,\n 50286,\n 50287,\n 50288,\n 50289,\n 50290,\n 50291,\n 50292,\n 50293,\n 50294,\n 50295,\n 50296,\n 50297,\n 50298,\n 50299,\n 50300,\n 50301,\n 50302,\n 50303,\n 50304,\n 50305,\n 50306,\n 50307,\n 50308,\n 50309,\n 50310,\n 50311,\n 50312,\n 50313,\n 50314,\n 50315,\n 50316,\n 50317,\n 50318,\n 50319,\n 50320,\n 50321,\n 50322,\n 50323,\n 50324,\n 50325,\n 50326,\n 50327,\n 50328,\n 50329,\n 50330,\n 50331,\n 50332,\n 50333,\n 50334,\n 50335,\n 50336,\n 50337,\n 50338,\n 50339,\n 50340,\n 50341,\n 50342,\n 50343,\n 50344,\n 50345,\n 50346,\n 50347,\n 50348,\n 50349,\n 50350,\n 50351,\n 50352,\n 50353,\n 50354,\n 50355,\n 50356,\n 50357\n ],\n \"suppress_ids\": [\n 1,\n 2,\n 7,\n 8,\n 9,\n 10,\n 14,\n 25,\n 26,\n 27,\n 28,\n 29,\n 31,\n 58,\n 59,\n 60,\n 61,\n 62,\n 63,\n 90,\n 91,\n 92,\n 93,\n 359,\n 503,\n 522,\n 542,\n 873,\n 893,\n 902,\n 918,\n 922,\n 931,\n 1350,\n 1853,\n 1982,\n 2460,\n 2627,\n 3246,\n 3253,\n 3268,\n 3536,\n 3846,\n 3961,\n 4183,\n 4667,\n 6585,\n 6647,\n 7273,\n 9061,\n 9383,\n 10428,\n 10929,\n 11938,\n 12033,\n 12331,\n 12562,\n 13793,\n 14157,\n 14635,\n 15265,\n 15618,\n 16553,\n 16604,\n 18362,\n 18956,\n 20075,\n 21675,\n 22520,\n 26130,\n 26161,\n 26435,\n 28279,\n 29464,\n 31650,\n 32302,\n 32470,\n 36865,\n 42863,\n 47425,\n 49870,\n 50254,\n 50258,\n 50358,\n 50359,\n 50360,\n 50361,\n 50362\n ],\n \"suppress_ids_begin\": [\n 220,\n 50257\n ]\n}\n\nFile v1.0.2:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)\n\nArchive v1.0.1: 10 files, 880940 bytes\n\nFiles: _meta.json (133b), config.json (2370b), requirements.txt (1672b), scripts/download_models.sh (2329b), scripts/record_and_transcribe.py (5405b), scripts/record_audio.py (8271b), scripts/transcribe.py (11310b), SKILL.md (8251b), tokenizer.json (2203239b), vocabulary.txt (459861b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: speech-transcriber\ndescription: |\n 语音转文字（Speech-to-Text）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# Speech Transcriber | 语音转录器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt\n```\n\n### 2. 下载模型\n\n```bash\n# 下载 faster-whisper 模型（推荐）\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/stt/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/stt/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/stt/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型存放在 skill 目录的 `models/` 文件夹中（便携设计）：\n\n```\n~/.openclaw/workspace/skills/speech-transcriber/models/\n└── (模型文件)\n```\n\n### 下载模型\n\n```bash\n# 下载指定大小的模型\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. skill 的 `models/` 目录\n3. `~/.cache/huggingface/modules/`\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/stt/` 目录下：\n\n```\n~/.openclaw/workspace/projects/stt/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n```\nspeech-transcriber/\n├── SKILL.md # 本文档\n├── requirements.txt # Python 依赖\n├── scripts/\n│ ├── record_audio.py # 录音脚本\n│ ├── transcribe.py # 转写脚本\n│ ├── record_and_transcribe.py # ⭐ 一键录音+转写\n│ └── download_models.sh # 模型下载脚本\n└── models/ # 模型目录（需单独下载）\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1775446685397\n}\n\nFile v1.0.1:config.json\n\n{\n \"alignment_heads\": [\n [\n 5,\n 3\n ],\n [\n 5,\n 9\n ],\n [\n 8,\n 0\n ],\n [\n 8,\n 4\n ],\n [\n 8,\n 7\n ],\n [\n 8,\n 8\n ],\n [\n 9,\n 0\n ],\n [\n 9,\n 7\n ],\n [\n 9,\n 9\n ],\n [\n 10,\n 5\n ]\n ],\n \"lang_ids\": [\n 50259,\n 50260,\n 50261,\n 50262,\n 50263,\n 50264,\n 50265,\n 50266,\n 50267,\n 50268,\n 50269,\n 50270,\n 50271,\n 50272,\n 50273,\n 50274,\n 50275,\n 50276,\n 50277,\n 50278,\n 50279,\n 50280,\n 50281,\n 50282,\n 50283,\n 50284,\n 50285,\n 50286,\n 50287,\n 50288,\n 50289,\n 50290,\n 50291,\n 50292,\n 50293,\n 50294,\n 50295,\n 50296,\n 50297,\n 50298,\n 50299,\n 50300,\n 50301,\n 50302,\n 50303,\n 50304,\n 50305,\n 50306,\n 50307,\n 50308,\n 50309,\n 50310,\n 50311,\n 50312,\n 50313,\n 50314,\n 50315,\n 50316,\n 50317,\n 50318,\n 50319,\n 50320,\n 50321,\n 50322,\n 50323,\n 50324,\n 50325,\n 50326,\n 50327,\n 50328,\n 50329,\n 50330,\n 50331,\n 50332,\n 50333,\n 50334,\n 50335,\n 50336,\n 50337,\n 50338,\n 50339,\n 50340,\n 50341,\n 50342,\n 50343,\n 50344,\n 50345,\n 50346,\n 50347,\n 50348,\n 50349,\n 50350,\n 50351,\n 50352,\n 50353,\n 50354,\n 50355,\n 50356,\n 50357\n ],\n \"suppress_ids\": [\n 1,\n 2,\n 7,\n 8,\n 9,\n 10,\n 14,\n 25,\n 26,\n 27,\n 28,\n 29,\n 31,\n 58,\n 59,\n 60,\n 61,\n 62,\n 63,\n 90,\n 91,\n 92,\n 93,\n 359,\n 503,\n 522,\n 542,\n 873,\n 893,\n 902,\n 918,\n 922,\n 931,\n 1350,\n 1853,\n 1982,\n 2460,\n 2627,\n 3246,\n 3253,\n 3268,\n 3536,\n 3846,\n 3961,\n 4183,\n 4667,\n 6585,\n 6647,\n 7273,\n 9061,\n 9383,\n 10428,\n 10929,\n 11938,\n 12033,\n 12331,\n 12562,\n 13793,\n 14157,\n 14635,\n 15265,\n 15618,\n 16553,\n 16604,\n 18362,\n 18956,\n 20075,\n 21675,\n 22520,\n 26130,\n 26161,\n 26435,\n 28279,\n 29464,\n 31650,\n 32302,\n 32470,\n 36865,\n 42863,\n 47425,\n 49870,\n 50254,\n 50258,\n 50358,\n 50359,\n 50360,\n 50361,\n 50362\n ],\n \"suppress_ids_begin\": [\n 220,\n 50257\n ]\n}\n\nFile v1.0.1:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)\n\nArchive v1.0.0: 9 files, 14327 bytes\n\nFiles: models/config.json (2370b), models/README.md (532b), requirements.txt (1672b), scripts/download_models.sh (2038b), scripts/record_and_transcribe.py (5405b), scripts/record_audio.py (7965b), scripts/transcribe.py (11310b), SKILL.md (8251b), _meta.json (133b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: speech-transcriber\ndescription: |\n 语音转文字（Speech-to-Text）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# Speech Transcriber | 语音转录器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\npip install -r requirements.txt\n```\n\n### 2. 下载模型\n\n```bash\n# 下载 faster-whisper 模型（推荐）\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/stt/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/stt/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\npython3 scripts/transcribe.py audio.wav\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `audio_file` | (必需) | 要转写的音频文件路径 |\n| `--model` | base | 模型名称或路径 |\n| `--language` | (不填) | 语言代码，如 `zh`、`en`、`ja`。留空则自动检测 |\n| `--task` | transcribe | `transcribe`（转写）或 `translate`（翻译为英文） |\n| `--engine` | auto | 转写引擎：`auto`、`faster-whisper`、`whisper`、`api` |\n| `--api-url` | (env) | API URL（API 模式） |\n| `--api-key` | (env) | API 密钥（API 模式） |\n| `--output-dir` | projects/stt/transcriptions | 输出目录 |\n\n**模型选择**:\n\n| 模型 | 大小 | 内存需求 | 速度 | 精度 |\n|------|------|----------|------|------|\n| `tiny` | ~39M | ~1GB | 最快 | 较低 |\n| `base` | ~74M | ~1GB | 快 | 中等 |\n| `small` | ~244M | ~2GB | 中 | 较高 |\n| `medium` | ~769M | ~5GB | 慢 | 高 |\n| `large` | ~1550M | ~10GB | 最慢 | 最高 |\n\n**示例**:\n\n```bash\n# 转写（自动检测语言，推荐）\npython3 scripts/transcribe.py audio.wav\n\n# 使用 small 模型转写中文\npython3 scripts/transcribe.py audio.wav --model small --language zh\n\n# 使用 small 模型并翻译成英文\npython3 scripts/transcribe.py audio.wav --model small --task translate\n\n# 使用 API 转写\npython3 scripts/transcribe.py audio.wav \\\n --engine api \\\n --api-url https://api.openai.com/v1 \\\n --api-key sk-xxx \\\n --model whisper-1\n```\n\n---\n\n## 模型管理\n\n### 模型存放位置\n\n模型存放在 skill 目录的 `models/` 文件夹中（便携设计）：\n\n```\n~/.openclaw/workspace/skills/speech-transcriber/models/\n└── (模型文件)\n```\n\n### 下载模型\n\n```bash\n# 下载指定大小的模型\nbash scripts/download_models.sh base\n\n# 可选模型大小: tiny, base, small, medium, large\nbash scripts/download_models.sh small\n```\n\n### 模型搜索路径\n\n脚本按以下顺序查找模型：\n1. 环境变量 `STT_MODEL_PATH`\n2. skill 的 `models/` 目录\n3. `~/.cache/huggingface/modules/`\n\n---\n\n## 输出目录\n\n运行结果统一保存在工作区的 `projects/stt/` 目录下：\n\n```\n~/.openclaw/workspace/projects/stt/\n├── recordings/ # 原始录音文件 (record_audio.py)\n│ └── recording_20260401_123456.wav\n└── transcriptions/ # 转写结果 (transcribe.py)\n └── recording_20260401_123456.txt\n```\n\n---\n\n## 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OPENCLAW_WORKSPACE` | 工作区根目录 |\n| `STT_MODEL_PATH` | Whisper 模型路径 |\n| `STT_API_URL` | OpenAI 兼容 API URL |\n| `STT_API_KEY` | API 密钥 |\n\n**API 模式设置示例**:\n\n```bash\nexport STT_API_URL=https://api.openai.com/v1\nexport STT_API_KEY=sk-your-key\n```\n\n---\n\n## 故障排查\n\n### 录音失败\n\n**检查音频设备**:\n\n```bash\npython3 scripts/record_audio.py --list-devices\n```\n\n**解决方案**:\n- Linux: 安装 `portaudio19-dev` 或 `libasound-dev`\n- Windows: 安装 PyAudio wheel\n- macOS: 可能需要给终端麦克风权限\n\n**安装音频依赖**:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install portaudio19-dev libasound-dev\n\n# macOS\nbrew install portaudio\n\n# 然后安装 PyAudio\npip install pyaudio\n```\n\n### 转写速度慢\n\n**使用 faster-whisper**（推荐，比原版快 2-4 倍）:\n\n```bash\npip install faster-whisper\n```\n\n**降低模型大小**:\n\n```bash\n# 使用 tiny 模型（最快）\npython3 scripts/transcribe.py audio.wav --model tiny\n```\n\n**使用 GPU**:\n\n```bash\n# 确认 CUDA 可用\npython3 -c \"import torch; print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n### 模型下载失败\n\n```bash\n# 使用镜像\nexport HF_ENDPOINT=https://hf-mirror.com\n\n# 手动下载\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n### API 模式错误\n\n- 确认 API URL 正确（包含 `/v1`）\n- 确认 API Key 有效\n- 检查网络连接\n\n---\n\n## 平台特定说明\n\n### Linux\n- **音频后端**: ALSA + PulseAudio\n- **录音工具**: PyAudio 或 arecord\n- **权限**: 确保用户在 `audio` 组\n ```bash\n sudo usermod -a -G audio $USER\n ```\n\n### Windows\n- **音频后端**: WASAPI / DirectSound\n- **录音工具**: PyAudio\n- **注意**: 部分驱动可能需要管理员权限\n\n### macOS\n- **音频后端**: Core Audio + AVFoundation\n- **录音工具**: PyAudio\n- **权限**: 系统偏好设置 → 安全性与隐私 → 麦克风 → 允许终端\n- Apple Silicon 支持 MPS 加速\n\n### GTX 10xx / Pascal 显卡兼容性\n- GTX 10xx 系列（Pascal 架构）不支持高效的 float16\n- 脚本已自动降级为 float32，不会报错但速度稍慢\n\n## 目录结构\n\n```\nspeech-transcriber/\n├── SKILL.md # 本文档\n├── requirements.txt # Python 依赖\n├── scripts/\n│ ├── record_audio.py # 录音脚本\n│ ├── transcribe.py # 转写脚本\n│ ├── record_and_transcribe.py # ⭐ 一键录音+转写\n│ └── download_models.sh # 模型下载脚本\n└── models/ # 模型目录（需单独下载）\n```\n\n---\n\n## 依赖\n\n```\n# requirements.txt\nfaster-whisper>=1.0.0\npyaudio>=0.2.14\nopenai>=1.0.0\nnumpy>=1.24.0\ntorch>=2.0.0\n```\n\nFile v1.0.0:models/README.md\n\n# Whisper 模型下载说明\n\n本目录的模型文件需单独下载，请运行根目录的下载脚本：\n\n```bash\ncd ~/.openclaw/workspace/skills/speech-transcriber\nbash scripts/download_models.sh base\n```\n\n或手动下载（需设置镜像源）：\n```bash\nexport HF_ENDPOINT=https://hf-mirror.com\npython3 -c \"from faster_whisper import download_model; download_model('base', output_dir='models/')\"\n```\n\n支持的模型大小：tiny / base / small / medium / large\n\n模型来源：https://huggingface.co/Systran/faster-whisper\n\nFile v1.0.0:_meta.json\n\n{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1775384282512\n}\n\nFile v1.0.0:models/config.json\n\n{\n \"alignment_heads\": [\n [\n 5,\n 3\n ],\n [\n 5,\n 9\n ],\n [\n 8,\n 0\n ],\n [\n 8,\n 4\n ],\n [\n 8,\n 7\n ],\n [\n 8,\n 8\n ],\n [\n 9,\n 0\n ],\n [\n 9,\n 7\n ],\n [\n 9,\n 9\n ],\n [\n 10,\n 5\n ]\n ],\n \"lang_ids\": [\n 50259,\n 50260,\n 50261,\n 50262,\n 50263,\n 50264,\n 50265,\n 50266,\n 50267,\n 50268,\n 50269,\n 50270,\n 50271,\n 50272,\n 50273,\n 50274,\n 50275,\n 50276,\n 50277,\n 50278,\n 50279,\n 50280,\n 50281,\n 50282,\n 50283,\n 50284,\n 50285,\n 50286,\n 50287,\n 50288,\n 50289,\n 50290,\n 50291,\n 50292,\n 50293,\n 50294,\n 50295,\n 50296,\n 50297,\n 50298,\n 50299,\n 50300,\n 50301,\n 50302,\n 50303,\n 50304,\n 50305,\n 50306,\n 50307,\n 50308,\n 50309,\n 50310,\n 50311,\n 50312,\n 50313,\n 50314,\n 50315,\n 50316,\n 50317,\n 50318,\n 50319,\n 50320,\n 50321,\n 50322,\n 50323,\n 50324,\n 50325,\n 50326,\n 50327,\n 50328,\n 50329,\n 50330,\n 50331,\n 50332,\n 50333,\n 50334,\n 50335,\n 50336,\n 50337,\n 50338,\n 50339,\n 50340,\n 50341,\n 50342,\n 50343,\n 50344,\n 50345,\n 50346,\n 50347,\n 50348,\n 50349,\n 50350,\n 50351,\n 50352,\n 50353,\n 50354,\n 50355,\n 50356,\n 50357\n ],\n \"suppress_ids\": [\n 1,\n 2,\n 7,\n 8,\n 9,\n 10,\n 14,\n 25,\n 26,\n 27,\n 28,\n 29,\n 31,\n 58,\n 59,\n 60,\n 61,\n 62,\n 63,\n 90,\n 91,\n 92,\n 93,\n 359,\n 503,\n 522,\n 542,\n 873,\n 893,\n 902,\n 918,\n 922,\n 931,\n 1350,\n 1853,\n 1982,\n 2460,\n 2627,\n 3246,\n 3253,\n 3268,\n 3536,\n 3846,\n 3961,\n 4183,\n 4667,\n 6585,\n 6647,\n 7273,\n 9061,\n 9383,\n 10428,\n 10929,\n 11938,\n 12033,\n 12331,\n 12562,\n 13793,\n 14157,\n 14635,\n 15265,\n 15618,\n 16553,\n 16604,\n 18362,\n 18956,\n 20075,\n 21675,\n 22520,\n 26130,\n 26161,\n 26435,\n 28279,\n 29464,\n 31650,\n 32302,\n 32470,\n 36865,\n 42863,\n 47425,\n 49870,\n 50254,\n 50258,\n 50358,\n 50359,\n 50360,\n 50361,\n 50362\n ],\n \"suppress_ids_begin\": [\n 220,\n 50257\n ]\n}\n\nFile v1.0.0:requirements.txt\n\n# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)","readmeExcerpt":"Skill: STT Recognizer | STT 识别器 Owner: moroiser Summary: 语音转文字（Speech-to-Text / STT）工具。 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字， 或通过 OpenAI 兼容 API 进行云端转写。 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。 适用平台：Linux / Windows... Tags: latest:1.0.8 Version history: v1.0.8 | 2026-04-29T14:09:00.715Z | user 1. Fix all internal path references and display names to match the renamed stt-recognizer slug. 修复所有内部路径引用和展示名，统一为新命名的 stt-rec","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"技能目录（发布用）：\n~/.openclaw/workspace/skills/stt-recognizer/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音\n ├── transcribe.py # 转写\n └── record_and_transcribe.py # 一键录音+转写\n\n项目目录（运行时数据）：\n~/.openclaw/workspace/projects/stt-recognizer/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n\n模型缓存（统一命名，技能专属）：\n~/.cache/huggingface/modules/stt-recognizer/\n├── small/ # small 模型（464MB，默认使用）\n└── base/ # base 模型（约 142MB，可选）"},{"language":"bash","snippet":"cd ~/.openclaw/workspace/skills/stt-recognizer\npip install -r requirements.txt --break-system-packages"},{"language":"bash","snippet":"cd ~/.openclaw/workspace/skills/stt-recognizer\nbash scripts/download_models.sh base"},{"language":"bash","snippet":"# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/stt-recognizer/recordings/recording_xxx.wav"},{"language":"bash","snippet":"cd ~/.openclaw/workspace/skills/stt-recognizer\npython3 scripts/record_and_transcribe.py --duration 10 --language zh"},{"language":"bash","snippet":"cd ~/.openclaw/workspace/skills/stt-recognizer\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: STT Recognizer | STT 识别器\ndescription: |\n 语音转文字（Speech-to-Text / STT）工具。\n 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字，\n 或通过 OpenAI 兼容 API 进行云端转写。\n 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。\n 适用平台：Linux / Windows / macOS。\n---\n\n# STT Recognizer | STT 识别器 🎤\n\n将语音转换为文字，支持本地推理和 API 调用。\n\n---\n\n## 文件结构\n\n```\n技能目录（发布用）：\n~/.openclaw/workspace/skills/stt-recognizer/\n├── SKILL.md # 本文档\n├── _meta.json # 元数据\n├── .clawhub/ # ClawHub 源信息\n└── scripts/ # 运行时脚本\n ├── download_models.sh # 下载模型\n ├── record_audio.py # 录音\n ├── transcribe.py # 转写\n └── record_and_transcribe.py # 一键录音+转写\n\n项目目录（运行时数据）：\n~/.openclaw/workspace/projects/stt-recognizer/\n├── requirements.txt # Python 依赖\n├── recordings/ # 录音文件\n└── transcriptions/ # 转写结果\n\n模型缓存（统一命名，技能专属）：\n~/.cache/huggingface/modules/stt-recognizer/\n├── small/ # small 模型（464MB，默认使用）\n└── base/ # base 模型（约 142MB，可选）\n```\n\n---\n\n## 目录\n\n1. [概述](#概述)\n2. [快速开始](#快速开始)\n3. [录音脚本](#录音脚本)\n4. [转写脚本](#转写脚本)\n5. [模型管理](#模型管理)\n6. [输出目录](#输出目录)\n7. [环境变量](#环境变量)\n8. [故障排查](#故障排查)\n\n---\n\n## 概述\n\n### 支持的转写引擎\n\n| 引擎 | 说明 | 优点 |\n|------|------|------|\n| `faster-whisper` | 本地 GPU/CPU 高效推理 | 快速、免费、无需网络 |\n| `whisper` | OpenAI 原生 Whisper | 准确、完整功能 |\n| `api` | OpenAI 兼容 API | 可用云端算力、支持大模型 |\n\n### 支持的音频格式\n\n- WAV (推荐，16-bit PCM)\n- MP3\n- OGG\n- FLAC\n- M4A\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\npip install -r requirements.txt --break-system-packages\n```\n\n### 2. 下载模型\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\nbash scripts/download_models.sh base\n```\n\n### 3. 录音并转写\n\n```bash\n# 方式一：一键录音+转写（推荐）\npython3 scripts/record_and_transcribe.py --duration 10\n\n# 方式二：分开执行\n# 录制 10 秒音频\npython3 scripts/record_audio.py --duration 10\n\n# 转写音频文件\npython3 scripts/transcribe.py ~/.openclaw/workspace/projects/stt-recognizer/recordings/recording_xxx.wav\n```\n\n---\n\n## 录音脚本\n\n### record_and_transcribe.py ⭐ 推荐\n\n一键录音并转写，适合快速使用：\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\npython3 scripts/record_and_transcribe.py --duration 10 --language zh\n```\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--language` | (自动) | 语言代码，留空自动检测 |\n| `--model` | base | 模型大小 |\n| `--engine` | faster-whisper | 转写引擎 |\n\n### record_audio.py\n\n从麦克风录制音频，输出 WAV 文件。\n\n```bash\ncd ~/.openclaw/workspace/skills/stt-recognizer\npython3 scripts/record_audio.py \\\n --duration 10 \\\n --sample-rate 16000 \\\n --channels 1\n```\n\n**参数说明**:\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--duration` | 10 | 录音时长（秒） |\n| `--sample-rate` | 16000 | 采样率（Hz），Whisper 推荐 16000 |\n| `--channels` | 1 | 声道数，1=单声道 |\n| `--list-devices` | - | 列出可用的音频设备 |\n| `--output-dir` | projects/stt-recognizer/recordings | 输出目录 |\n| `--filename` | auto | 输出文件名 |\n\n**示例**:\n\n```bash\n# 列出所有音频设备\npython3 scripts/record_audio.py --list-devices\n\n# 录制 30 秒\npython3 scripts/record_audio.py --duration 30 --filename my_voice.wav\n```\n\n---\n\n## 转写脚本\n\n### transcribe.py\n\n将音频文件转写为文字。\n\n```bash\ncd ~/.openc"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn75k53tcdhqwka2fra5x817p9821zpb\",\n \"slug\": \"stt-recognizer\",\n \"version\": \"1.0.8\",\n \"publishedAt\": 1777471740715\n}"},{"path":"skill-card.md","content":"## Description:\n\nSpeech-to-text skill that records microphone audio and transcribes audio files locally with Whisper/faster-whisper or through an OpenAI-compatible API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[moroiser](https://clawhub.ai/user/moroiser)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and end users can record speech or submit audio files for transcription, choosing local Whisper inference or an OpenAI-compatible API based on privacy, hardware, and connectivity needs.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can record microphone audio and upload audio to an OpenAI-compatible API, which may expose sensitive speech.\n\nMitigation: Get explicit user consent, prefer local transcription for sensitive audio, use only trusted HTTPS endpoints or intentional localhost endpoints, and delete recordings and transcripts when no longer needed.\n\nRisk: Dependency installation guidance uses broad version ranges and includes --break-system-packages.\n\nMitigation: Install in a virtual environment and pin or lock dependencies before operational use.\n\nRisk: API keys can be passed through command-line options and may be exposed through shell history or process listings.\n\nMitigation: Avoid passing API keys on the command line; use a secret manager or protected environment configuration and rotate keys if exposure is suspected.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/moroiser/skills/stt-recognizer)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Shell commands, Configuration, Files, Guidance]\n\n**Output Format:** [Markdown guidance with bash commands; runtime outputs include WAV recordings and text transcription files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Transcriptions may be saved as txt, srt, or vtt files; recorded audio and transcripts can remain on disk until deleted.]\n\n## Skill Version(s):\n\n1.0.8 (source: server release metadata and artifact _meta.json)\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."},{"path":"requirements.txt","content":"# Audio STT Skill - Python Dependencies\n# Install: pip install -r requirements.txt\n\n# ── Core STT Engines ────────────────────────────────────────────────────────\n# Option 1: faster-whisper (recommended - GPU/CPU efficient)\nfaster-whisper>=1.0.0\n\n# Option 2: openai-whisper (full model, slower but accurate)\n# Note: Install ONLY one of faster-whisper or whisper, not both\n# whisper>=20231117\n\n# ── Audio Recording ─────────────────────────────────────────────────────────\n# Option 1: PyAudio (cross-platform)\npyaudio>=0.2.14\n\n# Option 2: SoundDevice + SoundFile (alternative)\n# sounddevice>=0.4.5\n# soundfile>=0.12.1\n\n# ── API Support ────────────────────────────────────────────────────────────\n# For OpenAI-compatible API transcription\nopenai>=1.0.0\n\n# ── Core ───────────────────────────────────────────────────────────────────\nnumpy>=1.24.0\ntorch>=2.0.0\n\n# ── Platform-specific ──────────────────────────────────────────────────────\n# Linux: for ALSA audio recording\n# alsaaudio (optional, for arecord fallback)\n\n# macOS: for AVFoundation (included in system)"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"语音转文字（Speech-to-Text / STT）工具。 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字， 或通过 OpenAI 兼容 API 进行云端转写。 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。 适用平台：Linux / Windows... Skill: STT Recognizer | STT 识别器 Owner: moroiser Summary: 语音转文字（Speech-to-Text / STT）工具。 支持从麦克风录音，使用 Whisper（faster-whisper）在本地进行语音转文字， 或通过 OpenAI 兼容 API 进行云端转写。 触发词：录音、语音转文字、STT、语音识别、转写、录音转文字。 适用平台：Linux / Windows... Tags: latest:1.0.8 Version history: v1.0.8 | 2026-04-29T14:09:00.715Z | user 1. Fix all internal path references and display names to match the renamed stt-recognizer slug. 修复所有内部路径引用和展示名，统一为新命名的 stt-rec","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1049,"uniquenessScore":54,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:28:26.639Z","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-11T20:28:26.639Z","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-12T09:31:53.099Z","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"}]}}}