视频号下载转录逐字稿@Amber灵霄
Quick Summary（大白话版）
> 这个技能的作用：给你一个视频号分享链接，自动把视频里说的话变成文字。
>
> 分三步：
> 1. 下载视频 — 用腾讯元宝解析视频号链接，拿到视频文件。
> 2. 语音转文字 — 用 AI 听一遍音频，逐句输出带时间戳的文字稿。
> 3. 语义后处理 — 用 AI 语言理解给连续文本加上正确的标点符号和段落分段，方便阅读。
>
> 你只需要提供链接，剩下的全是自动完成。
> ⚠️ 首次使用须知
>
> 第一次使用时，会弹出一个 Chrome 窗口，需要你用微信扫码登录腾讯元宝。
> 这是一步性操作，登录后长期有效，后续不用重复扫码。
> 如果过了一段时间登录过期，会再次提示扫码。
> 支持多种输出格式
>
> - json — 带时间戳的结构化数据（默认）
> - srt — SRT 字幕文件，可直接加载到视频播放器
> - md — Markdown 逐字稿，带时间戳分段 + 完整连续文本
>
> 支持批量处理多个链接，支持说话人分离（多人对话场景）。
数据与凭据使用说明 (Credentials & Data Disclosure)
为了让审核方和使用者清楚本技能读取了什么、发往哪里，特此完整披露：
读取范围（最小化白名单）
- 你扫码登录腾讯元宝后，脚本通过 Playwright 监听浏览器对 yuanbao.tencent.com/api/* 的请求，
仅捕获以下 8 个鉴权请求头（见 scripts/wx_channels.py 中的 AUTH_HEADER_WHITELIST 常量）：
authorization、x-id、x-agentid、x-device-id、x-hy92、x-hy93、t-userid、accept-language
- 不读取、不保存其他任何请求头，不读取页面内容，不上传剪贴板或本地文件。
用途与去向
- 捕获的凭据仅驻留内存，仅用于向腾讯元宝官方接口
yuanbao.tencent.com/api/weixin/get_parse_result 发起视频解析请求；
- 视频下载地址来自解析结果返回的 token，通过微信官方接口
channels.weixin.qq.com/finder-preview/api/feed/get_feed_info 获取；
- 凭据不会发送到任何第三方服务器，不会写入磁盘或日志，命令结束即释放。
本地保留的数据
- 登录 Cookie 保存在本机专用浏览器配置目录（~/Library/Application Support/sphdownload/
或 %LOCALAPPDATA%\sphdownload\），用于下次免扫码，不会上传；
- 下载的视频和转录文本保存在你指定的输出目录。
Overview
End-to-end pipeline to extract a word-for-word transcript (逐字稿) from a WeChat
Channels (视频号) share link. Three stages: download video → speech-to-text →
semantic post-processing (punctuation + paragraphing). This skill is fully
self-contained — all scripts are in scripts/, no dependency on other skills.
> Before trying alternative approaches, read references/failed-approaches.md.
> It documents 7 dead ends (API reverse-engineering, disabled API keys, Windows-only
> tools, proxy issues, etc.) so you don't waste time rediscovering them.
Prerequisites
Python Environment
You need a Python venv with the required packages installed. The bare system
Python will NOT work — packages must go into a venv.
# Step 1: Identify the managed Python
MANAGED_PYTHON="$(python3 -c 'import sys; print(sys.executable)')"
# Step 2: Use (or create) the default venv for package installation
VENV_DIR="$HOME/.workbuddy/binaries/python/envs/default"
if [ ! -x "$VENV_DIR/bin/python3" ]; then
"$MANAGED_PYTHON" -m venv "$VENV_DIR"
fi
VENV_PYTHON="$VENV_DIR/bin/python3"
Required Packages
Install pinned versions from the bundled requirements.txt (not loose
version ranges) — this guarantees reproducible behavior and supply-chain
traceability:
PIP="$VENV_PYTHON -m pip"
$PIP install -r "$SKILL_ROOT/requirements.txt"
$VENV_PYTHON -m playwright install chromium # fallback browser if system Chrome missing
Pinned versions (tested 2026-08):
| Package | Version |
|---------|---------|
| playwright | 1.62.0 |
| imageio-ffmpeg | 0.6.0 |
| faster-whisper | 1.2.1 |
Optional (for speaker diarization):
$PIP install pyannote-audio torch
# Also requires HF_TOKEN environment variable (https://huggingface.co/settings/tokens)
System Browser (Chrome or Edge)
The downloader reuses a real browser profile to log into Tencent Yuanbao.
- macOS: Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
- Windows: Chrome at %PROGRAMFILES%\Google\Chrome\Application\chrome.exe
- Fallback: If no system browser found, Playwright's bundled Chromium is used automatically.
Scripts
All scripts are in this skill's scripts/ directory — no external skill dependency.
scripts/wx_channels.py— Self-contained video downloader (cross-platform, built-in macOS support)scripts/transcribe.py— Speech-to-text with SRT/JSON/MD output, batch processing, speaker diarization, and--videoauto audio extraction
How to Locate Script Paths
This skill's scripts live at {SKILL_ROOT}/scripts/. To get SKILL_ROOT, find
the directory containing this SKILL.md file. In practice:
# Match the exact directory name to avoid false matches (e.g. novaai-wechat-channels-transcript-extractor)
SKILL_ROOT="$(dirname "$(find ~/.workbuddy/skills -name SKILL.md -path '*/wechat-channels-transcript/SKILL.md' -print -quit)")"
SKILL_SCRIPTS="$SKILL_ROOT/scripts"
Workflow
Stage 1: Download Video
Use the self-contained downloader script:
# First-time setup — check environment
$VENV_PYTHON "$SKILL_SCRIPTS/wx_channels.py" doctor --browser chrome
# First-time login (opens Chrome window, user scans QR with WeChat)
$VENV_PYTHON "$SKILL_SCRIPTS/wx_channels.py" login --browser chrome --timeout 300
# Download video
$VENV_PYTHON "$SKILL_SCRIPTS/wx_channels.py" download \
"https://weixin.qq.com/sph/XXXXX" \
--browser chrome --output-dir /tmp/wxvideo
Output: an MP4 file in the output directory.
Stage 2: Extract Audio + Transcribe
The transcribe.py script can accept a video file directly via --video,
automatically extracting audio internally — no manual ffmpeg step needed.
However, if you prefer to extract audio separately (e.g. to inspect it first):
FFMPEG="$($VENV_PYTHON -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())")"
"$FFMPEG" -i /tmp/wxvideo/video.mp4 \
-vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/wxvideo/audio.wav -y
Key parameters: 16 kHz sample rate, mono channel — optimal for Whisper.
Run the transcription
Set up environment variables once, then use --audio or --video:
# Environment prefix — define once, reuse for all transcription commands
export HF_ENV="HTTP_PROXY= HTTPS_PROXY= http_proxy= https_proxy= ALL_PROXY= all_proxy= HF_HUB_DISABLE_XET=1 HF_ENDPOINT=https://hf-mirror.com"
# --- Option A: Input video file directly (auto-extracts audio) ---
env $HF_ENV $VENV_PYTHON "$SKILL_SCRIPTS/transcribe.py" \
--video /tmp/wxvideo/video.mp4 \
--output /tmp/wxvideo/transcript.json \
--model small --language zh
# --- Option B: Input pre-extracted audio file ---
env $HF_ENV $VENV_PYTHON "$SKILL_SCRIPTS/transcribe.py" \
--audio /tmp/wxvideo/audio.wav \
--output /tmp/wxvideo/transcript.json \
--model small --language zh
# --- SRT subtitle output ---
env $HF_ENV $VENV_PYTHON "$SKILL_SCRIPTS/transcribe.py" \
--video /tmp/wxvideo/video.mp4 \
--output /tmp/wxvideo/subtitle.srt \
--format srt --model small
# --- Batch processing (mix of audio/video files OK) ---
env $HF_ENV $VENV_PYTHON "$SKILL_SCRIPTS/transcribe.py" \
--batch video1.mp4 audio2.wav video3.mov \
--output-dir /tmp/wxvideo/transcripts \
--format srt
# --- With speaker diarization (multi-person dialogue) ---
env $HF_ENV HF_TOKEN="your_huggingface_token" \
$VENV_PYTHON "$SKILL_SCRIPTS/transcribe.py" \
--video /tmp/wxvideo/video.mp4 \
--output /tmp/wxvideo/transcript.json \
--diarize --num-speakers 2
Critical environment variables:
- HTTP_PROXY="" etc. — clear proxy env vars; local proxies (e.g. 127.0.0.1:54931)
block HuggingFace model downloads.
- HF_ENDPOINT=https://hf-mirror.com — fallback option for mainland China, where
huggingface.co is often unreachable (502). If you can access the official site,
omit this variable and download directly from huggingface.co (preferred — the
source of truth for checksums).
- HF_HUB_DISABLE_XET=1 — disable Xet download protocol (requires authentication).
- HF_TOKEN — only needed for speaker diarization (pyannote-audio model access).
Model integrity verification (optional but recommended): models come from the
official repos (e.g. small = Systran/faster-whisper-small). After the first
download they are cached at ~/.cache/huggingface/hub/. To verify a mirror-sourced
model against the official release, compare the file SHA256 with the value listed
on the model's official HuggingFace page:
shasum -a 256 ~/.cache/huggingface/hub/models--Systran--faster-whisper-small/snapshots/*/model.bin
Network requirements: All steps use domestic services (PyPI, Tencent Yuanbao,
hf-mirror.com). No VPN or overseas access is needed at any point. The Whisper model
is downloaded only once and cached locally; subsequent runs are fully offline.
Model selection:
- small (480MB) — recommended default. Good Chinese accuracy, ~5 min to download.
- medium (1.5GB) — better accuracy but slow download and CPU transcription.
- base (145MB) — fastest, lower accuracy. Use for quick drafts.
Output formats:
| Format | Flag | Description |
|--------|------|-------------|
| JSON | --format json (default) | Structured data with timestamps, language, duration |
| SRT | --format srt | Standard subtitle file, loadable in video players |
| Markdown | --format md | Human-readable with timestamped segments + continuous text |
Transcription speed: On Apple M2 Max CPU, small model processes
5-minute audio in ~3-4 minutes. Longer videos scale linearly.
Batch mode loads the model once and reuses it across all files.
Stage 3: Post-process Transcript (Semantic Punctuation + Paragraphing)
The raw transcript from Stage 2 has timestamps and segment-level text, but the
continuous text lacks semantic punctuation and paragraph breaks. As the final step,
use your language understanding to produce a readable document — do NOT rely on
simple gap-based rules (e.g. "gap > 1s → period"), which produce poor results.
Steps:
- Read the transcript JSON output from Stage 2.
- Add proper Chinese punctuation based on semantic meaning:
-。for sentence endings (complete thought)
-，for clause pauses within a sentence
-？for questions (listen for interrogative tone)
-！for exclamations
-、for listing items
-；for separating parallel clauses - Break into paragraphs by topic shift — group sentences that discuss the
same point into one paragraph, start a new paragraph when the speaker moves
to a new topic. - Save as a Markdown document with:
- Header: source link, duration, model, date
- Section 1: Timestamped segments (from raw output, lightly cleaned)
- Section 2: Post-processed continuous text with paragraphs and punctuation
- Footer note:AI 语音识别自动生成，存在同音字误差，请校对后使用。 - Do NOT include specific homophone error examples in the document — each
video has different errors, listing specific ones is misleading.
This step requires no additional packages or scripts — it uses your own language
understanding, like a human editor reading through the raw transcript.
Troubleshooting
See references/troubleshooting.md for detailed solutions to common issues.
Quick reference:
- Model download fails (502/timeout) → clear proxy env vars, use HF mirror
- Playwright not found → pip install -r requirements.txt + playwright install chromium
- Browser not found → install Chrome, or rely on Playwright Chromium fallback
- Yuanbao login expired → re-run login --force --browser chrome
- Video URL missing → link may be deleted/private/expired; re-run resolve to check
- Speaker diarization fails → ensure pyannote-audio installed + HF_TOKEN set
References
references/troubleshooting.md— Detailed error codes and solutionsreferences/failed-approaches.md— Dead ends and approaches that do NOT work (read before trying alternatives)
