crowny-class 업로드 → 비동기 CVF 인코딩 배선
개요
/api/video/upload (admin) 업로드 시 mp4 저장 직후 CVF 인코딩을 백그라운드 잡으로 분리했다.
업로드 응답은 인코딩을 기다리지 않고 즉시 반환하고, 인코딩 완료/실패는 meta.cvfStatus로 갱신된다.
무엇을 했는지
scripts/encode-upload.sh <mp4path> <id> "<title>" 신규 작성
- ffmpeg 프레임 추출(fps9, scale 108:60) → mp3 사이드카(64k mono) → cvf-encoder.js(color9/gop9/depth8) →
ccp c로 cvf-archive/에 .ccp 보관
- 마지막 stdout 줄: 성공
ENCODE_DONE <바이트수> / 실패
ENCODE_ERROR <이유>
- 임시 프레임 디렉토리는 mktemp + trap 정리
modules/video/routes.js
-
handleUpload: saveJson 직전
meta.cvf/cvfAudio/cvfStatus:'encoding' 세팅 → 저장 → 즉시
{ok,id,...meta} 응답 → 그 다음
startEncodeJob()으로 encode-upload.sh를 spawn(비블로킹)
-
startEncodeJob:
encodingInFlight Set으로 동일 id 중복 스폰 방지. child close에서
code===0 && cvf파일존재 && stdout에 ENCODE_DONE 이면 meta 재로드 후
cvfStatus:'ready' +
cvfSize(실측 바이트) 갱신, 아니면
cvfStatus:'error' +
cvfError 저장
- 신규 라우트
GET /api/video/encode-status/<id> (admin) →
{id,cvfStatus,cvf,cvfError}, 레코드 없으면 404
-
handleCvf/
handleCvfAudio:
meta.cvfStatus가 설정돼 있고
'ready'가 아니면 409
{error:'인코딩 중'}.
레거시 호환: 기존 23개 클립 레코드는
cvfStatus 필드가 아예 없으므로(가드 조건이
meta.cvfStatus && !== 'ready') 그대로 통과 — 기존 재생을 깨지 않음.
검증
node --check modules/video/routes.js 통과encode-upload.sh를 영상원본/클립/o4-1.mp4 + id=TESTA로 직접 실행 → 32초 만에 ENCODE_DONE 15732415 출력, cvf/class_TESTA.cvf(15.7MB) + cvf/class_TESTA.cvf.mp3(1.7MB) + cvf-archive/class_TESTA.cvf.ccp(1.7MB) 생성 확인 후 3개 파일 삭제(테스트 잔재 없음)
관련 파일
/Users/ef/crowny-class/modules/video/routes.js/Users/ef/crowny-class/scripts/encode-upload.sh/Users/ef/crowny-class/한선씨/인코딩판정.한선 (+ .toau) — 잡종료판정/상태판정/서빙게이트 4상 로직 미러(면책: 실배선 없음, routes.js가 JS로 직접 판정)
잔여 이슈
- ccp 아카이브(cvf-archive/*.cvf.ccp)를 서빙/복원하는 라우트는 아직 없음(현재는 보관 전용)
- 서버 재기동은 이 세션에서 하지 않음(Integrate 담당 — 지시사항)
- class.html/admin.html 등 프론트는 건드리지 않음(admin 쪽 인코딩 상태 UI는 별도 문서
2026-07-12-crowny-class-admin-cvf-encode-ui.md 참조, 상호 확인 필요)