# 비디오 프로세서

**Video Processor**는 비디오 모델의 입력 특징을 준비하고 출력의 후처리를 담당하는 유틸리티입니다. 리사이징, 정규화, PyTorch로의 변환과 같은 변환을 제공합니다. `VideoProcessor` 클래스는 변환과 함께 로컬 경로 또는 URL로부터의 비디오 디코딩([`torchcodec`](https://pypi.org/project/torchcodec/) 필요) 및 모델별 전략에 따른 프레임 샘플링을 처리합니다.

video processor는 이미지와 구별되는 고유한 인자 세트를 사용하여 VLM(Vision Large Language Models)이 비디오를 처리할 수 있도록 함으로써 이미지 프로세서의 기능을 확장합니다. 이는 원시 비디오 데이터와 모델 간의 가교 역할을 하며, 입력 기능이 VLM에 최적화되도록 보장합니다.

Video processor 설정은 `video_preprocessor_config.json`에 저장됩니다. 이전 체크포인트의 경우 `preprocessor_config.json`에 저장되어 있을 수 있습니다. 재로드 시 커스텀 백엔드 등록에 대해서는 [저장 및 재로드](#save-and-reload)를 참조하세요.

## 사용 예시

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

Preprocessing은 입력 텐서의 디바이스에서 실행되며, 다른 입력의 경우 CPU에서 실행됩니다. `device`를 설정하여 전처리 전에 비디오를 다른 디바이스로 이동할 수 있으며, 이는 백엔드를 변경하지 않습니다. 가속기를 사용하는 경우 `torch.compile`로 torchvision 전처리를 컴파일할 수도 있습니다.

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

## Video processor 백엔드

내장 비디오 프로세서에서는 배치 리사이징, 리스케일링, 정규화를 위해 [torchvision](https://pytorch.org/vision/stable/index.html)을 사용합니다. 이를 사용하려면 PyTorch와 torchvision을 설치해야 합니다. 이미지 프로세서와 달리, 내장 비디오 프로세서는 PIL 백엔드를 제공하지 않습니다.

[AutoVideoProcessor](/docs/transformers/v5.24.0/ko/model_doc/auto#transformers.AutoVideoProcessor)는 기본적으로 `torchvision` 백엔드를 선택합니다. 명시적으로 요청할 수도 있으며, 로드된 프로세서의 `backend` 속성을 검사할 수 있습니다.

```python
from transformers import AutoVideoProcessor

model_id = "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
video_processor = AutoVideoProcessor.from_pretrained(model_id, backend="torchvision")
print(video_processor.backend)
# torchvision
```

`backend` 인자는 비디오 디코더가 아니라 전처리 구현을 선택합니다. 디코딩 및 프레임 샘플링에 대해서는 [샘플링 동작](#sampling-behavior)을 참조하세요.

### 사용자 지정 백엔드

[BaseVideoProcessor](/docs/transformers/v5.24.0/ko/main_classes/video_processor#transformers.BaseVideoProcessor)는 torchvision 기반의 전처리 기능을 제공합니다. torchvision이 아닌 구현을 사용하려면 [VideoProcessorMixin](/docs/transformers/v5.24.0/ko/main_classes/video_processor#transformers.VideoProcessorMixin)을 서브클래스로 상속받아 `preprocess`를 오버라이드하고, 모델이 기대하는 입력을 포함하는 [BatchFeature](/docs/transformers/v5.24.0/ko/main_classes/feature_extractor#transformers.BatchFeature)를 반환하도록 하면 됩니다.

[AutoVideoProcessor.register()](/docs/transformers/v5.24.0/ko/model_doc/auto#transformers.AutoVideoProcessor.register)로 커스텀 클래스를 등록하고, `video_processor_classes`를 사용하여 백엔드 이름을 클래스에 매핑합니다. 아래 예시는 `NewCustomVideoProcessor`가 LLaVA-OneVision 체크포인트에 필요한 전처리를 포함하여 정의되어 있다고 가정합니다.

```python
from transformers import LlavaOnevisionConfig

AutoVideoProcessor.register(
    LlavaOnevisionConfig,
    video_processor_classes={"custom": NewCustomVideoProcessor},
    exist_ok=True,
)
custom_processor = AutoVideoProcessor.from_pretrained(model_id, backend="custom")
```

`LlavaOnevisionConfig`이 이미 등록되어 있으므로 `exist_ok=True`를 사용합니다. 제공된 항목은 해당 백엔드 매핑에 병합되며, 이름이 일치하는 항목은 대체되고, `torchvision`처럼 제공되지 않은 항목은 유지됩니다.

### 저장 및 다시 로드

[save_pretrained()](/docs/transformers/v5.24.0/ko/main_classes/video_processor#transformers.VideoProcessorMixin.save_pretrained)는 백엔드 매핑이 아닌 전처리 구성을 저장합니다. [AutoVideoProcessor.register()](/docs/transformers/v5.24.0/ko/model_doc/auto#transformers.AutoVideoProcessor.register)로 추가한 백엔드 매핑은 저장되지 않습니다. 동일한 Python 프로세스에서 `backend="custom"`를 사용하여 저장된 프로세서를 다시 로드합니다:

```python
custom_processor.save_pretrained("./saved-video-processor")
custom_processor = AutoVideoProcessor.from_pretrained("./saved-video-processor", backend="custom")
```

커스텀 등록은 현재 Python 프로세스에만 적용됩니다. 새 프로세스에서는 커스텀 클래스를 정의하거나 가져온 후, 로딩 전에 다시 등록해야 합니다.

## 샘플링 동작

Video processor는 주어진 모델에 가장 적합한 기법을 사용하여 비디오 프레임을 샘플링할 수도 있습니다. 샘플링 동작은 `do_sample_frames` 인자로 제어되며, `num_frames` 또는 `fps`(비디오가 샘플링되는 비율)와 같은 모델별 파라미터를 통해 설정할 수 있습니다. 입력 비디오가 로컬 경로 또는 URL(`str`)로 제공되는 경우, 프로세서가 자동으로 디코딩합니다. 샘플링된 프레임 인덱스, 원래 해상도, 길이, fps와 같이 디코딩된 비디오에 대한 메타데이터를 얻으려면 프로세서에 `return_metadata=True`를 전달하세요.

- `num_frames`를 지정해도 출력이 정확히 해당 프레임 수를 포함한다고 보장되지 않습니다. 모델에 따라 샘플러가 최소 또는 최대 프레임 제한을 강제할 수 있습니다.

- 기본 디코더는 [`torchcodec`](https://pypi.org/project/torchcodec/)이며, 설치되어 있어야 합니다.

```python
import torch
from transformers import AutoVideoProcessor

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

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
processed_video_inputs = processor(videos=["video_path.mp4"], return_metadata=True, do_sample_frames=True, return_tensors="pt")
video_metadata = processed_video_inputs["video_metadata"]

# See how many frames the original video had and what was the original FPS
print(video_metadata.total_num_frames, video_metadata.fps)
```

이미 디코딩된 비디오 배열을 전달하되 모델별 프레임 샘플링을 활성화하려면, `VideoMetadata` 객체나 일반 dict로 video_metadata를 제공하는 것이 강력히 권장됩니다. 이를 통해 샘플러가 원본 비디오의 길이와 FPS를 알 수 있습니다.

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

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

processor = AutoVideoProcessor.from_pretrained("llava-hf/llava-onevision-qwen2-0.5b-ov-hf", device=device)
decoded_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, # in seconds
)
processed_video_inputs = processor(videos=[decoded_video], video_metadata=video_metadata, do_sample_frames=True, num_frames=10, return_tensors="pt")
print(processed_video_inputs.pixel_values_videos.shape)
[10, 3, 384, 384]
```

## VideoProcessorMixin[[transformers.VideoProcessorMixin]]

#### transformers.VideoProcessorMixin[[transformers.VideoProcessorMixin]]

```python
transformers.VideoProcessorMixin(**kwargs: *<class 'transformers.processing_utils.VideosKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L76)

#### fetch_videos[[transformers.VideoProcessorMixin.fetch_videos]]

```python
fetch_videos(video_url_or_urls: str | list[str] | list[list[str]], sample_indices_fn = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L559)

단일 URL 또는 URL 목록을 해당하는 `np.array` 객체로 변환합니다.

단일 url이 전달되면 반환 값은 단일 객체입니다. 목록이 전달되면 객체의 목록이 반환됩니다.

#### from_dict[[transformers.VideoProcessorMixin.from_dict]]

```python
from_dict(video_processor_dict: dict[str, typing.Any], **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L431)

**매개변수:**

video_processor_dict (`dict[str, Any]`) : video processor 객체를 인스턴스화하는 데 사용되는 사전. 이러한 사전은 `~video_processing_utils.VideoProcessorBase.to_dict` 메서드를 활용하여 사전 학습된 체크포인트에서 가져올 수 있습니다.

kwargs (`dict[str, Any]`) : video processor 객체를 초기화할 때 사용할 추가 매개변수.

**반환값:** `~video_processing_utils.VideoProcessorBase`

해당 파라미터에서 인스턴스화된 비디오 프로세서 객체입니다.

`~video_processing_utils.VideoProcessorBase`의 유형을 매개변수의 Python 사전에서 초기화합니다.

#### from_json_file[[transformers.VideoProcessorMixin.from_json_file]]

```python
from_json_file(json_file: str | os.PathLike)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L514)

**매개변수:**

json_file (`str` 또는 `os.PathLike`) : 매개변수가 포함된 JSON 파일의 경로.

**반환값:** `~video_processing_utils.VideoProcessorBase` 유형의 비디오 프로세서

해당 JSON 파일에서 인스턴스화된 video_processor 객체.

`~video_processing_utils.VideoProcessorBase` 유형의 비디오 프로세서 인스턴스를 매개변수 JSON 파일의 경로에서 생성합니다.

#### from_pretrained[[transformers.VideoProcessorMixin.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, cache_dir: str | os.PathLike | None = None, force_download: bool = False, local_files_only: bool = False, token: str | bool | None = None, revision: str = 'main', **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L142)

**매개변수:**

pretrained_model_name_or_path (`str` 또는 `os.PathLike`) : 다음 중 하나일 수 있습니다. - huggingface.co의 모델 저장소에 호스팅된 사전 학습된 비디오의 *model id*인 문자열. - `~video_processing_utils.VideoProcessorBase.save_pretrained` 메서드를 사용하여 비디오 프로세서 파일을 저장한 *디렉터리*의 경로, 예: `./my_model_directory/`. - 저장된 비디오 프로세서 JSON *파일*의 경로, 예: `./my_model_directory/video_preprocessor_config.json`.

cache_dir (`str` 또는 `os.PathLike`, *선택 사항*) : 표준 캐시를 사용하지 않을 경우, 다운로드된 사전 학습된 모델의 video processor를 캐시할 디렉터리의 경로입니다.

force_download (`bool`, *선택 사항*, 기본값 `False`) : 비디오 프로세서 파일을 (재)다운로드를 강제하고, 캐시된 버전이 존재하는 경우 이를 덮어쓸지 여부.

proxies (`dict[str, str]`, *선택*) : 프로토콜 또는 엔드포인트별로 사용할 프록시 서버의 사전입니다. 예: `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}.` 각 요청에 프록시가 사용됩니다.

token (`str` 또는 `bool`, *선택*) : 원격 파일에 대한 HTTP bearer 인증으로 사용할 토큰입니다. `True`이거나 지정되지 않은 경우, `hf auth login` 실행 시 생성된 토큰(`~/.huggingface`에 저장됨)을 사용합니다.

revision (`str`, *선택 사항*, 기본값 `"main"`) : 사용할 특정 모델 버전입니다. huggingface.co에서 모델 및 기타 산출물을 저장하기 위해 git 기반 시스템을 사용하므로, `revision`은 git에서 허용하는 모든 식별자, 즉 브랜치 이름, 태그 이름 또는 커밋 ID가 될 수 있습니다. Hub에서 만든 pull request를 테스트하려면 `revision="refs/pr/<pr_number>"`를 전달할 수 있습니다.

return_unused_kwargs (`bool`, *선택 사항*, 기본값 `False`) : `False`인 경우, 이 함수는 최종 video processor 객체만 반환합니다. `True`인 경우, 이 함수는 `Tuple(video_processor, unused_kwargs)`를 반환하며, 여기서 *unused_kwargs*는 video processor 속성이 아닌 키/값 쌍으로 구성된 사전입니다. 즉, `kwargs` 중 `video_processor`를 업데이트하는 데 사용되지 않고 무시되는 부분입니다.

subfolder (`str`, *선택 사항*, 기본값 `""`) : 관련 파일이 huggingface.co의 모델 저장소 내 하위 폴더에 있는 경우, 여기에 폴더 이름을 지정할 수 있습니다.

kwargs (`dict[str, Any]`, *선택*) : kwargs의 값 중 video processor 속성에 해당하는 키는 로드된 값을 덮어쓰는 데 사용됩니다. video processor 속성이 *아닌* 키/값 쌍에 대한 동작은 `return_unused_kwargs` 키워드 매개변수로 제어됩니다.

**반환값:**

`~video_processing_utils.ImagVideoProcessorBase` 유형의 비디오 프로세서입니다.

`~video_processing_utils.VideoProcessorBase`의 유형을 비디오 프로세서에서 인스턴스화합니다.

예:

```python
# We can't instantiate directly the base class *VideoProcessorBase* so let's show the examples on a
# derived class: *LlavaOnevisionVideoProcessor*
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf"
)  # Download video_processing_config from huggingface.co and cache.
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "./test/saved_model/"
)  # E.g. video processor (or model) was saved using *save_pretrained('./test/saved_model/')*
video_processor = LlavaOnevisionVideoProcessor.from_pretrained("./test/saved_model/video_preprocessor_config.json")
video_processor = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf", do_normalize=False, foo=False
)
assert video_processor.do_normalize is False
video_processor, unused_kwargs = LlavaOnevisionVideoProcessor.from_pretrained(
    "llava-hf/llava-onevision-qwen2-0.5b-ov-hf", do_normalize=False, foo=False, return_unused_kwargs=True
)
assert video_processor.do_normalize is False
assert unused_kwargs == {"foo": False}
```

#### get_video_processor_dict[[transformers.VideoProcessorMixin.get_video_processor_dict]]

```python
get_video_processor_dict(pretrained_model_name_or_path: str | os.PathLike, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L296)

**매개변수:**

pretrained_model_name_or_path (`str` 또는 `os.PathLike`) : 매개변수 사전(dictionary)을 가져오려는 사전 학습된 체크포인트의 식별자입니다.

subfolder (`str`, *선택 사항*, 기본값 `""`) : 관련 파일이 huggingface.co의 모델 저장소 내 하위 폴더에 있는 경우, 여기에 폴더 이름을 지정할 수 있습니다.

**반환값:** `tuple[Dict, Dict]`

video processor 객체를 인스턴스화하는 데 사용될 사전(들).

`pretrained_model_name_or_path`에서 매개변수 사전으로 해석하여, `from_dict`를 사용해 `~video_processing_utils.VideoProcessorBase` 유형의 비디오 프로세서 인스턴스를 생성하는 데 사용합니다.

#### preprocess[[transformers.VideoProcessorMixin.preprocess]]

```python
preprocess(videos: typing.Union[list['PIL.Image.Image'], numpy.ndarray, ForwardRef('torch.Tensor'), list[numpy.ndarray], list['torch.Tensor'], list[list['PIL.Image.Image']], list[list[numpy.ndarray]], list[list['torch.Tensor']], transformers.video_utils.URL, list[transformers.video_utils.URL], list[list[transformers.video_utils.URL]], transformers.video_utils.Path, list[transformers.video_utils.Path], list[list[transformers.video_utils.Path]]], **kwargs: *<class 'transformers.processing_utils.VideosKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L98)

**매개변수:**

videos (`Union[list[PIL.Image.Image], numpy.ndarray, torch.Tensor, list[numpy.ndarray], list[torch.Tensor], list[list[PIL.Image.Image]], list[list[numpy.ndarray]], list[list[torch.Tensor]], ~video_utils.URL, list[~video_utils.URL], list[list[~video_utils.URL]], ~video_utils.Path, list[~video_utils.Path], list[list[~video_utils.Path]]]`) : 전처리할 비디오입니다. 픽셀 값이 0에서 255 범위로 이루어진 단일 비디오 또는 비디오 배치(batch)를 입력으로 기대합니다. 픽셀 값이 0에서 1 범위로 이루어진 비디오를 전달하는 경우, `do_rescale=False`로 설정하십시오.

do_convert_rgb (`bool`, *kwargs*, *선택*) : 이미지를 RGB로 변환할지 여부.

do_resize (`bool`, *kwargs*, *선택*) : 이미지를 리사이즈할지 여부.

size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : 모델의 최대 입력 차원을 설명합니다.

default_to_square (`bool`, *kwargs*, *선택*) : size가 int인 경우 리사이즈 시 정사각형 이미지로 기본 설정할지 여부.

resample (`Annotated[Union[int, PILImageResampling, NoneType], None]`, *kwargs*) : 이미지를 리사이즈할 때 사용할 리샘플링 필터입니다. `PILImageResampling` enum 중 하나를 사용할 수 있습니다. `do_resize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_rescale (`bool`, *kwargs*, *선택*) : 이미지를 다시 스케일링할지 여부.

rescale_factor (`float`, *kwargs*, *선택*) : `do_rescale`가 `True`로 설정된 경우 이미지를 재조정하는 데 사용되는 재조정 계수입니다.

do_normalize (`bool`, *kwargs*, *선택*) : 이미지를 정규화할지 여부.

image_mean (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택*) : 정규화에 사용할 이미지 평균값. `do_normalize`이 `True`로 설정된 경우에만 효과가 있습니다.

image_std (`Union[float, list[float], tuple[float, ...]]`, *kwargs*, *선택*) : 정규화에 사용할 이미지 표준 편차. `do_normalize`가 `True`로 설정된 경우에만 효과가 있습니다.

do_center_crop (`bool`, *kwargs*, *선택*) : 이미지를 중앙 크롭할지 여부.

do_pad (`bool`, *kwargs*, *선택*) : 이미지를 패딩할지 여부입니다. 패딩은 배치 내 가장 큰 크기로 수행하거나, 이미지마다 고정된 정사각형 크기로 수행합니다. 정확한 패딩 전략은 모델에 따라 달라집니다.

crop_size (`Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None]`, *kwargs*) : `center_crop`를 적용한 후의 출력 이미지 크기.

data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : `ChannelDimension.FIRST`만 지원됩니다. 느린 프로세서와의 호환성을 위해 추가되었습니다.

input_data_format (`Union[str, ~image_utils.ChannelDimension]`, *kwargs*, *선택*) : 입력 이미지의 채널 차원 형식입니다. 설정하지 않으면 입력 이미지에서 채널 차원 형식을 추론합니다. 다음 중 하나일 수 있습니다: - `"channels_first"` 또는 `ChannelDimension.FIRST`: (num_channels, height, width) 형식의 이미지. - `"channels_last"` 또는 `ChannelDimension.LAST`: (height, width, num_channels) 형식의 이미지. - `"none"` 또는 `ChannelDimension.NONE`: (height, width) 형식의 이미지.

device (`Annotated[Union[str, torch.device, NoneType], None]`, *kwargs*) : 비디오를 처리할 장치입니다. 설정되지 않은 경우, 입력 비디오에서 장치를 추론합니다.

do_sample_frames (`bool`, *kwargs*, *선택*) : 처리 전에 비디오에서 프레임을 샘플링할지, 아니면 비디오 전체를 처리할지 여부.

video_metadata (`Annotated[~video_utils.VideoMetadata | dict | list[dict | ~video_utils.VideoMetadata] | list[list[dict | ~video_utils.VideoMetadata]] | None, None]`, *kwargs*) : 총 길이, fps, 총 프레임 수에 대한 정보를 포함하는 비디오의 메타데이터입니다. 비디오에서 프레임을 샘플링하거나 타임스탬프를 계산하는 데 사용됩니다. 비디오를 수동으로 디코딩하여 처리하려는 경우를 제외하고는 메타데이터를 전달하지 마세요

fps (`Annotated[int | float | None, None]`, *kwargs*) : `do_sample_frames=True`일 때 초당 샘플링할 대상 프레임 수.

num_frames (`Annotated[int | None, None]`, *kwargs*) : `do_sample_frames=True`일 때 샘플링할 최대 프레임 수.

return_metadata (`bool`, *kwargs*, *선택*) : 비디오 메타데이터를 반환할지 여부입니다. 비디오 메타데이터는 비디오 길이, fps, 디코딩 백엔드 등에 대한 정보를 포함하는 객체입니다.

return_tensors (`Annotated[str | ~utils.generic.TensorType | None, None]`, *kwargs*) : `'pt'`로 설정된 경우 스택된 텐서를 반환하고, 그렇지 않으면 텐서 목록을 반환합니다.

**반환값:** `~image_processing_base.BatchFeature`

- **data** (`dict`) -- __call__ 메서드가 반환하는 리스트/배열/텐서 딕셔너리('pixel_values' 등).
- **tensor_type** (`Union[None, str, TensorType]`, *선택 사항*) -- 초기화 시 PyTorch/Numpy 텐서에서 정수 목록을 변환하려면 여기에 tensor_type을 지정할 수 있습니다.

#### register_for_auto_class[[transformers.VideoProcessorMixin.register_for_auto_class]]

```python
register_for_auto_class(auto_class = 'AutoVideoProcessor')
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L533)

**매개변수:**

auto_class (`str` 또는 `type`, *선택 사항*, 기본값 `"AutoVideoProcessor "`) : 이 새로운 video processor를 등록할 auto class입니다.

이 클래스를 지정된 auto class에 등록합니다. 라이브러리에 포함된 video processor는 이미 `AutoVideoProcessor `에 매핑되어 있으므로, 이 메서드는 커스텀 video processor에만 사용해야 합니다.

이 API는 실험적이며 다음 릴리스에서 일부 경미한 호환성 변경 사항이 있을 수 있습니다.

#### save_pretrained[[transformers.VideoProcessorMixin.save_pretrained]]

```python
save_pretrained(save_directory: str | os.PathLike, push_to_hub: bool = False, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L248)

**매개변수:**

save_directory (`str` 또는 `os.PathLike`) : 비디오 프로세서 JSON 파일을 저장할 디렉터리(존재하지 않으면 생성됨).

push_to_hub (`bool`, *선택 사항*, 기본값 `False`) : 모델을 저장한 후 Hugging Face 모델 허브에 푸시할지 여부입니다. `repo_id`를 사용하여 푸시할 저장소를 지정할 수 있으며, 지정하지 않으면 네임스페이스 내 `save_directory`의 이름이 기본값으로 사용됩니다.

kwargs (`dict[str, Any]`, *선택*) : [push_to_hub()](/docs/transformers/v5.24.0/ko/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 메서드에 함께 전달되는 추가 키워드 인자입니다.

`save_directory` 디렉토리에 비디오 프로세서 객체를 저장하여 `~video_processing_utils.VideoProcessorBase.from_pretrained` 클래스 메서드를 사용해 다시 로드할 수 있도록 합니다.

#### to_dict[[transformers.VideoProcessorMixin.to_dict]]

```python
to_dict()
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L472)

**반환값:** `dict[str, Any]`

이 video processor 인스턴스를 구성하는 모든 속성의 사전입니다.

이 인스턴스를 Python 딕셔너리로 직렬화합니다.

## BaseVideoProcessor[[transformers.BaseVideoProcessor]]

#### transformers.BaseVideoProcessor[[transformers.BaseVideoProcessor]]

```python
transformers.BaseVideoProcessor(**kwargs: *<class 'transformers.processing_utils.VideosKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L587)

#### convert_to_rgb[[transformers.BaseVideoProcessor.convert_to_rgb]]

```python
convert_to_rgb(video: torch.Tensor)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L588)

**매개변수:**

video (`"torch.Tensor"`) : 변환할 비디오.

**반환값:** `torch.Tensor`

변환된 비디오.

비디오를 RGB 형식으로 변환합니다.

#### sample_frames[[transformers.BaseVideoProcessor.sample_frames]]

```python
sample_frames(metadata: VideoMetadata, num_frames: int | None = None, fps: int | float | None = None, **kwargs)
```

[소스](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/video_processing_utils.py#L605)

**매개변수:**

metadata (`VideoMetadata`) : 총 길이, fps, 총 프레임 수에 대한 정보를 포함하는 비디오의 메타데이터입니다.

num_frames (`int`, *선택 사항*) : 샘플링할 최대 프레임 수. 기본값은 `self.num_frames`입니다.

fps (`int` 또는 `float`, *선택 사항*) : 초당 샘플링할 대상 프레임 수. 기본값은 `self.fps`입니다.

**반환값:** `np.ndarray`

video 프레임에서 샘플링할 인덱스.

0부터 총 프레임 수까지 원하는 프레임 수를 균등하게 샘플링하는 기본 샘플링 함수입니다. 메타데이터와 함께 `fps`가 전달되면, 초당 `fps` 프레임이 균등하게 샘플링됩니다. `num_frames`와 `fps` 인수는 상호 배타적입니다.

