장애 대응 점검표 - 증상에서 원인까지 찾아가는 순서

#문제 조사의 기본 순서

영상 처리 문제는 원인이 입력 파일, 변환 설정, 도구 버전, 스토리지, 네트워크 중 어디에나 있을 수 있습니다. 감으로 짐작하기 전에 순서대로 좁혀 가는 습관이 시간을 줄여 줍니다.

① 증상을 정확히 기록 → ② 입력 파일 분석 → ③ 재현 → ④ 최소화 → ⑤ 변수 하나씩 비교 → ⑥ 원인 확정·수정 → ⑦ 재발 방지

#① 증상을 정확히 기록

"영상이 이상해요"를 그대로 두지 말고 다음을 모읍니다.

어느 소재(ID), 어느 파일(원본/프록시)인가
어느 시점(타임코드) 에서 무엇이 어떻게 이상한가(캡처 포함)
언제부터인가, 다른 소재도 그런가
어느 환경(브라우저, 플레이어, 서버)에서 그런가

#② 입력 파일 분석

문제의 절반은 입력 파일의 특성에서 옵니다. 3장의 도구로 먼저 확인합니다.

MediaInfo, FFprobe: 코덱, 프레임레이트(분수), 스캔 타입, 타임코드, 스트림 구성
프레임 통계: GOP, VFR 여부
구조 검사: 완결성(Footer/RIP, moov), 프레임 수 vs 길이
체크섬: 인제스트 때 기록한 값과 현재 값

#③ 재현

같은 파일, 같은 명령으로 같은 증상이 다시 나오는지 확인합니다. 재현이 안 되면 환경(버전, 부하, 동시성, 스토리지 상태)을 의심합니다.

#④ 최소화

긴 영상은 문제 구간만 잘라 쓴다(-ss, -t; 재인코딩 컷 또는 정확 컷, 4장).
복잡한 필터 체인은 하나씩 제거해 증상이 사라지는 지점을 찾는다.
작은 파일로 줄이면 시도 속도가 빨라지고 회귀 테스트 샘플로도 쓸 수 있다.

#⑤ 변수를 하나씩 바꿔 비교

바꿔 볼 변수	예
입력	정상 파일 vs 문제 파일
도구 버전	FFmpeg 버전을 바꿔 비교
옵션	필터·프로파일·코덱 설정
환경	다른 서버, 다른 스토리지 경로
복본	아카이브 복본과 비교

한 번에 여러 개를 바꾸면 무엇이 원인이었는지 알 수 없습니다.

#증상별 점검표

증상	먼저 볼 것	상세
파일이 안 열림	구조(`moov`, Footer/RIP), 잘림	3장, 4장 7편
길이·프레임 수가 다름	컨테이너 길이 vs `-count_frames`, VFR, TS 타임스탬프	3장, 사례 4
프록시와 원본 구간이 어긋남	시작 타임코드, DF/NDF, 프레임레이트	사례 1
입 모양과 소리가 어긋남	스트림 `start_time` 차이, VFR	사례 2
빗살 무늬 / 흐릿한 윤곽	스캔 플래그 vs `idet`	사례 3
화면이 눌리거나 늘어남	SAR/DAR	4장 5편
소리가 한쪽/일부만 나옴	트랙·채널 매핑, `-map`	4장 4편
소리가 사라짐	`-map`으로 오디오 선택 여부	4장 1편
브라우저에서 재생 안 됨	`pix_fmt`, H.264 프로파일	4장 7편
웹 재생 시작이 느림	`faststart`, GOP 길이	2장
일부 구간이 깨짐	디코딩 경고, 체크섬, 복본	사례 4
변환이 멈춘/느림	입력 스토리지 읽기 속도, 동시 작업 수, 큐	5장
검색이 안 됨	색인 동기화, 2글자 검색, 토크나이저	5장 5편

#운영 시스템에 심어 둘 사전 방어

문제가 생긴 뒤 조사하는 것보다 미리 걸러 내는 장치가 훨씬 싸게 먹힙니다.

장치	효과
인제스트 구조 검사 + 체크섬	손상·잘림 파일의 유입 차단
분석 결과 정규화 + 경고	비표준 프레임레이트, 홀수 해상도, 스캔 불일치 조기 발견
변환 결과 검증(길이, 스트림 수, 타임코드, 프로파일)	잘못된 변환 결과의 등록 방지
변환 로그 수집(경고 포함)	손상 은폐(concealment) 감지
도구 버전 고정 + 샘플 회귀 테스트	버전 업그레이드로 인한 변경 감지
작업 이력(명령, 버전, 종료 코드, 소요 시간)	사후 조사 가능
파생물에 원본 체크섬 기록	원본-프록시 불일치 감지
정기 무결성 점검	조용한 손상 감지
샘플 파일 라이브러리	문제가 생긴 파일을 모아 회귀 테스트 세트로 활용

#회귀 테스트 세트

문제를 해결할 때마다 해당 샘플 파일(작게 줄인 것)과 기대 결과를 테스트 세트에 추가하세요. 시간이 지나면 이 세트가 가장 가치 있는 자산이 됩니다.

samples/
  df_timecode_prores.mov        # DF 타임코드 보존
  tff_flag_progressive.mxf      # 플래그는 인터레이스, 내용은 프로그레시브
  audio_start_offset.mp4        # 오디오 시작 0.5초 지연
  truncated_footer.mxf          # Footer/RIP 없음
  vfr_gap.mp4                   # 프레임 하나 누락
expected.json                   # 각 샘플의 기대 분석 결과

도구나 FFmpeg 버전을 바꿀 때 이 세트로 분석 결과를 비교하면 영향 범위를 바로 알 수 있습니다.

#기록과 공유

문제와 해결 과정을 짧은 문서(증상, 원인, 확인 방법, 해결)로 남깁니다. 같은 증상은 반드시 다시 나타납니다.
담당자가 바뀌어도 쓸 수 있도록 재현 파일과 명령을 함께 보관합니다.
외부 장비·소프트웨어의 문제라면 재현 파일과 로그를 포함해 제조사에 문의하면 해결이 빠릅니다(고객 자료를 외부로 보낼 때는 반드시 보안 정책을 확인하세요).

#정리

조사는 증상 기록 → 입력 분석 → 재현 → 최소화 → 변수 비교 순서로 합니다.
증상별 점검표로 의심 지점을 빠르게 좁히고, 이 가이드의 해당 장으로 되돌아가 확인합니다.
사전 방어(검증·정규화·체크섬·회귀 테스트)와 기록이 장애를 줄이고, 해결한 문제를 자산으로 만듭니다.