기술 · 실용 가이드
FFprobe가 표지 이미지를 골랐나요? 매핑 전에 영상 스트림을 확인하세요
첨부 이미지를 제외하고 후보 수를 센 다음, 같은 파일의 실제 스트림 인덱스로 미리보기를 검증합니다.
파일의 영상 스트림 중 하나가 표지 이미지일 수 있습니다. 스크립트가 첫 영상 행을 본편으로 간주하면 표지 크기를 읽거나 엉뚱한 썸네일을 만들 수 있습니다. 먼저 스트림 목록을 확인하세요. 출력 코덱을 바꾼다고 올바른 입력을 선택했다는 증거가 생기지는 않습니다.
이 절차는 완전하고 변경되지 않는 로컬 파일에서 영상 스트림 하나의 확인용 미리보기를 만드는 데 적용됩니다. 후보가 없거나 하나 또는 여러 개인 경우를 나눕니다. 라이브러리의 표지를 삭제하거나 선호하는 카메라 각도를 자동으로 고르거나 실시간 방송의 매핑을 고치는 절차는 아닙니다.
1. 범위를 좁히기 전에 전체 목록 보관하기
경로, 크기, 수정 시각, FFmpeg와 ffprobe 빌드를 기록하세요. 다른 프로그램이 다운로드하거나 다시 쓰는 중이라면 특히 변하지 않는 복사본을 사용해야 합니다. ffprobe -v error -show_streams -show_format -of json "INPUT"을 실행하고 표준 출력, 표준 오류, 종료 코드를 보관하세요. INPUT은 실제 경로로 바꿉니다. 탐색 실패는 별도 문제입니다. 일부만 나온 JSON이나 빈 출력을 정상 목록으로 취급하지 마세요.
각 스트림의 index, codec_type, codec_name, 크기, 태그, disposition을 확인하세요. 한 사례의 표지가 MJPEG였다고 모든 MJPEG 스트림을 제외해서는 안 됩니다. 프레임 수 누락이나 0처럼 보이는 프레임 속도만으로도 본편을 결정할 수 없습니다. 독립적인 Stack Overflow 질문에는 첨부 MJPEG 이미지가 H.264 영상보다 앞에 나타나는 사례가 있습니다.
2. 선택하기 전에 후보 수 세기
ffprobe -v error -select_streams V -show_entries stream=index,codec_name,width,height:stream_disposition=default,attached_pic:stream_tags=title,language -of json "INPUT"을 실행하세요. 대문자 V를 의도적으로 사용합니다. 명령이 성공한 뒤 streams 배열을 읽고, 없는 선택적 메타데이터는 미상으로 남겨 두세요. 인식된 표지 스트림은 제외하지만 잘못 표시된 모든 정지 이미지를 식별하지는 못합니다.
후보가 없으면 목록을 보관하고 영상 미리보기 절차를 멈춥니다. 표지가 있는 오디오 파일에서는 정상일 수 있습니다. 하나면 실제 index를 보관한 뒤 화면을 확인합니다. 여러 개면 이름, 크기, 미리보기를 비교해 원하는 트랙을 명시적으로 고릅니다. default 표시나 큰 해상도는 단서일 뿐 원하는 내용을 대신 결정하지 않습니다. 모호함을 숨기려고 :0을 붙이지 마세요.
3. 배열 위치 대신 실제 인덱스 전달하기
필터링된 JSON에 index: 1인 행 하나가 있다고 가정합니다. 배열에서는 streams[0]이지만 입력 스트림 번호는 여전히 1입니다. 같은 파일을 FFmpeg의 첫 입력으로 사용한다면 명시적 매핑은 0:1입니다. 앞의 0은 입력 파일, 뒤의 1은 그 안의 스트림입니다. 스크립트에서는 index를 선택한 파일 및 선택 근거와 함께 보관하세요.
파일, 입력 순서 또는 디먹싱 옵션이 달라지면 다시 탐색하세요. 실시간 URL, 계속 갱신되는 재생목록, 녹화 중인 파일에는 그대로 적용하지 마세요. 다시 열었을 때 다른 목록이 관측될 수 있습니다. Jellyfin의 실시간 TV 보고서에도 이런 열거 불일치 사례가 있습니다. 개별 보고이며 모든 로컬 컨테이너나 실시간 소스의 동작을 보장하는 것은 아닙니다.
4. 별도 미리보기를 만들고 오류 원인 구분하기
확인한 인덱스가 1이라면 ffmpeg -hide_banner -loglevel error -nostdin -n -i "INPUT" -map 0:1 -frames:v 1 "preview-check.jpg"을 실행하세요. 실제 인덱스를 넣고 존재하지 않는 출력 이름을 사용합니다. 이 명령은 오디오나 다른 트랙 없이 이미지 한 장만 만듭니다. 열어서 알아볼 수 있는 내용이 원하는 영상인지 확인하세요. 시작 화면이 검다면 뒤쪽의 다른 샘플을 별도로 확인할 수 있습니다.
화면 선택은 맞는데 코덱이나 비트스트림 필터 오류가 남으면 표지를 지우지 말고 전체 명령을 조사하세요. Immich의 과거 썸네일 장애는 HEVC 메타데이터 필터가 MJPEG 첨부 이미지까지 포함한 영상 스트림에 너무 넓게 적용된 사례였습니다. 승인된 수정은 필터를 선택된 스트림으로 제한했으며 2026년 5월 1일 병합됐습니다. 이는 옵션 적용 범위라는 별도 문제를 보여 주며, 현재 모든 Immich 설치에 같은 버그가 있다는 증거는 아닙니다.
5. 검증 범위를 명확히 기록하기
합성 테스트에는 Ubuntu FFmpeg 6.1.1-3ubuntu5를 사용했습니다. 표지가 있는 MP3는 v 스트림 하나와 V 스트림 0개를 반환했습니다. 오디오가 먼저인 MP4는 V 후보 하나를 반환했고 배열 위치는 0이지만 절대 인덱스는 1이었습니다. 영상이 두 개인 MP4는 후보 두 개여서 사람의 선택을 기다리도록 멈췄습니다. 단일 후보 미리보기는 열렸고 선택한 전체 스트림 디코딩은 종료 코드 0이었으며, 입력 파일 세 개의 해시는 모두 그대로였습니다.
Immich 보고의 DJI 원본, 실시간 입력, 모든 FFmpeg 빌드를 시험한 것은 아닙니다. 실제 파일에서는 목록, 선택 인덱스, 정확한 명령과 결과를 보관하세요. 추가 디코딩 검사는 ffmpeg -hide_banner -loglevel error -nostdin -i "INPUT" -map 0:1 -f null -이며 인덱스를 바꿔야 합니다. 선택한 스트림을 읽으므로 전체 영상 처리 시간이 걸릴 수 있습니다. 종료 코드와 표준 오류를 함께 살피세요. 올바른 정지 화면 한 장이나 정상 디코딩만으로 선호하는 촬영 각도 또는 이후 내보내기의 모든 트랙 보존까지 증명되지는 않습니다.
