cleaning-auto-transcripts

自動生成トランスクリプトのクリーニング

誤字、話者のアクセントによる逸脱、不正確な音訳を含む、YouTube の自動生成トランスクリプトを処理、取得、ノイズ除去するためのスキルです。誤ったテキストを正しい表記のデータベースと照合し、後続のコンテンツをクリーンで完全な状態にします。

使用するタイミング

• 要約やタイムスタンプ作成のために、YouTube の自動生成トランスクリプトをダウンロードするとき。
• 特定の配信者／話者向けのエラーマッピングファイル（Error Mapping）がすでに存在する場合。例：Pu Boat（FGO／ZZZ／ゲームの VOD）。
• 空白の正規化や、重複する用語の曖昧さを解消する必要があるとき。

** 母語 ** （例：「โรนิน」と「เบโรนินะครับ」の区別） ** 母語 **

---

厳守する手順ガイド

重要な指示：手順を省略することは禁止されています。このプロセスは、必ず順番どおりに実行してください。

ステップ 1：必須の環境確認

アクション：ファイルを操作する前に、ネイティブツールを実行して実行環境を確認します。

• Bash：echo $SHELL && uname -a && command -v yt-dlp && command -v python3
• Windows PowerShell：$PSVersionTable.PSVersion; Get-Command yt-dlp; Get-Command python 重要：シェルとツールを確認するまで、次に進むことは禁止されています。

ステップ 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

トランスクリプト操作（ネイティブなワンライナー）

重要なルール：JSON トランスクリプトの検索に、組み込みの grep や search ツールを使用しないでください。タイムスタンプが失われたり、「No files found」エラーが発生したりします。必ず、以下の 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 Grouped Schema（mappings: { "CanonicalWord": ["pattern1", "pattern2"] }）で記述されています。clean_garbled_english.py は resource_path() を使って自動的に読み込み、update_garbled_dictionary.py はルートとスキルの両方のコピーを同期します。ルールは正規表現で、re.IGNORECASE を使用し、最初に一致したものが適用されます。各 canonical word 内では、より長く具体的なパターンが先に試されます。

配信にまだ混在表記が見られる場合のワークフロー

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. 固有名詞を決して推測しない：1 回しか出現しない曖昧な名前（ดองซ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 Winds Meet、Roblox）の置換パターンとして、一般的な会話で使われる英語のフレーズ（例：where we meet、where meet、Rock One）を登録しないでください。
3. サブタイトルの過剰なマッピング：default_mappings.json では、一般的なタイ語の単語や広範なルート名（คอนโทรล、เฟย、until dawn）を、特定のビデオのサブタイトルや未確認の続編（Control: Resonant、God of War: Laufey、Until Dawn 2）にマッピングしないでください。基本タイトルのみを使用してください（Control、Laufey、Until Dawn）。

連鎖誤りの防止と正解データによる照合（必須）

1. 生の文字起こしとの照合：チャンクやサブエージェントから文字化けしたメモを抽出する場合、後処理済みテキストを決して鵜呑みにしないでください。必ず 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. 接尾辞および短い部分文字列の衝突防止不変条件（文字化け辞書のガード）：
   • 一般的なタイ語の音節／接尾辞（例：รถ、การ、ความ、ตัว、ผล、คน、ไป、มา）の後に、ラテン文字1文字、またはスペースとラテン文字1文字が続く、アンカーなしのパターンを登録しないでください（例：รถ 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：
   • 必須サブスキル：会議議事録レポートから文字起こしノイズを取り除くため、基本のクリーニング手順として fetch_transcript.py の生データではなく、clean_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 スクリプトに任せてください。