• 목록

Media Batch Manager 제품 명세서

1. 문서 정보

• 제품명: Media Batch Manager
• 현재 제품 버전: 1.1.0
• 문서 기준: 저장소의 현재 구현 및 배포 설정
• 목적: 제품의 대상 사용자, 기능, 처리 규칙, 운영 제약을 정의한다.
• 범위: 사용자가 이용하는 Windows 데스크톱 프로그램과 배포 요건

이 문서는 현재 코드에 구현된 동작을 설명한다. 향후 계획이나 미구현 기능을 약속하지 않는다.

2. 제품 개요

Media Batch Manager는 여러 동영상 파일을 한 번에 분석하고, 오디오·자막 트랙을 선택적으로 정리하거나 외부 자막을 병합해 출력하는 Windows GUI 프로그램이다. 입력 파일의 미디어 정보를 미리 확인하고, 실제 처리 전에 파일별 계획과 출력 경로를 검토할 수 있다.

트랙 구성이 바뀌는 작업은 FFmpeg를 사용해 재인코딩 없이 스트림을 재구성(remux)한다. 트랙 구성이 바뀌지 않는 작업은 선택한 출력 경로와 파일명 규칙에 따라 파일을 복사하거나 이동한다.

3. 대상 사용자 및 사용 목적

• 여러 영상의 오디오·자막 언어 구성을 일괄 정리하려는 사용자
• 같은 언어의 외부 자막 파일을 영상에 추가하거나 내장 자막 대신 사용하려는 사용자
• 미디어 라이브러리의 파일명과 폴더 구조를 정리하려는 사용자
• 작업 결과, 실패 원인, FFmpeg 출력을 파일별로 확인해야 하는 사용자

4. 실행 및 배포 요건

4.1 실행 환경

• 운영체제: Windows 10 버전 1809(빌드 17763) 이상
• 아키텍처: x64
• 런타임: .NET 8 Desktop Runtime (x64)
• 필수 외부 도구: ffmpeg.exe 및 ffprobe.exe

프로그램은 FFmpeg 도구를 앱 폴더의 ffmpeg 하위 폴더, 앱 실행 파일과 같은 폴더, 또는 PATH에서 자동으로 찾는다. 자동 검색에 실패하면 Tools > Options에서 각 실행 파일 경로를 지정할 수 있다. FFmpeg/ffprobe는 빌드 스크립트에서 앱과 함께 설치하지 않으므로 별도로 준비해야 한다.

4.2 배포

• build.bat은 version.txt의 버전을 읽어 Release 구성으로 win-x64 앱을 게시한다.
• 앱은 framework-dependent single-file 게시 방식이므로 .NET Desktop Runtime이 별도로 필요하다.
• Inno Setup 6 컴파일러가 있으면 설치 프로그램도 생성한다. 컴파일러가 없으면 앱 게시를 마친 뒤 설치 프로그램 생성을 건너뛴다.
• 설치 프로그램은 현재 사용자 권한으로 설치하며, 설치 중 .NET 8 Desktop Runtime이 감지되지 않으면 공식 다운로드 페이지를 열 수 있다.

5. 주요 사용자 흐름

1. 사용자가 동영상 파일 또는 폴더를 추가한다.
2. 폴더를 추가할 때 하위 폴더까지 검색할지 선택한다.
3. 프로그램이 ffprobe로 미디어 스트림을 분석하고, 인접한 외부 자막 후보를 검색한다.
4. 사용자가 오디오·자막 규칙, 출력 위치, 파일명 템플릿을 설정한다.
5. 큐에서 파일을 선택해 파일별 트랙 포함 여부를 조정하고 처리 계획을 확인한다.
6. Start를 눌러 선택된 준비 완료 파일을 순차 처리한다.
7. 진행률과 결과를 확인하고, 필요하면 트랜잭션 로그에서 상세 내역을 조회한다.

6. 기능 명세

6.1 파일 추가 및 큐 관리

• 파일 선택 대화상자, 폴더 선택 대화상자, 드래그 앤 드롭으로 입력을 받는다.
• 지원 입력 확장자: .mkv, .mp4, .m4v, .mov, .avi, .wmv, .ts, .m2ts, .webm
• 폴더 검색은 최상위 폴더만 또는 하위 폴더 포함 방식으로 수행한다.
• 이미 큐에 있는 경로와 중복 입력 파일은 대소문자를 구분하지 않고 한 번만 추가한다.
• 큐에서 파일명·경로 검색, 상태 필터링, 처리 선택 여부 설정을 지원한다.
• 선택 파일 제거, 완료 파일 제거, 실패 파일 제거, 전체 제거, 선택 항목 재분석을 지원한다.
• 큐에는 상태, 컨테이너, 영상 정보, 재생 시간, 오디오·자막 스트림, 계획 또는 실제 출력 경로, 경고를 표시한다.

6.2 미디어 분석 및 상세 정보

• ffprobe를 사용해 컨테이너, 길이, 비트레이트, 영상·오디오·자막 스트림과 첨부 파일 정보를 읽는다.
• 오디오 및 자막 스트림의 언어, 코덱, 제목, 기본/강제 상태 등 분석된 트랙 정보를 표시한다.
• 분석 중인 파일은 최대 3개까지 병렬 분석한다.
• 선택 파일의 스트림 목록에서 오디오·자막 트랙별로 Auto, Include, Exclude를 지정할 수 있다. 수동 지정은 언어별 자동 규칙에 우선한다.
• 선택 파일의 처리 계획, 미디어 정보, 자동 감지 파일명 필드를 별도 패널에서 확인할 수 있다.
• 입력 영상이 없거나, 언어 태그가 없거나, 도구 분석에 실패한 경우 상태 또는 경고를 표시한다.

6.3 오디오 처리

• 모드: 변경 없음, 지정 언어만 유지, 지정 언어 제거
• 언어 입력: 쉼표로 구분하며 언어 코드와 알려진 별칭을 정규화해 비교한다.
• und 등 언어 미지정 오디오를 유지하거나 제거하도록 설정할 수 있다.
• 기본값은 오디오 변경 없음이며, 기본 언어 목록은 kor,eng이다.
• 주 오디오가 모두 제거되거나, 원본에 주 오디오가 있는데 코멘터리/음성 설명 트랙만 남게 되는 계획은 차단한다.

6.4 내장 및 외부 자막 처리

• 내장 자막에도 오디오와 같은 변경 없음/지정 언어만 유지/지정 언어 제거 모드를 적용한다.
• 언어 미지정 자막의 유지 또는 제거 여부를 정할 수 있다.
• 외부 자막 자동 검색은 선택적으로 켜고 끌 수 있다.
• 외부 자막 파일은 영상과 같은 폴더에 <영상 파일명>.<언어 코드>.<확장자> 형식으로 있어야 한다.
• 외부 자막 지원 확장자: ASS/SSA, SRT, SMI/SAMI
• 같은 언어의 후보가 여러 개면 ASS/SSA, SRT, SMI/SAMI 순으로 우선한다. 동일 우선순위에 후보가 여러 개면 자동 선택하지 않고 경고한다.
• 외부 자막으로 같은 언어의 내장 자막을 대체하도록 설정할 수 있다. 강제 자막은 대체 중에도 유지하도록 처리한다.
• 지원되는 경우 이벤트 수와 페이로드 크기를 비교해 내장 자막과 동일한 외부 자막의 중복 병합을 피한다.
• UTF-8, BOM이 있는 UTF-8/UTF-16 및 일부 레거시 인코딩을 감지해 처리한다. 감지가 불확실하면 경고를 표시한다.
• 외부 텍스트 자막이 병합되는 작업에서는 출력이 Matroska(.mkv) 형식으로 생성된다.

6.5 출력 위치와 파일명

• 출력 위치는 지정 폴더 또는 원본 폴더 아래의 사용자 지정 하위 폴더 중 선택한다. 기본 하위 폴더 이름은 Processed이다.
• 트랙 변경이 필요한 파일은 .mkv로 출력한다. 트랙 변경이 없는 파일 정리 작업은 원본 확장자를 유지한다.
• 트랙 변경 작업에서 남은 오디오·자막 언어 태그를 파일명에 추가할 수 있다.
• 사용자 지정 영화 및 시리즈 파일명 템플릿을 지원한다. {title}, {year}, {resolution}, {audioLangs}, {subLangs}, {ext} 등의 토큰, 선택 그룹, 필드별 고정값 또는 자동 감지값을 사용할 수 있다.
• 파일명 템플릿은 원본 파일명과 ffprobe 정보에서 제목, 연도, 에디션, 소스, 코덱, 해상도, HDR, 오디오·자막 언어, 릴 그룹 등의 값을 채운다.
• 시리즈 판별은 자동, 항상 영화, 항상 시리즈 중 선택한다. 자동 회차 감지는 사용자 지정 정규식으로 조정할 수 있다.
• 시리즈 출력 폴더는 폴더 없음, 작품명, 작품명/시즌 폴더 중 선택한다. 영화·단편은 파일명과 같은 폴더를 만들도록 설정할 수 있다.
• 기존 파일과 이름이 충돌할 때 자동 번호 추가, 덮어쓰기, 건너뛰기 중 선택한다.
• 외부 자막 파일을 결과물과 함께 복사하고 출력 파일명에 맞춰 이름을 변경하는 옵션을 지원한다.

6.6 계획 확인 및 배치 실행

• 파일별 계획 미리보기에서 유지·제거·추가할 트랙, 경고, 출력 경로, 자막 부가 파일 복사 계획을 확인할 수 있다.
• 미리보기/검증은 출력 폴더를 생성하거나 파일을 변경하지 않는다.
• 처리 대상은 큐에서 선택되어 있고 분석 상태가 Ready 또는 Warning인 파일이다.
• 하나의 배치에서 FFmpeg 작업은 파일별로 순차 실행한다.
• 진행 UI에는 전체 및 현재 파일 진행률, 현재 파일명, 경과 시간, 처리 수, 예상 남은 시간이 표시된다.
• Stop은 실행 중인 파일의 종료를 요청하고 다음 파일을 시작하지 않는다. Cancel은 실행 중인 FFmpeg 프로세스 트리를 즉시 종료하고 나머지 파일을 취소한다.
• 처리 중에는 큐와 설정을 잠근다.
• FFmpeg 출력은 임시 .partial 파일로 작성한 후, 파일이 비어 있지 않고 ffprobe에서 영상 스트림이 확인될 때 최종 출력 파일로 확정한다.
• 트랙 구성이 바뀌지 않는 작업은 파일 복사 또는 이동으로 수행할 수 있으며, 원본 삭제 옵션이 켜져 있으면 성공한 작업에서 이동 방식이 사용될 수 있다.

6.7 원본 및 부가 파일 처리

• Delete origin files는 사용자의 확인을 받은 뒤에만 실행한다.
• 출력 검증과 관련 부가 자막 처리가 성공한 뒤 원본을 삭제한다.
• Windows 휴지통 사용이 가능한 경로·파일은 휴지통으로 보내며, 네트워크/이동식 드라이브, 휴지통 비활성화, 용량 제한 등의 경우 영구 삭제될 수 있다.
• 휴지통을 사용할 수 없는 상황과 영구 삭제 가능성은 실행 전 계획 및 확인 대화상자에 안내한다.
• 원본 미디어 파일은 설치 제거 과정에서 삭제하지 않는다.

6.8 프로필, 설정 및 로그

• 처리 설정을 이름 있는 프로필로 저장·불러오기·삭제할 수 있다.
• 마지막 처리 설정, 창 크기, FFmpeg/ffprobe 경로, 로그 보관 개수는 사용자 AppData의 MediaBatchManager 아래에 저장된다.
• 트랜잭션 로그는 JSON 형식으로 저장하며, 파일별 상태, 입출력 경로, 실행 모드, FFmpeg 명령 및 출력, 오류, 원본 처리 결과를 포함할 수 있다.
• 로그 뷰어에서 트랜잭션, 파일별 작업, 파일 상세 내역을 탐색한다.
• 로그 정리 로직은 최근 로그 20개를 보관한다. Options 화면에는 1~500개 보관 개수 설정이 있지만, 현재 로그 정리 동작은 이 설정값을 반영하지 않고 20개를 기준으로 한다.
• 프로그램 제거 시 사용자 설정·프로필·로그 데이터를 제거한다.

7. 상태 및 오류 처리

파일 상태는 대기 분석, 분석 중, 준비 완료, 경고, 분석 오류, 대기열 등록, 처리 중, 완료, 실패, 취소, 건너뜀 등의 상태로 관리한다.

• 필수 외부 도구를 찾지 못하면 설정 경로를 지정하도록 안내한다.
• 분석 및 FFmpeg 실행 오류는 큐 상태와 상세 로그에 기록한다.
• FFmpeg 결과가 없거나 비어 있거나 영상 스트림을 확인할 수 없으면 실패로 처리하고 임시 결과를 정리한다.
• 처리 계획에서 오디오 보존 규칙을 위반하면 해당 파일을 처리하지 않고 차단 사유를 표시한다.
• 외부 자막 인코딩·파일 충돌 등 자동 처리에 주의가 필요한 상황은 경고로 표시한다.

8. 비기능 요구사항 및 제약

• 프로그램은 .NET 8 및 Windows Forms 기반의 x64 데스크톱 애플리케이션이다.
• FFmpeg 스트림 복사(remux) 중심으로 처리해 영상·오디오 재인코딩을 수행하지 않는다.
• 미리보기와 실제 실행은 동일한 작업 계획 로직을 사용한다.
• FFmpeg/ffprobe는 앱 외부 의존성이며, 사용자가 접근 가능한 실행 파일 경로에 있어야 한다.
• UI는 주로 영어 레이블을 사용하며 일부 옵션 설명과 도움말에 한국어 문구가 포함된다.
• 입력 미디어의 암호 해제, 손상 복구, 영상·음성 재인코딩 기능은 현재 범위에 포함하지 않는다.