zimodzh/hls-dot0-to-mp4-skill

HLS .0 キャッシュ → MP4

Huaweiブラウザの嗅探ダウンロードは、各動画を暗号化HLSのUUIDフォルダとして保存し、すべてのファイル名に .0 を追加します。携帯電話のプレイヤーは独自のデータベースとこれらのファイル名を読み取りますが、PCのプレイヤーやFFmpegは読み取れません。

このスキルは、.ts.0 → .ts、.key.0 → .key へのハードリンクを作成し、元のプレイリストをFFmpeg（-c copy）に渡して変換した後、一時的な名前のみを削除することで、そのキャッシュを変換します。Huaweiブラウザのキャッシュで検証済み。他のベンダーは未検証です。

使用するタイミング

以下のいずれかに該当する場合にアクティブにしてください：

• フォルダ名が 64f1723d-421b-495c-8a10-85ab7d74ddab のような形式
• ファイル名が aq.m3u8.0、*.ts.0、*.key.0
• ユーザーが「嗅探下载」「华为浏览器」「VideoData」「携帯では再生できるがPCではできない」と言っている
• ログに行に DLEngine、DLSegMgr、download_content_ が含まれている

使用しない場合：m3u8 URLのダウンロード（その場合はN_m3u8DL-RE / 猫抓）、Widevine / PSSH DRM、または既にプレーンな .mp4 のリマックス。

レイアウト（ワークスペース検索は信頼しないでください）

Cursor / ripgrepはバイナリの *.0 ファイルをスキップします。Glob **/*.ts.0 は、73個のセグメントが存在しても0を返します。ディレクトリ一覧（Get-ChildItem / dir / Path.iterdir）を表示するか、プレイリスト名のパスを読み取る（バイナリ読み取りエラー = ファイル存在）ことでファイルを証明します。

各動画フォルダ：

<uuid>/
  aq.m3u8.0          # プレイリスト；foo.ts と foo.key を参照（.0 なし）
  <digits>.ts.0      # AES-128 MPEG-TS、約10秒ごと
  <digits>.key.0     # 16バイトHLSキー

オプションの兄弟ディレクトリ log/<uuid>.txt はDLEngineテキストであり、メディアではありません。

ツリーが異なる場合（キーがない、ネストされたディレクトリ、aq.m3u8.0 がない）は、references/layout.md を参照してください。

ワークフロー

ハードゲート — 変換またはダウンロードの前に必ず実行してください。

0. ffmpegを見つけるか、停止して尋ねる

制限付き検索のみ（ドライブ全体を再帰的に検索しない）。scripts/convert.py も同じ順序を使用します：

1. --ffmpeg / 環境変数 HLS_DOT0_FFMPEG
2. <cache-root>/ffmpeg.exe または <cache-root>/ffmpeg
3. PATH（where.exe ffmpeg / command -v ffmpeg）
4. まだ見つからない場合、いくつかの一般的なディレクトリ：%LOCALAPPDATA%\Microsoft\WinGet\Links\ffmpeg.exe、%USERPROFILE%\scoop\shims\ffmpeg.exe、C:\ffmpeg\bin\ffmpeg.exe、/opt/homebrew/bin/ffmpeg、/usr/local/bin/ffmpeg

ffmpeg -version（またはその絶対パス）を実行します。成功 → ステップ1に進みます。

見つからない場合は停止します。ユーザーに以下の2つのオプションを正確に尋ねてください。ユーザーが回答するまで、インストールや変換を行わないでください：

• A. ユーザーが自分でffmpegをインストールまたは配置し、準備ができたらその旨を伝える — 再度この検索 + -version を実行します。
• B. あなたがインストールする — まずOSとアーキテクチャを検出します（win32 + PROCESSOR_ARCHITECTURE / uname -s + uname -m）。次に、references/ffmpeg-install.md の一致するデフォルトのみに従います。

インストールルール：1つのデフォルトコマンド、失敗した場合の1つのフォールバック、その後再度尋ねます。ユーザーが同意しない限り、ffmpegを入手するためだけにHomebrew / Chocolatey / Scoopをインストールしないでください。ダウンロードしたバイナリをこのスキルリポジトリにコミットしないでください。インストールが成功したら、新しいシェルまたはインストーラのパスを介して-versionを検証します（WindowsのPATHはしばしば古いままです）。

1. 計画（表示してから変換）

UUIDディレクトリ（8-4-4-4-12の16進数）を一覧表示します。それぞれについて、*.ts.0、*.key.0の数をカウントし、aq.m3u8.0が存在するかどうかを確認します。セグメントが0個またはキーがないフォルダはスキップします。

デフォルトの順序：フォルダ名A–Z。--out-dir（デフォルト <cache-root>/mp4）に、--start（デフォルト1）からの番号で出力 01.mp4、02.mp4、… を生成します。スクリプトは、そのmp4が既に存在する場合、その名前をスキップします（JSON skipped: true）。--force が指定されていない限り。部分的なバッチの後に同じコマンドを再実行しても、既に完了した番号はそのまま残り、残りが変換されます。2つ目の番号付けスキームを考案しないでください。

2. バンドルされたスクリプトを実行する（再発明しない）

このスキルのルートから：

python scripts/convert.py --root <cache-root> --dry-run
python scripts/convert.py --root <cache-root> --out-dir <cache-root>/mp4 --start 1
python scripts/convert.py --root <cache-root> --folder <uuid> --name 01 --force

新しいツリーでは常に最初に --dry-run を渡します。スクリプトの標準出力はJSONです。進捗は標準エラー出力に出力されます。

しないこと: プレイリストを *.ts.0 に書き換える。FFmpegは -allowed_extensions ALL を使用してもその拡張子を拒否します（not in allowed_segment_extensions）。aq.m3u8.0 内の名前へのハードリンク/コピーを実行してください。

しないこと: PowerShell $ErrorActionPreference = "Stop" と ffmpeg -i file -f null - を使用して出力をプローブする。FFmpegはバナーを標準エラー出力に書き込みます。PowerShellはそれを終了エラーとして扱い、mp4を削除する catch が成功した変換を消去します。

正確なFFmpegフラグ（壊れやすい — 削除しないでください）：

ffmpeg -y -hide_banner -loglevel warning -stats -allowed_extensions ALL -protocol_whitelist file,crypto,data -i play.m3u8 -c copy out.mp4

3. クリーンアップとレポート

スクリプトは、この実行で作成した一時的な名前のみを削除します（既に.0ファイルを指している残りのハードリンクも含む）。また、常に play.m3u8 を削除します。元の *.ts.0 / *.key.0 / aq.m3u8.0 はそのまま残ります。.0ファイルへのハードリンクではない、既存の .ts / .key は削除しません。

表を報告します：番号、サイズ、既知の場合は長さ、sps_warning。SPSおよびその他の障害については、references/troubleshooting.md を参照してください。

ユーザーがSPS警告のあるファイルの再エンコードを要求した場合：ffmpeg -i 04.mp4 -c:v libx264 -crf 18 -c:a copy 04_fixed.mp4 — バッチ全体ではなく、それらのファイルのみ。

チェックリスト

• ディレクトリ一覧に .ts.0 と .key.0 が表示されている（検索ツールが嘘をつく可能性があります）
• ffmpegが見つかった（制限付き検索）か、ユーザーがA/Bを選択した。-version がOK。全ディスクスキャンなし
• インストールする場合：OS/アーキテクチャを検出。references/ffmpeg-install.md 内の一致するコマンドのみを使用
• --dry-run 計画が正しい（カウント、出力名、既存mp4の SKIP）
• 1つのフォルダが変換され、ユーザーが再生できる（すべて変換するように言われていない限り）
• バッチJSONで ok / skipped / アイテムごとのエラー。一時的なリンクは削除されている
• SPS警告の番号に言及し、ユーザーがスポットチェックできるようにする

出力形式

N/M 個の動画を変換しました → <out-dir>
01.mp4  101 MB  (~12:10)  ok
04.mp4  251 MB  (~23:59)  SPS warning — 開始部分と約10秒のカットを確認してください
FAIL  <uuid>  missing key.0

注意点

• .0 が実際のメディアです。 バイナリをスキップするGlob/インデックスは「ファイルがない」ことを意味しません。
• プレイリスト URI="….key" と ….ts — ディスク上では ….key.0 / ….ts.0 です。
• ハードリンクは同じボリューム上にある必要があります。os.link が失敗した場合はコピー（遅い、余分なディスク使用）してください。
• non-existing SPS 0 referenced in buffering period は通常、-c copy では表面的なものです。10秒境界を確認してください。再生が壊れている場合のみ再エンコードしてください。
• GUIツール（N_m3u8DL-RE、m3u8-to-mp4）は標準的な拡張子を期待します。これらは名前の変更/ハードリンク後に機能し、生のHuawei名では機能しません。
• これはローカルキーを使用した標準的なHLS AES-128です（DLEngineログに no pssh）。Widevine回避ではありません。
• ffmpegがない → まずA/Bを尋ねてください。 無言で winget/brew/apt を実行したり、exeをダウンロードしたりしないでください。
• 既存の 01.mp4… はスキップされ、エラーではありません。ユーザーがそれらのファイルを上書きしたい場合にのみ --force を使用してください。