**TypeScript ํ์คํ ๊ธฐ๋ฐ AI ์๋๋ผ๋ง ์๋ ์ ์ ํ๋ซํผ**
[](https://nodejs.org)
[](https://vuejs.org)
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
[](https://github.com/chatfire-AI/huobao-drama/releases/latest)
[ไธญ่ฑๅ่ฏญ](README.md) | [English](README.en.md) | [็ฎไฝไธญๆ](README.zh-CN.md) | [ๆฅๆฌ่ช](README.ja.md) | **ํ๊ตญ์ด**
[๊ธฐ๋ฅ](#-๊ธฐ๋ฅ) โข [๋น ๋ฅธ ์์](#-๋น ๋ฅธ-์์) โข [ํํ ๋ฆฌ์ผ](#-๊ทธ๋ฆผ-ํํ ๋ฆฌ์ผ) โข [๋ฐ์คํฌํฑ ์ฑ](#-๋ฐ์คํฌํฑ-์ฑ-๊ถ์ฅ) โข [๋ฐฐํฌ](#-๋ฐฐํฌ)
**ํ
์คํธ ยท ์ด๋ฏธ์ง ยท ์์ ๋ชจ๋ AI ๊ธฐ๋ฅ, Key ํ๋๋ก ํ์ฑํ**
๋ฐฐํฌ ํ ใ์ค์ โ ็ซๅฎๅฟซๆท ์ค์ ใ์ Key ๋ฅผ ๋ถ์ฌ๋ฃ์ผ๋ฉด ์ถ์ฒ ์ค์ 3๊ฐ๊ฐ ํ ๋ฒ์ ์
๋ ฅ๋ฉ๋๋ค
---
## ๐ ํ๋ก์ ํธ ์๊ฐ
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-static` npm ํจํค์ง์ ๋ฐ์ด๋๋ฆฌ๊ฐ ๋ด์ฅ๋์ด ๋ฐ๋ก ์ฌ์ฉํ ์ ์์ต๋๋ค.
### โ๏ธ ํ๊ฒฝ ๋ณ์
์ค์ ํ์ผ ์์ด ํ๊ฒฝ ๋ณ์๋ก ์ค์ ํฉ๋๋ค(๋ชจ๋ ๊ธฐ๋ณธ๊ฐ์ด ์์ด ๋ก์ปฌ ๊ฐ๋ฐ์ ๋ฌด์ค์ ์ผ๋ก ์์ ๊ฐ๋ฅ):
| ๋ณ์ | ๊ธฐ๋ณธ๊ฐ | ์ค๋ช
|
|---|---|---|
| `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์ ใ์ค์ ใ ํ์ด์ง์์ ์ค์ ํ์ฌ ๋ฐ์ดํฐ๋ฒ ์ด์ค์ ์ ์ฅํฉ๋๋ค. ์ค์ ํ์ผ์ด๋ ํ๊ฒฝ ๋ณ์๋ก ๊ด๋ฆฌํ์ง ์์ต๋๋ค.
### ๐ฅ ์ค์น
```bash
# ์ ์ฅ์ ํด๋ก
git clone https://github.com/chatfire-AI/huobao-drama.git
cd huobao-drama
# ๋ฐฑ์๋ ์์กด์ฑ ์ค์น
cd backend && npm install
# ํ๋ฐํธ์๋ ์์กด์ฑ ์ค์น
cd ../frontend && npm install
```
### ๐ฏ ์คํ
#### ๋ฐฉ๋ฒ 1: ๊ฐ๋ฐ ๋ชจ๋(๊ถ์ฅ)
ํ๋ฐํธ์๋์ ๋ฐฑ์๋๋ฅผ ๋ถ๋ฆฌํ์ฌ ํซ ๋ฆฌ๋ก๋ ์ง์:
```bash
# ํฐ๋ฏธ๋ 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์ ํ๋ฐํธ์๋ ์ ์ ํ์ผ์ ๋ชจ๋ ์ ๊ณต:
```bash
# 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`๋ก ๋นํ์ฑํํ ์ ์์ต๋๋ค.
```bash
# ์๋ ์คํ๋ ๊ฐ๋ฅ(๋์ DB๊ฐ ๋น์ด ์์ง ์์ผ๋ฉด --force ํ์, ์ฐ๊ธฐ ์ ์๋ ๋ฐฑ์
)
cd backend && npx tsx scripts/import-mysql-to-sqlite.ts
```
> ๋ง์ด๊ทธ๋ ์ด์
์ ๋ฐ์ดํฐ๋ฒ ์ด์ค ํ๋ง ํฌํจํฉ๋๋ค. ๊ตฌ ๋ฐฐํฌ์ `data/static/` ์๋ ์ด๋ฏธ์ง/์์ ๋ฑ ๋ฏธ๋์ด ํ์ผ์ ์๋์ผ๋ก ๋ณต์ฌํด์ผ ํ๋ฉฐ, ๊ทธ๋ ์ง ์์ผ๋ฉด ๊ธฐ์กด ์์ฌ์ ์ ๊ทผํ ์ ์์ต๋๋ค.
### ๐ ์ฒซ ์ฌ์ฉ: AI ์๋น์ค ์ค์
์์ ํ ๋ชจ๋ AI ๊ธฐ๋ฅ(ํ
์คํธ/์ด๋ฏธ์ง/์์)์ ์ฌ์ฉํ๋ ค๋ฉด ๋จผ์ ๋ชจ๋ธ ์๋น์ค๋ฅผ ์ค์ ํด์ผ ํฉ๋๋ค. ๋ฏธ์ค์ ์ ํ์ด์ง ์๋จ์ ๋ฐฐ๋๋ก ์๋ดํฉ๋๋ค:
1. ใ์ค์ ใ ํ์ด์ง ์ด๊ธฐ
2. ใ็ซๅฎๅฟซๆท ์ค์ ใ์ Huobao API Key ๋ถ์ฌ๋ฃ๊ธฐ([api.firemux.com์์ ๋ฐ๊ธ](https://api.firemux.com)). ํ
์คํธ, ์ด๋ฏธ์ง, ์์ ์ถ์ฒ ์ค์ 3๊ฐ๊ฐ ํ ๋ฒ์ ์
๋ ฅ๋ฉ๋๋ค
3. ๋๋ ใ์๋ ํ
ํ๋ฆฟใ์ผ๋ก ํ๋ก๋ฐ์ด๋๋ณ ์ถ๊ฐ. ์ฐ๊ฒฐ ํ
์คํธ ์ง์
์ค์ ์ด ์๋ฃ๋๋ฉด ๋ฐฐ๋๊ฐ ์๋์ผ๋ก ์ฌ๋ผ์ง๊ณ ์ํผ์๋ ์ ์์ ์์ํ ์ ์์ต๋๋ค.
---
## ๐ ๊ทธ๋ฆผ ํํ ๋ฆฌ์ผ
์์ค๋ถํฐ ์์ฑ ์ํผ์๋๊น์ง์ ์ ์ฒด ์ ์ ํ๋ฆ์
๋๋ค. ์ผ์ชฝ ์งํ ํ์์ค์ด ํญ์ ํ์ฌ ๋จ๊ณ๋ฅผ ๋ณด์ฌ์ค๋๋ค.
### 1๋จ๊ณ ยท ํ๋ก์ ํธ ์์ฑ
ํ์์ "์ ํ๋ก์ ํธ"๋ฅผ ํด๋ฆญํ๊ณ **ํ๋ฉด ๋น์จ**(16:9 ๊ฐ๋ก / 9:16 ์ธ๋ก, ์์ฑ ํ ๋ณ๊ฒฝ ๋ถ๊ฐ)๊ณผ **ํํ**(3D / ์ค์ฌ ๋ฑ, ๋ชจ๋ ์ด๋ฏธ์ง ํ๋กฌํํธ์ ์ฃผ์
)์ ์ ํํฉ๋๋ค.