deep-printfilm:
스크립트에서 단편 영화까지, AI 만화극 워크벤치

한 줄 아이디어를 입력하면 분장 → 장면 → 키프레임 → 동영상까지 4단계로 풀어 만드는 React 19 + Electron 기반 데스크톱·웹 영상 생성 스튜디오. 5월 26일 TrendShift 1위.

0먼저, 「短剧」와 「만화극」이 뭔가?

이 레포가 만들려는 결과물을 알아야 한다.

중국 모바일 인터넷에서 폭발한 콘텐츠 장르가 短剧(duǎnjù, 단편극)이다. 회당 1~3분, 총 80~100회 분량의 세로형 미니드라마인데, 2024년 기준 시장 규모가 500억 위안(약 9.5조 원)을 넘어 박스오피스를 추월할 정도로 커졌다. 짧고 자극적인 훅 → 빠른 갈등 → 다음화 후크로 도파민을 직격하는 구성이 특징이다.

「만화극(漫剧)」은 그 변형이다. 실사 촬영 대신 일러스트 + 가벼운 모션 + 더빙으로 만들어, 배우·로케이션 비용 없이 한 사람이 회사처럼 양산할 수 있다. deep-printfilm은 바로 이 「혼자서 회사처럼 양산」을 가능하게 하는 도구다.

1한 줄 요약 — 왜 주목받는가

577★, TrendShift 1위, 5/26 기준.

경쟁 제품과 비교해 보면 차별점이 더 선명하다.

TrendShift 1위에 오른 건 결국 「중국 短剧 시장」이라는 거대한 실수요와 「Sora/Veo 출시 직후의 워크플로 공백」이 정확히 맞물린 타이밍 때문이다. 별 567개 중 대다수가 최근 30일에 찍혔다.

2기술 스택 전체 지도

package.json·Dockerfile·vite.config.ts에서 그대로 뽑은 사실들.

이 프로젝트는 풀스택 백엔드가 없다. 자체 서버 없이 브라우저에서 모든 것을 처리하고, AI 호출만 외부 API로 보내는 「서버리스 데스크톱 앱」 구조다.

프론트엔드 (전부 클라이언트에서 돌아감)

데스크톱 패키징 (Windows·macOS 네이티브 앱)

인프라 — Docker + Nginx 정적 호스팅

# Dockerfile 핵심 (multi-stage build)
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev && \
    npm install --no-save vite@^6.2.0 ...   # Electron은 일부러 제외
COPY . .
RUN npm run build                            # → dist/ 생성

FROM nginx:alpine                            # 2단계: 가벼운 Nginx
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

이 Dockerfile에는 흥미로운 디테일이 있다. 주석에 「Electron은 의존성 트리가 너무 커서 npm이 멈춘 것처럼 보임 → 일부러 제외」라고 적혀 있다. 도커 이미지 안에서는 웹용 빌드만 만들어 Nginx에 얹는다.

AI 통합 — GitCC API 단일 게이트웨이

이게 deep-printfilm의 가장 큰 「판매 포인트」이자 「의존 포인트」다. OpenAI·Anthropic·Google에 각각 키를 받지 않고, GitCC라는 중국 AI 게이트웨이 1개에만 키를 등록하면 GPT·Claude·Gemini·Sora·Veo를 OpenAI 호환 API로 부를 수 있다.

데이터 저장 — IndexedDB 100%

백엔드 DB가 없다. 프로젝트·캐릭터·장면·키프레임·생성 로그 전부 브라우저의 IndexedDB에 저장된다. 장점은 「설치·서버 운영 비용 0」, 단점은 「브라우저 데이터 지우면 모든 작품이 날아감」이라는 점.

3아키텍처 심화 분석

「Script-to-Asset-to-Keyframe」 4단계 파이프라인의 실체.

전체 흐름을 그림으로 그려보면 이렇다.

┌─────────────────────────────────────────────────────────────────┐
│                  사용자 (브라우저 또는 Electron 창)                │
└───────────────────────────────┬─────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
        ▼                       ▼                       ▼
┌──────────────┐       ┌──────────────┐         ┌──────────────┐
│ React UI     │──────▶│ services/    │────────▶│ /api-proxy   │
│ (App.tsx,    │       │ geminiService│  fetch  │ (Vite dev    │
│  components/)│       │ ~98KB        │         │  또는 Nginx  │
└──────┬───────┘       │              │         │  reverse     │
       │               │ + adapters/  │         │  proxy)      │
       │ 상태 저장     │ + modelReg.. │         └──────┬───────┘
       ▼               │ + storageSvc │                │
┌──────────────┐       │ + exportSvc  │                ▼
│ IndexedDB    │◀──────│ + renderLog  │      ┌─────────────────┐
│ (브라우저)   │       │              │      │ api.gitcc.com   │
│              │       └──────────────┘      │ (OpenAI 호환    │
│ - projects   │                             │   게이트웨이)   │
│ - assets     │                             │                 │
│ - keyframes  │                             │ GPT / Claude /  │
│ - videos     │                             │ Gemini /        │
│ - renderLogs │                             │ Sora / Veo      │
└──────────────┘                             └─────────────────┘

  ─── 데스크톱 모드일 때만 ───
                                                     ▲
┌───────────────────────┐                            │
│ electron/main.cjs     │  Express + http-proxy-     │
│ + 내장 Express 서버   │──middleware 로 /api-proxy ─┘
│ (Electron 메인 프로세스) │  처리 (CORS 우회)
└───────────────────────┘

핵심 설계 패턴 — Stage 분리 + 단일 상태 객체

types.ts에 있는 ProjectState가 「프로젝트 1개의 우주 전체」다. 이 객체 하나에 스크립트, 캐릭터, 장면, 컷, 키프레임, 비디오 인터벌, 렌더 로그가 모두 들어 있다. UI는 stage: 'script' | 'assets' | 'director' | 'export' | 'prompts' 필드만 보고 어떤 화면을 그릴지 결정한다.

// types.ts에서 발췌
export interface ProjectState {
  id: string;
  title: string;
  stage: 'script' | 'assets' | 'director' | 'export' | 'prompts';

  rawScript: string;              // 사용자가 처음 입력한 문장
  scriptData: ScriptData | null;  // AI가 파싱한 구조 (캐릭터·장면·컷)
  shots: Shot[];                  // 컷 배열 (keyframes + interval 포함)
  renderLogs: RenderLog[];        // 생성 기록 (모델·토큰·비용·실패 이유)
}

키프레임 구동 (Keyframe-driven generation) — 가장 중요한 아이디어

이 프로젝트가 「Sora를 그대로 쓰는」 일반 영상 생성기와 갈라지는 지점이 여기다. 한 컷(Shot)에 무조건 「시작 프레임(start keyframe) + 끝 프레임(end keyframe)」을 두고, 이 두 그림을 보간(interpolation)해 영상을 만든다.

제일 비대한 파일 — services/geminiService.ts (약 98KB)

레포 전체에서 가장 비대한 단일 파일이 services/geminiService.ts다. 무려 약 98KB(약 3,000줄 추정). 이름은 「Gemini」지만 실제로는 OpenAI 호환 채팅·이미지·비디오 API를 한 군데서 호출하는 「범용 AI 어댑터」다.

모델 레지스트리 — 모델 추가를 데이터로 처리

services/modelRegistry.ts(15KB)는 「어떤 모델이 있고, 어떤 endpoint·파라미터를 받는지」를 데이터로 정의해둔 파일이다. types.ts의 VideoModelConfig에 보이는 'veo' | 'sora-2' | 'veo_3_1_t2v_fast_landscape' | 'veo_3_1_i2v_s_fast_fl_portrait' 같은 모델 ID가 이 파일에서 관리된다.

새로운 모델이 GitCC 게이트웨이에 추가될 때마다 코드를 거의 안 고치고 이 파일만 업데이트하면 UI에 자동으로 노출되는 구조 — 「Convention over Configuration」의 한 형태다.

4디렉토리 구조 해부

35커밋, 거의 100% TypeScript.

deep-printfilm/
├── App.tsx                  # 최상위 React 컴포넌트, 라우팅·상태
├── index.tsx                # ReactDOM.render 엔트리
├── index.html               # Vite가 처리하는 HTML 셸
├── package.json             # 의존성 + Electron build 설정
├── vite.config.ts           # /api-proxy 리버스 프록시, alias
├── Dockerfile               # multi-stage: node → nginx
├── docker-compose.yaml      # 포트 3005, 단일 서비스
├── nginx.conf               # 정적 호스팅 + API 프록시
├── tsconfig.json            # TypeScript 옵션
├── types.ts                 # ★ 모든 도메인 타입 (한 파일 집중)
├── metadata.json            # 앱 메타 (Electron 빌드용)
│
├── electron/                # 데스크톱 패키징
│   └── main.cjs             # Express 내장 서버 + BrowserWindow
│
├── components/              # React UI (Stage별 분리)
│   ├── Dashboard.tsx        # 프로젝트 목록
│   ├── Sidebar.tsx          # 좌측 네비
│   ├── ModelConfig/         # 모델·API Key 설정 UI
│   ├── Onboarding/          # 첫 사용자 가이드
│   ├── StageScript/         # Phase 01 — 대본·분경
│   ├── StageAssets/         # Phase 02 — 캐릭터·장면
│   ├── StageDirector/       # Phase 03 — 키프레임·영상
│   ├── StageExport/         # Phase 04 — 미리보기·다운로드
│   └── StagePrompts/        # 자산 프롬프트 관리
│
├── services/                # 비즈니스 로직 (UI 없음)
│   ├── geminiService.ts     # ★ 약 98KB AI 어댑터 본체
│   ├── modelRegistry.ts     # 모델 카탈로그
│   ├── modelConfigService.ts# 사용자 모델 설정 영속화
│   ├── modelService.ts      # 모델 호출 헬퍼
│   ├── storageService.ts    # IndexedDB CRUD
│   ├── assetLibraryService.ts # 캐릭터/장면 자산 관리
│   ├── renderLogService.ts  # 생성 기록 영속화
│   ├── exportService.ts     # JSZip으로 자산 패키징
│   ├── soraVideoResolve.ts  # Sora 비동기 결과 폴링
│   ├── videoHttpErrors.ts   # 영상 API 에러 분류
│   ├── mockData.ts          # 데모 데이터
│   └── adapters/            # chatAdapter.ts · imageAdapter.ts · videoAdapter.ts · index.ts (모델별 어댑터 분리 완료)
│
├── images/                  # README 스크린샷
├── public/                  # 정적 자산
└── types/                   # 추가 타입 모듈

주목할 패턴 1: components/Stage* 폴더 — 한 「Stage」가 한 폴더다. Phase 01~04 + 자산 관리 = 5개 Stage. 같은 Stage 안의 작은 컴포넌트들은 폴더에 모이고, 다른 Stage가 그것에 의존하지 못한다. 「수직 슬라이스(vertical slice)」 구조.

주목할 패턴 2: services/ vs components/ 분리 — UI는 components/, 비즈니스 로직은 services/. React 컴포넌트가 fetch 하지 않고, 항상 service 함수를 부른다. 이 덕분에 모델·API가 바뀌어도 UI 코드는 안 건드린다.

주목할 패턴 3: types.ts 단일 파일 — TypeScript 타입을 한 파일에 모두 모았다. 도메인이 크지 않을 때(이 경우 200줄 정도) 가장 빨리 「전체 모델을 머리에 그리는」 방법. 도메인이 더 커지면 도메인별 파일로 쪼개야 한다.

5학습 포인트 — 이 레포에서 뭘 배울 수 있나

기술별로 정리. 각 항목 끝에 「직접 해볼 것」.

React 19 — 최신 안정 버전을 실제 프로덕트에서 사용한 예

react@^19.2.0을 실전 투입한 오픈소스가 아직 흔치 않다. App.tsx에서 어떤 19 신기능을 쓰는지 살펴보면 좋다. useActionState로 양식 처리 / useOptimistic으로 「영상 생성 중」 낙관적 UI / 새 use() 훅으로 Promise 직접 읽기 같은 패턴이 있는지 체크.

해볼 것: App.tsx와 components/StageDirector를 클론 받아 git log로 「React 19 마이그레이션」 커밋이 있는지 찾아보고, 18 → 19로 바꾼 코드 diff를 학습.

Electron + React 통합 — 「웹앱을 데스크톱으로」

일반 Electron 튜토리얼은 mainWindow.loadFile('index.html')로 정적 파일을 띄운다. deep-printfilm은 한 단계 더 나가 express + http-proxy-middleware를 내장해 데스크톱 안에서 API 프록시까지 처리한다. 로컬에 풀스택 환경을 한 .exe로 배포하는 패턴이다.

해볼 것: electron/main.cjs를 열어 BrowserWindow 옵션, contextIsolation, preload script를 확인. 「Express 서버를 왜 메인 프로세스에 띄웠는가」를 직접 추적.

Docker multi-stage build — 50MB 이미지를 만드는 법

Dockerfile 한 파일에 「빌드용 무거운 이미지(node:20-alpine ~200MB)」와 「실행용 가벼운 이미지(nginx:alpine ~25MB)」를 둘 다 쓰고, 빌드 결과물만 후자에 복사한다. --from=builder가 그 마법이다.

해볼 것: 자기 프로젝트의 Dockerfile을 single-stage → multi-stage로 리팩토링. docker images로 전후 크기 비교.

Vite 리버스 프록시 — CORS를 빌드 시간에 우회

vite.config.ts의 server.proxy 설정으로 개발 모드에서 /api-proxy/* → http://api.gitcc.com/*로 보낸다. 브라우저는 자기 자신(localhost)에 요청한 줄 아니까 CORS 오류가 안 난다. 풀스택 백엔드 없이 API 호출하는 가장 빠른 패턴.

해볼 것: 자기 SPA에서 「외부 API를 직접 fetch했더니 CORS 막힘」 경험이 있다면, Vite·Next.js의 dev proxy로 풀어보기.

IndexedDB — 백엔드 없이 「프로젝트 관리」 구현

services/storageService.ts(8KB)를 읽으면 IndexedDB CRUD 패턴을 배울 수 있다. idb 라이브러리도 안 쓰고 네이티브 API를 직접 사용한 것으로 보인다(의존성에 없음). Promise로 감싸는 헬퍼, version migration, transaction 패턴이 포인트.

해볼 것: storageService.ts를 그대로 떼어내, 「오프라인 작동하는 to-do 앱」에 이식.

AI 모델 어댑터 패턴 — 모델별 차이를 한 곳에 격리

OpenAI·Anthropic·Google·Sora·Veo는 요청 스펙이 다 다르다(특히 동영상). geminiService.ts + modelRegistry.ts + modelService.ts 3개가 만드는 「공통 인터페이스 → 모델별 어댑터」 분리 방식을 학습하면, LangChain 같은 무거운 라이브러리 없이도 멀티 LLM 앱을 만들 수 있다.

해볼 것: 자기 챗봇에 OpenRouter 1개만 붙여본 적이 있다면, 같은 패턴으로 「로컬 Ollama + OpenAI + Claude」를 한 번에 부르도록 확장.

Sora 비동기 폴링 — 영상 생성 API의 특수한 사정

이미지·텍스트와 달리 영상 모델은 결과가 30초~5분 걸린다. 따라서 「제출 → ID 받고 → 폴링 → 완료되면 URL 반환」하는 비동기 패턴이 필수. soraVideoResolve.ts(2.8KB)가 그 핵심.

해볼 것: 한 번이라도 직접 Sora·Runway API를 호출해본 적 없다면, 이 파일을 모방해 작은 폴링 헬퍼를 만들어보고 setTimeout vs Web Workers의 차이를 비교.

6하드웨어·시스템 요구사항

로컬 모델이 없으니 의외로 가볍다.

이 프로젝트는 모든 AI 추론을 외부 API에 위임하므로, 로컬에서는 브라우저만 잘 돌면 된다. ComfyUI·Stable Diffusion처럼 24GB VRAM이 필요하지 않다.

7직접 해볼 수 있는 실습 과제

난이도별 5개. 위에서 아래로 갈수록 어렵다.

8관련 기술 심화 학습 로드맵

8주 코스. 매주 한 영역.

9핵심 키워드 사전

레포에 등장하는 용어 모음.