video-downloader

動画ダウンローダー 2.0

境界

このスキルは、メディアの前処理ワークフロー全体を担当します。

video link or local file
→ acquire video and platform caption
→ usable timed platform subtitles, otherwise cloud ASR
→ choose keyframes / full-video / Agent clips
→ preview and confirm each exact cloud payload
→ Doubao image or native-video understanding
→ timestamped plain Markdown

最終的な受け渡し対象は、通常のテキストファイルである multimodal_transcript.md です。Cangjie Skill は変更せず、テキストを消費してスキルを生成するだけです。ダウンロード、ASR、フレーム、OCR、または視覚モデルのロジックを Cangjie Skill に移さないでください。

要件

メディアを扱う際に必要なもの：

• Python 3.10 以降。
• ffmpeg および ffprobe。
• Bilibili、YouTube、Xiaohongshu 用の yt-dlp。一部のプラットフォームではフォールバックとしても使用します。

任意：

• クラウド ASR 用の SILICONFLOW_API_KEY。
• オフライン ASR 用のローカル whisper CLI。
• Doubao の視覚理解用の ARK_API_KEY。
• WeChat Channels の初回の対話型認証用の Playwright。

速度の既定値と品質のトレードオフ

• Bilibili、YouTube、Xiaohongshu では 正確に 1080p（--download-quality 1080p）を優先します。利用できない場合は、4K であっても利用可能な最高画質をダウンロードします。これは解像度の上限ではありません。ダウンロードしたファイル名には画質の優先設定が含まれるため、古い 4K ファイルが新たに取得した 1080p ファイルに見せかけることはありません。他のプロバイダーでは、プロバイダー固有の画質設定が引き続き適用されます。
• WeChat Channels では、実行のたびにリンクプロファイルと有効期限付きの再生 URL が更新されますが、既存の保存先 MP4 を再利用するのはメディアプローブに合格した場合のみです。プラットフォーム上のメディア自体を更新する必要がある場合は、--force-redownload を使用してください。--force-reprocess は引き続き ASR／視覚分析結果のキャッシュを迂回する意味であり、メディアのダウンロードを行うものではありません。
• --asr auto は、利用可能な時間情報付きのプラットフォーム字幕を優先します（人手による字幕が自動字幕より優先されます）。字幕がない場合は SiliconFlow を使用します。自動字幕も ASR も誤る可能性があり、どちらかがすべての動画で本質的に最も正確というわけではありません。音声を新たに文字起こしするには、--no-platform-subtitles または --asr siliconflow を使用してください。
• クラウド ASR は約 60 秒のチャンクを使用し、可能な場合は無音部分付近で区切り、音声時間をすべて保持しながら、同時に実行するリクエストを最大 4 件に制限します。これは音声認識のチャンクであり、10 分間の視覚チャンク制限ではありません。
• エージェントのシーン検出は 384px／4fps で音声処理と並行して実行され、キャッシュされます。これは大まかな選択を補助するものであり、OCR 入力や完全なショット一覧ではありません。
• CLI のネイティブ動画の同時実行数は、既定で 4 です。準備済みクリップでは、最大 720p、エンコード時 12fps、高速エンコード、圧縮音声を使用します。プロバイダーのサンプリングは既定で 0.5fps のままです。小さな文字や素早く切り替わる MV のカットでは、より高いサンプリングレートや専用のキーフレームが必要になる場合があります。
• --vision-thinking disabled を指定すると、エージェントによる選択とネイティブ動画分析で、深い推論による遅延を回避できます。auto または enabled を明示的に指定することもできます。これはキーフレーム画像リクエストには影響しません。動画リクエストの出力トークン数は最大 16,384 です。不完全な応答は失敗とみなされ、完了した結果としては使用できません。
• 進捗状況には各処理段階と各クラウドチャンクが表示されます。timings.json には実際の経過時間と、実行が 600 秒の目標を達成したかどうかが記録されます。重複する処理段階の時間を単純に合計しないでください。10 分はテスト上の目標であり、任意の動画の長さ、ネットワーク、API キューに対する保証ではありません。
• エージェントによる選択では、広告の繰り返しよりも、異なる手法やデモンストレーションを優先します。初期プランでソース時間の一部が未選択のままの場合、同じソース素材を使って、テキストモデルへの追加リクエストを 1 回行い、見落としを確認します。確認済みのプランはキャッシュされます。最終的な Markdown には、選択されなかった視覚範囲が記載されます。選択した時間のカバー率は、情報の正確さや網羅性を示すものではありません。
• 選択への入力には、生の start_ms/end_ms を指定して時間変換の誤りを減らします。冒頭／末尾のフォールバック用センチネルは通常の候補数に含まれません。そのため、チャンク分割とセンチネルによって、実行ファイル数が --vision-max-clips を超える場合があります。正の値で明示された合計時間の上限は引き続き適用されます。
• トランスクリプトのキューは、数値のミリ秒を含む JSON 行としてシリアライズされます。初回および確認時の各テキストリクエストでは、JSON の形式が不正な場合、厳密な形式を指示して 1 回再試行できます。再試行しても失敗した場合は、選択を停止します。この制限付きの形式再試行は見落としの確認とは別であり、切り詰められた応答を黙って受け入れることはありません。
• 無効なタイムスタンプまたは時間基準を含むネイティブ動画の完了済み応答は、既存のクラウドファイルと明示的な相対範囲を使って、最大 1 回再観測します。ファイルは再アップロードされず、タイムスタンプが黙って範囲内に丸められることもありません。2 回目の無効な回答も失敗となります。600 秒の合格フラグが付くには、処理が完了し、かつ経過時間が目標以内である必要があります。

macOS の場合：

brew install ffmpeg yt-dlp
python3 -m pip install playwright

Playwright は、インストール済みの Google Chrome を再利用できます。Chrome を利用できない場合：

python3 -m playwright install chromium

Doubao Vision を設定する

ビジュアルプロバイダーは Volcano Ark Responses API と Files API を使用します。

• Responses エンドポイント：https://ark.cn-beijing.volces.com/api/v3/responses
• Files エンドポイント：https://ark.cn-beijing.volces.com/api/v3/files
• 画像／テキストモデル：キーフレームと Agent によるテキスト選択に使用する --vision-model。デフォルトは doubao-seed-evolving です。
• ネイティブ動画モデル：動画全体および選択したクリップの分析にのみ使用する --vision-video-model。2026-08-30 に機密情報を含まない合成動画でのスモークテストが成功したことを受け、デフォルトは doubao-seed-evolving です。
• 認証情報：環境変数 ARK_API_KEY

現在のターミナルでキーを設定します。

export ARK_API_KEY="replace-with-your-new-key"

実際のキーを SKILL.md、ソースコード、Git にコミットするコマンド、テストフィクスチャ、スクリーンショット、metadata.json に記載しないでください。

このスキルで使用する最小限の API 形式：

curl https://ark.cn-beijing.volces.com/api/v3/responses \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-evolving",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_image", "image_url": "https://example.com/frame.jpg"},
        {"type": "input_text", "text": "请描述画面中的可见事实和屏幕文字。"}
      ]
    }]
  }'

ローカルのキーフレームは Base64 データ URL として送信されます。このスキルは正規化された観測結果を保存し、プロバイダーの応答全体は保存しません。

動画全体および Agent が選択したクリップの分析では、このスキルはアップロードに適した H.264 MP4 を作成し、ソースに音声が含まれる場合は圧縮 AAC 音声トラックを保持します。準備したファイルを purpose=user_data でアップロードし、Files API のステータスが active になるまで待ってから、input_video + file_id を Responses API に送信します。アップロードしたファイルは finally で可能な限り削除されます。削除に失敗した場合は、クリーンアップが成功したものとして扱わず、その旨を報告します。埋め込み音声の理解は設定された動画モデルに依存するため、ネイティブ動画分析は ASR を補完するものであり、置き換えるものではありません。

このワークフローに関連する Files API の公式制限：

• Ark のマネージドストレージでは、各ファイルの上限は 512 MB です。この実装では、動画全体のプロキシをより厳しいローカル安全上限の 480 MB 未満に保ち、動画データをメモリにすべて読み込まずにマルチパート形式でストリーミングし、上限を超えるプロキシはアップロードせずに処理を停止します。現在、上限を超える動画全体のプロキシを自動的に分割する機能はありません。
• 小文字の拡張子を使用する場合、MP4、AVI、MOV がサポートされます。ただし、コンテナがサポートされていても、内部のすべてのコーデック形式が認識されるとは限りません。
• URL または Base64 による動画入力には、動画ごとに別途 50 MB の上限があります。このスキルでは、代わりに準備済みの動画に Files API を使用します。
• 動画の前処理における fps は 0.2～5 です。--vision-video-fps 0.5 は、Files API がモデル入力用に約 2 秒ごとに 1 フレームをサンプリングすることを意味します。これはプロキシのエンコード時のフレームレートではなく、フレーム単位の分析でもありません。
• 有効期限を明示せずにアップロードしたファイルは、デフォルトで 7 日間保持されます。保持期間は 1～30 日に設定できます。このスキルは expire_at を設定しません。分析後すぐに削除を試みますが、削除に失敗すると、有効期限が切れるまでファイルがマネージドストレージに残ることがあります。
• プロバイダーは、1 本の動画につき 80k 動画トークンを上限としてドキュメントに記載しています。設定されたモデルのコンテキスト上限や入力上限は、これより低い場合があります。公式に定められた一律の「最大分数」はないため、長い動画や変化の速い動画では、前処理の fps を下げるか、Agent が選択したクリップを使用する必要がある場合があります。

プロトコルのリファレンス：

• Volcano Ark の動画理解
• Volcano VEADK Responses API と Files API
• 公式 Python SDK の ResponseInputVideoParam

提供された API キーがリポジトリ、アップロード計画、メタデータ、ログ、Markdown 出力に書き込まれることはありません。キーをチャットやドキュメントに貼り付けたことがある場合は、Volcano Ark でキーをローテーションし、新しいキーのみを ARK_API_KEY に保存してください。

クイックスタート

このスキルのディレクトリから実行します。

ASR と Doubao のビジョン機能を使うプラットフォーム URL：

python3 scripts/download_video.py "https://www.youtube.com/watch?v=..." \
  --output-dir ./downloads \
  --asr auto \
  --vision auto \
  --vision-mode agent-clips \
  --profile knowledge

信頼できるタイムスタンプ付き ASR がある場合、この対話型コマンドでは、クラウドに送信する 2 つの範囲を個別にプレビューして確認します。まず、エージェントの選択に使うタイムスタンプ付き文字起こし、プラットフォームの字幕、シーンのインデックスを確認し、次に選択された動画クリップを正確に確認します。信頼できるタイムスタンプ付き文字起こしがない場合、選択はローカルのシーン情報にフォールバックし、確認が必要なのはクリップのアップロードだけです。自動化では、--confirm-cloud-upload は、その実行におけるすべての Doubao の処理段階に対する、最初に行う 1 回の許可です。個別に人が 2 回確認するものではありません。

--vision-plan-only は Doubao のビジュアルリクエストのみをブロックします。SILICONFLOW_API_KEY が設定されている場合、--asr auto はすでに音声を SiliconFlow に送信している可能性があります。計画の実行全体をローカルで完結させる必要がある場合は、--asr whisper または --asr none を使用してください。

ローカル動画：

python3 scripts/download_video.py "/absolute/path/demo.mp4" \
  --output-dir ./downloads \
  --local-caption "产品演示" \
  --local-author "作者名" \
  --asr auto \
  --vision doubao \
  --vision-mode keyframes \
  --profile tech

プラットフォームのテキストとメタデータのみをダウンロードします：

python3 scripts/download_video.py "https://v.douyin.com/..." \
  --output-dir ./downloads \
  --metadata-only

どちらかの処理をスキップします：

python3 scripts/download_video.py "/absolute/path/video.mp4" \
  --asr none \
  --vision doubao \
  --vision-mode keyframes
python3 scripts/download_video.py "/absolute/path/video.mp4" --vision none
python3 scripts/download_video.py "/absolute/path/video.mp4" --asr none --vision none

ビジュアルモードを選択する

ビジュアル分析を有効にする場合、ユーザーは 1 つのモードを選択する必要があります。スキルが、何をマシンの外部に送信するかを暗黙に決めてはなりません。

モード	送信される内容	強み	制限事項
keyframes	シーン／間隔を組み合わせた JPEG キーフレーム	トークン使用量とコストが最小	動きやサンプリングされていない情報を見落とす可能性があります
full-video	最大 10 分のチャンクに分割された、圧縮済みの 720p 動画	ソース全体をカバーします	入力量が増え、圧縮によって小さな文字が失われる可能性があります
agent-clips	選択用のタイムスタンプ付きテキスト、その後に範囲を限定した MP4 クリップ	バランスの取れた方法として推奨	クラウドでの処理が 2 段階必要で、Agent による実際の選択には信頼できるタイムスタンプ付き ASR が必要です

対話型ターミナルでは、--vision-mode を省略すると 3 つの選択肢を示すメニューが開き、agent-clips が推奨されます。非対話型の実行では、省略すると終了コード 2 で終了します。--metadata-only と --vision none は引き続き対象外です。

keyframes と full-video では、Doubao にリクエストを送信する前に vision_plan.json を書き込み、表示します。agent-clips では、最初に vision_selection_plan.json を書き込みます。選択とローカルでの切り出しが完了した後に限り、正確なクリップのパス、サイズ、長さを含む第 2 段階の vision_plan.json を書き込めます。ユーザーが y と回答するか、自動化で --confirm-cloud-upload をすべての Doubao 処理段階に対する最初の許可として渡すまでは、Doubao へのリクエストは発生しません。

--vision-plan-only を使うと、現在ローカルで実行可能なすべてのビジュアルアーティファクトを準備し、Doubao へのリクエストを送信する前に終了します。Agent モードでは、クラウドでのテキスト選択が必要な場合は vision_selection_plan.json の作成時点で終了するため、第 2 段階の正確なクリップ計画を事前に表示できません。使用可能なタイムスタンプ付きテキストがない場合は、ローカルのシーンフォールバックで候補を切り出し、終了前に第 2 段階の正確な vision_plan.json を書き込めます。このフラグは、先行する SiliconFlow ASR リクエストを無効にしません。計画の実行をローカルで完結させるには、ローカルの Whisper を選択するか、ASR を無効にしてください。

1. キーフレーム

python3 scripts/download_video.py "/absolute/path/video.mp4" \
  --asr none \
  --vision doubao \
  --vision-mode keyframes \
  --vision-plan-only

このモードでは、シーンの変化を検出し、固定間隔でのカバレッジを追加して、近接するタイムスタンプを統合し、最終セットの上限を設定します。確認後にのみ、小さな画像バッチを送信します。

2. 動画全体

python3 scripts/download_video.py "/absolute/path/video.mp4" \
  --asr none \
  --vision doubao \
  --vision-mode full-video \
  --vision-video-model doubao-seed-evolving \
  --vision-video-fps 0.5 \
  --vision-plan-only

このスキルは、元のファイルをアップロードせずに H.264/AAC 動画を準備します。--vision-max-clip-seconds（デフォルトは 600）より長いソースは、vision/clips/ の下に連続したチャンクとして直接切り出されます。25 分の動画は、10 + 10 + 5 分に分割されます。full-video モードには、動画全体の長さや Agent 候補の上限はありません。より短いソースには、最大 1280×720、エンコード時のフレームレート 12 fps で vision/full-video-proxy.mp4 が使用されます。どちらの方法でも --vision-concurrency（CLI のデフォルトは 4）、チャンクごとのチェックポイント、ソースの順序でのマージを使用します。計画には、準備されたすべてのファイルと実際のサイズ／長さが記載されます。有効なキャッシュ結果は再利用され、再アップロードされません。--vision-video-fps 0.5 はプロバイダー側のサンプリングを制御するものであり、エンコードを制御するものではありません。短いソースのプロキシには引き続き 480 MB のローカル上限が適用され、準備されたクリップには Files API のサイズチェックが適用されます。

3. エージェントクリップ（推奨）

python3 scripts/download_video.py "/absolute/path/video.mp4" \
  --asr auto \
  --asr-language Chinese \
  --vision doubao \
  --vision-mode agent-clips \
  --vision-max-clips 8 \
  --vision-max-clip-seconds 600 \
  --vision-max-total-clip-seconds 0 \
  --vision-concurrency 4 \
  --vision-clip-padding-seconds 2

選択モデルには、タイムスタンプ付きの完全な文字起こし、プラットフォームのキャプション、再生時間、シーンのタイムスタンプが渡されます。音声だけでなく、無音のデモ／Bロールや冒頭・末尾の文脈も考慮する必要があります。返された範囲は検証され、範囲内に収められ、パディングされて統合されます。--vision-max-clips 8 は分割前の候補区間数を制限するものであり、実行チャンク数を制限するものではありません。デフォルトの --vision-max-total-clip-seconds 0 では合計時間の上限は設けられません。選択された時間はすべて、最大600秒のチャンクに分割されるため、25分の区間は10 + 10 + 5に、95分の区間は10チャンクになる場合があります。正の合計予算を明示すると、選択範囲が切り詰められることがあります。省略された範囲は、失われた末尾部分も含め、警告と最終的なMarkdownで報告されます。準備された各クリップでは、ソースに音声が含まれている場合、AACが保持されます。

2つ目のプレビューには、ネイティブ動画分析の前に、これらのクリップがそのまま表示されます。複数のクリップは、CLIのデフォルトである最大4並列で分析されます。進捗は [current/total] として表示され、結果はソースの順序に戻されます。また、各クリップはそれぞれ独立してクラウドにアップロードされ、分析後に削除されます。順次処理するには --vision-concurrency 1 を、アカウントのレート制限に余裕がある場合は最大 4 を指定します。--vision-video-fps は、クリップのエンコードやフレーム単位の検査ではなく、各クリップに対するプロバイダー側のフレームサンプリングを制御します。

進捗では、アップロード／前処理、モデル分析、受信したレコード数、クリーンアップが区別されます。[i/total] は処理済み数ではなく、クリップ番号を示します。クリップ1より先にクリップ2の処理が完了することもあります。モデルがセグメントを順不同で返した場合でも、最終レコードは元の動画のタイムスタンプ順に並べられます。プロバイダーの応答で不完全と明示された場合、解析可能なJSONが含まれていてもエラーとして報告されます。

ネイティブ動画プロンプトでは、短い要約ではなく、操作やショット単位の根拠を求めます。関連するボタン、パラメーター、ファイル名、画面に表示されたコマンド、操作前後のUI状態などが対象です。音声だけの情報を、画面上で確認できる根拠として提示してはいけません。また、判読できないテキストを推測してはいけません。10分は設定可能な処理上限であり、精度が保証されるしきい値ではありません。情報量の多い録画で実際に確認した際に詳細の欠落が見つかった場合は、--vision-max-clip-seconds をより小さくしてください。出力レコード数だけから精度を推測してはいけません。並列処理のテストとして動画を2つに分割する方法は手動の検証戦略であり、エージェントがその境界を選択したことを示す根拠にはなりません。

ASRが要求されているものの、処理中または失敗している場合、エージェントモードは完全な音声トラックが得られるまで待機し、映像クリップの選択やアップロードは行いません。同じ設定で再実行すると、成功済みのASRチャンクを再利用して処理を続行できます。これにより、一時的なASRエラーによって不要なシーンのみのクラウド処理が発生するのを防ぎます。ユーザーが明示的に --asr none を選択した場合、または完了した文字起こしにセグメントのタイムスタンプが実際に含まれていない場合は、シーン変更の候補と冒頭・末尾のセンチネルにフォールバックできます。その場合は selection_method: scene-fallback が記録されます。タイムスタンプのないテキストをエージェントが動画に対応付けたかのように扱うことはありません。

便利な設定：

--vision auto|doubao|none
--vision-mode keyframes|full-video|agent-clips
--vision-plan-only
--confirm-cloud-upload
--vision-model doubao-seed-evolving
--vision-video-model doubao-seed-evolving
--vision-video-fps 0.5
--vision-frame-interval 10
--vision-max-frames 24
--vision-scene-threshold 0.32
--vision-batch-size 4
--vision-max-clips 8
--vision-max-clip-seconds 600
--vision-max-total-clip-seconds 0
--vision-concurrency 4
--vision-clip-padding-seconds 2
--vision-prompt "额外关注……"
--force-reprocess

ARK_API_KEY が設定されていなくても、実行可能なローカル準備は完了します。キーフレームや動画全体のプロキシを作成でき、エージェントモードでは、少なくとも選択プランや、該当する場合はシーンベースのフォールバック素材を作成できます。ビジョンのステータスは partial になり、クラウドでの映像分析に成功したかのように装うのではなく、Markdownで情報が不足していることを報告します。

プロファイル

次から1つ選択します。

プロファイル	視覚的な注目点
knowledge	フレームワーク、スライド、グラフ、例、教育用デモ
tech	UI の状態、ボタン、パラメーター、コード、エラー、変更前後の結果
vlog	場所、行動、A ロール／B ロール、感情、環境、トランジション
mv	パフォーマンス、色、構図、モチーフ、カメラの動き、リズムの手がかり
short-video	冒頭のフック、字幕のリズム、意外な展開、CTA、ショット密度

1本の動画から目に見える制作パターンを把握することはできますが、目に見えない裏側のワークフローを証明することはできません。推測に基づくワークフローの主張は、すべて仮説として扱ってください。クリエイターのスタイルを分析する場合、繰り返し見られる手法を説明する前に、少なくとも3本、できれば5～10本の動画を使用してください。

出力仕様

完成したフォルダーには、次のファイルが含まれる場合があります。

downloads/<platform>-<id>/
├── video.mp4
├── post_caption.txt
├── metadata.json
├── audio.mp3 or audio.m4a
├── transcript.txt
├── transcript.segments.jsonl
├── frames/
│   └── kf-0001-0000003500.jpg
├── frames.jsonl
├── visual_notes.jsonl
├── vision_plan.json
├── vision_selection_plan.json     # Agent mode
├── clip_selection.json            # Agent mode
├── vision/
│   ├── full-video-proxy.mp4       # Complete-video mode
│   ├── full-video-proxy.manifest.json
│   ├── clips/*.mp4                # Agent mode
│   └── clips/*.manifest.json      # Source/cache identity
└── multimodal_transcript.md

主なファイル：

• post_caption.txt：元のプラットフォーム上のタイトル、説明、ハッシュタグ、またはユーザーが提供したローカルのキャプション。
• transcript.txt：音声のみのプレーンテキスト書き起こし。
• transcript.segments.jsonl：ASR バックエンドがセグメントを提供する場合に正規化されたセグメントのタイムスタンプ。
• platform_subtitles.json：取得したプラットフォームの字幕テキスト、実際の字幕キュー時刻、言語、人間によるものか自動生成かを示す情報。
• timings.json：各ステージの実行時間、視覚関連サブステージの測定値、600秒の目標に対する結果。
• frames.jsonl：キーフレームのタイムスタンプとサンプリング理由。
• visual_notes.jsonl：目に見える事実、画面上のテキスト、動作、ショットのメモ、明確に区別された推論。
• vision_plan.json：視覚データのアップロードに関するファイル／データ型、バイト数、メディアの秒数、モデル、制限、同意、実行状況の詳細。
• vision_selection_plan.json：エージェントによる選択用の、第1段階における文字起こし／キャプション／シーンインデックスのアップロード計画。
• clip_selection.json：検証済みの範囲、理由、シーンのシグナル、フォールバック状態、ローカルのクリップパス。
• *.manifest.json：同じパスにあるソースファイルが変更された後に、古いプロキシ／クリップを再利用しないようにするためのソースフィンガープリントとエンコーディングパラメーター。
• multimodal_transcript.md：後続の分析または Cangjie Skill に渡すための最終的なプレーンテキスト。

区間にわたる動画の観察結果については、対応する Markdown の発話部分に、時間が重なる ASR セグメントがすべて時系列順で含まれます。単一画像の観察結果は、点ベースの対応付けを維持します。音声の完全な書き起こしも別途保存されます。

ASR

--asr auto は、まず利用可能なプラットフォームの字幕トラックを使用し、次に有効な ASR チェックポイントを使用し、その後、設定されている場合は SiliconFlow を使用します。CLI は、認証情報がない場合やクラウド ASR が失敗した場合に、ローカル Whisper を暗黙に起動することはありません。SILICONFLOW_API_KEY を設定するか、--asr whisper を明示的に選択するか、--allow-local-asr-fallback を指定してください。音声トラックの処理が保留中または失敗している場合、映像分析が成功していても、完全な文字起こしとして説明してはなりません。クラウド固有のモデル名が Whisper base にマッピングされるのは、ローカルへのフォールバックが明示的に許可されている場合のみです。認識された Whisper のモデル名はそのまま保持されます。--asr siliconflow を明示した場合、プロバイダーは切り替わりません。

ここでいう「プラットフォーム ASR」とは、既存の字幕または文字起こし結果を意味し、別の認識技術ではありません。SiliconFlow と Whisper も ASR です。デフォルトの優先順位は、既存のプラットフォームの文字起こし → SiliconFlow → ユーザーが承認したローカル Whisper（最も低速）です。CLI も公開関数 run_asr も、ローカルへのフォールバックを暗黙に選択することはありません。

使用可能な文字起こし結果がなく、キーもない場合、対話型 CLI はユーザーに選択を求めます。（1）エコーされない形式で SiliconFlow のキーを入力する、または（2）ローカル Whisper を実行する、のいずれかです。非対話型の実行では、終了コード 3 とともに pending、action_required: choose_asr_backend、および両方の選択肢を返します。映像に関するリクエストや不要なシーンスキャンは開始しません。呼び出し元のエージェントはユーザーに選択を求めてから処理を再開する必要があります。Whisper を暗黙に選択したり、音声を省略したり、処理完了を主張したりしてはなりません。 キーが拒否または期限切れになった場合や、その他のクラウドエラーが発生した場合は、その内容を報告してください。明示的な許可なしに Whisper に切り替えてはなりません。オプトインの --allow-local-asr-fallback は、デフォルトではなく、引き続き明示的な許可として扱われます。

SiliconFlow の永続的な設定

CLI は、環境にすでに存在する空でない SILICONFLOW_API_KEY をそのまま保持します。それ以外の場合は、~/.config/kangarooking-skills/video-downloader/env から文字どおりの変数を読み込みます（ファイルの必須モードは 0600、親ディレクトリの推奨モードは 0700）。これにより、シェルの起動ファイルを読み込まないデスクトッププロセスでも利用できます。Python ローダーはシェルの内容を実行しません。所有者のマシンでは、新しい zsh シェルが .zshenv 経由でこのプライベートファイルを読み込みます。すでに実行中のシェルプロセスでは、ファイルの読み込みまたは再起動が必要になる場合があります。このプライベートファイルを Skill、Git、ログ、テスト成果物にコピーしてはなりません。対話形式での入力は現在の実行にのみ反映されます。永続化にはユーザーの依頼が必要です。

指定モデルは FunAudioLLM/SenseVoiceSmall です。2026-09-07 に確認したところ、公式の料金ページでは無料と記載されています。無料であっても、スループットが無制限であることや、レイテンシが保証されることを意味するものではありません。有料モデルや Pro モデルに暗黙に置き換えてはなりません。--asr-model base は、SiliconFlow ではこのモデルにマッピングされる互換性用のエイリアスであり、Whisper base の実行を要求するものではありません。

再開とキャッシュ

通常の CLI 再実行では、ソースフィンガープリント、要求されたバックエンド／モデル、言語、プロンプト、任意の長さ制限を使って、ASR のテキスト／タイムスタンプが再利用されます。テキスト／raw JSON／セグメントのアーティファクトのチェックサムは、再利用前に検証されます。ソースまたは文字起こしの設定を変更した場合、ファイルが存在しない場合、またはテキストが破損している場合は、再処理されます。--asr none を指定すると、そのトラックが明示的に無効になります。再利用するには、同じ ASR 設定を使用してください。

エージェントによるテキスト選択は、選択プロンプト全体とモデルに基づいてキャッシュされ、その後、現在のチャンク設定で再度正規化されます。動画全体およびエージェントのネイティブ動画の結果は、各チャンクの処理とクラウドのクリーンアップが成功するたびに、アトミックにチェックポイントへ保存されます。キャッシュキーには、準備済みファイルのフィンガープリント、時間コンテキスト、プロファイル／プロンプト、モデル、サンプリング fps が含まれます。失敗したチャンクはキャッシュされません。再実行時には、成功したチャンクを再利用し、未処理または失敗したチャンクを再試行します。--force-reprocess は ASR、選択、ネイティブ動画の結果キャッシュを無効にします。メディアのプロキシ／クリップのフィンガープリントによる安全なエンコードの再利用は引き続き可能です。キーフレーム分析では現在、画像のバッチが毎回再処理され、ネイティブ動画のチェックポイントキャッシュの対象にはなりません。

キャッシュの保存先には、asr-cache/、asr-chunks/、vision/scene-cache/、vision/selection-cache/、vision/analysis-cache/ があります。ネイティブ動画のチェックポイントには、正規化された応答テキスト、プロバイダーの使用状況、アップロード／モデルの処理時間が含まれますが、クラウドのファイル ID や認証情報は含まれません。キャッシュの識別情報には推論設定が含まれます。ASR の識別情報にはチャンク設定とクラウドの利用可否も含まれるため、新たに設定したクラウド ASR が、以前のローカルフォールバックを誤って再利用することはありません。プレビュー計画には、準備された候補ペイロードが記載されます。進捗メッセージに示されるとおり、キャッシュ済みのステージではリクエストが送信されないことがあります。Responses、クラウド ASR のチャンク、取得、削除の呼び出しでは、過負荷／サーバーエラー時の自動再試行は最大 3 回です。ファイル作成の POST と、結果が不明なタイムアウトは自動的に再送されません。

バックエンド：

--asr auto|siliconflow|whisper|none
--asr-model base
--asr-language Chinese
--asr-prompt "请使用简体中文转写。关键词：……"
--asr-chunk-seconds 60
--asr-concurrency 4

SiliconFlow では、base/auto のデフォルトは FunAudioLLM/SenseVoiceSmall です。Whisper では通常のモデル名が使用されます。SiliconFlow のドキュメントで保証されている応答はテキストであり、単語単位のタイムスタンプではありません。そのため、並列クラウド文字起こしでは、実際の音声ウィンドウの範囲に timestamp_precision: chunk のラベルが付けられます。60 秒の範囲は文単位のアラインメントではありません。レンダラーはこの制限を明示します。プラットフォームの手がかりには実際のタイムスタンプが保持されます。タイムスタンプのないファイル全体のテキストも、アラインメントを捏造せずに利用できます。無音スキャンが失敗した場合は、連続した同じ長さの音声チャンクにフォールバックします。クラウドチャンクが失敗した場合、成功したチャンクのチェックポイントは保持されますが、音声トラック全体は未完了として示されます。

公式リファレンス：SiliconFlow 文字起こし API、Ark 推論設定。

WeChat Channels（実験的機能）

WeChat Channels のサポートはこのスキルに統合されていますが、引き続き experimental です。モックのテスト範囲と、公開共有リンクを使ったエンドツーエンドの検証 1 件は、保存済みの Yuanbao セッション経由で 2026-09-07 に完了しました。これはテストした経路を証明するものであり、すべてのアカウント、リンク種別、将来のプラットフォーム変更に対する一般的な互換性を証明するものではありません。経路は 3 つあります。

経路 1：互換性のあるパーサー API

export WX_CHANNELS_API_URL="https://your-parser.example/api/channels/parse_sph"
export WX_CHANNELS_API_TOKEN="replace-if-needed"

python3 scripts/download_video.py "https://weixin.qq.com/sph/..." \
  --output-dir ./downloads \
  --asr none \
  --vision none

--wechat-api-url を渡すこともできます。トークンがシェルの履歴に残らないよう、--wechat-api-token よりも WX_CHANNELS_API_TOKEN を優先してください。

経路 2：既存の Yuanbao Cookie

export WX_CHANNELS_COOKIE="hy_user=...; hy_token=..."
python3 scripts/download_video.py "https://weixin.qq.com/sph/..." \
  --asr none \
  --vision none

これは制御された自動化に便利ですが、環境変数やプロセスの検査によって Cookie が漏えいする可能性があります。通常の利用には、保存済みセッション経由の方法を推奨します。

ルート 3：初回の対話型認証

実際のターミナルで実行します：

python3 scripts/download_video.py "https://weixin.qq.com/sph/..." \
  --wechat-login-timeout 300 \
  --asr none \
  --vision none

有効なセッションが存在しない場合、スキルは分離されたブラウザープロファイルを開きます。WeChat／Yuanbao に一度ログインしてください。スキルがセッションを検証し、hy_user、hy_token、hy_source のみを保存してから処理を続行します。

保護されるデフォルトのパス：

~/.config/kangarooking-skills/video-downloader/yuanbao-cookies.json
~/.config/kangarooking-skills/video-downloader/yuanbao-browser-profile/

Cookie ディレクトリの権限は 0700、Cookie ファイルの権限は 0600 です。スキルはユーザーの通常の Chrome プロファイルを読み取りません。

便利なフラグ：

--wechat-login
--no-wechat-auto-login
--wechat-login-timeout 300
--wechat-cookie-file /private/path/yuanbao-cookies.json
--wechat-api-url URL
--wechat-api-token TOKEN
--force-redownload

プロバイダーは実行のたびにメタデータと有効期限が切れる再生 URL を更新しますが、出力先の決定論的なパスに有効な MP4 がすでにある場合は、ASR とビジュアルのキャッシュを安定させるため、デフォルトではそれを再利用します。破損または空のファイルは再ダウンロードされます。直接解析が機能しない場合は、kg百宝箱 を使って適法に動画を保存し、同じ CLI にローカルファイルを渡してください。ASR とビジュアルのパイプラインは同一です。

プロバイダーの動作

• Douyin：まず H5 ルートを試し、次に yt-dlp にフォールバックします。
• Bilibili：可能な場合は、メタデータ、字幕、結合済み MP4 を yt-dlp で取得します。
• YouTube：yt-dlp を使用します。必要に応じてローカルの Node、リモートコンポーネント、またはブラウザー Cookie を使用する場合があります。
• Xiaohongshu：yt-dlp を使用し、ブラウザー Cookie にフォールバックします。
• WeChat Channels：互換性のある API または Yuanbao 認証を使用します。実験的な機能です。
• ローカルファイル：コピーは不要です。ソースメディアを検査し、読み取り専用で再利用します。

失敗状態

• done：要求されたステージが完了しました。
• planned：ローカルの成果物とアップロード計画が作成されましたが、Doubao へのリクエストは開始されていません。
• partial：有用な成果物はありますが、バックエンドまたはフレームのバッチを利用できませんでした。
• failed：ステージで使用可能な出力を生成できませんでした。
• skipped：ユーザーによって無効化されたか、該当しません。

ファイルが存在することだけから、処理の完了を推測しないでください。全体の status、asr.status、vision.status、およびエラーを確認してください。CLI の終了コード：完了した処理、または明示的に計画・スキップされた処理は 0、要求されたステージ（ASR を含む）が失敗した場合は 1、引数または対話に問題がある場合は 2、要求された処理が部分的または保留中の場合は 3 です。ASR エラーと選択範囲の網羅性に関する警告は Markdown に含まれます。ネイティブ動画のレコードには、明示的に指定された有限かつ範囲内の正の長さのタイムスタンプと、観測された根拠が必要です。タイムスタンプの欠落、空のレコード、範囲外の区間は、暗黙に補完されたり、網羅に成功したものとして数えられたりしません。

安全性とプライバシー

• ユーザーが所有している、ダウンロードの許可を得ている、または適法にアーカイブできる素材のみをダウンロードしてください。
• DRM、有料アクセス、プライベート権限、またはプラットフォームのアクセス制御を回避しないでください。
• 一時的な署名付き動画 URL、生の WeChat API プロファイル、Cookie、Bearer トークン、API キーは、公開成果物に含まれません。
• 選択したモードに応じて、キーフレーム、圧縮動画プロキシ、タイムスタンプ付きの文字起こし／字幕／シーンのタイムスタンプ、または選択したクリップが Volcano Ark に送信されるのは、対話型の確認を行った後、または非対話型実行で事前に --confirm-cloud-upload による認証を行った後に限られます。エージェントモードでは、対話型の使用時に Doubao の 2 つのステージが個別にプレビューされます。自動化フラグは両方を事前に認証します。現在利用可能なビジュアル処理の範囲を確認するには --vision-plan-only を使用し、ビジュアルプロバイダーに絶対に送信してはならない素材には --vision none を使用してください。
• --vision-plan-only は SiliconFlow ASR には適用されません。ソースの音声や文字起こしをマシンの外部に出せない場合は、ローカルの Whisper を使用するか、ASR を無効にしてください。
• クラウドファイルの削除はベストエフォートです。報告されたクリーンアップエラーを確認してください。削除に失敗したファイルが設定済みの有効期限前に削除されたと想定しないでください。
• クリエイターの分析では一般的な手法を抽出できますが、許可なく人物の声や顔、著作権で保護された素材、またはフレームごとの創作表現を模倣してはなりません。