<p>
  <a href="https://github.com/HBAI-Ltd/Toonflow-app">
    <img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub" />
  </a>
  &nbsp;|&nbsp;
  <a href="https://gitee.com/HBAI-Ltd/Toonflow-app">
    <img src="https://img.shields.io/badge/Gitee-C71D23?style=flat-square&logo=gitee&logoColor=white" alt="Gitee" />
  </a>
  &nbsp;|&nbsp;
  <a href="https://gitcode.com/HBAI-Ltd/Toonflow-app">
    <img src="./atomgitLogo.png" alt="Atomgit" style="height:16px"/>
    Atomgit
  </a>
</p>

<p align="center">
  <a href="/README.md">简体中文</a> | 
  <a href="./README.zhtw.md">繁體中文</a> | 
  <a href="./README.en.md">English</a> | 
  <a href="./README.th.md">ไทย</a> | 
  <strong>Tiếng Việt</strong> | 
  <a href="./README.ja.md">日本語</a> | 
  <a href="./README.ru.md">Русский</a>
</p>

<div align="center">

<img src="./logo.png" alt="Toonflow Logo" height="120"/>

# Toonflow

  <p align="center">
    <b>
      Xưởng sản xuất phim ngắn AI
      <br />
      Động ngón tay là tiểu thuyết hóa thành phim ngay!
      <br />
      Kịch bản AI × Hình ảnh AI × Tạo dựng thần tốc 🔥
    </b>
  </p>
  <p align="center">
    <a href="https://github.com/HBAI-Ltd/Toonflow-app/stargazers">
      <img src="https://img.shields.io/github/stars/HBAI-Ltd/Toonflow-app?style=for-the-badge&logo=github" alt="Stars Badge" />
    </a>
    <a href="https://www.apache.org/licenses/LICENSE-2.0" target="_blank">
      <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge" alt="Apache-2.0 License Badge" />
    </a>
    <a href="https://github.com/HBAI-Ltd/Toonflow-app/releases">
      <img alt="release" src="https://img.shields.io/github/v/release/HBAI-Ltd/Toonflow-app?style=for-the-badge" />
    </a>
  </p>
  
  > 🚀 **Công cụ sản xuất phim ngắn một cửa**: Từ văn bản tới nhân vật, từ dàn cảnh tới video, toàn bộ quy trình AI hóa không cần kỹ năng, tăng hiệu quả sáng tạo gấp 10 lần+!
</div>

---

# 🌟 Tính năng chính

Toonflow là công cụ AI tạo phim truyện tranh ngắn, tận dụng công nghệ AI để chuyển tự động tiểu thuyết thành kịch bản, kết hợp hình ảnh, video AI để sáng tác phim ngắn hiệu quả. Với Toonflow, bạn dễ dàng hoàn thành toàn bộ quy trình từ văn bản tới hình ảnh, khiến chế tác phim ngắn trở nên thông minh và tiện lợi hơn bao giờ hết.

- ✅ **Tạo nhân vật**  
   Phân tích tự động văn bản tiểu thuyết gốc, nhận diện thông minh và xây dựng thiết lập nhân vật, gồm ngoại hình, tính cách, thân phận,... cung cấp nền tảng chắc chắn cho sáng tác kịch bản và hình ảnh sau này.
- ✅ **Tạo kịch bản**  
   Dựa trên sự kiện và chương đã chọn, hệ thống tự động tạo kịch bản có cấu trúc gồm thoại, mô tả cảnh, diễn biến tình tiết, chuyển đổi hiệu quả từ văn học sang kịch bản truyền hình, điện ảnh.
- ✅ **Làm phân cảnh**  
   Theo nội dung kịch bản, tự động tạo từ khóa phân cảnh, thiết kế hình ảnh, chi tiết tiền trung hậu cảnh, động thái nhân vật, thiết lập đạo cụ và bố trí trường quay, tự động phân cảnh dựa trên kịch bản, tối ưu đường lối sản xuất video.
- ✅ **Tổng hợp video**  
   Tích hợp công nghệ tạo ảnh và video AI, dùng AI tạo phân đoạn video, biên tập trực tuyến, hỗ trợ điều chỉnh cá nhân hóa đầu ra, giúp sáng tác phim hiệu quả, triển khai nhanh.

---

# 📦 Ứng dụng

- Sáng tác nội dung video ngắn
- Thử nghiệm điện ảnh hóa tiểu thuyết
- Công cụ AI chuyển thể văn học
- Phát triển, dựng mẫu nhanh kịch bản
- Tạo nguyên liệu video

---

# 🔰 Hướng dẫn sử dụng

## 📺 Video hướng dẫn

https://www.bilibili.com/video/BV1na6wB6Ea2
[![Toonflow 8 phút nhanh chóng làm chủ AI Video](./videoCover.png)](https://www.bilibili.com/video/BV1na6wB6Ea2)

**Toonflow 8 phút nhanh chóng bắt đầu với AI Video**
👉 [Click xem tại đây](https://www.bilibili.com/video/BV1na6wB6Ea2/?share_source=copy_web&vd_source=5b718c25439a901a34c7bc0c1d35b38e)

📱 Quét mã QR trên WeChat để xem trên điện thoại

<img src="./videoQR.png" alt="微信扫码观看" width="150"/>

---

# 🚀 Cài đặt

## Điều kiện tiên quyết

Trước khi cài đặt và sử dụng, hãy chuẩn bị:

- ✅ Địa chỉ API dịch vụ mô hình ngôn ngữ lớn (AI)
- ✅ Địa chỉ API dịch vụ video Sora hoặc Đậu Bao
- ✅ Địa chỉ API dịch vụ tạo ảnh Nano Banana Pro

## Cài đặt tại máy

### 1. Tải về & cài đặt

| Hệ điều hành | Tải GitHub                                                | Tải qua Quark Drive                            | Ghi chú         |
| :---------: | :-------------------------------------------------------- | :--------------------------------------------- | :-------------- |
| Windows     | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Drive](https://pan.quark.cn/s/94ef07509df0) | Gói cài chính thức|
| Linux       | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Drive](https://pan.quark.cn/s/94ef07509df0) | Gói cài chính thức|
| macOS       | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Drive](https://pan.quark.cn/s/94ef07509df0) | Gói cài chính thức|

> [!CAUTION]
> Đối với MacOS, vào Cài đặt - Quyền riêng tư & Bảo mật để cấu hình, nếu không phần mềm có thể không mở được do vấn đề chứng chỉ
>
> Tham khảo tài liệu Zhihu: [https://www.zhihu.com/question/433389276](https://www.zhihu.com/question/433389276)

> Do hạn chế môi trường Gitee OS và kích thước upload Release, hiện chưa cung cấp đường dẫn tải Release tại Gitee.

### 2. Khởi động dịch vụ

Cài đặt xong, mở chương trình là có thể bắt đầu sử dụng.

> ⚠️ **Đăng nhập lần đầu**  
> Tài khoản: `admin`  
> Mật khẩu: `admin123`

## Triển khai Docker

### Điều kiện

- Đã cài đặt [Docker](https://docs.docker.com/get-docker/) (version 20.10+)

### Cách 1: Triển khai trực tuyến

Đang hoàn thiện, tạm thời sử dụng build trên máy.

### Cách 2: Build local

Dùng mã nguồn sẵn có, phù hợp cho dev hoặc người đã clone repo, cần cài git trên máy:

```shell
# Clone nếu chưa có
git clone https://github.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app

# Build và khởi động bằng docker-compose
yarn docker:local

# Hoặc build thủ công
docker build -t toonflow .
docker run -d -p <cổng máy>:10588 -v <đường dẫn data>: /app/data toonflow

# Sau đó, truy cập trang qua /web/index.html trên cổng phù hợp
# Ví dụ http://localhost:10588/web/index.html
```

### Giải thích cổng dịch vụ

| Cổng      | Mục đích       | Mapping deploy      |
| --------- | ------------- | ------------------- |
| `10588`   | Giao diện     | `10588:10588`       |

**Các biến môi trường:**

| Biến        | Giải thích                              |
| ----------- | -------------------------------------- |
| `NODE_ENV`  | Môi trường chạy, `prod` là production  |
| `PORT`      | Cổng dịch vụ (mặc định 10588)          |
| `OSSURL`    | Địa chỉ truy cập tệp tĩnh (OSS)        |

---

## Triển khai trên máy chủ

### A. Yêu cầu máy chủ

- **Hệ điều hành**: Ubuntu 20.04+ / CentOS 7+
- **Node.js**: 24.x (khuyến nghị, tối thiểu 23.11.1+)
- **RAM**: 2GB+

### B. Triển khai

#### 1. Cài đặt môi trường

```bash
# Cài Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 24
# Cài Yarn & PM2
npm install -g yarn pm2
```

#### 2. Triển khai dự án

**Clone từ GitHub:**

```bash
cd /opt
git clone https://github.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app
yarn install
yarn build
```

**Clone từ Gitee (khuyên dùng tại VN):**

```bash
cd /opt
git clone https://gitee.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app
yarn install
yarn build
```

#### 3. Cấu hình PM2

Tạo file `pm2.json`:

```json
{
  "name": "toonflow-app",
  "script": "data/serve/app.js",
  "instances": "max",
  "exec_mode": "cluster",
  "env": {
    "NODE_ENV": "prod",
    "PORT": 10588,
    "OSSURL": "http://127.0.0.1:10588/"
  }
}
```

**Giải thích biến môi trường:**

| Biến        | Giải thích                              |
| ----------- | -------------------------------------- |
| `NODE_ENV`  | Môi trường chạy, `prod` là production  |
| `PORT`      | Cổng dịch vụ                           |
| `OSSURL`    | Địa chỉ truy cập tài nguyên tĩnh        |

---

#### 4. Khởi động dịch vụ

```bash
pm2 start pm2.json
pm2 startup
pm2 save
```

#### 5. Lệnh thường dùng

```bash
pm2 list              # Xem danh sách tiến trình
pm2 logs toonflow-app # Xem logs
pm2 restart all       # Khởi động lại dịch vụ
pm2 monit             # Màn hình monitor
```

> ⚠️ **Đăng nhập lần đầu**  
> Tài khoản: `admin`  
> Mật khẩu: `admin123`

#### 6. Triển khai web frontend

Nếu cần deploy riêng hoặc custom giao diện, tham khảo mã nguồn frontend:

- **GitHub**: [Toonflow-web](https://github.com/HBAI-Ltd/Toonflow-web)
- **Gitee**: [Toonflow-web](https://gitee.com/HBAI-Ltd/Toonflow-web)

> 💡 **Ghi chú**: Repo này đã chứa sẵn tài nguyên frontend được build, người dùng thông thường không cần deploy thêm phần giao diện, repo frontend chỉ dành cho dev muốn tùy biến sâu.

---

# 🔧 Hướng dẫn quy trình phát triển

> [!CAUTION]
> 🚧 **Quy tắc gửi PR** 🚧
>
> ⛔ Không nhận PR gửi thẳng vào nhánh `master` ｜ ✅ Gửi PR vào nhánh `develop`
>
> Chào mừng các dev cùng góp sức phát triển Toonflow. Muốn tham gia nhóm, liên hệ admin ACT trong group chat.

## 🛠️ Công nghệ sử dụng

| Loại       | Công nghệ                                                                                      |
| ---------- | --------------------------------------------------------------------------------------------- |
| Runtime    | Node.js 23.11.1+                                                                              |
| Ngôn ngữ    | TypeScript 5.x                                                                               |
| Backend    | Express 5                                                                                     |
| Database   | SQLite (better-sqlite3/knex)                                                                  |
| Tích hợp AI| Vercel AI SDK (OpenAI/Anthropic/Google/DeepSeek/Zhipu/MiniMax/TongyiQianwen/xAI)               |
| Suy luận local| @huggingface/transformers (ONNX)                                                          |
| Realtime   | Socket.IO                                                                                     |
| Desktop    | Electron 40                                                                                   |
| Xử lý ảnh  | Sharp                                                                                         |
| Container  | Docker                                                                                        |

## Chuẩn bị môi trường phát triển

- **Node.js**: yêu cầu >= 23.11.1
- **Yarn**: khuyến nghị quản lý package

## Khởi động nhanh

1. **Clone dự án**

   **Từ GitHub:**

   ```bash
   git clone https://github.com/HBAI-Ltd/Toonflow-app.git
   cd Toonflow-app
   ```

   **Từ Gitee (khuyên dùng VN):**

   ```bash
   git clone https://gitee.com/HBAI-Ltd/Toonflow-app.git
   cd Toonflow-app
   ```

2. **Cài dependency**

   Chạy trong thư mục gốc:

   ```bash
   yarn install
   ```

3. **Khởi động môi trường dev**

   Dự án gồm 2 phần: **API backend** và **giao diện frontend**. Tuỳ bạn chọn cách chạy:

   - **Cách 1: Chạy chỉ API backend**

     ```bash
     yarn dev
     ```

     > ⚠️ Lệnh này chỉ khởi động API backend (port 10588), **không gồm frontend** và truy cập `http://localhost:10588` chỉ gọi được API, không có web. Nếu muốn vừa backend vừa giao diện web, chạy GUI hoặc deploy bổ sung frontend.

   - **Cách 2: Chạy GUI ứng dụng desktop Electron**

     ```bash
     yarn dev:gui
     ```

     > Lệnh này khởi động backend đồng thời mở cửa sổ desktop Electron có build frontend sẵn, dùng liền, không cấu hình gì thêm. Dành cho dev muốn trải nghiệm trọn bộ.

   - **Cách 3: Chạy chế độ production**

     ```bash
     yarn start
     ```

     > Chạy trực tiếp bản build (cần build bằng `yarn build` trước).

4. **Đóng gói dự án**

   - Biên dịch TypeScript:

     ```bash
     yarn build
     ```

   - Đóng gói thành exe Windows:

     ```bash
     yarn dist:win
     ```

   - Đóng gói MacOS:

     ```bash
     yarn dist:mac
     ```

   - Đóng gói Linux:

     ```bash
     yarn dist:linux
     ```

5. **Kiểm tra chất lượng code**

   - Đánh giá tổng thể chuẩn code:

     ```bash
     yarn lint
     ```

6. **Bảng debug AI (tùy chọn)**

   Khởi động bảng debug AI SDK, dễ test AI call:

   ```bash
   yarn debug:ai
   ```

## Phát triển Frontend

Nếu muốn chỉnh sửa UI, vào repo frontend:

- **GitHub**: [Toonflow-web](https://github.com/HBAI-Ltd/Toonflow-web)
- **Gitee**: [Toonflow-web](https://gitee.com/HBAI-Ltd/Toonflow-web)

Sau khi build frontend, copy thư mục `dist` vào `data/web` của repo này để tích hợp.

## Cấu trúc dự án

```
📂 build/                    # File build
📂 data/                     # Dữ liệu runtime
│  ├─ 📂 models/            # Model local (ONNX)
│  ├─ 📂 oss/               # Lưu trữ asset (media/nhân vật/cảnh)
│  ├─ 📂 serve/             # Entry prod
│  ├─ 📂 skills/            # Prompt kỹ năng Agent
│  └─ 📂 web/               # Thành phẩm frontend (built-in)
📂 docs/                     # Tài liệu
📂 env/                      # Cấu hình môi trường
📂 scripts/                  # Script build & phụ trợ
📂 src/
├─ 📂 agents/               # Module AI Agent
│  ├─ 📂 productionAgent/   # Agent sản xuất
│  └─ 📂 scriptAgent/       # Agent kịch bản
├─ 📂 lib/                  # Thư viện chung (init db, response...)
├─ 📂 middleware/           # Middleware
├─ 📂 routes/               # Router các module
│  ├─ 📂 agents/            # Quản lý memory Agent
│  ├─ 📂 artStyle/          # Quản lý style tranh
│  ├─ 📂 assets/            # Asset
│  ├─ 📂 assetsGenerate/    # Sinh asset
│  ├─ 📂 cornerScape/       # Quản lý phân cảnh
│  ├─ 📂 general/           # API chung
│  ├─ 📂 login/             # Đăng nhập/ xác thực
│  ├─ 📂 migrate/           # Di trú dữ liệu
│  ├─ 📂 modelSelect/       # Chọn model AI
│  ├─ 📂 novel/             # Quản lý tiểu thuyết
│  ├─ 📂 other/             # Chức năng khác
│  ├─ 📂 production/        # Quản lý sản xuất
│  ├─ 📂 project/           # Quản lý project
│  ├─ 📂 script/            # Tạo kịch bản
│  ├─ 📂 scriptAgent/       # API Agent kịch bản
│  ├─ 📂 setting/           # Thiết lập hệ thống
│  ├─ 📂 task/              # Quản lý task
│  └─ 📂 test/              # API test
├─ 📂 socket/               # WebSocket realtime
├─ 📂 types/                # Định nghĩa TypeScript
├─ 📂 utils/                # Hàm tiện ích
├─ 📄 app.ts                # App entry
├─ 📄 core.ts               # Init core
├─ 📄 env.ts                # Xử lý biến môi trường
├─ 📄 err.ts                # Xử lý lỗi
├─ 📄 logger.ts             # Ghi log
├─ 📄 router.ts             # Đăng ký routes
└─ 📄 utils.ts              # Tiện ích chung
📄 Dockerfile                # Build Docker
📄 electron-builder.yml      # Cấu hình build Electron
📄 skillList.json            # Danh sách skill
📄 LICENSE                   # License (Apache-2.0)
📄 NOTICES.txt               # Ghi chú phụ thuộc third-party
📄 package.json              # Cấu hình dự án
📄 tsconfig.json             # Cấu hình TypeScript
```

---

# 🔗 Repo liên quan

| Repo             | Giải thích                        | GitHub                                             | Gitee                                            |
| ---------------- | -------------------------------- | -------------------------------------------------- | ------------------------------------------------ |
| **Toonflow-app** | Ứng dụng client đầy đủ (repo này, người dùng nên dùng) | [GitHub](https://github.com/HBAI-Ltd/Toonflow-app) | [Gitee](https://gitee.com/HBAI-Ltd/Toonflow-app) |
| **Toonflow-web** | Mã nguồn frontend (cho dev UI)   | [GitHub](https://github.com/HBAI-Ltd/Toonflow-web) | [Gitee](https://gitee.com/HBAI-Ltd/Toonflow-web) |

> 💡 **Lưu ý**: Nếu chỉ muốn dùng Toonflow, tải về client repo này là đủ. Repo frontend chỉ dành cho ai cần phát triển/custome UI thêm.

---

# 👨‍👩‍👧‍👦 Nhóm chat WeChat

~~Nhóm 1~~

~~Nhóm 2~~

...

~~Nhóm 10~~

~~Nhóm 11~~

~~Nhóm 12~~

~~Nhóm 13~~

...

~~Nhóm 24~~

Bot mời tham gia:

<img src="./QR.png" alt="Toonflow QR" height="400"/>

---

# 💌 Liên hệ

📧 Email: [ltlctools@outlook.com](mailto:ltlctools@outlook.com?subject=Toonflow咨询)

---

# 📜 Giấy phép

Toonflow phát hành mã nguồn mở theo Apache-2.0, kèm thỏa thuận thương mại bổ sung.

Chi tiết: https://www.apache.org/licenses/LICENSE-2.0

## Thỏa thuận bổ sung

- Nếu phân phối phần mềm này dưới dạng sản phẩm cho **2 bên thứ ba độc lập trở lên**, bạn phải có **ủy quyền thương mại bằng văn bản** từ HBAI-Ltd.
- **≤ 5 pháp nhân** cùng vận hành nội bộ mà không cung cấp dịch vụ ra bên ngoài được coi là **sử dụng nội bộ, không cần ủy quyền**.
- Không được xóa hoặc sửa đổi nhãn hiệu, logo hoặc thông tin bản quyền trong Toonflow.

## Miễn phí vĩnh viễn

- ✅ Sử dụng Toonflow tạo nội dung và nhận chia sẻ doanh thu nền tảng
- ✅ Phát triển thêm cho sử dụng nội bộ nhóm
- ✅ ≤ 5 pháp nhân vận hành chung nội bộ
- ✅ Học tập cá nhân, nghiên cứu, mục đích phi thương mại

## Bảng giá ủy quyền thương mại

| Giai đoạn | Doanh thu năm | Phí hàng năm |
|------|---------|------|
| 🌱 Ươm tạo | < ¥100,000 | **Miễn phí** |
| 🚀 Khởi nghiệp | ¥100,000–500,000 | ¥5,000/năm |
| 📈 Tăng trưởng | ¥500,000–1,500,000 | ¥20,000/năm |
| 🏢 Mở rộng | ¥1,500,000–5,000,000 | ¥80,000/năm |
| 🌐 Doanh nghiệp | > ¥5,000,000 | Thương lượng |

> **Điều khoản không hồi tố**: Người dùng đã sử dụng Toonflow theo AGPL-3.0 trước khi phát hành v1.0.8 không bị ảnh hưởng. Việc sử dụng hiện tại tiếp tục theo AGPL-3.0.

Xem thỏa thuận đầy đủ tại [LICENSE](../LICENSE).

---

# ⭐️ Lịch sử đánh dấu sao

[![Star History Chart](https://api.star-history.com/svg?repos=HBAI-Ltd/Toonflow-app&type=timeline&legend=top-left)](https://www.star-history.com/#HBAI-Ltd/Toonflow-app&type=timeline&legend=top-left)

---

# 🙏 Lời cảm ơn

Cảm ơn các dự án open source sau đã hỗ trợ Toonflow mạnh mẽ:

- [Express](https://expressjs.com/) - Framework Web Node.js nhanh, mở, gọn nhẹ
- [AI SDK](https://ai-sdk.dev/) - Bộ tool AI cho TypeScript
- [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3) - Bindings SQLite3 hiệu năng cao
- [Sharp](https://sharp.pixelplumbing.com/) - Thư viện xử lý ảnh Node.js nhanh
- [Axios](https://axios-http.com/) - HTTP client dựa trên Promise
- [Zod](https://zod.dev/) - Library kiểm tra schema ưu tiên TypeScript
- [Socket.IO](https://socket.io/) - Engine realtime song phương sự kiện
- [Electron](https://www.electronjs.org/) - Framework phát triển desktop app đa nền tảng
- [Hugging Face Transformers](https://huggingface.co/docs/transformers.js) - Thư viện infer ML local

Cảm ơn các tổ chức/đơn vị/cá nhân sau đã hỗ trợ Toonflow:

<table>
  <tr>
    <td>
      <img src="./sponsored/sophnet.png" alt="算能云 Logo" width="48">
    </td>
    <td>
      <b>Suanneng Cloud</b> tài trợ năng lực tính toán
      <a href="https://www.sophnet.com/">[Trang chủ]</a>
    </td>
  </tr>
</table>

Danh sách phụ thuộc bên thứ ba, vui lòng xem `NOTICES.txt`

