[VideoLLaMA 3][processor] load_video

load_video

• 요약하면, load_video 메서드는
  • ffmpeg 기반의 강력한 비디오 전처리 파이프라인을 구현하여,
  • 사용자가 원하는 구간, 해상도, 프레임 속도에 맞추어 비디오를 로드하고,
  • 모델에 적합한 형태의 프레임 데이터와 타임스탬프를 제공하는 역할을 수행
• load_video 메서드는
  • 주어진 비디오 파일을 로드하여 전처리한 후,
  • 비디오의 프레임들과 각 프레임의 타임스탬프를 추출해 반환

1. 입력 파라미터 설정 및 기본값 적용
   • 인자로 비디오 파일 경로(video_path), 시작 시간(start_time), 종료 시간(end_time), 프레임 속도(fps), 최대 프레임 수(max_frames), 출력 크기(size) 등 다양한 옵션을 받습니다.
   • fps와 max_frames 등은 전달되지 않은 경우, 객체의 기본값(self.fps, self.max_frames)을 사용

2. 특수 상황 처리

• 아래의 경우 load_video_from_ids 함수를 호출하여 비디오를 처리합니다.
  • 만약 시작 시간과 종료 시간이 모두 주어지고 두 시간의 차이가 1초 미만이거나,
  • 비디오 파일 경로가 디렉토리(프레임 이미지들이 저장된 경우) 또는 GIF 파일인 경우

3. ffmpeg를 이용한 비디오 정보 추출 및 전처리
   • ffmpeg.probe 함수를 사용하여 비디오 파일의 메타데이터(총 길이, 시작 시간, 해상도 등)를 추출
     • 추출한 정보에서 비디오 스트림을 찾아 해상도(w, h)와 재생 시작 시간을 확인
   • 필요한 경우, start_time과 end_time을 기반으로 비디오의 일부 구간을 잘라내기 위해
     • ffmpeg의 입력(input_kwargs)이나 출력(output_kwargs) 파라미터를 설정

4. 크기 조정 및 FPS 조정
   • size 인자가 제공되면: 비디오의 짧은 변의 길이에 맞추어 크기를 조정하고,
   • size_divisible 인자를 이용해: 새로운 해상도가 특정 값으로 나누어 떨어지도록 보정
   • fps 인자가 있으면, ffmpeg의 fps 필터를 사용해 프레임 속도를 조정

5. ffmpeg를 통한 비디오 디코딩 및 프레임 추출
   • ffmpeg.input과 ffmpeg.output을 사용하여
     • 비디오 스트림을 설정하고,
     • "rawvideo" 형식과 "rgb24" 픽셀 포맷으로 출력받습니다.
   • ffmpeg.run으로 실제 명령을 실행해 비디오를 디코딩하고,
     • 출력된 바이트 데이터를 NumPy 배열로 변환한 후, 프레임의 차원(채널, 높이, 너비)을 재배열

6. 타임스탬프 계산 및 프레임 샘플링
   • fps 정보와 시작 시간을 기반으로 각 프레임에 대응하는 타임스탬프를 계산
   • 만약 추출된 프레임 수가 max_frames보다 많을 경우, np.linspace 함수를 사용해 일정 간격으로 프레임을 재샘플링합니다.
   • temporal_factor가 1보다 큰 경우, 프레임 수가 해당 값으로 나누어 떨어지도록 마지막 프레임을 반복하여 패딩합니다.

7. 최종 결과 반환
   • 전처리된 프레임 리스트와 각 프레임에 대응하는 타임스탬프 리스트를 반환합니다.

load_video_from_ids

• load_video_from_ids 함수는 주어진 비디오 데이터(파일 경로 또는 디렉토리, GIF 등)를 읽어,
  • 지정된 시간 구간과 샘플링 기준에 따라 프레임과 타임스탬프를 추출
  • 특정 시간 구간 내의 프레임들을 샘플링하고, 이를 모델 입력에 적합한 형태로 반환하는 역할

1. 입력 파라미터 보정 및 시간 구간 결정
   • 인자로 주어지는 시작 시간(s)과 종료 시간(e)이 있을 경우, 음수가 아니도록 보정하고, s가 e보다 크면 서로 교환합니다.
   • 만약 두 값이 같다면 최소 1초의 구간을 확보하기 위해 e를 s + 1로 설정합니다.

2. 비디오 데이터 로딩
   • 디렉토리인 경우:
     • 디렉토리 내의 이미지 파일들을 정렬하여 프레임 파일 목록을 구성하며, 기본 FPS(3fps)를 사용
   • GIF 파일인 경우: imageio를 사용하여 GIF의 프레임들을 읽고, 기본 FPS(25fps)를 사용
   • 일반 비디오 파일인 경우:
     • decord의 VideoReader를 이용해 비디오 파일을 읽고, 평균 FPS와 총 프레임 수를 얻습니다.

3. 프레임 범위 및 인덱스 계산
   • 주어진 시작/종료 시간과 비디오 FPS를 기반으로
     • 시작 프레임(f_start)과 종료 프레임(f_end)을 계산
   • 이 범위 내의 프레임 인덱스 리스트(frame_indices)를 생성

4. 프레임 샘플링
   • 비디오의 지속 시간이 max_frames에 비해 짧고 fps가 주어졌다면, 'fps' 모드를 사용해 프레임 인덱스를 선택
   • 그렇지 않으면, 'uniform' 모드를 이용해 전체 구간에서 최대 max_frames 개의 프레임을 균등하게 샘플링

5. 프레임 데이터 추출
   • 선택된 인덱스에 따라 각 경우(디렉토리, GIF, 일반 비디오)에 맞게 프레임 데이터를 불러옵니다.
   • 불러온 프레임은 OpenCV 또는 VideoReader를 이용해 읽어오며, RGB 색상 순서로 변환되고, (N, H, W, C) 형태에서 (N, C, H, W) 형태로 재배열됩니다.

6. 타임스탬프 계산 및 temporal_factor 적용
   • 각 선택된 프레임에 대해, 인덱스를 FPS로 나눈 값을 기반으로 타임스탬프를 계산
   • temporal_factor가 1보다 큰 경우,
     • 프레임 수가 해당 값의 배수가 되도록 마지막 프레임을 복제해 패딩하며, 이에 맞춰 타임스탬프도 보정

7. 최종 반환
   • 처리된 프레임 리스트와 각 프레임에 대응하는 타임스탬프 리스트를 반환하여, 이후 모델 입력 또는 후처리 단계에서 사용할 수 있도록 합니다.