# Video Processor

Um **Video Processor** é uma utilitário responsável por preparar os recursos de entrada para modelos de vídeo, bem como por tratar o pós-processamento de suas saídas. Ele fornece transformações como redimensionamento, normalização e conversão para PyTorch.

O processador de vídeo estende a funcionalidade dos processadores de imagem, permitindo que os modelos tratem vídeos com um conjunto distinto de argumentos em comparação com imagens. Ele atua como a ponte entre os dados brutos de vídeo e o modelo, garantindo que os recursos de entrada sejam otimizados para o VLM.

Use [from_pretrained()](/docs/transformers/main/pt/main_classes/video_processor#transformers.VideoProcessorMixin.from_pretrained) para carregar a configuração de um processador de vídeo (tamanho da imagem, se normalizar e reescalar, etc.) a partir de um modelo de vídeo no [Hub](https://hf.co) do Hugging Face ou em um diretório local. A configuração de cada modelo pré-treinado deve ser salva em um arquivo [video_preprocessor_config.json], mas modelos mais antigos podem ter a configuração salva em um arquivo [preprocessor_config.json](https://huggingface.co/llava-hf/llava-onevision-qwen2-0.5b-ov-hf/blob/main/preprocessor_config.json). Observe que este último é menos recomendado e será removido no futuro.

Quando um processador de vídeo faz parte de um processador multimodal, sua configuração fica aninhada em `processor_config.json`. Consulte [Salvar e carregar um processador](./processors#save-and-load-a-processor) para mais detalhes.

## Exemplo de uso

Aqui está um exemplo de como carregar um processador de vídeo com o modelo [`llava-hf/llava-onevision-qwen2-0.5b-ov-hf`](https://huggingface.co/llava-hf/llava-onevision-qwen2-0.5b-ov-hf):

```python
from transformers import AutoVideoProcessor

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

Atualmente, ao usar o processador de imagem base para vídeos, os dados de vídeo são processados tratando cada quadro como uma imagem individual e aplicando transformações quadro a quadro. Embora funcional, essa abordagem não é muito eficiente. O uso de `AutoVideoProcessor` permite aproveitar os **processadores de vídeo rápidos**, utilizando a biblioteca [torchvision](https://pytorch.org/vision/stable/index.html). Os processadores rápidos lidam com o lote inteiro de vídeos de uma vez, sem iterar sobre cada vídeo ou quadro. Essas atualizações introduzem aceleração por GPU e aumentam significativamente a velocidade de processamento, especialmente para tarefas que exigem alto throughput.

Processadores de vídeo rápidos estão disponíveis para todos os modelos e são carregados por padrão quando um `AutoVideoProcessor` é inicializado. Ao usar um processador de vídeo rápido, você também pode definir o argumento `device` para especificar o dispositivo no qual o processamento deve ser realizado. Por padrão, o processamento é feito no mesmo dispositivo dos inputs, caso os inputs sejam tensors, ou na CPU, caso contrário. Para uma melhoria ainda maior de velocidade, podemos compilar o processador ao usar um acelerador como dispositivo.

```python
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")
```

## Amostragem de quadros

Um video processor decodifica um vídeo e seleciona os frames que o modelo realmente vê. Defina `do_sample_frames=True` para ativar a amostragem e, em seguida, escolha os frames de uma das duas formas.

- `num_frames` solicita uma contagem fixa distribuída uniformemente ao longo do vídeo.
- `fps` solicita uma taxa em quadros por segundo.

Passe um caminho ou URL e o processador decodifica o vídeo para você com [torchcodec](https://meta-pytorch.org/torchcodec/stable/index.html), o decodificador padrão. Se o torchcodec não estiver disponível e você estiver usando uma versão mais antiga do torchvision, a decodificação usa o torchvision como alternativa.

Adicione `return_metadata=True` para obter de volta os índices dos quadros amostrados, as dimensões originais, a duração e o fps.

```python
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)
```

Os padrões de amostragem são específicos de cada modelo, e uma solicitação de `num_frames` ou `fps` é um ponto de partida, não uma garantia. O Qwen3-VL amostra em `fps=2` e limita o resultado entre `min_frames=4` e `max_frames=768`, de modo que um clipe de um segundo ainda gera 4 frames e uma gravação longa é limitada a um valor muito inferior ao seu número real de frames.

Modelos com `temporal_patch_size` adicionam uma segunda restrição, na qual os quadros são agrupados em patches com esse número de quadros ao longo do eixo do tempo, e o quadro final é repetido até que a contagem seja divisível.

Se você passar um array de vídeo já decodificado e ainda quiser amostragem específica do modelo, forneça também `video_metadata`. Sem ele, o amostrador não sabe a duração original ou o fps, e a amostragem por `fps` emite um aviso e assume que o vídeo foi gravado a 24 fps.

```python
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"
)
```