cleaning-auto-transcripts

清理自动生成的字幕

用于处理、获取和降噪自动生成的 YouTube 字幕的技能，适用于包含拼写错误、说话者口音偏差或转写错误的字幕。将错误文本与正确拼写数据库进行匹配，生成干净、完整的下游内容。

适用场景

• 下载自动生成的 YouTube 字幕，用于摘要或添加时间戳时。
• 已有针对特定主播／说话者的错误映射文件（Error Mapping）时，例如 Pu Boat（FGO／ZZZ／游戏录像）。
• 需要进行空格规范化并消除重叠术语歧义时。

母语 （例如，区分“โรนิน”和“เบโรนินะครับ”） 母语

---

严格的分步指南

重要指示：禁止跳过步骤。必须严格按顺序执行此流程。

步骤 1：必须检查环境

操作：在处理任何文件之前，使用原生工具验证执行环境。

• Bash：echo $SHELL && uname -a && command -v yt-dlp && command -v python3
• Windows PowerShell：$PSVersionTable.PSVersion; Get-Command yt-dlp; Get-Command python 重要：验证 shell 和工具之前，禁止继续操作。

步骤 2：准备工作区、下载并分块处理字幕

操作：运行 prepare_video.py 脚本。该脚本会自动创建 youtube_VIDEO_ID_workspace，使用原生 yt-dlp 安全下载字幕，并一次性完成清理和分块。

• 查找 [SKILL_ROOT]：查看提示词顶部的 <skill location="..."> XML 标签。去掉文件名 SKILL.md（在 Windows 上也可能带有反斜杠 \）。将所有 \ 替换为 /。结果即为 [SKILL_ROOT]。
• 命令： 使用技能目录中的流水线脚本：

  python3 "[SKILL_ROOT]/scripts/prepare_video.py" "VIDEO_URL"
  

步骤 3：验证输出

操作：验证新工作区中是否已成功生成 cleaned_transcript.json（或 chunks/ 文件夹）。 重要路径规则：文件读取工具不会展开 $HOME 或 ~。必须使用真正的绝对路径。先运行 pwd 或 Get-Location 找到确切目录，然后追加文件路径（例如，C:\Users\peter\youtube_VIDEO_ID_workspace\chunks\chunk_00.json）。

---

映射规则结构

用于存储拼写错误到正确拼写映射的文件采用 JSON 格式：

{
  "mappings": [
    {
      "correct": "Resident Evil: Code Veronica",
      "patterns": ["veronica", "venomica", "venonica", "เบโรนิ", "เโรica"]
    },
    {
      "correct": "TMNT: The Last Ronin",
      "patterns": ["last ronin", "โรนิน"],
      "exclude_if_contains": ["เบโรนิน"]
    }
  ]
}

---

辅助脚本和原生工具

重要规则（马尾模式）：不要为一次性 JSON 操作构建可复用的 CLI 抽象。搜索、导出和预览字幕时，只使用原生工具（jq 或 PowerShell ConvertFrom-Json）。

如需方便地清理基于正则表达式的映射，请使用：

• clean_transcript.py

获取字幕（原生方式）

重要：安全地将字幕获取到独立工作区的确切命令，见步骤 2。

反机器人拦截处理（YouTube 429 错误／需要登录）：

• 本地运行：告知用户并询问他们使用的浏览器（例如 chrome、brave、edge）。在 yt-dlp 命令中追加 --cookies-from-browser <browser_name>。不要猜测浏览器名称或使用随机会话字符串。
• OpenCode／云沙盒运行：如果你处于隔离的云环境中，--cookies-from-browser 将会失败。请用户在本地下载字幕，并将 raw_transcript.json 上传到会话工作区。

clean_transcript.py 用法

使用简单的位置参数：python3 "[SKILL_ROOT]/scripts/clean_transcript.py" <input.json> [custom_mappings.json] > output.json

# Default mapping (outputs single JSON to stdout)
python3 "[SKILL_ROOT]/scripts/clean_transcript.py" raw_transcript.json > cleaned_transcript.json

# Custom mapping
python3 "[SKILL_ROOT]/scripts/clean_transcript.py" raw_transcript.json custom_mappings.json > cleaned_transcript.json

# Chunking mode (for MapReduce pipelines like anibon-timestamper)
# Use the --chunk flag to output segments with overlap directly to a folder, instead of stdout.
python3 "[SKILL_ROOT]/scripts/clean_transcript.py" raw_transcript.json --chunk --chunk-dir chunks --block 900 --overlap 60

转录文本操作（原生单行命令）

关键规则：不要使用内置的 grep 或 search 工具搜索 JSON 转录文本！这样会丢失时间戳，或遇到“未找到文件”错误。必须使用以下 PowerShell 单行命令，并使用绝对路径。始终强制使用 UTF-8 编码，以免泰语字符损坏成乱码！

• 搜索关键词： powershell -c "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; (Get-Content -Encoding UTF8 'C:\Users\peter\youtube_VIDEO_ID_workspace\cleaned_transcript.json' -Raw | ConvertFrom-Json) | ? text -match 'keyword' | Select-Object start, text"
• 导出时间范围： powershell -c "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; (Get-Content -Encoding UTF8 'C:\Users\peter\youtube_VIDEO_ID_workspace\cleaned_transcript.json' -Raw | ConvertFrom-Json) | ? { $_.start -ge 1000 -and $_.start -le 1200 }"

---

泰语与拉丁字母混合文本清理（乱码外来词）

Whisper 对泰语的自动转录会将拉丁字母片段混入泰语词中，这是因为英语音素被转写为 ASCII 字符：อีเวent（event）、ยูทูer（YouTuber）、ทarเก็ต（target）、เซerกอร（Berserker）、อิบukิ（Ibuki）。这些内容会漏过 default_mappings.json（它只处理游戏标题），也是 ANIBON 直播中乱码的主要来源。

资源：规则存放在共享文件 resources/garbled_replacements.json（插件根目录）中，采用 Version 2 分组架构（mappings: { "CanonicalWord": ["pattern1", "pattern2"] }）。clean_garbled_english.py 会通过 resource_path() 自动加载该文件，而 update_garbled_dictionary.py 会同步根目录和技能目录中的副本。规则使用正则表达式和 re.IGNORECASE，按首次匹配生效；对于每个规范词，会优先尝试更长、更具体的模式。

直播转录文本仍显示混合词时的工作流

1. 检测：扫描转录文本中的 [\u0e00-\u0e7f]+[A-Za-z]{2,}（泰语字符串与拉丁字母尾部连在一起）。统计词元和唯一词元的数量。
2. 结合上下文解码：打印每个候选项前后各 60 个字符。正确形式是拉丁字母尾部所属的完整泰语词（อีเวent → อีเวนต์）。
3. 自动更新词典：运行 python3 scripts/update_garbled_dictionary.py --add "CanonicalWord" "pattern1" "pattern2"，或使用 --from-raw-dir ~/workspace/garbled_notes_raw/ --workspace ~/workspace 从笔记导入。
4. 绝不猜测专有名词：对于含义不明且只出现一次的名称（ดองซam、โinaa、โอเดet），在笔记中标记为未解决，并向用户询问正确形式，不要盲目添加正则规则（参见铁律）。
5. 验证：重新扫描，确认剩余的混合词仅为有意保留的英语外来词（FGO、NP、YouTube）或尚未确认的专有名词。

专有名词与真实标题保护关卡（强制执行）

1. 真实游戏／商标冲突检查：向 garbled_replacements.json 或 default_mappings.json 添加任何替换规则前，先确认候选模式是否为合法的独立游戏标题、商标或系列名称（例如 MARVEL Tōkon: Fighting Souls、Alien: Isolation、TMNT: The Last Ronin、Rayman Legends）。绝不可将真实游戏标题替换成 โทคุ 之类的通用词或角色名称。
2. 保护通用短语：绝不可将常见的英语会话短语（例如 where we meet、where meet、Rock One）注册为游戏标题（例如 Where Winds Meet、Roblox）的替换模式。
3. 避免对具体副标题进行过度映射：在 default_mappings.json 中，绝不可将常见泰语词或宽泛的名称词根（คอนโทรล、เฟย、until dawn）映射到特定视频副标题或未经确认的续作（Control: Resonant、God of War: Laufey、Until Dawn 2）。只使用基础标题（Control、Laufey、Until Dawn）。

反级联与事实依据交叉核验（强制要求）

1. 原始转录交叉核验：从分块内容或子 Agent 提取乱码笔记时，绝不可盲目信任清理后的文本。务必对照 raw_transcript.th-orig.json3 中的时间戳，确认原始 ASR 字符串。
2. 清理器伪影清除：如果候选乱码字符串中包含已知的多词英文游戏／动漫标题（例如 Yuri on Ice、Chaos Zero Nightmare、Where Winds Meet、SLAPP），且该标题嵌在泰文文本中（例如 pYuri on Iceshิ、SLAPPอย），则这是宽泛正则清理器碰撞产生的伪影。不要将多词标题保存为模式。应清理原始 ASR 形式（punishิ、สปอยล์）。
3. 防前缀破坏不变量（乱码词典防护）：
   • 绝不可将纯泰文前缀或截断的泰文词根（例如 โปรดักชั）注册为替换成英文单词（例如 Production）的模式。
   • 破坏风险：当干净的泰文外来词出现时（例如 โปรดักชั่น），匹配截断前缀会破坏自然的泰文构词，产生错误的混合词（例如 Production่น）。
   • 英文目标词允许使用的模式必须符合以下条件： a. 确实损坏的泰文与拉丁字母混合形式（例如 adดapt → Adapt、prชเชอร์ → เพรสเชอร์）。 b. 含义明确的完整泰文音译（例如 ไฟนอล → Final）。 c. 绝不可使用作为自然泰文词或外来词合法形态前缀的子串。
4. 防后缀与短子串碰撞不变量（乱码词典防护）：
   • 绝不可注册由常见泰文音节／后缀（例如 รถ、การ、ความ、ตัว、ผล、คน、ไป、มา）加一个拉丁字母，或加空格后再加一个拉丁字母（例如 รถ M、การ C、ตัว B）组成的未锚定模式。
   • 碰撞风险：在未分词的泰文文本中，常见泰文词（例如 สามารถ 或 ปรารถนา）后接英文外来词（例如 สามารถ Move on、ปรารถนา Make sense）时会匹配 รถ M。子串替换会破坏泰文词根，使其变成残缺片段（สามา<Replacement>ove on）。
   • 英文缩写或系列名称（例如 LoM、FGO、OPM）允许使用的模式必须符合以下条件： a. 使用完整的泰文音译（例如 ลอร์ดออฟมิสเตอรีส์、หลอด Mystery）。 b. 使用严格的正则词边界（例如 \bLord of My\b、\bLoM\b）。 c. 绝不可使用与拉丁字符粘连或空格相连的短泰文后缀。

本地音频片段 Whisper 验证（Metal GPU）与分镜依据

当无法根据转录上下文可靠地判断含义模糊的外来词、品牌名称或专有名词时：

1. 下载一次音频流： yt-dlp --remote-components ejs:github --cookies-from-browser chrome -f 249/ba "<URL>" -o "audio.opus"
2. 截取 15 秒的目标音频片段： ffmpeg -y -ss <START_SEC> -t 15 -i audio.opus -ar 16000 -ac 1 -c:a pcm_s16le slice.wav
3. 使用 whisper.cpp 在本地转录（通过 Apple Silicon Metal GPU 加速，每个片段约需 0.4 秒）： whisper-cli -m ggml-large-v3-turbo.bin -f slice.wav -l th -nt
4. 借助分镜帧进行视觉确认： 提取 storyboard.mhtml 幻灯片（frames/slides/slide_XXX.jpg），以视觉确认屏幕上的网页、拍卖目录、玩具展示或游戏画面。

---

与其他技能集成

启用摘要或时间戳技能时，请遵循以下步骤：

1. anibon-timestamper：
   • 必需子技能：运行时间戳脚本前，使用 cleaning-auto-transcripts 清理转录文件，以便稳定匹配关键词。
2. youtube-minutes-synthesis：
   • 必需子技能：将获取并清理转录的基础步骤切换为使用 clean_transcript.py（而不是原始的 fetch_transcript.py），以确保会议纪要报告不含转录噪声。

铁律

• 绝不修改原始时间戳：清理文本时，绝不编辑或调整原始转录中的 start 和 duration 字段。
• 先进行空格规范化：进行任何比较前，始终先进行空格规范化。不均匀的空格会破坏词语映射。
• 谨慎处理排除项：始终严格通过脚本中的 exclude_if_contains 系统管理重叠词排除项。
• 绝不使用 Python YouTube Transcript API：不要编写 python3 -c "from youtube_transcript_api import ..."，也不要安装额外依赖。使用标准原生 yt-dlp --write-auto-subs 获取转录。
• 不得覆盖真实标题或常见短语：绝不要将合法的外部游戏标题、系列名称或常见英语对话短语，映射为会被泰语词语或其他游戏名称覆盖的乱码模式。
• 询问用户并记录未知或不匹配的搜索词：如果你使用搜索工具查找陌生或失真的词语，但搜索结果似乎与口语上下文不符（例如，搜索 “Bฟet” 得到的是自助餐结果，但上下文讨论的是法律／继承），请停止搜索，并直接在聊天中询问用户。显示不匹配的词语、其准确时间戳，以及周围的转录句子／片段。用户澄清正确含义后，将修正后的语音映射保存到 default_mappings.json 或自定义映射中。
• 低上下文 AI 防护（上下文少于 8k）：如果你的上下文限制极其严格（例如 gemma4:31b 或 e2b），绝不要对转录或映射文件执行不受限制的搜索、预览或全文读取。必须严格限制输出，使用管道传给 head／Select-Object -First，在适用时添加 --limit 5，或将 dump 范围严格控制在 60 秒以内。完全依靠 Python 脚本进行全量处理，以保护上下文窗口。