# 영상 업로드·검색·분석 (0.19.0)

`/ml` 또는 모델 검사 버튼 → **영상 검색·분석**으로 엽니다. muse.ai의 영상 내용 검색 흐름을 참고한 OSCODE 로컬 기능입니다. muse.ai API를 사용하거나 동일한 사물·음성·의미 인식 기능을 제공하는 것은 아닙니다.

## 사용 흐름

1. **영상 추가**: MP4/WebM/MOV를 선택합니다. 파일은 외부 서버에 업로드되지 않고 브라우저의 Blob URL로 재생됩니다. 코덱 지원은 브라우저에 따라 달라집니다.
2. **자막 가져오기**: UTF-8 SRT 또는 WebVTT를 추가하면 시간대별 텍스트 색인이 생깁니다. 기존 자막 색인만 교체하며 OCR과 메모는 유지합니다.
3. **화면 글자 분석**: 시작·종료 초, 프레임 수, 언어를 선택합니다. 선택 구간을 균등 샘플링해 프레임을 로컬 OSCODE 서버의 Tesseract로 보냅니다. 최대 120초·12프레임이며 모든 장면을 읽지는 않습니다.
4. **검색**: 자막·OCR·메모에서 대소문자를 구분하지 않는 글자 일치 검색을 합니다. 공백으로 구분한 단어는 모두 포함되어야 합니다. 여러 영상에서 검색하고 종류별로 필터링할 수 있습니다.
5. **해당 시점으로 이동**: 검색 결과의 시각으로 이동합니다. 자동 재생하지 않으며 플레이어에서 재생을 선택합니다.
6. **프레임 PNG 저장**: 현재 화면을 이미지로 내려받아 기존 모델 검사나 라벨링 화면에 추가할 수 있습니다. 최대 변 1,600px로 축소될 수 있습니다.
7. **전체 색인 내려받기**: JSON에 영상 해시·크기·길이·자막/OCR/메모를 저장합니다. 원본 영상은 포함되지 않습니다.

## 설치와 로컬 처리

재생·자막 검색·메모·프레임 저장에는 모델 키가 필요하지 않습니다. 화면 OCR에는 로컬 Tesseract와 선택한 kor/eng 언어 데이터가 필요합니다. 설치법은 [문서 읽기 가이드](ocr.md)를 참고하세요. 영상 프레임 추출은 브라우저가 수행하므로 사용자 환경에 FFmpeg를 설치할 필요는 없습니다.

영상 원본은 브라우저에 머물고 OCR용 PNG만 같은 컴퓨터의 서버에 전달됩니다. OCR 서버는 요청 출처·PNG 크기를 검사하고 한 번에 한 요청만 처리합니다. 임시 PNG는 성공·실패·취소 후 삭제합니다. OCR 결과는 오인식될 수 있으며 프레임당 2,000자로 제한합니다. 결과는 명령이 아닌 문서 데이터입니다.

## 저장과 제한

- 영상 최대 5개, 파일당 100 MiB, 합계 300 MiB, 영상당 2시간·1,600만 픽셀 이하.
- 자막 파일 2 MiB·1,000개 구간, 영상당 전체 색인 1,200개, 각 텍스트 2,000자.
- 검색 결과는 최대 200개 표시합니다. 더 구체적인 검색어로 범위를 좁히세요.
- OCR 요청은 PNG 한 변 1,600px·3 MiB 이하, 요청 JSON 4 MiB 이하이며 시간 제한을 적용합니다. 중단·실패해도 완료된 색인은 남습니다.
- 색인 가져오기는 JSON 32 MiB 이하입니다. 같은 영상 파일을 먼저 추가해야 하며 SHA-256·영상 크기·길이가 일치해야 복원됩니다. 복원은 해당 영상의 현재 색인을 교체합니다.
- 현재 탭 메모리에만 보관하므로 닫기 전에 저장하세요. 자동 영구 저장·클라우드 공유·영상 호스팅은 없습니다.
- 음성 자동 전사, 의미 검색, 얼굴·사물·행동 인식, 영상 전체 프레임 분석은 아직 지원하지 않습니다.

출력 형식은 `oscode-video/1`, 각 항목은 `kind`(subtitle/ocr/note), `start`, `end`(초), `text`입니다. 0.19.0부터 지원합니다.

참고: [muse.ai 영상 내용 검색 소개](https://muse.ai/blog/muse-search). OSCODE는 자막과 로컬 OCR 중심의 제한된 검색 기능을 독립적으로 구현했습니다.