Toonflow-app/docs

 |   | 

简体中文 | 繁體中文 | English | ไทย | Tiếng Việt | 日本語 | Русский

Toonflow

AI Short Drama Factory
Turn your novel into episodes with just a few clicks!
AI Scripts × AI Visuals × Ultra-fast Generation 🔥

🚀 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!

---

🌐 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

Toonflow: 8-Minute AI Video Quick Start 👉 Click to Watch

📱 Scan the QR code to watch on mobile

---

🚀 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	Release	Quark Drive	Official Installer
Linux	Release	Release	Quark Drive	Official Installer
macOS	Release	Release	Quark Drive	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

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 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:

# 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

# 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:

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):

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:

{
  "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

pm2 start pm2.json
pm2 startup
pm2 save

5. Common Commands

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
• Gitee: 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:

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

   From Gitee (Recommended for China):

   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:

   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

     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

     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

     yarn start
     

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

4. Project Build & Packaging

   • Compile and generate TypeScript files:

     yarn build
     

   • Package as a Windows executable:

     yarn dist:win
     

   • Package as a Mac executable:

     yarn dist:mac
     

   • Package as a Linux executable:

     yarn dist:linux
     

5. Code Quality Checks (Linting)

   • Run global syntax and styling checks:

     yarn lint
     

6. AI Debug Panel (Optional)

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

   yarn debug:ai
   

Frontend Development

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

• GitHub: Toonflow-web
• Gitee: 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	Gitee
Toonflow-web	Frontend source code (For frontend developers)	GitHub	Gitee

💡 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:

Or click the direct link: https://discord.gg/HEjKmpNpAZ

---

💌 Contact Us

📧 Email: ltlctools@outlook.com

---

📜 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 file.

---

⭐️ Star History

---

🙏 Acknowledgements

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

• Express - Fast, unopinionated, minimalist web framework for Node.js
• AI SDK - The AI toolkit for TypeScript
• Better-SQLite3 - High-performance SQLite3 binding library
• Sharp - High-performance Node.js image processing
• Axios - Promise-based HTTP client
• Zod - TypeScript-first schema validation
• Socket.IO - Real-time bidirectional event-based communication
• Electron - Cross-platform desktop application framework
• Hugging Face Transformers - State-of-the-art Machine Learning for the web

Thanks to the following organizations/individuals for supporting Toonflow:

Logo	Name	Support Type	Description	Website
	Sophnet	💻 Computing Sponsor	Committed to creating a faster, more stable, and more cost-effective one-stop model inference API service platform	Website
	Atlas Cloud	💻 Computing Sponsor	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.	Website

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

Copyright © Huaibei AIA Network Technology Co., Ltd.