| |

# 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](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 Scan 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](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 :10588 -v :/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:

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