qwen-mm-plugins-core

ローカルファイルの確認

qwen-mm-plugins-core の MCP ツールを利用できます。これらを使って、対応するローカルファイルの読み取りと可視化、メディアのメタデータの確認、画像の切り抜きや注釈の追加、ドキュメントのページや動画のフレームの保存を行えます。手動でスクリプトを作成するより、これらの MCP ツールを優先してください。

デフォルトのネイティブモードでは、これらのツールはモデル API を呼び出すことなく、エージェントが確認できるテキストと画像を返します。QWEN_MM_NATIVE_MODE=0 の場合、共有キャプションフォールバックは画像の結果を設定済みの VL エンドポイントに送信し、テキストのキャプションを返します。

スキーマとパラメーターの詳細については、ツール一覧で qwen-mm-plugins-core のツールを確認してください。

ツールの使い分け

読み取りと確認：

• 動画／音声のメタデータを最初に確認します（長さ、解像度、fps、コーデック、ビットレート、音声／動画／字幕トラック、回転、チャプター）。→ media_info。read_video の実行前、およびクリップ／編集の前に実行してください。詳しくは下記の「メタデータを最初に確認」を参照してください。
• ファイルを確認します（PDF、Office、CSV、コード、ノートブック、3D など）。→ visualize
• 動的解像度で画像を読み取ります。→ read_image
• 動画を読み取ります（フレームを抽出）。→ read_video
• 動画の特定のフレームをファイルに保存します。→ save_view（times=[...] を渡します）
• ドキュメントのページを画像として保存します。→ save_view（pages="..." を渡します）

生成／注釈（画像ファイルを書き込みます）：

• 画像から矩形領域を切り抜きます。→ crop
• 写真の座標：read_image、crop、draw_bbox は EXIF の向きを適用します。grounding が返すボックスを含め、表示画像上の 0～1000 の座標を使用してください。
• 画像にバウンディングボックスを描画します。→ draw_bbox

可視化 — 対応フォーマット

カテゴリ	拡張子	備考
ドキュメント	.pdf、.svg	組み込み（pypdfium2 + resvg）
Office	.docx、.pptx、.vsdx	libreoffice が必要
データ	.csv、.xlsx	テキストの表 + グラフ画像
コード	.js、.ts、.py、.go、.rs、.md、...	テキストを返します（Markdown のコードブロック）
プレーンテキスト	.txt、.text、.log	テキストを返します（フェンス付きブロック）
Web ページ	.html、.htm、.mhtml	スクリーンショット。playwright が必要
図	.drawio	XML → SVG にレンダリング
字幕	.srt、.vtt	テキストを返します
3D モデル	.obj、.stl、.glb、.gltf、.fbx、.ply、.step、.stp	組み込み。最高品質での処理には blender を使用
GIS／地理空間	.geojson、.kml、.shp	組み込み
ノートブック	.ipynb	テキストセル + 埋め込み画像
LaTeX	.tex	PDF にコンパイル。失敗した場合はソースにフォールバック
画像／動画	.jpg、.mp4、...	read_image／read_video に委譲

この表には対応フォーマットが記載されています。拡張子が不明なファイルには、未対応タイプのエラーが返されます。

ページ範囲には pages、解像度には budget、出力数の上限には max_pages を使用してください。

メタデータを最初に確認

動画／音声ファイルに対しては、read_video の実行前、およびクリップ／トリミング／連結／多重化の前に、必ず media_info を実行してください。ヘッダーのみを読み取るため、巨大なファイルでも高速に実行でき、ソースの扱い方がわかります。fps と長さがわかると、read_video もより適切にサンプリングできます。

アクションカメラのクリップ、VFX／ストック映像、ナレーション、効果音など、異なる種類の素材を扱うときは、気づかないうちに編集が破損する原因を media_info で確認できます。次の点に注意してください。

• VFR（可変フレームレート。スマートフォンやアクションカメラでよく見られます）：media_info は「possibly VFR」としてフラグを表示します。フレーム単位で正確にカットするには、事前に一定の fps に変換する必要があります（動画編集の工程）。VFR ソースの fps が一定だと決めつけないでください。
• 回転（rotation 90°/180°）：表示上の向きと保存されたピクセルの向きが異なります。切り抜きやオーバーレイの前に、回転を映像に反映してください。
• クリップ間で fps／解像度／DAR が一致しない場合：プロジェクトのタイムベースを決め、差異のあるクリップを変換してください。
• 音声のサンプルレートとチャンネル数（ナレーション、音楽、効果音では異なることがよくあります。例：44.1k と 48k、モノラルとステレオ）：ミキシングの前に、プロジェクト内で統一したレートにリサンプリングしてください。
• 音声トラックがない場合や、コンテナの start_time が通常と異なる場合：media_info はこれらを検出します。どちらも単純なタイムスタンプ計算にずれを生じさせたり、処理を壊したりする原因になります。

ヒント

解像度の予算：プレビューには small、デフォルトの normal（約1024）、細部の確認には large を使用します。

動画の処理方法：fps=0 は自動選択されます。5分ごとに fps=1, budget="normal" でざっと確認し、興味深い区間を fps=2, budget="large" で詳しく確認します。時間範囲の指定には start_time／end_time を使用します。

他の機能との関係

Core はファイルの読み取り、レンダリング、基本的な画像処理を担います。専用のモデル推論や検索を行うには、次の機能をインストールしてください。

• モデルでメディアを理解する → モデルファミリーごとに分類された qwen-mm-plugins-api：VL（vision_chat、ocr、grounding）、Omni A/V（タイムスタンプ付きキャプション生成、複数話者の ASR、時間的グラウンディング、イベントのカウント）、さらに transcribe_audio と segmentation。ここで grounding の出力に draw_bbox で注釈を付けます。
• 事実を確認する／エンティティを特定する（画像検索＋ウェブ）→ qwen-mm-plugins-search。まずここで save_view を使ってフレームを取得します。