doclib 비디오 스트리밍 기능 설계

목표

로그인한 사용자가 포털 안에서 MP4, WebM, Ogg 동영상을 업로드·목록 조회·재생·삭제할 수 있게 한다. 기본 구현은 브라우저의 HTML5 <video> 플레이어와 HTTP Range 응답을 사용해, 별도 트랜스코딩 서비스 없이도 탐색·이어보기·부분 다운로드가 가능한 재생 흐름을 제공한다.

구조

server/features/video-streaming/
  index.ts                 # 업로드·목록·스트림·삭제 API
  store.ts                 # 영상 메타데이터 JSON 인덱스와 파일 저장소
  policy.ts                # 허용 형식·크기·Range 파싱

client/src/features/video-streaming/
  api/video-api.ts         # /api/videos 호출
  components/VideoLibrary.tsx
  index.ts

API	인증	동작
GET /api/videos	로그인 필요	최신 영상 메타데이터 목록을 반환한다.
POST /api/videos	로그인 필요	MP4·WebM·Ogg 파일과 제목·설명을 업로드한다.
GET /api/videos/:id/stream	로그인 필요	Range 헤더를 처리해 영상 바이트를 부분 응답한다.
DELETE /api/videos/:id	업로더 또는 관리자	영상 메타데이터와 원본 파일을 삭제한다.

저장·보안 원칙

동영상 원본과 메타데이터 인덱스는 VIDEO_STORAGE_ROOT 환경변수가 가리키는 디렉터리에 둔다. 설정하지 않으면 프로젝트의 storage/video-library를 사용한다. 모든 API는 서버 인증 미들웨어를 통과하며, 스트림 URL도 세션 쿠키가 있어야 접근할 수 있다. 삭제는 업로더 또는 관리자에게만 허용한다.

업로드는 MP4, WebM, Ogg만 허용하며 기본 최대 크기는 250MB로 둔다. 운영 환경에서는 저장소 용량, 백업, CDN 요구사항에 맞춰 VIDEO_MAX_UPLOAD_BYTES와 VIDEO_STORAGE_ROOT를 설정한다. R2 기반 장기 보관·대용량 다중 업로드·트랜스코딩은 다음 단계로 분리한다.

화면 흐름

/videos 경로에서 최신 영상 목록과 선택된 영상을 보여 준다. 선택한 영상은 인증된 스트림 URL을 <video controls>로 재생하며, 업로드 권한을 가진 로그인 사용자는 새 영상을 추가한다. 업로더 및 관리자는 해당 항목을 삭제할 수 있다.