30 KiB
🎬 Huobao Drama - AI 숏드라마 생성 플랫폼
TypeScript 풀스택 기반 AI 숏드라마 자동 제작 플랫폼
中英双语 | English | 简体中文 | 日本語 | 한국어
기능 • 빠른 시작 • 튜토리얼 • 데스크톱 앱 • 배포
🔑 Huobao API Key 받기 👉 바로 보기
텍스트 · 이미지 · 영상 모든 AI 기능, Key 하나로 활성화
배포 후 「설정 → 火宝快捷 설정」에 Key 를 붙여넣으면 추천 설정 3개가 한 번에 입력됩니다
📥 데스크톱 앱 다운로드 (macOS / Windows)
🌐 공식 웹사이트
📖 프로젝트 소개
Huobao Drama는 AI 기반 숏드라마 자동 제작 플랫폼으로, 각본 생성, 캐릭터 디자인, 스토리보드 제작부터 영상 합성까지 전 과정을 자동화합니다.
🎯 핵심 가치
- 🤖 AI 기반：대규모 언어 모델로 각본을 분석하여 캐릭터, 장면, 스토리보드 정보를 추출
- 🎨 지능형 창작：AI 이미지 생성으로 캐릭터 이미지와 장면 배경 제작
- 📹 영상 생성：텍스트→영상 및 이미지→영상 모델로 스토리보드 영상 자동 생성
- 🔄 워크플로：아이디어부터 완성 영상까지 숏드라마 제작 전 과정을 한 곳에서 완료
🛠️ 기술 아키텍처
frontend/ — Nuxt 3 + Vue 3 + TypeScript (순수 CSS, UI 프레임워크 없음)
backend/ — Hono + Drizzle ORM + Mastra AI Agents + better-sqlite3
backend/workspace/skills/ — Agent 스킬 정의 (SKILL.md, UI에서 온라인 편집 가능)
desktop/ — Electron 데스크톱 버전 (메인 프로세스 + esbuild 번들 + electron-builder로 dmg/exe 생성)
data/ — 생성된 에셋과 SQLite 데이터베이스
✨ 기능
🎭 캐릭터 관리
- ✅ AI 캐릭터 이미지 생성
- ✅ 캐릭터 일괄 생성
- ✅ 캐릭터 이미지 업로드 및 관리
🎬 영상 작업
- ✅ AI 영상 작업 자동 생성
- ✅ 장면 설명 및 영상 프롬프트 생성
- ✅ 작업별 영상 일괄 생성
🎥 영상 생성
- ✅ 텍스트→영상 자동 생성
- ✅ FFmpeg 샷 단위 합성 및 자막 처리
- ✅ 에피소드 전체 병합 및 납출
📦 에셋 관리
- ✅ 소재 라이브러리 통합 관리
- ✅ 로컬 스토리지 지원
- ✅ 작업 진행 상황 추적
🤖 AI Agents
4개의 Mastra Agent 내장, 데이터베이스 설정과 Skill 확장 지원:
| Agent | 역할 |
|---|---|
script_rewriter |
소설 → 형식화된 각본 리라이팅 |
extractor |
캐릭터 / 장면 / 소품 지능형 추출 및 중복 제거 |
storyboard_breaker |
각본 → 스토리보드 시퀀스 분해 |
prompt_generator |
캐릭터/장면/소품 이미지 프롬프트 + 스토리보드 영상 프롬프트 생성 |
🌐 다국어 UI
인터페이스는 中文 / English / 日本語 / 한국어 4개 언어를 내장하고, AI 생성 콘텐츠의 언어를 전역으로 설정할 수 있습니다.
🔌 멀티 프로바이더 지원
| 유형 | 지원 프로바이더 |
|---|---|
| 텍스트 | OpenAI(호환 API), Gemini |
| 이미지 | OpenAI, Gemini, Volcano Engine |
| 영상 | Volcano Engine Seedance 2.0(Standard / Fast / Mini), MiniMax H3, Alibaba Bailian Wan 3.0(Prime / Standard) |
🚀 빠른 시작
📋 환경 요구 사항
| 소프트웨어 | 버전 | 설명 |
|---|---|---|
| Node.js | 20+ | 프런트엔드/백엔드 실행 환경 |
| npm | 9+ | 패키지 관리 도구 |
데이터베이스 설치 불필요：SQLite 내장(프로젝트 데이터 디렉터리의 단일 파일)으로 데이터베이스 서버 설치가 필요 없습니다. FFmpeg 설치 불필요：
ffmpeg-static/ffprobe-staticnpm 패키지에 바이너리가 내장되어 바로 사용할 수 있습니다.
⚙️ 환경 변수
설정 파일 없이 환경 변수로 설정합니다(모두 기본값이 있어 로컬 개발은 무설정으로 시작 가능):
| 변수 | 기본값 | 설명 |
|---|---|---|
SQLITE_PATH |
<저장소>/data/huobao.sqlite3 |
SQLite 데이터베이스 파일 위치 |
PORT |
5679 |
백엔드 서비스 포트 |
STORAGE_PATH |
<저장소>/data/static |
생성 파일 저장 디렉터리 |
HUOBAO_DATA_DIR |
— | 데스크톱 버전에서 Electron 메인 프로세스가 주입(userData 데이터 루트) |
WORKSPACE_PATH |
backend/workspace |
Agent 스킬/프롬프트 디렉터리(데스크톱 버전은 userData의 쓰기 가능한 복사본) |
FRONTEND_DIST |
frontend/dist |
프런트엔드 정적 빌드 디렉터리 |
FFMPEG_BIN / FFPROBE_BIN |
npm 내장 바이너리 | 사용자 지정 ffmpeg/ffprobe 실행 파일 경로 |
PUBLIC_BASE_URL |
— | Seedance가 로컬 참조 리소스를 사용할 때 필요한 공개 주소(서버 배포용) |
설명：AI 서비스의 API Key, Base URL, 모델 파라미터는 모두 웹 UI의 「설정」 페이지에서 설정하여 데이터베이스에 저장합니다. 설정 파일이나 환경 변수로 관리하지 않습니다.
📥 설치
# 저장소 클론
git clone https://github.com/chatfire-AI/huobao-drama.git
cd huobao-drama
# 백엔드 의존성 설치
cd backend && npm install
# 프런트엔드 의존성 설치
cd ../frontend && npm install
🎯 실행
방법 1: 개발 모드(권장)
프런트엔드와 백엔드를 분리하여 핫 리로드 지원:
# 터미널 1: 백엔드
cd backend
npm run dev
# 터미널 2: 프런트엔드
cd frontend
npm run dev
- 프런트엔드 주소:
http://localhost:3013 - 백엔드 API:
http://localhost:5679/api/v1 - 프런트엔드가
/api와/static을 백엔드로 자동 프록시
방법 2: 단일 서비스 모드
백엔드가 API와 프런트엔드 정적 파일을 모두 제공:
# 1. 프런트엔드 빌드
cd frontend && npm run generate
# 2. 빌드 산출물을 백엔드가 읽는 디렉터리로 복사
# (generate 산출물은 .output/public, 백엔드는 frontend/dist를 읽음)
cp -r .output/public dist
# 3. 백엔드 시작
cd ../backend && npm start
접속: http://localhost:5679
🗄️ 데이터베이스
SQLite 내장(better-sqlite3 + WAL 모드). 최초 시작 시 테이블 자동 생성(멱등 DDL 재생 + 시드 데이터). 기본 파일은 data/huobao.sqlite3이며 SQLITE_PATH로 변경 가능. 데스크톱 버전의 데이터는 사용자 데이터 디렉터리(~/Library/Application Support/HuobaoDrama/data/)에 저장됩니다.
구버전 MySQL에서 데이터 마이그레이션:
시작 시 자동 마이그레이션(권장): MySQL이 명시적으로 설정되어 있고(DATABASE_URL 또는 MYSQL_HOST) SQLite가 비어 있으면, 백엔드 시작 시 자동으로 감지하여 모든 테이블을 한 번만 가져옵니다(테이블별 행 수 검증, 단일 트랜잭션 원자적 쓰기, 실패 시 자동 롤백 후 다음 시작 때 재시도, 성공 시 .mysql-imported 마커를 기록하여 중복 방지). MYSQL_AUTO_IMPORT=false로 비활성화할 수 있습니다.
# 수동 실행도 가능(대상 DB가 비어 있지 않으면 --force 필요, 쓰기 전 자동 백업)
cd backend && npx tsx scripts/import-mysql-to-sqlite.ts
마이그레이션은 데이터베이스 행만 포함합니다. 구 배포의
data/static/아래 이미지/영상 등 미디어 파일은 수동으로 복사해야 하며, 그렇지 않으면 기존 소재에 접근할 수 없습니다.
🔑 첫 사용: AI 서비스 설정
시작 후 모든 AI 기능(텍스트/이미지/영상)을 사용하려면 먼저 모델 서비스를 설정해야 합니다. 미설정 시 페이지 상단에 배너로 안내합니다:
- 「설정」 페이지 열기
- 「火宝快捷 설정」에 Huobao API Key 붙여넣기(api.firemux.com에서 발급). 텍스트, 이미지, 영상 추천 설정 3개가 한 번에 입력됩니다
- 또는 「수동 템플릿」으로 프로바이더별 추가. 연결 테스트 지원
설정이 완료되면 배너가 자동으로 사라지고 에피소드 제작을 시작할 수 있습니다.
📖 그림 튜토리얼
소설부터 완성 에피소드까지의 전체 제작 흐름입니다. 왼쪽 진행 표시줄이 항상 현재 단계를 보여줍니다.
1단계 · 프로젝트 생성
홈에서 "새 프로젝트"를 클릭하고 화면 비율(16:9 가로 / 9:16 세로, 생성 후 변경 불가)과 화풍(3D / 실사 등, 모든 이미지 프롬프트에 주입)을 선택합니다.
2단계 · AI 서비스 설정 (최초)
설정 페이지의 "휘바오 빠른 설정"에 API 키를 붙여넣으면 추천 설정 3종을 한 번에 등록합니다. 수동 템플릿으로 직접 추가할 수도 있습니다. 사용 모델은 상단 바에서 언제든 전환 가능합니다(5단계 참고).
3단계 · 대본 단계
제작 화면에 **원문(소설)**을 붙여넣고 "AI 재작성"을 실행하면 촬영용 대본이 생성됩니다 — 에피소드별 분할 및 장면·캐릭터 주석 포함. 모델과 톤을 바꿔가며 재작성할 수 있습니다.
4단계 · 에셋 제작
대본에 추출을 실행하면 캐릭터 / 장면 / 소품 목록이 자동 생성됩니다. 각 항목의 "이미지 생성"으로 일관성 있는 참조 이미지를 만들 수 있습니다(일괄 생성 지원). 이 이미지들은 영상 생성 시 참조 소재로 주입됩니다.
5단계 · 스토리보드와 영상
"영상 제작" 페이지에서 먼저 스토리보드 분할을 실행하세요(AI가 컷을 나누고 영상 프롬프트 생성). 그 후:
- 상단 바에서 영상 모델 선택(Seedance / Wan 3.0 / MiniMax 등). 해상도와 길이 옵션은 모델에 연동됩니다
- 오른쪽에서 각 컷의 프롬프트를 확인·조정(
@캐릭터명참조는 자동으로 참조 이미지에 매핑) - "일괄 영상 생성"으로 작업 시작. 실패한 작업은 원클릭 재시도
6단계 · 병합과 내보내기
컷을 선택(호버로 각 클립 미리보기)하고 "병합 시작"을 누르면 FFmpeg이 완성 에피소드를 자동 합성합니다. 온라인 재생·다운로드 가능. 완료 후 "완료 표시"를 누르면 진행 표시줄이 켜집니다.
에피소드 목록에서 각 화의 제작 현황을 확인하고 "제작 열기"로 이어서 작업할 수 있습니다:
📦 배포
🖥️ 데스크톱 앱(권장)
⬇️ 빌드된 설치 파일: GitHub Releases · 중국용 미러(Tencent COS)
| 플랫폼 | 다운로드 파일 |
|---|---|
| macOS(Apple Silicon, M 시리즈) | HuobaoDrama-4.0.5-arm64.dmg |
| macOS(Intel) | HuobaoDrama-4.0.5.dmg |
| Windows | HuobaoDrama.Setup.4.0.5.exe |
중국 본토에서는 GitHub이 불안정하므로 Tencent COS 미러를 이용하세요. 앱 내 업데이터도 COS를 우선하고 GitHub으로 폴백합니다.
커맨드라인 설치(권장, 복구 불필요): curl로 다운로드하면 macOS 격리 속성이 붙지 않아 "손상됨" 경고 없이 바로 실행됩니다(Apple Silicon은 -arm64.dmg, Intel은 일반 dmg 사용):
curl -L -o /tmp/HuobaoDrama.dmg https://installer.firemux.site/huobao-drama/v4.0.11/HuobaoDrama-4.0.11-arm64.dmg \
&& hdiutil attach -nobrowse /tmp/HuobaoDrama.dmg \
&& cp -R /Volumes/HuobaoDrama*/HuobaoDrama.app /Applications/ \
&& hdiutil detach /Volumes/HuobaoDrama*
빌드 불필요 — dmg/exe를 다운로드해 바로 설치하면 됩니다. 설치된 클라이언트는 내장 업데이터로 자동 업데이트됩니다. (소스에서 직접 패키징하려면 아래 명령을 참조하세요.)
더블클릭 설치로 바로 사용할 수 있는 데스크톱 버전(macOS + Windows). 데이터베이스(SQLite), 생성된 미디어 파일, Agent 스킬은 모두 사용자 데이터 디렉터리에 저장되며 앱을 삭제필필도 데이터에 영향이 없습니다.
# 원커맨드 패키징(프런트엔드 generate → 백엔드 esbuild → electron-builder)
npm run dist # macOS dmg(arm64 + Intel)
npm run dist:win # Windows NSIS 설치 프로그램(win-x64, macOS에서 크로스 빌드 가능)
# 산출물
# desktop/release/HuobaoDrama-<버전>-arm64.dmg (Apple Silicon)
# desktop/release/HuobaoDrama-<버전>.dmg (Intel)
# desktop/release/HuobaoDrama Setup <버전>.exe (Windows)
설치 안내:
-
macOS 미서명 패키지는 첫 실행 시 "App이 손상되어 열 수 없습니다"라는 메시지가 뜰 수 있습니다(Apple Silicon에서 흔함). 이는 Gatekeeper 격리 속성 때문이며 파일이 실제로 손상된 것은 아닙니다. 복구 방법은 두 가지입니다:
- dmg에 복구 스크립트 포함: 앱을 "응용 프로그램"으로 드래그한 후 dmg 창 하단의 "如提示已损坏请双击我.command"를 더블클릭하면 자동으로 복구됩니다;
- 또는 터미널에서
sudo xattr -cr /Applications/HuobaoDrama.app실행.
복구는 처음 한 번만 필요하며, 이후에는 정상 실행되고 앱 내 자동 업데이트에도 영향이 없습니다.
-
Windows 미서명 패키지는 SmartScreen에서 「추가 정보 → 실행」 선택
-
사용자 데이터 디렉터리:
~/Library/Application Support/HuobaoDrama/(데이터베이스, 생성된 미디어, 온라인 편집한 스킬 복사본) -
FFmpeg/FFprobe 바이너리 내장, 시스템 설치 불필요
-
Electron은 37.x로 고정: better-sqlite3의 win32 프리빌드가 해당 ABI까지만 지원(크로스 패키징 시 컴파일 불필요의 핵심)
-
앱 내 외부 링크(「api.firemux.com에서 Key 받기」 등)는 시스템 브라우저로 바로 열립니다
🔄 앱 내 업데이트(Apple 서명 불필요)
데스크톱 버전에는 업데이터가 내장되어 있습니다(Tauri와 동류 방식: macOS 디렉터리 교체 / Windows 사일런트 설치, 로컬 sha256 검증). 새 버전 릴리스 절차:
# 1. desktop/package.json의 version을 수정한 후 패키징
npm run dist # macOS(dmg + 업데이트용 zip 산출)
npm run dist:win # Windows(Setup.exe 산출)
# 2. 버전 매니페스트 release/latest.json 생성(플랫폼별 sha256 포함)
cd desktop && npm run feed
# 3. 릴리스: latest.json + 설치 패키지 + zip을 GitHub Release에 업로드(태그는 v1.0.1 형식)
설치된 클라이언트는 시작 후 매니페스트를 자동으로 확인하고(「설정 → 정보 및 업데이트」에서 수동 확인도 가능), 새 버전을 발견하면 다운로드 및 설치를 안내합니다. 매니페스트 주소는 HUOBAO_UPDATE_FEED 환경 변수로 변경할 수 있습니다.
데스크톱 버전 개발 디버깅:
npm run build:frontend # 프런트엔드 정적 산출물(frontend/.output/public)
cd desktop && npm run dev # 백엔드 번들 후 Electron 창으로 실행
알려진 제한: Seedance 영상 모델이 로컬 참조 리소스를 사용하려면
PUBLIC_BASE_URL공개 주소가 필요합니다. 데스크톱 버전에는 공개 진입점이 없어 해당 시나리오에서는 명확한 오류 메시지가 표시됩니다. 텍스트→영상/이미지 생성 등 나머지 기능에는 영향이 없습니다.
🏭 서버 배포
# 1. 프런트엔드 빌드
cd frontend && npm run generate
# 2. 빌드 산출물 복사(generate 산출물은 frontend/.output/public, 백엔드는
# frontend/dist를 읽음. 이 단계를 생략하면 API는 정상이지만 페이지가 404)
cp -r .output/public dist && cd ..
# 3. 백엔드 시작
cd backend && npm start
서버에 업로드할 파일:
backend/ # 백엔드 소스 + node_modules
backend/workspace/skills/ # Agent 스킬 파일
frontend/dist/ # 프런트엔드 빌드 산출물
data/ # 데이터 디렉터리(최초 실행 시 자동 생성)
Nginx 리버스 프록시
server {
listen 80;
server_name your-domain.com;
# 참조 영상/오디오 업로드 최대 50MB
client_max_body_size 100m;
# 생성된 이미지/영상은 디스크에서 직접 서빙(Node를 거치지 않음):
# sendfile 제로 카피 + 장기 캐시
# (파일은 uuid 명명, 내용 불변이므로 immutable 캐시 안전)
location /static/ {
alias /path/to/huobao-drama/data/static/;
sendfile on;
tcp_nopush on;
expires 1y;
add_header Cache-Control "public, immutable";
}
location / {
proxy_pass http://localhost:5679;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
미디어 로딩 최적화: 이미지 생성 시 백엔드가 목록 페이지용 400px 썸네일(
*_thumb.webp)을 자동 생성하고, 영상은 포스터 프레임(*_poster.jpg)을 커버로 추출합니다. 프런트엔드는 큰 이미지를 열거나 재생할 때만 원본 파일을 로드합니다. 기존 파일은backend/에서npm run backfill-artwork를 실행해 일괄 보완할 수 있습니다.
🐳 Docker 배포(앱 내 업데이트 포함)
방법 A — 사전 빌드 이미지(클론·빌드 불필요): 멀티 아키텍처(linux/amd64 + linux/arm64), x86 서버와 ARM 디바이스 자동 매칭
docker pull huobao/huobao-drama:4.0.6
docker run -d \
--name huobao-drama \
-p 5679:5679 \
-v huobao-data:/app/data \
--restart unless-stopped \
huobao/huobao-drama:4.0.6
방법 B — docker compose(소스 빌드 + Watchtower 인앱 업데이트): 저장소 루트에 올인원 Dockerfile(프런트엔드 generate + 백엔드 의존성/런타임 3단계, 백엔드는 서버 배포와 동일하게 tsx로 실행)과 docker-compose.yml(앱 + Watchtower)을 제공합니다:
# 1. 환경 설정(Watchtower 토큰, app과 watchtower 양쪽이 일치해야 함)
cp .env.example .env # WATCHTOWER_TOKEN 수정
# 2. 빌드 및 시작(릴리스 시 버전을 주입하여 「정보 및 업데이트」 비교에 사용)
HUOBAO_VERSION=4.0.5 docker compose up -d --build
# 3. http://localhost:5679 접속
- 데이터 영속화: 네임드 볼륨
huobao-data를/app/data에 마운트(SQLite + 생성된 이미지/영상 + workspace/skills). 이미지 업데이트 시에도 데이터 유지 - 앱 내 업데이트: compose에 Watchtower 사이드카 포함(
--label-enable로 라벨이 지정된 컨테이너만 업데이트,--cleanup으로 구 이미지 정리, 매일 자체 점검). 「설정 → 정보 및 업데이트」에서 새 버전 확인 및 「지금 업데이트」 가능 — 백엔드가 Watchtower HTTP API를 통해 트리거하여 새 이미지를 가져와 컨테이너를 재생성합니다. 몇 분 후 페이지를 새로고침하면 완료 - 수동 모드:
docker-compose.yml에서 app의HUOBAO_WATCHTOWER_*환경 변수 2개(또는 watchtower 서비스 전체)를 삭제하면 「정보 및 업데이트」는 새 버전 알림 + 수동 명령docker compose pull && docker compose up -d으로 전환됩니다 - 이미지 릴리스:
docker buildx build --platform linux/amd64,linux/arm64 --build-arg HUOBAO_VERSION=x.y.z -t huobao/huobao-drama:x.y.z -t huobao/huobao-drama:latest --push .. 버전 매니페스트는 데스크톱 버전과 GitHub Releases의latest.json을 공유(HUOBAO_UPDATE_FEED로 재정의 가능)
🎨 기술 스택
백엔드
- 런타임: Node.js 20+
- 웹 프레임워크: Hono
- ORM: Drizzle ORM + better-sqlite3(WAL 모드)
- AI Agent: Mastra + AI SDK(OpenAI 호환)
- 영상 처리: FFmpeg(fluent-ffmpeg + 내장 바이너리)
- 이미지 처리: Sharp
데스크톱
- 셸: Electron(utilityProcess가 백엔드를 호스팅, BrowserWindow는 동일 출처로 로드)
- 패키징: esbuild(백엔드 단일 파일 번들) + electron-builder(dmg arm64/x64, NSIS win-x64)
프런트엔드
- 프레임워크: Nuxt 3(SPA 모드)
- 언어: Vue 3 + TypeScript
- 라우팅: 파일 라우팅(Vue Router 4)
- 스타일: 순수 CSS + CSS Variables
- 아이콘: Lucide Vue
- i18n: vue-i18n(中文 / English / 日本語 / 한국어)
📝 자주 묻는 질문
Q: 데스크톱 버전의 데이터는 어디에 저장되나요?
A: ~/Library/Application Support/HuobaoDrama/data/(SQLite 데이터베이스 + 생성된 이미지/영상)에 저장되며, 온라인 편집한 스킬의 복사본은 같은 수준의 workspace/ 디렉터리에 있습니다. 개발 모드에서는 저장소의 data/ 디렉터리를 사용합니다.
Q: 구버전 MySQL 데이터를 SQLite로 마이그레이션하려면?
A: MySQL에 연결 가능한 상태(환경 변수 또는 backend/.env)를 유지하고 cd backend && npx tsx scripts/import-mysql-to-sqlite.ts를 실행하세요. 스크립트가 자동으로 테이블을 생성하고 테이블별로 가져오며 행 수를 검증합니다(대상 DB가 비어 있지 않으면 --force 필요, 쓰기 전 자동 백업).
Q: FFmpeg가 설치되지 않았거나 찾을 수 없다고 나옵니다?
A: 설치할 필요가 없습니다. 프로젝트에 ffmpeg-static / ffprobe-static 바이너리가 내장되어 있습니다(데스크톱 버전에도 포함). 시스템 PATH의 FFmpeg와 충돌하지 않으며, FFMPEG_BIN/FFPROBE_BIN으로 명시적으로 지정할 수도 있습니다.
Q: 페이지 상단에 「모델 미설정」이 표시됩니다?
A: 정상적인 첫 배포 안내입니다. 「설정」 페이지에서 「火宝快捷 설정」에 API Key를 붙여넣어 한 번에 입력하거나, 「수동 템플릿」으로 프로바이더를 추가하세요. 텍스트, 이미지, 영상 3가지 모두에 활성화된 설정이 있으면 배너가 자동으로 사라집니다.
Q: 프런트엔드가 백엔드 API에 연결되지 않습니다?
A: 백엔드가 시작되었는지, 포트가 올바른지 확인하세요. 개발 모드의 프록시 설정은 frontend/nuxt.config.ts에 있습니다.
Q: 데이터베이스 테이블이 생성되지 않았습니다?
A: 백엔드는 최초 시작 시 모든 테이블을 자동으로 생성합니다. 로그에서 초기화 성공 여부를 확인하세요.
📋 업데이트 로그
v4.0.0 (2026-08)
🖥️ 데스크톱 앱 + 데이터베이스 마이그레이션
- Electron 데스크톱 버전(macOS dmg, arm64/x64 듀얼 아키텍처)
- 더블클릭 설치, 즉시 사용: 자동 포트 선택, 단일 인스턴스 잠금, 충돌 분리된 백엔드 서브프로세스
- 사용자 데이터 분리: SQLite DB / 생성된 미디어 / 스킬 복사본 모두 userData 디렉터리에 저장
- FFmpeg/FFprobe 포함 배포. workspace 스킬 템플릿은 첫 시작 시 복사, 업그레이드 시 누락분만 보충하고 덮어쓰지 않음
- 데이터베이스를 MySQL에서 SQLite로 완전 마이그레이션(better-sqlite3 + WAL)
- 비즈니스 코드 변경 제로(Drizzle 쿼리 계층은 본질적으로 이식 가능), 멱등 DDL 재생
- 1회용 가져오기 스크립트
import-mysql-to-sqlite.ts추가(테이블별 행 수 검증 + 자동 백업)
- 백엔드 esbuild 단일 파일 번들(externals: sharp/better-sqlite3/ffmpeg 바이너리 패키지)
- Docker/MySQL 배포 방식 제거(git 히스토리에서 복구 가능)
v3.1.0 (2026-09)
- Alibaba Bailian Wan 3.0 동영상 모델 추가(Prime / 표준, 공식 input.media/parameters 파라미터 지원)
- 작업대 상단 바에 해상도 선택기 추가, 제공사별 네이티브 단계 표시(Seedance 480p/720p, MiniMax 768P/2K, Wan 480P/720P/1080P)
- 기본 동영상 모델을 Seedance 2.0 Mini로 변경
- 동영상 모델 전환 시 제공사/모델 불일치로 인한 생성 오류 수정
- 배치 동영상: 선택 모드 + 생성 전 확인(숏 수/총 길이/모델/해상도), 실패 작업 원클릭 재시도
- 스토리보드 길이를 동영상 생성 파라미터 영역에서 직접 편집·저장, 단건/배치 생성에 통일 적용
- 실사/민감 콘텐츠 심사 실패 시 모델 전환 후 재시도 안내
v3.0.0 (2026-08)
🚀 배포 및 경험 최적화
- Docker 배포 준비 개선
- MySQL / 앱 헬스 체크, 데이터베이스 준비 후 앱 시작
- 데이터베이스 초기화에 재시도 추가, 컨테이너 오케스트레이션에서 첫 배포 무인 완료
- 시스템 FFmpeg 의존 제거, 내장 바이너리로 전면 전환
- Agent skills 디렉터리 볼륨 영속화(설정 페이지 온라인 편집 유실 방지)
docker/init.sql및 납출 스크립트 추가(DBA 검토 / 사전 테이블 생성)
- 첫 사용 가이드
- AI 서비스 미설정 시 사이트 상단 배너로 설정 페이지 안내
- 설정 페이지에 「火宝快捷 설정」 추가: Key 하나로 텍스트/이미지/영상 추천 설정 3개 입력
- 모델 미설정 오류의 중국어화 및 설정 페이지 안내
- 영상 모델 기본값을 Seedance 2.0 Fast로 조정
- 프로바이더 통합: OpenAI / Gemini / Volcano Engine만 유지
- 워크벤치: 작업 목록 드로어, 파이프라인 대섹션 상태, 선택적 병합(병합 전 영상 파일 존재 검증)
- 소재 라이브러리 개편, @멘션 최적화, 에피소드 목록 재구성
v2.0.0 (2026-04)
🚀 대규모 업데이트
- 프로젝트를 TypeScript 기술 스택으로 전면 마이그레이션
- 백엔드: Hono + Drizzle ORM + mysql2
- 프런트엔드: Nuxt 3 + Vue 3
- AI Agent: Mastra 프레임워크
- 에피소드 워크벤치 UI와 제작 플로우 재구축
- 더 컴팩트한 콘솔 레이아웃
- 스토리보드 편집 영역 재구축
- 샷 이미지, 영상, 합성, 납출 화면 재구축
- Docker 배포 지원 추가, 프런트엔드와 백엔드를 단일 이미지로 통합
- 런타임 Skill 로딩 메커니즘 추가
- 멀티 프로바이더 미디어 어댑터 확장
- 이미지: OpenAI, Gemini, Volcano Engine, Alibaba
- 영상: Volcano Engine/Seedance, Vidu, Alibaba
- 로컬 파일 처리 및 참조 이미지 온디맨드 트랜스코딩 최적화
v1.0.4 (2026-01-27)
- 로컬 스토리지 전략 도입으로 외부 리소스 링크 실효 회피
- Base64 참조 이미지 임베디드 전송
- 샷 전환 상태 리셋 문제 수정
- 장면의 챕터 마이그레이션 추가
v1.0.3 (2026-01-16)
- 데이터베이스 동시 접근 성능 최적화
- Docker 크로스 플랫폼 host.docker.internal 지원
v1.0.2 (2026-01-14)
- 영상 생성 API 응답 파싱 문제 수정
- OpenAI Sora 영상 엔드포인트 설정 추가
- 오류 처리 및 로그 출력 최적화
📄 라이선스
이 프로젝트는 CC BY-NC-SA 4.0(저작자표시-비영리-동일조걳경변경허락 4.0 국제) 라이선스를 채택하고 있습니다.
- ✅ 개인 사용, 학습·연구, 비영리 프로젝트는 자유롭게 사용 가능
- ✅ 수정 및 재배포 가능, 단 저작자 표시와 동일 라이선스로 공유 필요
- ❌ 상업적 사용 금지 — 저작자의 서면 허가 없이 이 프로젝트의 전부 또는 일부를 어떠한 상업적 목적(유료 서비스, 상업 배포, 재판매 등)으로도 사용할 수 없습니다
라이선스 전문은 LICENSE를 참조하세요.
🤝 기여 가이드
Issue와 Pull Request를 환영합니다!
- 이 프로젝트를 Fork
- 기능 브랜치 생성(
git checkout -b feature/AmazingFeature) - 변경 사항 커밋(
git commit -m 'Add some AmazingFeature') - 브랜치 푸시(
git push origin feature/AmazingFeature) - Pull Request 생성
자주 쓰는 검사 명령:
cd backend && npm run typecheck
cd ../frontend && npm run build
💬 WeChat 그룹
QR 코드를 스캔하여 WeChat 그룹에 참여하세요:
"AI가 더 창의적인 일을 돕게 하자"
🔗 관련 링크
이 프로젝트는 LINUX DO 커뮤니티의 링크 승인을 받았습니다.
- LINUX DO — 진정한 오픈소스 정신, 함께 만들고 공유하는 기술 커뮤니티