<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.svg" alt="Atomgit" style="height:20px"/>
  </a>
</p>

<p align="center">
  <a href="../README.md">简体中文</a> | 
  <a href="./README.zhtw.md">繁體中文</a> | 
  <strong>English</strong> | 
  <a href="./README.th.md">ไทย</a> | 
  <a href="./README.vi.md">Tiếng Việt</a> | 
  <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>
      AI Short Drama Factory
      <br />
      Turn your novel into episodes with just a few clicks!
      <br />
      AI Scripts × AI Visuals × Ultra-fast Generation 🔥
    </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>
  
> 🚀 **All-in-One Short Drama Studio**: From text to characters, from storyboard to final video.  
> Fully AI-powered workflow with zero barrier to entry — boosting your creative efficiency by 10x or more!
</div>

---

# 🌐 Multi-Language Support

Toonflow supports the following interface languages:

| Language | Language Name |
|------|----------|
| 简体中文 | Chinese (Simplified) |
| 繁體中文 | Chinese (Traditional) |
| English | English |
| ไทย | Thai |
| Tiếng Việt | Vietnamese |
| 日本語 | Japanese |
| Русский | Russian |

> 💡 More languages are on the way. Translation contributions are highly welcome!

---

# 🌟 Main Features

Toonflow is an AI-powered tool for creating short dramas, short films, and comics. It can automatically transform novels into scripts, then combine AI-generated characters, images, and videos to produce high-quality content efficiently.  

With Toonflow, you can complete the entire workflow from text to final video with ease — making short-form video and drama production significantly smarter and more convenient.

- ✅ **Character Generation**  
  Automatically analyzes the original novel text, intelligently identifies key elements, and generates detailed character profiles including appearance, personality, background, and relationships — laying a strong foundation for scriptwriting and visual production.

- ✅ **Script Generation**  
  Based on selected events and chapters, the system automatically creates well-structured scripts with natural dialogue, scene descriptions, and plot development, enabling efficient adaptation from literature to cinematic format.

- ✅ **Storyboard Creation**  
  From the generated script, Toonflow intelligently creates storyboard prompts and visual layouts. It details foreground, midground, and background elements, character movements, props, and scene composition — providing a complete and ready-to-use blueprint for video production.

- ✅ **Video Synthesis**  
  Integrates advanced AI image and video generation technologies to produce high-quality video clips. The built-in online editor allows flexible personalization and fine-tuning, making the entire creative process smooth, fast, and highly efficient.

---

# 📦 Use Cases

- Short video content creation (Shorts, Reels, TikTok)
- Novel-to-film / drama adaptation experiments
- AI-powered literary adaptation tool
- Script development and rapid prototyping
- Video asset and footage generation

---

# 🔰 User Guide

## 📺 Video Tutorial

[https://www.bilibili.com/video/BV1oXD7BqEqJ](https://www.bilibili.com/video/BV1oXD7BqEqJ)
[![Toonflow 12-Minute AI Video Quick Start](./videoCover.jpg)](https://www.bilibili.com/video/BV1oXD7BqEqJ)

**Toonflow: 8-Minute AI Video Quick Start**
👉 [Click to Watch](https://www.bilibili.com/video/BV1oXD7BqEqJ/?share_source=copy_web&vd_source=5b718c25439a901a34c7bc0c1d35b38e)

📱 Scan the QR code to watch on mobile

<img src="./videoQR.png" alt="Scan QR code to watch on mobile" width="150"/>

---

# 🚀 Installation

## Prerequisites

Before installing and using Toonflow, please prepare the following:

- ✅ API endpoint for Large Language Model (LLM)
- ✅ API endpoint for video generation services (Sora or Doubao)
- ✅ API endpoint for image generation model (Nano Banana Pro)

## Local Installation

### 1. Download and Install

| OS | GitHub | Atomgit | Quark Drive Download | Description |
| :------: | :----------------------------------------------------------- | :------------------------------------------------------------ | :---------------------------------------------- | :------------- |
| Windows  | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Release](https://gitcode.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Drive](https://pan.quark.cn/s/94ef07509df0) | Official Installer |
|  Linux   | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Release](https://gitcode.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Drive](https://pan.quark.cn/s/94ef07509df0) | Official Installer |
|  macOS   | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Release](https://gitcode.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Drive](https://pan.quark.cn/s/94ef07509df0) | Official Installer |

> [!CAUTION]
> **MacOS Users:** Please go to `System Settings > Privacy & Security` to allow the application to run; otherwise, it may fail to open due to certificate issues.
>
> Reference (Zhihu): [https://www.zhihu.com/question/433389276](https://www.zhihu.com/question/433389276)

> Due to Gitee OS environment constraints and Release file size upload limits, Gitee Release download links are currently unavailable.

### 2. Start the Service

After installation, simply launch the program to start using the service.

> ⚠️ **Default Login** 
> Username: `admin`  
> Password: `admin123`

## Docker Deployment

### Prerequisites

- [Docker](https://docs.docker.com/get-docker/) installed (Version 20.10+)

### Method 1: Online Deployment

To be updated. Please use local build for now.

### Method 2: Local Build

Build directly using the local source code. This is suitable for developers or users who have cloned the repository. You will need `git` installed locally:

```shell
# Clone the repository first (skip if already cloned)
git clone https://github.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app

# Build and start locally using docker-compose
yarn docker:local

# Or build manually
docker build -t toonflow .
docker run -d -p <Local_Port>:10588 -v <Local_Data_Path>:/app/data toonflow

# You can now access the page at the corresponding port at /web/index.html
# Example: http://localhost:10588/web/index.html
```

### Service Port Description

| Port    | Purpose  | Deployment Mapping |
| ------- | -------- | ------------- |
| `10588` | Software UI | `10588:10588` |

**Environment Variables:**

| Variable   | Description                               |
| ---------- | ----------------------------------------- |
| `NODE_ENV` | Operating environment, `prod` for production |
| `PORT`     | Service listening port (Default: 10588)   |
| `OSSURL`   | File storage access URL, used for static resources |

---

## Cloud Deployment

### 1. Server Requirements

- **OS**: Ubuntu 20.04+ / CentOS 7+
- **Node.js**: 24.x (Recommended, Minimum 23.11.1+)
- **Memory**: 2GB+

### 2. Server Deployment

#### 1. Install Environment

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

#### 2. Deploy Project

**Clone from GitHub:**

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

**Clone from Gitee (Recommended for users in China):**

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

#### 3. Configure PM2

Create a `pm2.json` file:

```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/"
  }
}
```

**Environment Variables:**

| Variable   | Description                                           |
| ---------- | ----------------------------------------------------- |
| `NODE_ENV` | Operating environment (`prod` = Production)           |
| `PORT`     | Service listening port (default: 10588)               |
| `OSSURL`   | Object Storage URL for storing and serving static files |

---

#### 4. Start the Service

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

#### 5. Common Commands

```bash
pm2 list              # View processes
pm2 logs toonflow-app # View logs
pm2 restart all       # Restart services
pm2 monit             # Monitoring dashboard
```

> ⚠️ **Default Login** 
> Username: `admin`  
> Password: `admin123`

#### 6. Deploy Frontend

If you need to deploy or customize the frontend interface separately, please refer to the frontend repository:

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

> 💡 **Note**: This repository already includes the compiled frontend resources.  
> Regular users do not need to deploy the frontend separately. The Toonflow-web repository is intended only for developers who want to make custom modifications or contribute to the frontend.

---

# 🔧 Development Workflow Guide

> [!CAUTION]
> 🚧 **PR Submission Guidelines** 🚧
>
> ⛔ **No PRs accepted on the `master` branch**  
> ✅ **Please submit all Pull Requests to the `develop` branch**

We welcome all developers who want to contribute to Toonflow.  
If you're interested in joining, please contact the project maintainer (ACT) in our community group.

## 🛠️ Tech Stack

| Category   | Technology                                                                                |
| ---------- | ----------------------------------------------------------------------------------------- |
| Runtime    | Node.js 23.11.1+                                                                          |
| Language   | TypeScript 5.x                                                                            |
| Backend    | Express 5                                                                                 |
| Database   | SQLite (better-sqlite3 / knex)                                                            |
| AI Integ.  | Vercel AI SDK (OpenAI / Anthropic / Google / DeepSeek / Zhipu / MiniMax / Qwen / xAI)     |
| Local Inf. | @huggingface/transformers (ONNX)                                                          |
| Real-time  | Socket.IO                                                                                 |
| Desktop UI | Electron 40                                                                               |
| Image Proc.| Sharp                                                                                     |
| Container  | Docker                                                                                    |

## Development Environment Prep

- **Node.js**: Version 23.11.1 or higher required
- **Yarn**: Recommended package manager

## Quick Start

1. **Clone the Project**

   **From GitHub:**

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

   **From Gitee (Recommended for China):**

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

2. **Install Dependencies**

   Run the following command in the project root directory:

   ```bash
   yarn install
   ```

3. **Start the Development Environment**

   This project consists of two parts: the **Backend API Service** and the **Frontend Pages**. Choose your startup method based on your needs:

   - **Method 1: Start Backend Service Only**

     ```bash
     yarn dev
     ```

     > ⚠️ This command only starts the backend API service (Port 10588) and **does not include the frontend pages**. Visiting `http://localhost:10588` directly will only allow API calls without a UI. To use the frontend, start the frontend project separately or use the GUI mode below.

   - **Method 2: Start Electron Desktop Client**

     ```bash
     yarn dev:gui
     ```

     > This command launches both the backend service and the Electron desktop window simultaneously. It comes with built-in frontend pages ready out-of-the-box, requiring no extra configuration. Ideal for developers who want to experience the full feature set.

   - **Method 3: Start in Production Mode**

     ```bash
     yarn start
     ```

     > Run the compiled service directly in production mode (requires running `yarn build` first).

4. **Project Build & Packaging**

   - Compile and generate TypeScript files:

     ```bash
     yarn build
     ```

   - Package as a Windows executable:

     ```bash
     yarn dist:win
     ```

   - Package as a Mac executable:

     ```bash
     yarn dist:mac
     ```

   - Package as a Linux executable:

     ```bash
     yarn dist:linux
     ```

5. **Code Quality Checks (Linting)**

   - Run global syntax and styling checks:

     ```bash
     yarn lint
     ```

6. **AI Debug Panel (Optional)**

   Launch the AI SDK visual debugging tool to easily trace AI calls:

   ```bash
   yarn debug:ai
   ```

## Frontend Development

If you need to modify or customize the frontend interface, please go to the frontend repository:

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

After building the frontend, copy the entire `dist` folder into the `data/web` directory of this project to integrate it.

## Project Structure

```
📂 build/                    # Build artifacts
📂 data/                     # Runtime data
│  ├─ 📂 models/             # Local inference models (ONNX)
│  ├─ 📂 oss/                # Object storage (images, characters, scenes)
│  ├─ 📂 serve/              # Production environment entry point
│  ├─ 📂 skills/             # Agent skill prompts
│  └─ 📂 web/                # Built frontend assets (embedded)
📂 docs/                     # Documentation and resources
📂 env/                      # Environment configurations
📂 scripts/                  # Build and utility scripts
📂 src/
├─ 📂 agents/                # AI Agent modules
│  ├─ 📂 productionAgent/    # Production Agent
│  └─ 📂 scriptAgent/        # Script Agent
├─ 📂 lib/                   # Shared libraries (DB initialization, response formatting)
├─ 📂 middleware/            # Express middlewares
├─ 📂 routes/                # Routing modules
│  ├─ 📂 agents/             # Agent memory management
│  ├─ 📂 artStyle/           # Art style management
│  ├─ 📂 assets/             # Asset management
│  ├─ 📂 assetsGenerate/     # Asset generation
│  ├─ 📂 cornerScape/        # Storyboard management
│  ├─ 📂 general/            # General APIs
│  ├─ 📂 login/              # Authentication
│  ├─ 📂 migrate/            # Data migration
│  ├─ 📂 modelSelect/        # Model selection
│  ├─ 📂 novel/              # Novel management
│  ├─ 📂 other/              # Other functionalities
│  ├─ 📂 production/         # Production and editing management
│  ├─ 📂 project/            # Project management
│  ├─ 📂 script/             # Script generation
│  ├─ 📂 scriptAgent/        # Script Agent interface
│  ├─ 📂 setting/            # System settings
│  ├─ 📂 task/               # Task management
│  └─ 📂 test/               # Test APIs
├─ 📂 socket/                # Real-time communication via WebSocket
├─ 📂 types/                 # TypeScript type declarations
├─ 📂 utils/                 # Utility functions
├─ 📄 app.ts                 # Application entry point
├─ 📄 core.ts                # Core system initialization
├─ 📄 env.ts                 # Environment variables handling
├─ 📄 err.ts                 # Error handling
├─ 📄 logger.ts              # Logging module
├─ 📄 router.ts              # Route registration
└─ 📄 utils.ts               # General utilities
📄 Dockerfile                # Docker build file
📄 electron-builder.yml      # Electron packaging configuration
📄 skillList.json            # Skill list
📄 LICENSE                   # License (Apache-2.0)
📄 NOTICES.txt               # Third-party dependency notices
📄 package.json              # Project configuration
📄 tsconfig.json             # TypeScript configuration
```

---

# 🔗 Related Repositories

| Repository       | Description                                                                 | GitHub                                             | Gitee                                            |
|------------------|-----------------------------------------------------------------------------|----------------------------------------------------|--------------------------------------------------|
| **Toonflow-app** | Full client (This repository — recommended for most users)                  | [GitHub](https://github.com/HBAI-Ltd/Toonflow-app) | [Gitee](https://gitee.com/HBAI-Ltd/Toonflow-app) |
| **Toonflow-web** | Frontend source code (For frontend developers)                              | [GitHub](https://github.com/HBAI-Ltd/Toonflow-web) | [Gitee](https://gitee.com/HBAI-Ltd/Toonflow-web) |

> 💡 **Tip**: If you just want to use Toonflow, downloading the client from this repository is sufficient. The Toonflow-web repository is intended only for developers who need to customize the UI or perform secondary development.

---

# 👨‍👩‍👧‍👦 Discord Community

Click the icon below to join our Discord:

[![Join our Discord](https://cdn.prod.website-files.com/6257adef93867e50d84d30e2/67d00cf7266d2c75571aebde_Example.svg)](https://discord.gg/HEjKmpNpAZ)

Or click the direct link: [https://discord.gg/HEjKmpNpAZ](https://discord.gg/HEjKmpNpAZ)

---

# 💌 Contact Us

📧 Email: [ltlctools@outlook.com](mailto:ltlctools@outlook.com?subject=Toonflow%20Inquiry)

---

# 📜 License

Toonflow is open-sourced under the Apache-2.0 License with an additional supplementary commercial agreement.

License details: https://www.apache.org/licenses/LICENSE-2.0

## Supplementary Commercial Agreement

- If this software is distributed as a product to **2 or more independent third parties**, a **written commercial license** from HBAI-Ltd is required.
- Joint operation and internal use by **≤ 5 legal entities** (without providing services to external users) is considered internal use and **does not require a license**.
- It is strictly prohibited to remove or modify any logos or copyright information within Toonflow.

## Forever Free Usage Scenarios

- ✅ Using Toonflow to create content and earning revenue share from video platforms
- ✅ Secondary development for internal team use
- ✅ Joint/internal use by up to 5 legal entities
- ✅ Personal learning, research, and non-commercial purposes

## Commercial License Pricing

| Phase          | Annual Revenue          | Annual Fee          |
|----------------|-------------------------|---------------------|
| 🌱 Incubation  | < $15,000               | **Free** |
| 🚀 Startup     | $15,000 – $75,000       | $750 / year         |
| 📈 Growth      | $75,000 – $200,000      | $2,900 / year       |
| 🏢 Scale       | $200,000 – $750,000     | $11,500 / year      |
| 🌐 Enterprise  | > $750,000              | Negotiable          |

> **Non-Retroactivity Clause**: Users who were using Toonflow under the AGPL-3.0 license before version v1.0.8 will continue to be governed by AGPL-3.0 and are not affected by this agreement change.

For the full agreement, please refer to the [LICENSE](./LICENSE) file.

---

# ⭐️ Star History

[![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)

---

# 🙏 Acknowledgements

We sincerely thank the following open-source projects for providing robust support to Toonflow:

- [Express](https://expressjs.com/) - Fast, unopinionated, minimalist web framework for Node.js
- [AI SDK](https://ai-sdk.dev/) - The AI toolkit for TypeScript
- [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3) - High-performance SQLite3 binding library
- [Sharp](https://sharp.pixelplumbing.com/) - High-performance Node.js image processing
- [Axios](https://axios-http.com/) - Promise-based HTTP client
- [Zod](https://zod.dev/) - TypeScript-first schema validation
- [Socket.IO](https://socket.io/) - Real-time bidirectional event-based communication
- [Electron](https://www.electronjs.org/) - Cross-platform desktop application framework
- [Hugging Face Transformers](https://huggingface.co/docs/transformers.js) - State-of-the-art Machine Learning for the web

Thanks to the following organizations/individuals for supporting Toonflow:

<table>
  <thead>
    <tr>
      <th align="center">Logo</th>
      <th align="center">Name</th>
      <th align="center">Support Type</th>
      <th>Description</th>
      <th align="center">Website</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td align="center"><img src="./sponsored/sophnet.png" alt="Sophnet Logo" width="48"></td>
      <td align="center"><b>Sophnet</b></td>
      <td align="center">💻 Computing Sponsor</td>
      <td>Committed to creating a faster, more stable, and more cost-effective one-stop model inference API service platform</td>
      <td align="center"><a href="https://www.sophnet.com/">Website</a></td>
    </tr>
    <tr>
      <td align="center"><img src="./sponsored/atlascloud.png" alt="Atlas Cloud Logo" width="48"></td>
      <td align="center"><b>Atlas Cloud</b></td>
      <td align="center">💻 Computing Sponsor</td>
      <td>The world's first full-modal inference platform built for developers. Run AI across every modality—chat, reasoning, image, audio, video—through one unified API. 300+ models including DeepSeek, Minimax, Seedance 2.0, Flux. OpenAI-compatible, no provider switching. Explore, test, scale inference seamlessly.</td>
      <td align="center"><a href="https://www.atlascloud.ai/">Website</a></td>
    </tr>
    <tr>
      <td align="center"><img src="./sponsored/hunyuan.webp" alt="Tencent Hunyuan3D Logo" width="48"></td>
      <td align="center"><b>Tencent Hunyuan3D</b></td>
      <td align="center">🌐 World Model Technical Support</td>
      <td>Tencent Hunyuan3D AI Creation Engine is based on Tencent Hunyuan3D generative model v2.5 — the industry's first all-in-one 3D content AI creation platform. Supports text-to-3D, image-to-3D, 3D animation generation, texture generation, sketch-to-3D, and 3D character generation, with advantages in low-poly model generation.</td>
      <td align="center"><a href="https://3d.hunyuan.tencent.com/">Website</a></td>
    </tr>
  </tbody>
</table>

For a complete list of third-party dependencies, please refer to `NOTICES.txt`.

##### Copyright © Beijing AIA Network Technology Co., Ltd.