Video Processor

Video Processorは、動画モデルの入力特徴量の準備や、出力のポストプロセッシングを担当するユーティリティです。リサイズ、正規化、PyTorch への変換などの変換処理を提供します。

video processorは、画像プロセッサの機能を拡張し、画像とは異なる一連の引数を用いてモデルが動画を処理できるようにします。生の動画データとモデルの間のブリッジとして機能し、入力特徴量がVLM向けに最適化されることを保証します。

from_pretrained() を使用して、Hugging Face Hub またはローカルディレクトリ上の動画モデルから、動画プロセッサの設定（画像サイズ、正規化およびリスケールを行うかどうかなど）を読み込みます。各事前学習済みモデルの設定は [video_preprocessor_config.json] ファイルに保存されるべきですが、古いモデルでは設定が preprocessor_config.json ファイルに保存されている場合があります。後者の形式は推奨されておらず、将来的に削除される予定です。

ビデオプロセッサーがマルチモーダルプロセッサーの一部である場合、その設定は代わりにprocessor_config.jsonにネストされます。詳細については、プロセッサーの保存と読み込みを参照してください。

使用例

llava-hf/llava-onevision-qwen2-0.5b-ov-hf モデルでビデオプロセッサを読み込む例を以下に示します。

from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf")

現在、ベースの image processor を動画に使用する場合、各フレームを個別の画像として扱い、フレームごとに変換を適用して動画データを処理します。このアプローチは機能しますが、効率は高くありません。AutoVideoProcessor を使用すると、高速な video processor を活用でき、torchvision ライブラリを利用できます。高速な processor は、各動画やフレームを反復せずに、動画のバッチ全体を一度に処理します。これらの更新により GPU アクセラレーションが導入され、特に高スループットを必要とするタスクにおいて、処理速度が大幅に向上します。

すべてのモデルで高速なビデオプロセッサが利用可能であり、AutoVideoProcessorを初期化するとデフォルトで読み込まれます。高速ビデオプロセッサを使用する場合は、device引数を設定して、処理を実行するデバイスを指定することもできます。デフォルトでは、入力がテンソルの場合は入力が存在するデバイス上で、それ以外の場合はCPU上で処理が行われます。さらに速度を向上させるには、アクセラレータをデバイスとして使用する場合にプロセッサをコンパイルできます。

import torch
from transformers.video_utils import load_video
from transformers import AutoVideoProcessor

device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"

video = load_video("video.mp4")
processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
processor = torch.compile(processor)
processed_video = processor(video, return_tensors="pt")

フレームサンプリング

Video processorは動画をデコードし、モデルが実際に参照するフレームを選択します。do_sample_frames=Trueを設定してサンプリングを有効にし、その後、以下の2つの方法のいずれかでフレームを選択します。

• num_frames は、動画全体に均等に分散した固定のフレーム数を指定します。
• fps は、1秒あたりのフレーム数でのレート指定を要求します。

パスまたはURLを渡すと、プロセッサがデフォルトのデコーダーであるtorchcodecを使用して動画をデコードします。torchcodecが利用可能でなく、かつ古いバージョンのtorchvisionを使用している場合、デコードはtorchvisionにフォールバックします。

return_metadata=True を追加すると、サンプリングされたフレームのインデックス、元の解像度、再生時間、fps が返されます。

from transformers import AutoVideoProcessor

processor = AutoVideoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
inputs = processor(videos=["video.mp4"], do_sample_frames=True, fps=1, return_metadata=True, return_tensors="pt")

print(inputs.pixel_values_videos.shape, inputs.video_grid_thw)
print(inputs["video_metadata"][0].total_num_frames)

サンプリングのデフォルト値はモデルごとに異なり、num_frames や fps へのリクエストは保証ではなく、あくまで出発点です。Qwen3-VL は fps=2 でサンプリングを行い、結果を min_frames=4 から max_frames=768 の範囲にクランプします。そのため、1秒のクリップでも4フレームが生成され、長い録画は実際のフレーム数よりはるかに少ない値で上限が設定されます。

temporal_patch_size を持つモデルでは、時間軸に沿ってその数だけフレームをグループ化してパッチにするという第2の制約が追加され、最後のフレームが繰り返されて、フレーム数が均等に割り切れるまで調整されます。

デコード済みの動画配列を渡す場合でも、モデル固有のサンプリングを行いたい場合は、video_metadata も提供してください。これを指定しないと、サンプラーは元の再生時間や fps を把握できず、fps によるサンプリングでは警告が表示され、動画が 24 fps で記録されたものと仮定されます。

import torch
from transformers import AutoVideoProcessor
from transformers.video_utils import VideoMetadata

processor = AutoVideoProcessor.from_pretrained("Qwen/Qwen3-VL-4B-Instruct")
video = torch.randint(0, 255, size=(100, 3, 1280, 1280))  # short video of 100 frames
video_metadata = VideoMetadata(total_num_frames=100, fps=24, duration=4.1)

inputs = processor(
    videos=[video], video_metadata=[video_metadata], do_sample_frames=True, num_frames=16, return_tensors="pt"
)