{"slug":"jianshuo-wjs-transcribing-audio-a48e94","title":"\u97f3\u89c6\u9891\u8f6c\u5199\u4e0eSRT\u5b57\u5e55\u751f\u6210","description":"\u628a\u97f3\u89c6\u9891\u8f6c\u6210\u6e90\u8bed\u8a00\u5e26\u65f6\u95f4\u6233\u7684SRT\uff1a\u4e2d\u6587\u9ed8\u8ba4\u8d70\u706b\u5c71\u6d41\u5f0fASR\uff0c\u5176\u4ed6\u8bed\u8a00\u8d70Whisper\u8bcd\u7ea7\u65f6\u95f4\u6233\u5e76\u81ea\u884c\u6309\u6807\u70b9\u7ec4\u88c5\u5b57\u5e55\uff1b\u542b\u5206\u5757\u3001\u504f\u79fb\u62fc\u63a5\u3001\u9632\u5faa\u73af\u4e0e\u9519\u522b\u5b57\u6821\u6b63\u89c4\u5219\u3002\u53ea\u4ea7\u51fa\u6e90\u8bed\u8a00\u5b57\u5e55\uff0c\u4e0d\u542b\u7ffb\u8bd1\u4e0e\u538b\u5236\u3002","category":"\u7d20\u6750\u4e0e\u6548\u7387","tags":["jianshuo","\u5efa\u7855","\u7d20\u6750\u4e0e\u6548\u7387"],"author":"\u5efa\u7855 \u00b7 jianshuo","source_url":"https://github.com/jianshuo/claude-skills/blob/d36bc423286a34eb32adc604121e5c7714b08740/wjs-transcribing-audio/SKILL.md","license":"MIT","status":"published","verification":"source_reviewed","verification_notes":"\u5df2\u6838\u5bf9\u539f\u59cb\u4ed3\u5e93\u3001\u56fa\u5b9a\u63d0\u4ea4\u3001\u8bb8\u53ef\u3001\u6280\u80fd\u6b63\u6587\u4e0e\u5305\u7ed3\u6784\uff0c\u5e76\u8865\u5145\u4e2d\u6587\u6267\u884c\u9a8c\u6536\u8bf4\u660e\uff1b\u672a\u8fd0\u884c\u5305\u5185\u811a\u672c\u3002","revision":"05f818040d1c470daf49c61a48c39667","created_at":"2026-11-02T14:47:08+00:00","updated_at":"2026-11-02T14:47:08+00:00","source_repo":"jianshuo/claude-skills","source_path":"wjs-transcribing-audio/SKILL.md","source_commit":"d36bc423286a34eb32adc604121e5c7714b08740","source_updated_at":"2026-11-02T14:46:04+00:00","stars":0,"proxy_score":null,"score":null,"grade":null,"dimensions":{},"evaluation":{},"installs":0,"platforms":[],"formats":[],"category_slug":"workflow","category_name":"\u7d20\u6750\u4e0e\u6548\u7387","quality":{"review_type":"text_and_package_review","readiness":"requires_setup","reviewed_at":"2026-11-02T14:46:04+00:00","review_summary":"\u8f6c\u5199\u65b9\u6cd5\u4e0e\u5931\u8d25\u6a21\u5f0f\u8bf4\u660e\u5177\u4f53\u3001\u811a\u672c\u9f50\u5168\uff0c\u4f46\u4f9d\u8d56\u5916\u90e8\u4ed8\u8d39ASR\u4e0e\u7528\u6237\u79c1\u6709\u51ed\u636e\u914d\u7f6e\uff0c\u9700\u6309\u81ea\u8eab\u73af\u5883\u66ff\u6362\u8def\u5f84\u4e0e\u5bc6\u94a5\u540e\u65b9\u53ef\u4f7f\u7528\uff1b\u811a\u672c\u672a\u7ecf\u9a8c\u8bc1\u8fd0\u884c\u3002","cost_notes":"\u706b\u5c71ASR\u4e0eOpenAI Whisper API\u5747\u4e3a\u6309\u91cf\u8ba1\u8d39\u7684\u5916\u90e8\u670d\u52a1\uff0c\u8d39\u7528\u9700\u7528\u6237\u81ea\u884c\u786e\u8ba4\uff1b\u672c\u5ba1\u9605\u672a\u67e5\u8be2\u4efb\u4f55\u4ef7\u683c\u3002","source_sha256":"8a790d9754197006ab3edf9b6d88259cef0ae6512896bef84e2f6d825b2841a9","prerequisites":["ffmpeg \u53ef\u6267\u884c","Python 3 \u4e0e\u811a\u672c\u4f9d\u8d56\uff08httpx\u3001socksio \u89c6\u4ee3\u7406\u60c5\u51b5\uff09","\u706b\u5c71\u5927\u6a21\u578b\u6d41\u5f0fASR\u7684 APPID \u4e0e Access Token\uff0c\u6216 OpenAI API Key","\u7f51\u7edc\u53ef\u8bbf\u95ee\u5bf9\u5e94 API\uff1b\u5982\u8d70\u4ee3\u7406\u9700\u652f\u6301 SOCKS"],"checks":["SRT \u5e8f\u53f7\u4ece 1 \u8fde\u7eed\u9012\u589e\uff0c\u65f6\u95f4\u6233\u4e3a HH:MM:SS,mmm \u4e14\u76f8\u90bb\u4e0d\u91cd\u53e0","\u6bcf\u6761\u5b57\u5e55\u4ee5\u6807\u70b9\u7ed3\u5c3e\uff0c\u65e0\u8de8\u53e5\u622a\u65ad\uff1b\u5355\u884c\u5b57\u6570\u4e0d\u8d85\u8fc7\u8bbe\u5b9a\u4e0a\u9650","\u62bd\u67e5\u9996\u5757\u4e0e\u672b\u5757\u65f6\u95f4\u6233\uff0c\u786e\u8ba4\u5206\u5757\u504f\u79fb\u5df2\u6b63\u786e\u53e0\u52a0\uff08\u672b\u6761\u65f6\u95f4\u63a5\u8fd1\u97f3\u9891\u603b\u957f\uff09","\u8fde\u7eed\u91cd\u590d 3 \u6b21\u4ee5\u4e0a\u7684\u77ed\u8bed\u5df2\u6e05\u9664\uff0c\u65e0\u5faa\u73af\u5e7b\u89c9\u6b8b\u7559","polished \u7248\u4e0e\u539f\u59cb\u7248\u6761\u6570\u3001\u65f6\u95f4\u6233\u5b8c\u5168\u4e00\u81f4\uff0c\u4ec5\u6587\u5b57\u884c\u6709\u5dee\u5f02"],"limitations":["\u5305\u5185\u811a\u672c\u672a\u8fd0\u884c\uff0c\u65e0\u6cd5\u786e\u8ba4\u5176\u5bf9\u5f53\u524d API \u7248\u672c\u4e0e\u8fd4\u56de\u7ed3\u6784\u7684\u517c\u5bb9\u6027","\u706b\u5c71\u6d41\u5f0f\u63a5\u53e3\u7684\u4e8c\u8fdb\u5236\u5e27\u683c\u5f0f\u4e0e\u9274\u6743\u5934\u82e5\u53d8\u66f4\uff0c\u811a\u672c\u53ef\u80fd\u5931\u6548\uff0c\u9700\u6309\u5b98\u65b9\u6587\u6863\u6838\u5bf9","\u672c\u5730 Whisper \u8def\u5f84\u4e0d\u63d0\u4f9b\u8bcd\u7ea7\u65f6\u95f4\u6233\uff0c\u65e0\u6cd5\u5957\u7528\u540c\u4e00\u5957\u7ec4\u88c5\u903b\u8f91\uff0c\u8d28\u91cf\u4e0b\u9650\u66f4\u4f4e","\u4e13\u6709\u540d\u8bcd\u540c\u97f3\u9519\u5b57\u65e0\u6cd5\u81ea\u52a8\u5224\u5b9a\uff0c\u5fc5\u987b\u7531\u7528\u6237\u786e\u8ba4"],"issues":["SKILL.md \u591a\u5904\u5f15\u7528\u7528\u6237\u79c1\u6709\u73af\u5883\uff08~/code/.env\u3001~/.zshrc\u3001\u7279\u5b9a\u4ee3\u7406\u4e0e\u5e76\u53d1\u7ecf\u9a8c\u503c\uff09\uff0c\u5c5e\u4e2a\u4eba\u914d\u7f6e\uff0c\u5176\u4ed6\u7528\u6237\u9700\u81ea\u884c\u66ff\u6362","\u6587\u4e2d\u201c\u5b9e\u6d4b\u201d\u201cverified working path\u201d\u7b49\u8868\u8ff0\u4e3a\u539f\u4f5c\u8005\u7ecf\u9a8c\uff0c\u672c\u6b21\u5ba1\u9605\u672a\u590d\u73b0\uff0c\u4e0d\u5e94\u4f5c\u4e3a\u5df2\u9a8c\u8bc1\u7ed3\u8bba\u4f20\u64ad","\u4e0b\u6e38\u6280\u80fd\uff08wjs-mining-articles\u3001wjs-translating-subtitles \u7b49\uff09\u672a\u968f\u5305\u63d0\u4f9b\uff0c\u8de8\u6280\u80fd\u5f15\u7528\u9700\u7528\u6237\u53e6\u884c\u5177\u5907"],"missing_files":[]},"quality_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/SHILIU-QUALITY.md","usage_guide":{"task":"\u5c06\u7528\u6237\u63d0\u4f9b\u7684\u97f3\u9891\u6216\u89c6\u9891\u8f6c\u5199\u4e3a\u6e90\u8bed\u8a00SRT\u5b57\u5e55\uff0c\u5e76\u505a\u4e00\u6b21\u4ec5\u7ea0\u9519\u522b\u5b57\u7684\u6587\u672c\u6821\u6b63\u3002","inputs":"\u97f3\u89c6\u9891\u6587\u4ef6\u8def\u5f84\uff1b\u6e90\u8bed\u8a00\uff08\u5fc5\u987b\u663e\u5f0f\u6307\u5b9a\uff0c\u4e0d\u53ef\u81ea\u52a8\u68c0\u6d4b\uff09\uff1b\u706b\u5c71ASR\u7684APPID\u4e0eAccess Token\u6216OpenAI API Key\uff08\u4e8c\u9009\u4e00\uff0c\u6309\u8bed\u8a00\u8def\u7531\uff09\uff1b\u672c\u673affmpeg\uff1bPython\u73af\u5883\u53ca\u811a\u672c\u6240\u9700\u4f9d\u8d56\u3002","outputs":"<\u6e90\u6587\u4ef6\u540d>.srt\uff08\u6807\u51c6SRT\uff0c\u9017\u53f7\u6beb\u79d2\uff0c\u5e8f\u53f7\u8fde\u7eed\u3001\u65f6\u95f4\u4e0d\u91cd\u53e0\u3001\u6309\u6807\u70b9\u65ad\u53e5\u3001\u5355\u884c\u4e0d\u8d85\u8bbe\u5b9a\u5b57\u6570\uff09\uff1b\u53ef\u9009<\u6e90\u6587\u4ef6\u540d>.polished.srt\uff1b\u4e00\u4efd\u6539\u52a8\u6e05\u5355\uff08\u5982\u201c\u610f\u6570\u2192\u603b\u6570 @ 00:01:11\u201d\uff09\u4e0e\u4e13\u6709\u540d\u8bcd\u5f85\u786e\u8ba4\u5217\u8868\u3002","example_input":"\u628a\u8fd9\u4e2a 42 \u5206\u949f\u7684\u8bbf\u8c08 mp4 \u8f6c\u6210\u4e2d\u6587\u5b57\u5e55\uff0c\u8f93\u51fa SRT\uff0c\u4e13\u6709\u540d\u8bcd\u5355\u72ec\u5217\u51fa\u6765\u7ed9\u6211\u786e\u8ba4\u3002","example_output":"\u793a\u610f\uff08\u975e\u771f\u5b9e\u7ed3\u679c\uff09\uff1aout.srt \u5171 N \u6761\u5b57\u5e55\uff0c\u5e8f\u53f7 1..N \u8fde\u7eed\uff0c\u65f6\u95f4\u683c\u5f0f 00:00:01,200 --> 00:00:04,800\uff1bpolished \u7248\u4ec5\u6539\u6587\u5b57\u4e0d\u52a8\u65f6\u95f4\u8f74\uff1b\u9644\u6539\u52a8\u6e05\u5355\u82e5\u5e72\u6761\u4e0e\u201c\u4eba\u540d/\u54c1\u724c\u5f85\u786e\u8ba4\u201d\u5217\u8868\u3002"},"read_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94","skill_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/SKILL.md","download_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/download","install_url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/install","files":[{"path":"LICENSE","bytes":1082,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/LICENSE"},{"path":"SHILIU-QUALITY.md","bytes":2122,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/SHILIU-QUALITY.md"},{"path":"SKILL.md","bytes":18366,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/SKILL.md"},{"path":"scripts/build_srt_from_asr.py","bytes":6138,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/scripts/build_srt_from_asr.py"},{"path":"scripts/volc_asr_stream.py","bytes":8998,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/scripts/volc_asr_stream.py"},{"path":"shiliu-quality.json","bytes":2081,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/shiliu-quality.json"},{"path":"shiliu-source.json","bytes":274,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/shiliu-source.json"},{"path":"usage.json","bytes":1003,"url":"https://shiliuai.cn/api/v2/skills/jianshuo-wjs-transcribing-audio-a48e94/files/usage.json"}],"content":"---\nname: wjs-transcribing-audio\ndescription: Use when the user has audio or video and wants a timestamped transcript (SRT) in the source language. Routes by source language \u2014 Chinese defaults to Volcano (\u8c46\u5305) ASR; other languages (Spanish, English, Portuguese, French, Italian, Japanese, Korean, etc.) use OpenAI Whisper API with word-level timestamps and self-assembled cues. Outputs SRT with punctuation-bounded cues capped for on-screen reading. Triggers \u2014 \"\u8f6c\u5199\", \"\u8f6c\u6210\u5b57\u5e55\", \"\u505a SRT\", \"transcribe\", \"make subtitles\", \"speech to text\", \"\u51fa\u5b57\u5e55\".\n---\n\n# wjs-transcribing-audio\n\nSpoken audio in \u2192 timestamped SRT in the same language out. **This skill stops at the source-language SRT.** Translation to another language is the next skill (`/wjs-translating-subtitles`).\n\n## When to use\n\n- User provides a video or audio file and wants a transcript / SRT in the source language.\n- User already has a translated SRT and the source SRT is missing.\n- User asks \"\u505a SRT\" / \"make subtitles\" / \"\u51fa\u9010\u5b57\u7a3f\" with no translation step requested yet.\n\n## When NOT to use\n\n- Source-language SRT already exists \u2192 skip straight to `/wjs-translating-subtitles`.\n- User wants the transcript in a different language than spoken \u2192 run this skill first, then `/wjs-translating-subtitles`.\n- User wants only the dub or burn-in \u2192 if SRT exists, skip; otherwise run this first.\n\n## Routing: which engine\n\n| Source language | Default engine | Why |\n|---|---|---|\n| Chinese (zh-CN, zh-HK, zh-TW) | **Volcano (\u8c46\u5305) ASR** | Materially better accuracy than Whisper for Chinese \u2014 user's standing preference |\n| Any other (es, en, pt, fr, it, ja, ko, \u2026) | **OpenAI Whisper API** with word-level granularity | Whisper's multilingual is strong; word timestamps let us assemble cues ourselves |\n| Offline / no API access | Local `openai-whisper` (medium) | Quality floor; same loop/blob failure modes apply |\n\nFor Chinese, do **not** default to Whisper unless the user explicitly asks for it or Volcano is unavailable. This is a deliberate routing decision \u2014 see user's memory on Chinese ASR priority.\n\n## OpenAI Whisper API path (non-Chinese, and Chinese fallback)\n\n**The key principle: do not request `response_format=srt`.** Whisper cue-segmentation fails on long monologues (30-second blob cues) and quiet stretches (loop hallucinations). Request word-level timestamps and assemble cues yourself \u2014 the post-processing is deterministic and free.\n\n### Why not response_format=srt\n\nTwo failure modes that wreck `whisper-1` SRT output on long content:\n\n1. **30-second blob cues.** In long monologues, `whisper-1` with `response_format=srt` emits one cue covering the full 30s `condition_on_previous_text` window. Transcript is fine; timing is unusable for on-screen reading.\n2. **Loop hallucination on quiet tails.** Greedy `temperature=0` on low-energy audio produces \"\u4f60\u5982\u679c\u4e0d\u628a\u62e5\u62b1\u6d6a\u8d39\u5199\u5728\u8fd9\u4e0a\u9762,\u4f60\u5f88\u96be\u7684\" repeated 50 times.\n\nBoth stem from letting Whisper decide cue boundaries. Fix: word-level timestamps + your own punctuation-aware assembler.\n\n### Calling the API\n\n```bash\n# 1. Compress for upload \u2014 64kbps mono MP3 is plenty for speech.\n#    OpenAI limit is 25MB per request; chunk into 10-min pieces\n#    (\u22484.5MB at 64kbps) for resilience under flaky proxies.\nffmpeg -hide_banner -loglevel error -y \\\n  -ss <start> -t 600 -i input.mp4 \\\n  -vn -ac 1 -ar 16000 -c:a libmp3lame -b:a 64k chunk.mp3\n```\n\n```python\n# 2. Request word-level timestamps. Do NOT request response_format=srt.\nimport httpx, os\ndata = {\n    \"model\": \"whisper-1\",\n    \"language\": \"es\",                        # pin source language; never auto-detect\n    \"response_format\": \"verbose_json\",\n    \"timestamp_granularities[]\": \"word\",     # \u2190 the critical flag\n    \"temperature\": \"0.2\",                    # enable fallback chain (anti-loop)\n}\nwith open(\"chunk.mp3\", \"rb\") as f:\n    r = httpx.post(\n        \"https://api.openai.com/v1/audio/transcriptions\",\n        headers={\"Authorization\": f\"Bearer {os.environ['OPENAI_API_KEY']}\"},\n        data=data,\n        files={\"file\": (\"chunk.mp3\", f, \"audio/mpeg\")},\n        timeout=600.0,\n    )\nr.raise_for_status()\nj = r.json()\nwords    = j[\"words\"]      # [{\"word\": \"hola\", \"start\": 0.12, \"end\": 0.34}, ...]\nsegments = j[\"segments\"]   # see surprise below\n```\n\n### Surprise: words[] has no punctuation, segments[] is inconsistent\n\nWhisper's `words[]` array typically has **no punctuation** in `word[\"word\"]` \u2014 each entry is a bare token like `\"\u505a\"`, `\"\u4e2a\"`, `\"\u6d4b\"`, `\"\u8bd5\"`. Punctuation, when present, lives only in `segments[]` `text` field.\n\nWorse, `segments[]` text is **inconsistently punctuated** across chunks of the same file: chunk 0 of a 79-min podcast might emit 285 bare segments (\"\u505a\u4e2a\u6d4b\u8bd5\" \"\u4f60\u5728\" \"\u5475\u5475\") at 1-2s each with no punctuation; chunk 7 might emit 34 segments at 14-30s each *with* punctuation. Both behaviors ship in the same API response.\n\nSo the right recipe combines both: use `segments[]` for natural pause boundaries (already aligned to breath), but treat them as raw input to your own cue assembler, which uses word timestamps to split anywhere the segments are too long.\n\n### Cue assembly recipe\n\n```python\nTARGET_DUR = 3.0   # try to make cues this long\nMAX_CUE_DUR = 5.0  # never exceed\nMAX_CHARS = 18     # ~one line at Fontsize 14 on 1080-wide vertical\nMAX_GAP = 1.0      # silence threshold \u2192 force cue boundary\nMIN_PIECE = 0.3    # below this, merge with neighbor\nSPLIT_PUNCT = set(\"\uff0c\u3002\uff01\uff1f\uff1b,.;!?\")\n\n# Step A: merge short segments[] toward TARGET_DUR (use segments,\n#         not words \u2014 Whisper's segment boundaries are already\n#         pause-aligned).\ndef assemble(segments, offset):\n    cues, buf = [], []\n    def flush():\n        if buf:\n            cues.append((buf[0][\"start\"]+offset, buf[-1][\"end\"]+offset,\n                         \"\".join(s[\"text\"].strip() for s in buf)))\n            buf.clear()\n    for s in segments:\n        dur = s[\"end\"] - s[\"start\"]\n        # Long single segment WITH internal punct \u2192 split standalone\n        if dur > MAX_CUE_DUR and any(c in s[\"text\"] for c in SPLIT_PUNCT):\n            flush(); cues.extend(split_long_segment(s, offset)); continue\n        if not buf: buf.append(s); continue\n        if (s[\"start\"] - buf[-1][\"end\"]) >= MAX_GAP \\\n           or (buf[-1][\"end\"] - buf[0][\"start\"]) >= TARGET_DUR \\\n           or (s[\"end\"] - buf[0][\"start\"]) > MAX_CUE_DUR:\n            flush()\n        buf.append(s)\n    flush(); return cues\n\n# Step B: final pass \u2014 split every internal comma/period to its own cue\n#         (proportional timestamps by char position). Coalesce pieces\n#         shorter than MIN_PIECE forward.\n\n# Step C: any cue still > MAX_CHARS gets split at the largest inter-word\n#         gap using words[] timestamps. Recursive until under cap.\n```\n\nTweak `TARGET_DUR` and `MAX_CHARS` to platform reading rhythm. The 18-char cap matters for burn-in on vertical 1080\u00d71920 at `Fontsize=14` \u2014 longer wraps to multiple unreadable lines.\n\n### Operational details\n\n- **Auth:** credentials live in `~/code/.env`. Load with `set -a; source ~/code/.env; set +a` before invoking.\n- **SOCKS proxy on this machine:** `httpx` needs the `socksio` extra \u2014 use `uvx --with httpx --with socksio python ...` (without it you get `ImportError: Using SOCKS proxy, but the 'socksio' package is not installed`).\n- **Chunking:** 10-min pieces at 64kbps mono MP3 (~4.5MB each) are the reliability sweet spot. 20-min chunks (~9MB) sometimes RST under flaky proxies. Concurrency `max_workers=2` is more reliable than `4`.\n- **Retry:** every API call wrapped in 5\u00d7 exponential backoff (`time.sleep(min(2**n, 30))`) \u2014 `RemoteProtocolError: Server disconnected` is common and transient.\n- **Offset stitching:** each chunk's words come back with timestamps relative to that chunk. When merging, add the chunk's absolute start offset to every word's `start`/`end` before assembling cues.\n- **Loop guard (belt + suspenders):** even with `temperature=0.2`, occasionally a sub-chunk still loops. After assembly, run a loop-detector on each cue's text \u2014 if any phrase of length 8\u201340 chars repeats 3+ times consecutively, drop the cue.\n\n### Anti-patterns (do not do)\n\n- \u274c **Do not request `response_format=srt`** for content longer than ~2 minutes.\n- \u274c **Do not \"fix\" bad cues with a second API call.** If you got blob cues or loop hallucinations from your first call, redo with word-level granularity once \u2014 don't re-transcribe just the broken sub-range.\n- \u274c **Do not use `temperature=0`** on potentially-quiet audio (yoga, spiritual content, podcast outros). Greedy decoding loops. `0.2` enables the fallback chain.\n- \u274c **Do not skip `language=...`.** Auto-detect occasionally swaps Chinese\u2192Japanese or Spanish\u2192Portuguese on the first 30 seconds and the whole transcript is then wrong.\n\n## Volcano (\u8c46\u5305) ASR path \u2014 preferred for Chinese\n\nVolcano ASR routinely beats Whisper on Mandarin accuracy (recognition rate, punctuation, named entities). Use this as the default for `zh-*` source.\n\n> \u26d4 **NEVER use \u98de\u4e66\u5999\u8bb0 / lark-minutes for ASR.** It only gives turn-level (speaker-turn) timestamps, not per-word timing \u2014 subtitles built from it drift by seconds and break at unnatural places. The user's standing rule: \"\u4ee5\u540e\u4e0d\u8981\u7528\u98de\u4e66\u5999\u8bb0\u6765\u505aASR\uff0c\u4e0d\u80fd\u4f5c\u4e3aSRT\u4f7f\u7528\uff0c\u8bb0\u4f4f\". There is no \u98de\u4e66\u5999\u8bb0 fallback. If Volcano is unavailable, fall back to the OpenAI Whisper word-level path above (pin `language=zh`).\n\n### Use the STREAMING WebSocket API \u2014 pushes bytes, needs NO public URL\n\nThe file / \u5f55\u97f3\u6587\u4ef6\u8bc6\u522b / MediaKit APIs all require a publicly reachable HTTP(S) audio URL. The user rejected URL-hosting (\"\u4e0d\u8981\u518d\u7528\u4ec0\u4e48\u4ece\u670d\u52a1\u5668\u7aef\u53bb download \u7684\u8fd9 mp3 \u8fd9\u6837\u7684\u6a21\u5f0f\" \u2014 tunnels fail on their hotspot). The **\u5927\u6a21\u578b\u6d41\u5f0f\u8bed\u97f3\u8bc6\u522b (bigmodel streaming)** API sidesteps the URL entirely by pushing raw PCM bytes over a WebSocket. **This is the working path.** It returns per-word ms timestamps.\n\n**Bundled scripts (use these \u2014 they are the verified working path):**\n\n```bash\n# 1. Transcribe: pushes 16k mono PCM bytes over WebSocket \u2192 ASR JSON\n#    (decodes any input via ffmpeg; .pcm passes straight through)\nexport VOLC_ASR_APPID=\u2026  VOLC_ASR_ACCESS_TOKEN=\u2026   # credentials live with the user\npython3 scripts/volc_asr_stream.py <clip.mp4|wav|mp3|pcm> <out.asr.json>\n\n# 2. Build a clean, word-timed SRT from the ASR JSON\npython3 scripts/build_srt_from_asr.py <out.asr.json> <out.srt> [max_chars=18]\n#    Segmentation knobs (optional):\n#      --max-chars N   raise to keep cues whole / break on punctuation, not mid-sentence\n#      --soft-min N    min chars before a \uff0c\u3001\uff1b flushes a cue (default 8)\n#      --strip-punct   remove ALL punctuation from displayed text (clean subtitle look)\n```\n\n- **Endpoint:** `wss://openspeech.bytedance.com/api/v3/sauc/bigmodel`\n- **Headers:** `X-Api-App-Key:{appid}`, `X-Api-Access-Key:{token}`, `X-Api-Resource-Id:volc.bigasr.sauc.duration`, `X-Api-Connect-Id:{uuid}`\n- **Binary v3 framing:** 4-byte header `[(ver<<4)|hdrsize, (msgtype<<4)|flags, (ser<<4)|comp, 0]`. Full-client(0x1)+POS_SEQ sends gzipped JSON config; audio(0x2) packets send gzipped PCM chunks (200ms = 6400 bytes @16k mono s16le); last packet uses NEG_WITH_SEQ(0x3) with **negative** seq. Server full-response(0x9) returns gzipped JSON.\n- **Config JSON:** `{user:{uid}, audio:{format:\"pcm\",rate:16000,bits:16,channel:1,codec:\"raw\"}, request:{model_name:\"bigmodel\", enable_punc:true, enable_itn:true, show_utterances:true}}`. **Do NOT set `result_type:\"single\"`** \u2014 that returns only the latest sentence each frame; default mode accumulates all utterances.\n- **Result shape:** `result.utterances[]`, each with `text` (punctuated) + `words[]` (token + ms `start_time`/`end_time`). Latin tokens like \"AI\" come back with `start=end=0` \u2014 `build_srt_from_asr.py` forward/backward-fills from neighbours.\n- **build_srt_from_asr.py** also: splits cues on punctuation (HARD `\u3002\uff01\uff1f` flush; SOFT `\uff0c\u3001\uff1b` flush past `--soft-min` chars; hard cap `--max-chars`), optionally strips all punctuation from the display (`--strip-punct`), drops \u5443/\u55ef/\u5509 fillers, and collapses immediate duplicate short tokens (\u624d\u624d\u2192\u624d). Every cue is timed by its first/last word so it sits exactly on the spoken audio \u2014 no drift. **To avoid mid-sentence breaks, raise `--max-chars` so boundaries fall on punctuation rather than the char cap.**\n- **Per-clip transcription:** transcribe each *clip's own* audio (16k mono PCM) so the SRT timestamps come out clip-relative.\n- **Credentials:** live with the user (\u8c46\u5305\u8bed\u97f3\u5f15\u64ce). Env names accepted by the script: `VOLC_ASR_APPID`/`VOLC_APPID` and `VOLC_ASR_ACCESS_TOKEN`/`VOLC_TOKEN`; `FFMPEG_BIN` optional.\n  - **This user's \u706b\u5c71 ASR and TTS share ONE credential set** \u2014 same appid + access token work for both services. They're stored in `~/code/.env` as `VOLC_TTS_APPID` / `VOLC_TTS_ACCESS_TOKEN` (plus `VOLC_APPID` in `~/.zshrc`), with `VOLC_ASR_APPID` / `VOLC_ASR_ACCESS_TOKEN` aliases appended pointing at the same values. So `set -a; source ~/code/.env; set +a` is enough \u2014 no separate ASR token to hunt for. If the aliases are ever missing, recreate them from the TTS values (they're the same secret).\n- **Dead ends (don't retry):** MediaKit asr-subtitles (doc 6448/2381968) still needs a public URL *and* a separate MediaKit API key. The \u5f55\u97f3\u6587\u4ef6\u8bc6\u522b file API needs a public URL.\n\n## Local Whisper as last resort\n\nOnly when offline, the API quota is exhausted, or for ultra-cheap rough drafts. Quality is materially lower for Chinese; same blob/loop failure modes apply; local Whisper does not expose word-level timestamps via the CLI so the principled fix isn't available.\n\n```bash\nffmpeg -i input.mp4 -vn -ac 1 -ar 16000 -c:a pcm_s16le _audio.wav -y\nuvx --from openai-whisper whisper _audio.wav \\\n    --language zh --task transcribe \\\n    --model medium --output_format srt --output_dir .\nrm _audio.wav\n```\n\n`medium` is the practical floor for Chinese accuracy; `small` is OK only for clean studio English. Whisper writes `.` milliseconds; the file is still valid SRT. If you regenerate the SRT, always emit `,` ms.\n\n## AI \u6da6\u8272 pass \u2014 fix obvious \u9519\u522b\u5b57 (final step, always run for Chinese)\n\nEven Volcano ASR ships clear homophone errors that read wrong on screen \u2014 observed: \u300c\u603b\u6570\u300d\u2192\u300c\u610f\u6570\u300d, \u300c\u9700\u6c42\u300d\u2192\u300c\u865a\u6c42\u300d, \u300c\u7a0b\u5e8f\u5458\u300d\u2192\u300c\u6210\u5458\u300d. Raw ASR text is the floor, not the ceiling. After the SRT is assembled, do **one Claude polish pass** over the full SRT to correct obvious errors using sentence context.\n\nThis pass is done **in-session by Claude reading the SRT** \u2014 no external API call. Rewrite the `.srt` in place (or to `<stem>.polished.srt`).\n\n**Hard rules \u2014 this is correction, not editing:**\n\n- \u2705 Fix only *clear* homophone / \u9519\u522b\u5b57 errors where the intended word is unambiguous from context (\u610f\u6570\u2192\u603b\u6570, \u865a\u6c42\u2192\u9700\u6c42).\n- \u26d4 **NEVER change timestamps, cue numbering, or cue boundaries.** Edit the text line *inside* each existing cue only. Same number of cues in and out.\n- \u26d4 **Do not paraphrase, polish grammar, condense, or \"improve\" phrasing.** Keep the spoken register, fillers the assembler kept, repetitions, and sentence shape. The SRT must still match the audio word-for-word except for the corrected characters.\n- \u26d4 **Do not silently \"correct\" \u4e13\u6709\u540d\u8bcd / \u4eba\u540d / \u54c1\u724c / \u4ea7\u54c1\u540d.** Homophone-guessing names is how you ship \u300c\u9ec4\u4e00\u5b5f\u300d\u2192\u300c\u9ec4\u4e00\u68a6\u300d. Leave them as-is and surface a list to the user for confirmation (see pitfall below). Never invent a name you didn't hear.\n- \u2705 Keep the gold-block-worthy numbers exactly as spoken (50\u4e07, 1,000\u4e07) \u2014 don't normalize digits/units.\n\n**Workflow:** read the SRT \u2192 produce the corrected SRT with identical timing \u2192 report a short diff list of what changed (`\u610f\u6570\u2192\u603b\u6570 @ 00:01:11`) so the user can spot-check. If a correction is uncertain, leave the original and add it to the proper-noun/uncertain list rather than guessing.\n\nRun this **before** segmentation/clip-building so every downstream clip inherits the clean text.\n\n## Output\n\n- **File name**: `<source-stem>.srt` (no language suffix \u2014 this is the *source* language SRT, the master).\n- **Format**: standard SRT, `HH:MM:SS,mmm` (comma ms), 1-indexed.\n- **Cue rules**: punctuation-bounded; 3-8s typical duration; \u226418 Chinese chars or \u226442 Latin chars per visible line.\n- **Unclear audio**: mark `[inaudible]` only when necessary; do not guess.\n\n## Quality gate before handoff\n\n- Subtitle numbers are sequential\n- Timestamps don't overlap\n- Milliseconds use commas\n- No cue ends mid-word\n- No cue exceeds MAX_CHARS without an internal split\n- No phrase repeats 3+ times consecutively (loop residue)\n- AI \u6da6\u8272 pass run \u2014 obvious \u9519\u522b\u5b57 corrected, timestamps/cue count untouched, \u4e13\u6709\u540d\u8bcd surfaced to user not silently changed\n\n## Downstream\n\n- **`/wjs-mining-articles`** \u2014 turn a \u738b\u5efa\u7855 monologue/\u5bf9\u8c08 SRT into multiple \u5fae\u4fe1\u516c\u4f17\u53f7 articles.\n- **`/wjs-translating-subtitles`** \u2014 translate the source SRT to a target language with punctuation-bounded re-segmentation.\n- **`/wjs-dubbing-video`** \u2014 only if the user wants voice dub *in the source language* (rare); usually you translate first.\n- **`/wjs-burning-subtitles`** \u2014 only if the user wants the source-language SRT burned onto the source video (e.g., Spanish video with Spanish subs for hearing-impaired).\n\n## Common pitfalls\n\n- **Sending the whole 60-minute file in one API call.** OpenAI's hard limit is 25 MB and the call gets choppy at >15 min anyway. Chunk first.\n- **Treating `segments[]` text as authoritative.** It's inconsistently punctuated across chunks of the same file \u2014 never trust it without the assembler.\n- **Letting Whisper auto-detect language.** Pin every time.\n- **Forgetting to add chunk offsets.** Each API response has timestamps relative to the chunk's t=0; merging without adding the chunk's absolute start makes every cue past the first chunk wrong by minutes.\n- **\u4e13\u6709\u540d\u8bcd / \u4eba\u540d\u51e0\u4e4e\u4e00\u5b9a\u6709\u9519\u3002** ASR \u628a\u4eba\u540d\u3001\u54c1\u724c\u3001\u4ea7\u54c1\u540d\u542c\u6210\u540c\u97f3\u522b\u5b57\u662f\u5e38\u6001(\u5b9e\u6d4b\u300c\u9ec4\u4e00\u5b5f\u300d\u2192\u300c\u9ec4\u4e00\u68a6\u300d)\u3002SRT \u91cc\u7684\u4e13\u6709\u540d\u8bcd\u90fd\u5148\u5f53\u5b58\u7591,\u4e0b\u6e38\u6210\u6587/\u53d1\u5e03\u524d(\u5c24\u5176 `/wjs-mining-articles`)\u4e00\u5b9a\u8ddf\u7528\u6237\u6838\u5bf9,\u522b\u7167\u7740\u9519\u5b57\u5199\u51fa\u53bb\u3002\n","usage":"\u8bfb\u53d6 SKILL.md\uff0c\u5e76\u6309\u9700\u8bfb\u53d6\u914d\u5957\u6587\u4ef6\uff1b\u4e0b\u8f7d ZIP \u83b7\u53d6\u5b8c\u6574\u5305\u3002\u6280\u80fd\u662f\u4efb\u52a1\u65b9\u6cd5\uff0c\u4e0d\u6388\u4e88\u65b0\u589e\u8d26\u6237\u3001\u4ed8\u8d39\u6216\u7cfb\u7edf\u6743\u9650\u3002"}