Yueying – Let AI watch videos

yueying — AI に動画を見せる

動画を Claude、Cursor、または任意の MCP クライアントに渡すと、タイムスタンプ付きの文字起こしとキーフレームのコンタクトシートが返ってきます。オフラインで動作し、API キーも不要です。 まずはローカルファイルに対応しています。URL（YouTube、Bilibili、Douyin、Xiaohongshu、TikTok、Vimeo、…）は、処理する権利のある動画を指すもので、yt-dlp 経由で最大 720p で取得され、デフォルトでは処理後に削除されます。

中国語の説明 ↓

Yueying（阅影）は「動画を読む」という意味です。1 つのパッケージで、MCP サーバー、CLI、エージェントスキルを利用できます。

利用できる機能

yueying に接続した Claude Desktop：リンクを貼り付けて約 40 秒待つと、動画の内容がタイムスタンプ付きのメモとして返ってきます。この動画には字幕があるため、音声認識は実行されず、モデルは文字起こしのみを取得しました。画面を見る必要があるときは、get_frames を通じてキーフレームとコンタクトシートを取得します。デモ動画：GitInGifs: Git Branches、GitLab 提供、CC BY。

24 秒のデモクリップ（中国語のナレーション付きのアプリ画面4枚）のコンタクトシートです。各タイルの黄色いラベルはキーフレーム番号とタイムスタンプを示し、モデルはこれらを引用して回答します。

同じクリップの文字起こし — ローカルで音声認識を行い、言語は中国語と自動判定されました：

[00:00] 这是阅读,一个安静的桌面小说阅读器。整本书连续滚动,按段落记住进度。
        第二个画面是桌面模式,窗口变透明,只留文字浮在桌面上。
        第三个画面是伪装皮肤,一键变成代码编辑器。
        最后是伪装成表格的样子。

（アプリ名は月读ですが、音声認識では同音異義語の「阅读」と認識されました。音声認識では名前を誤認することがありますが、モデルはフレーム内の画面上のテキストをもとに修正します。）

すべての動画は、次のように1つのフォルダーに保存されます。

report.md          index for the model: metadata, chapters, contact sheets, keyframes, transcript
transcript.txt     paragraphs with [mm:ss] timestamps
transcript.srt     subtitles for any player
grid_01.jpg …      3x3 contact sheets, 9 keyframes each, in time order
frames/            full-size keyframes, e.g. f003_00m15s.jpg
manifest.json      machine-readable result (paths, segments, chapters, options)

yueying を選ぶ理由

• まず字幕を使い、必要な場合のみ Whisper を使用します。 プラットフォーム字幕がある場合はそれを使用します。字幕がない場合は、ローカルの faster-whisper を使用します。NVIDIA GPU では large-v3-turbo、CPU では small を使い、必要に応じて CPU に自動で切り替えます。何もアップロードされず、キーも不要です。
• ffmpeg を同梱しています。 Windows 11 でも追加設定なしで動作します（imageio-ffmpeg）。PATH の設定は不要です。
• トークン効率に優れています。 シーンの切り替わりでキーフレームを取得し、類似フレームを除外してから、タイムスタンプを焼き込んだ 3x3 のコンタクトシートにまとめます。1 枚のシートは9つの場面につき約 1～2K トークンです。文字起こしは [mm:ss] 形式の段落で返されます。
• 中国語圏のプラットフォームなどに対応しています。 Bilibili（複数パート、コレクション、ブラウザーのログイン情報を使った会員限定動画）、Douyin、Xiaohongshu のほか、YouTube、TikTok、Vimeo、X、および yt-dlp が対応するすべてのサイトに対応しています。
• API キー不要、テレメトリーなし。 ネットワーク通信は、指定した動画サイトと Whisper モデルのダウンロードに限られます。プライバシーポリシーをご覧ください。

ベンチマーク：6 分の Bilibili 動画は、RTX 5060 搭載ノート PC で約 90 秒でレポートを生成します。CPU で model=small を使う場合は、音声 10 分あたり約 1～2 分を見込んでください。

クイックスタート

1. uv をインストールします（Python は不要です）。

   winget install astral-sh.uv                         # Windows
   brew install uv                                     # macOS
   curl -LsSf https://astral.sh/uv/install.sh | sh     # Linux / macOS
   

2. 一度ウォームアップして、すべてを確認します（パッケージをインストールし、GPU を確認し、音声モデルをダウンロードして、2 秒間のスモークテストを実行し、貼り付け用の設定を表示します）。

   uvx yueying mcp --setup
   

3. 以下の手順でサーバーをクライアントに追加してから、「C:\videos\lecture3.mp4 を見て、手順をノートにまとめて」、または 「この動画では docker compose について何と言っていますか：https://www.bilibili.com/video/BV…」 と尋ねます。

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json（Windows）· ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。その後、Claude を完全に終了して、再起動します。

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Windows での注意：Claude Desktop から PATH が認識されない場合があります。サーバーの起動に失敗する場合（「spawn uvx ENOENT」）、絶対パスを使用してください。例："command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe"（where uvx でパスを確認できます）。ログ：%APPDATA%\Claude\logs\mcp-server-yueying.log（macOS では ~/Library/Logs/Claude/）。ここでは wait_seconds をデフォルト値のままにしてください。実行ルールを参照してください。

Claude Code

claude mcp add --transport stdio --scope user yueying --env PYTHONUTF8=1 -- uvx yueying mcp

または、このリポジトリの .mcp.json をプロジェクトに配置してください（長い動画に対する 1 回の watch_video 呼び出しを待てるよう、"timeout": 1800000 が設定されています）。Claude Code のツールタイムアウトをグローバルに延長するには、環境に MCP_TOOL_TIMEOUT=1800000（ミリ秒）を設定します。このリポジトリは Claude Code プラグイン（.claude-plugin/plugin.json：サーバー＋スキル）でもあります。

Cursor

上の Add to Cursor バッジをクリックするか、同じ JSON を ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）に記述します。

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Cline

MCP Servers → Configure（cline_mcp_settings.json）。timeout の単位は秒です。読み取り専用の 5 つのツールは、自動承認しても安全です。エージェント向けの手順はllms-install.mdを参照してください。

{
  "mcpServers": {
    "yueying": {
      "type": "stdio",
      "command": "uvx",
      "args": ["yueying", "mcp"],
      "env": { "PYTHONUTF8": "1" },
      "timeout": 1800,
      "autoApprove": ["get_transcript", "search_transcript", "get_frames", "get_frame_at", "list_videos"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

VS Code（Copilot エージェントモード）

上の Install in VS Code バッジをクリックするか、.vscode/mcp.json を作成します（ルートキーが servers である点に注意してください）。

{ "servers": { "yueying": { "type": "stdio", "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

カスタム URL スキームに対応するホスト向けの直接リンク：cursor://anysphere.cursor-deeplink/mcp/install?name=yueying&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ5dWV5aW5nIiwibWNwIl0sImVudiI6eyJQWVRIT05VVEY4IjoiMSJ9fQ== および vscode:mcp/install?%7B%22name%22%3A%22yueying%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22yueying%22%2C%22mcp%22%5D%2C%22env%22%3A%7B%22PYTHONUTF8%22%3A%221%22%7D%7D。

uv を使わない場合（pip / pipx）と Windows のワンクリックインストール

pip install yueying            # or: pipx install yueying
yueying mcp --setup            # prints a config with the absolute path of the yueying-mcp executable

その絶対パスを "command" として指定し、args は設定しません（Windows：...\Scripts\yueying-mcp.exe。python -m yueying mcp でも動作します）。Python のツールを使っていない Windows ユーザーは、チェックアウトしたリポジトリから install.cmd をダブルクリックできます。これにより %LOCALAPPDATA%\yueying\venv が作成され、Claude Code スキルがインストールされ、yueying mcp --setup が実行されて、正しいパスを含む JSON ブロックが表示されます。

GPU

uvx --from "yueying[cuda]" yueying mcp     # NVIDIA: adds the CUDA runtime wheels (cuBLAS, cuDNN)
pip install "yueying[cuda]"

デバイスとモデルは自動的に選択されます（model=auto：CUDA では large-v3-turbo、CPU では small）。GPU の試行に失敗した場合、認識は自動的に CPU にフォールバックします。

Docker

docker build -t yueying .
docker run --rm -i -v yueying-data:/data -v "$PWD/videos:/videos:ro" yueying

イメージは CPU 専用です（コンテナにはデフォルトで GPU が割り当てられません）。そのため、デフォルトでは small モデルを使用します。 動画を読み取り専用でマウントし、ツールにはコンテナ内のパス（/videos/lesson.mp4）を渡してください。結果と ダウンロードした Whisper の重みは /data ボリュームに保存されます。クライアント設定では、command に docker を、args に ["run", "--rm", "-i", "-v", "yueying-data:/data", "-v", "/your/videos:/videos:ro", "yueying"] を指定します。

ツール

ツール	エージェントが使用する場面	返される内容	制限
watch_video(video, mode="full", language="auto", model="auto", frame_interval_seconds=None, cookies_from_browser=None, output_dir=None, refresh=False, wait_seconds=45, max_chars=12000)	動画に対する最初の呼び出しです。絶対ローカルパスまたは URL を指定します。mode：full（文字起こし＋キーフレーム）、transcript、frames。	DONE の概要：タイトル、ソース、再生時間、テキストソース、フォルダー、ファイル、チャプター、コンタクトシートの範囲、[mm:ss] 形式の段落に分けられた文字起こし。処理中の場合はステージ／パーセント／ETA を含む RUNNING、エラーの場合は平易な英語のヒントを含む ERROR が返されます。	wait_seconds（0～1500）の間、待機します。文字起こしが max_chars で切り詰められた場合は、get_transcript の開始時刻が示されます。動画ごとにキャッシュされます。refresh=true で再処理します。
get_transcript(video, start="0", end=None, format="paragraphs", max_chars=8000)	概要が切り詰められた場合、特定の時間範囲を取得する場合、または字幕を書き出す場合（format="srt"）に使用します。	ヘッダーと、[mm:ss] 形式の段落／[mm:ss-mm:ss] 形式のセグメント／SRT ブロックが返されます。切り詰められた場合は TRUNCATED — next_start="…" が返されます。	max_chars は 1000～100000 です。時刻は秒、mm:ss、h:mm:ss で指定します。
search_transcript(video, query, context_seconds=15, limit=10)	「彼が X について言及するのはいつですか？」という場合に使用します。	該当箇所の時刻、周辺の文、最も近いキーフレーム番号、コンタクトシート番号が返されます。	用語をスペースで区切って指定します。一致する用語がある箇所が返され、用語が多いほど上位に表示されます。limit は 50 以下です。
get_frames(video, kind="grids", start=1, count=2, max_width=1280)	画面に表示されているものを確認する場合に使用します。まずコンタクトシート（grids）を使い、詳細確認が必要な場合にのみ単一のキーフレーム（frames）を使います。	時刻順に並んだ、画像ごとの JPEG の絶対パスが返されます。残りがある場合は Next: get_frames(start=…) が返されます。	1 回の呼び出しにつき画像は 3 枚以下です（デフォルトは 2 枚。Claude Desktop では 2 枚以下にしてください）。1280 px のコンタクトシート 1 枚あたり約 150 KB です。
get_frame_at(video, time, max_width=960)	ある時点のコード、スライド、チャート、UI を読む場合に使用します。	正確なフレーム（ローカルファイルがまだ存在する場合はソースから抽出）または最も近いキャッシュ済みキーフレームと、その前後に話された段落が返されます。	画像 1 枚。960 px で約 100 KB です。
list_videos(limit=20)	ユーザーが以前の動画について言及した場合、またはディスク使用量を確認する場合に使用します。	video_id、タイトル、再生時間、テキストソース、日付、サイズ、フォルダーを含むテーブルと、実行中のジョブが返されます。	即時に返され、読み取り専用です。

読み取りツールの video には、watch_video／list_videos の video_id、結果フォルダー、または watch_video に指定したものと同じパス／URL を指定できます。

RUNNING のルール

処理には数分かかることがあり、多くのホストではツール呼び出しが約 1 分でタイムアウトします。そのため watch_video は最大 wait_seconds まで待機し、その後 RUNNING video_id=… · stage 2/4 speech recognition 40% · elapsed 46 s · est. ~1 min remaining を返します。エージェントは同じ video を指定して watch_video を再度呼び出すだけで、同じジョブに再接続できます（実行中はオプションが無視されます。refresh=true を指定すると再起動します）。推奨する wait_seconds：

ホスト	wait_seconds	理由
Claude Desktop	45（デフォルト）	クライアントのタイムアウトは約 60 秒
Cursor	45（デフォルト）	60～120 秒
Claude Code	最大 1500	.mcp.json の timeout／MCP_TOOL_TIMEOUT を 1800000 ms に設定
Cline	最大 1500	"timeout": 1800（秒）を設定

進捗通知に対応するホストには、1.5 秒ごとに進捗通知が送信されます。1 台のサーバーで同時に処理できる動画は 1 本です。追加のリクエストはキューに入ります。

初回実行時： 最初の音声認識時に、Whisper モデルが 1 回ダウンロードされます（CPU では small が約 480 MB、GPU では large-v3-turbo が約 1.6 GB）。事前に uvx yueying mcp --setup を実行するとダウンロードできます。実行しない場合は、RUNNING の行に「初回実行では約…をダウンロードします。数分かかることがあります」と表示されます。

ファイルの保存先

ルート：$YUEYING_OUT_DIR が設定されている場合はその値、そうでない場合は ~/yueying_out です。動画ごとに1つのエントリーを作成し、<slug>-<video_id>（yt-<id>、bili-<BV>、またはファイル名）という名前を付けます。名前は変更されません。タイトルは manifest.json に保存されます。

~/yueying_out/
└── bili-BV1xx-3f9a2c1e/
    ├── report.md  transcript.txt  transcript.srt  manifest.json
    ├── grid_01.jpg … grid_07.jpg
    ├── frames/            f001_00m02s.jpg …   (+ frames/extra/ for get_frame_at)
    ├── .job               only while a job runs
    └── _download/         only with YUEYING_KEEP_SOURCE=1

環境変数	意味	デフォルト
YUEYING_OUT_DIR	結果のルートフォルダー（絶対パス。~ も使用可）	~/yueying_out
YUEYING_MODEL	model パラメーターのデフォルト値	auto
YUEYING_DEVICE	auto / cuda / cpu	auto
YUEYING_LANG	サーバーが作成する report.md の言語（en/zh）	en
YUEYING_COOKIES_FROM_BROWSER	Cookie のデフォルト取得元ブラウザー（chrome、edge、firefox、…）	未設定
YUEYING_KEEP_SOURCE	1 にすると、ダウンロードした ≤720p のソースを _download/ に保持します（URL の正確な時刻のフレーム取得が可能になります）	未設定
YUEYING_MAX_JOBS	サーバーごとに同時実行するパイプライン数	1
YUEYING_JOB_TIMEOUT	動画ごとのハードタイムアウト（秒）	7200
HF_HOME	Hugging Face のキャッシュ（Whisper の重みはここに保存されます）	HF のデフォルト
HF_ENDPOINT	ミラー（例：https://hf-mirror.com）	huggingface.co
PYTHONUTF8	文字化けを防ぐため、Windows では 1 に設定します	—

ディスク使用量：動画1時間あたり約 25 MB。YUEYING_KEEP_SOURCE=1 の場合は、さらに 300～600 MB/時間が必要です。ファイルは自動削除されません。サイズは list_videos で確認できます。空き容量を確保するにはフォルダーを削除してください。watch_video(refresh=true) を実行すると、1本の動画を再処理できます。ローカルファイルを編集するとサイズまたは更新日時が変わるため、新しいエントリーとして扱われます。

対応ソース

• ローカルファイル： ffmpeg が読み込めるファイル（mp4、mkv、mov、webm、avi、flv、ts、および mp3、m4a、wav などの音声ファイル）。音声のみの入力では、フレームのない文字起こしが生成されます。
• URL： yt-dlp が対応するすべてのサイト。≤720p で取得され、YUEYING_KEEP_SOURCE=1 でない限り処理後に削除されます。
• Bilibili： ログインしていない場合、Bilibili から配信されるのは 480p です。スライドやコードには十分です。HD または会員限定の動画では、cookies_from_browser="chrome"（または edge、firefox、brave、chromium、safari）を指定してください。Windows では、Chrome が Cookie データベースをロックするため、先に Chrome を終了してください。複数パートの動画やコレクションでは、p= リンクは個別のエントリーになります。CLI の --all を指定すると、すべて処理されます。
• 対象外： ライブストリームと画像。短縮リンク（b23.tv、v.douyin.com）も処理されますが、長い形式のリンクとの重複排除は行われません（サーバーが URL を自ら解決することはありません）。

CLI とエージェントスキルもあります

yueying video.mp4
yueying "https://www.bilibili.com/video/BVxxxx" --ui-lang en
yueying "https://www.youtube.com/watch?v=xxxx" --out ./notes/xxx
yueying lesson1.mp4 lesson2.mp4 "https://www.bilibili.com/video/BVyyyy"   # several at once, one folder each + index.md
yueying "https://www.bilibili.com/video/BVxxxx" --all                      # every part of a multi-part video / collection
yueying --install-skill                                                    # Claude Code skill -> ~/.claude/skills/yueying

デフォルトの出力先：./yueying_out/<name>/（入力が複数の場合は親フォルダー）。CLI のログ行と report.md はデフォルトで中国語です（英語にするには --ui-lang en を指定します）。0.3 ではデフォルトを英語に変更する予定です。

フラグ	意味
--out DIR	出力フォルダー（デフォルトは ./yueying_out/<name>。入力が複数の場合は親フォルダー）
--all	URL が Bilibili の分割動画／コレクション／プレイリストの場合、すべてのエントリーを処理します（デフォルトでは最初のものだけ）
--lang zh	音声言語コード（zh、en、ja、…）。デフォルトでは自動検出します
--model auto	Whisper モデル：auto／tiny／base／small／medium／large-v3／large-v3-turbo（CLI のデフォルト）。auto は NVIDIA GPU では large-v3-turbo、CPU では small を使用します
--device cpu	CPU を強制的に使用します（auto／cuda／cpu）
--interval 3	およそ N 秒ごとにキーフレームを 1 枚取得します。デフォルトは動画の長さに応じて、1 分未満では 2 秒、3 分未満では 3 秒、10 分未満では 6 秒、30 分未満では 12 秒、それ以上では 20 秒です
--frames 30	キーフレームの最大数（デフォルトは動画の長さに応じて設定され、上限は 150 枚。--interval を指定した場合は 300 枚）
--scene 0.2	シーン変化の感度（0～1）。数値が低いほど感度が高くなります（デフォルトは 0.3）
--no-dedupe	直前のフレームとほぼ同じフレームも保持します（デフォルトでは、サムネイルのピクセルの変化が 2 % 未満のフレームは削除されます）
--no-asr	字幕がない場合でも音声認識を行いません（画像のみ）
--no-frames	キーフレームを取得しません（テキストのみ）
--force-asr	字幕がある場合でも音声認識を実行します
--cookies-from-browser chrome	ブラウザーでログインした状態でダウンロードします（Bilibili の HD／会員限定動画、ログインが必要な YouTube 動画）
--keep	ダウンロードした元動画を保持します
--ui-lang en	report.md の見出しとラベルの言語：zh（デフォルト）または en
--json	最後にマニフェスト JSON を 1 行で出力します（スクリプト向け）
--install-skill	エージェントスキルを ~/.claude/skills/yueying にインストールします
mcp	MCP サーバーを実行します（mcp --setup、mcp --check、mcp --version）

スキル（src/yueying/skill/SKILL.md）では、コーディングエージェントに、MCP ツールが利用可能な場合はそれを優先し、そうでない場合は CLI を実行して report.md とコンタクトシートを読むよう指示しています。Agent Skills 規格に対応するツールでは、~/.claude/skills/yueying/SKILL.md を独自のスキルフォルダーにコピーできます。

類似プロジェクトとの比較（2026 年 9 月）

	yueying	claude-video	claude-real-video	mcp-video-analyzer
MCP サーバー	あり	なし（スキルのみ）	なし（スキル）	あり（Node）
オフライン音声認識	あり — まず字幕を使用し、それがない場合はローカルの faster-whisper を使用	クラウドの Whisper にフォールバック	ASR を優先	whisper は別途インストール
GPU の自動検出＋CPU フォールバック	あり	–	–	–
ffmpeg の同梱	あり	–	手動で ffmpeg を使用	–
Windows でのテスト	あり（Windows 11）	–	–	–
コンタクトシート（3x3）	あり	–	–	–
フレームへのタイムスタンプ焼き込み	あり	–	–	–
Bilibili／Douyin／Xiaohongshu	あり	–	–	–

「–」は、確認時にそのプロジェクトが該当機能を掲載していなかったことを示します。各プロジェクトの README を確認してください。状況が変わっている可能性があります。

プライバシーポリシー

yueying はデータを収集せず、テレメトリー、分析、クラッシュレポート、更新チェックも行いません。すべての処理はローカルで行われます。ネットワークへの接続は、（1）yt-dlp を介して、指定された URL の動画サイトに接続する場合と、（2）Whisper モデルを一度ダウンロードするために Hugging Face（または HF_ENDPOINT）に接続する場合のみです。出力は削除するまでご自身のフォルダーに保存されます。文字起こしと、リクエストしたフレームは、MCP クライアントが使用するよう設定されているモデルにのみ送信されます。この転送には、お使いのクライアントおよびプロバイダーの利用規約が適用され、yueying の規約は適用されません。お問い合わせ：GitHub のイシュー。全文：docs/privacy.md。

トラブルシューティング／FAQ

• Claude Desktop で「No result received」と表示される場合。 wait_seconds を 45 に設定してください（その後、エージェントが watch_video を再呼び出しします）。また、最初の呼び出しでモデルのダウンロードも行われないように、uvx yueying mcp --setup を一度実行してください。
• spawn uvx ENOENT が表示される／サーバーが起動しない場合。 ホストから PATH を参照できていません。uvx の絶対パス（where uvx／which uvx）または yueying-mcp の絶対パスを "command" に指定してください。
• Windows でコンソールウィンドウが一瞬表示される場合。 0.2.0 以降にアップデートしてください。子プロセスはウィンドウを表示せずに起動します。それでも表示される場合は、古いバージョンを実行しています（uv cache clean yueying）。
• タイトルが文字化けする／????? と表示される場合。 サーバー設定に "env": { "PYTHONUTF8": "1" } を追加してください（上記のすべての設定例に含まれています）。
• Bilibili でエラー 412／「-352」が発生する場合。 サイトでログインが必要です。cookies_from_browser="edge" または "chrome" を指定してください（Windows では、事前に Chrome を終了してください）。
• YouTube で「Sign in to confirm you're not a bot」と表示される場合。 同様に cookies_from_browser を指定してください。yt-dlp のアップデートもお試しください：uv cache clean yueying または pip install -U yt-dlp。
• CPU で処理が遅い場合。 NVIDIA GPU がない場合は、model="small" がすでに自動選択されています。画像だけが必要な場合は mode="frames" を、キーフレームを省略する場合は mode="transcript" を指定してください。
• 文字起こしの名前、数字、コードが正しくない場合。 どの ASR でも起こり得ます。エージェントには画面上のテキストを信頼するよう指示されています。該当箇所の get_frame_at を依頼してください。
• モデルのダウンロードが遅い／ブロックされる場合（中国本土）。 サーバーの env に HF_ENDPOINT=https://hf-mirror.com を設定してください（huggingface.co にアクセスできない場合、CLI は自動的にミラーへ切り替わります）。
• GPU エラー（CUDA／cuDNN／メモリ不足）が発生する場合。 model="small" または YUEYING_DEVICE=cpu を指定してください。CUDA 用ホイールを yueying[cuda] でインストールしてください。
• 異なる設定で再処理したい場合。 watch_video(video=…, refresh=true, …) を実行してください。その動画の実行中のジョブを終了し、エントリーを削除してから、処理を再開します。

仕組み

video / URL ──► yt-dlp (≤720p) + platform subtitles
            ──► ffmpeg 16 kHz audio ──► faster-whisper (skipped when subtitles exist)
            ──► ffmpeg scene detection ──► keyframes (near-duplicates dropped)
            ──► Pillow: burn "#n mm:ss", pack 3x3 contact sheets
            ──► report.md · transcript.txt · transcript.srt · manifest.json

MCP client ──stdio──► mcp_server.py ──spawns──► python -m yueying.cli <video> --json --ui-lang en
                       │  parses the child's progress lines, long-polls, caches per video
                       └─► store.py (cache keys / folders) · query.py (paging, search, frames)

サーバープロセス自体は yt-dlp、Whisper、CUDA を読み込みません。負荷の高い処理はすべて子プロセスで実行され、サーバーとともに終了します。すべてのファイルは src/yueying/ にあります。

ファイル	役割
cli.py	コマンドラインのエントリーポイント。パイプラインの実行、mcp サブコマンドの振り分け、--install-skill
mcp_server.py	MCP サーバー。6 つのツール、ジョブランナー、進捗状況の解析、DONE／RUNNING／ERROR の表示、--setup
store.py	出力ルート、正規化 URL、動画ごとのキャッシュキーとフォルダー名、.job マーカー
query.py	マニフェストを対象とする純粋関数。文字起こしのページ分割、検索、最寄りのフレーム、コンタクトシートの範囲、画像の縮小
models.py	Whisper のモデル名、サイズ、Hugging Face のリポジトリ（負荷の高いインポートなし）
download.py	yt-dlp によるダウンロード、字幕言語の選択、プレイリスト／コレクションの一覧表示
ffm.py	ffmpeg のラッパー。プローブ、音声抽出、埋め込み字幕、タイムアウト
subs.py	srt／vtt／Bilibili JSON 字幕の解析、YouTube 自動字幕の重複除去
asr.py	faster-whisper による文字起こし、GPU／CPU の選択、auto モデル、フォールバック
frames.py	シーン検出、フレームのタイミング設定と抽出、重複除去、タイムスタンプの焼き込み、コンタクトシート
report.py	report.md、文字起こしファイル、manifest.json（zh/en のラベル）、マニフェストの読み込み
skill/SKILL.md	エージェントスキル

ロードマップ

• 次期 — Claude Desktop 用のワンクリック .mcpb バンドル、Smithery への掲載。
• 0.3 — forget_video／整理ツール、CLI のデフォルトレポート言語を英語に変更、MCP 経由の --all（プレイリスト対応）。

クレジット

• faster-whisper、yt-dlp、imageio-ffmpeg、Pillow
• コンタクトシートへのタイムスタンプの焼き込みは video-vision-mcp に準拠しています。再生時間に基づくフレーム間隔は video-analyzer-skill に準拠しています。

ライセンス

MIT — LICENSE をご覧ください。

---

中国語の説明

阅影（yueying）は、AI が動画を理解できるようにします。 Claude Desktop、Claude Code、Cursor などの MCP 対応ツールに、ローカル動画ファイルまたは動画リンク（Bilibili／YouTube／Douyin／小红书 …）を渡すと、タイムスタンプ付きの文字起こしとキーフレームの9分割画像を取得できます。字幕があれば字幕を優先し、なければローカルの faster-whisper で認識します。すべてオフラインで処理され、アップロードも API key も不要です。リンクは yt-dlp で ≤720p でダウンロードされ、処理後は元動画がデフォルトで削除されます。詳しいドキュメントは上記の英語セクションをご覧ください。

インストール

# 1. 装 uv（不需要先装 Python）
winget install astral-sh.uv          # Windows；macOS: brew install uv
# 2. 预热：安装、探测显卡、下载模型、跑 2 秒冒烟测试、打印配置
uvx yueying mcp --setup

uv を使わない場合：pip install yueying（NVIDIA GPU がある場合は pip install "yueying[cuda]" も実行）後、yueying mcp --setup を実行すると、yueying-mcp の絶対パスが表示されます。Windows では、リポジトリをダウンロードして install.cmd をダブルクリックする方法もあります。独立した環境を作成し、Claude Code のスキルをインストールして、--setup を実行し、貼り付け可能な設定を表示します。

設定

Claude Desktop（%APPDATA%\Claude\claude_desktop_config.json。変更後は完全に終了してから再起動してください。Windows で uvx が見つからない場合は、C:\\Users\\<あなた>\\.local\\bin\\uvx.exe のように絶対パスを指定します）、Cursor（~/.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）では、いずれも同じ設定を使います。

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Claude Code では次の1行を実行します。

claude mcp add --transport stdio --scope user yueying --env PYTHONUTF8=1 -- uvx yueying mcp

Cline では同じ設定に "type": "stdio"、"timeout": 1800 を追加し、get_transcript、search_transcript、get_frames、get_frame_at、list_videos を autoApprove に追加します。VS Code の .vscode/mcp.json では、ルートキーを servers にして "type": "stdio" を追加します。

6つのツール

ツール	用途
watch_video(video, mode, language, model, frame_interval_seconds, cookies_from_browser, output_dir, refresh, wait_seconds, max_chars)	動画を見る：ローカルの絶対パスまたはリンクを指定します。DONE（概要＋文字起こし）、RUNNING（進行状況。同じ video を指定してもう一度呼び出すと、続けて待機できます）、または ERROR（英語のメッセージ）を返します。結果は動画ごとにキャッシュされ、refresh=true で再処理します
get_transcript(video, start, end, format, max_chars)	時間範囲を指定して文字起こしを読みます。format="srt" で字幕をエクスポートします
search_transcript(video, query, context_seconds, limit)	「X に言及している箇所」を検索し、時刻、前後の文脈、最も近いキーフレーム番号と9分割画像の番号を表示します
get_frames(video, kind, start, count, max_width)	映像を見る：まず9分割画像（grids）を確認し、細部が必要なら単一フレーム（frames）を確認します。1回につき最大3枚です
get_frame_at(video, time, max_width)	指定した時刻を見る：コード、PPT、グラフ、画面などを確認できます。ローカルファイルが残っていれば、正確なフレームを抽出します
list_videos(limit)	処理済みの動画（video_id、タイトル、長さ、文字起こしの取得元、日付、サイズ、ディレクトリ）と実行中のタスクを一覧表示します

Claude Desktop／Cursor では wait_seconds をデフォルトの 45 のままにします。Claude Code／Cline では timeout を設定すれば、1500 に設定して1回の呼び出しで結果が返るまで待機できます。音声認識の初回実行時にはモデルのダウンロードが必要です（CPU の場合は約 480 MB の small、GPU の場合は約 1.6 GB の large-v3-turbo）。--setup を実行すると、事前にダウンロードできます。

出力ディレクトリと環境変数

結果は ~/yueying_out/<名前>-<video_id>/ に保存されます（YUEYING_OUT_DIR で変更できます）。動画ごとにフォルダーが作成され、report.md、transcript.txt、transcript.srt、grid_01.jpg …、frames/、manifest.json が格納されます。動画1時間あたり約 25 MB です。自動削除はされないため、フォルダーを削除してください。よく使う環境変数：YUEYING_OUT_DIR（出力ルートディレクトリ）、YUEYING_MODEL（デフォルトは auto：NVIDIA GPU があれば large-v3-turbo、なければ small）、YUEYING_DEVICE（auto／cuda／cpu）、YUEYING_LANG（サーバー側の report.md の言語。デフォルトは en、中国語の場合は zh）、YUEYING_KEEP_SOURCE=1（ダウンロードした元動画を保持）、YUEYING_JOB_TIMEOUT（動画1本あたりの上限時間、秒単位。デフォルトは 7200）、PYTHONUTF8=1（Windows で文字化けを防止）。

Bilibili の cookie

Bilibili にログインしなくても 480p で視聴でき、PPT やコードを見るには十分です。高画質または会員限定の動画では cookies_from_browser="chrome"（または edge）を指定します。Windows では、cookie データベースを読み込めないため、先に Chrome を終了してください。412／-352 が発生した場合も、同様に対処してください。

国内向けミラー

モデルのダウンロードが遅い場合やブロックされている場合は、サーバー設定の env に "HF_ENDPOINT": "https://hf-mirror.com" を追加します。コマンドライン版では、huggingface.co に接続できない場合に自動的にミラーへ切り替わります。

コマンドラインの使い方

yueying 视频.mp4
yueying "https://www.bilibili.com/video/BVxxxx"
yueying "https://www.youtube.com/watch?v=xxxx" --out ./notes/xxx
yueying 第1课.mp4 第2课.mp4 "https://www.bilibili.com/video/BVyyyy"   # 多个一起，各出各的文件夹 + index.md
yueying "https://www.bilibili.com/video/BVxxxx" --all                      # B站 分 P / 合集 全部处理
yueying --install-skill                                                    # 装 Claude Code 技能

デフォルトでは ./yueying_out/<動画名>/ に出力され、ログと report.md はデフォルトで中国語です（英語に切り替えるには --ui-lang en を指定します）。よく使うオプション：--lang zh で言語を指定、--model small で小さいモデルに切り替え（auto では自動選択）、--device cpu、--interval 3 でフレーム間隔を指定、--frames 30 で最大フレーム数を指定、--scene 0.2 でシーン検出の感度を指定、--no-dedupe で重複排除を無効化、--no-asr で映像のみ取得、--no-frames で文字のみ取得、--force-asr で字幕があっても音声認識を実行、--cookies-from-browser chrome、--keep で元動画を保持、--json で最後に manifest を1行で出力します。詳しくは上記の英語の表をご覧ください。