ToonComposer

ToonComposer：通过生成式后关键帧技术简化卡通制作流程

李凌根、王广志、张兆阳、李耀伟、李晓宇、窦琪、顾金伟、薛天凡、单颖

   

👀 简要概述

传统的卡通/动漫制作耗时较长，需要熟练的艺术家进行关键帧绘制、中间帧补画和上色等工作。ToonComposer利用生成式AI技术简化了这一流程，将原本需要数小时的手动中间帧补画和上色工作整合为一个无缝衔接的自动化过程。更多详情请访问我们的项目页面并阅读我们的论文。

✏️ 更新

[2025年8月18日] 在Hugging Face Space上已上线Gradio在线演示。

[2025年8月15日] ToonComposer模型权重已在Hugging Face上发布。

⚠️ 非授权网站声明

网址https://tooncomposer.com并非由ToonComposer团队托管、授权或认可。该网站未经我们许可或通知便复制了我们开源项目的内容，我们对该网站运营者的身份及意图均不知情。

⚙️ 配置

1) 克隆仓库

git clone https://github.com/TencentARC/ToonComposer
cd ToonComposer

2) 设置Python环境

创建一个conda环境，并从requirements.txt中安装依赖项。

conda create -n tooncomposer python=3.10 -y
conda activate tooncomposer
pip install -r requirements.txt

注意：ToonComposer需要特定版本的gradio==5.25.2。

对于Linux用户，我们建议安装flash_attn。

pip install flash-attn==2.8.2 --no-build-isolation

3) 运行应用

应用会检查本地缓存，若缺少所需权重则会自动下载（详见下方的权重部分）。默认情况下，Gradio界面会在端口7860上启动。

python app.py

在浏览器中打开http://localhost:7860。如果您是在远程服务器上运行，请将localhost替换为您的服务器IP或主机名。

生成一个包含61帧的480p视频大约需要57GB的显存。如果您没有足够的GPU资源，我们建议您尝试使用我们的🤗 Hugging Face Spaces演示。

💾 权重与检查点

ToonComposer依赖于两组权重：

• Wan2.1 I2V 14B 480P（基础模型）：Wan-AI/Wan2.1-I2V-14B-480P
• ToonComposer权重：TencentARC/ToonComposer

应用程序会按照以下顺序解析权重：

• 如果您通过命令行参数或环境变量提供了本地目录（见下文），则优先使用这些目录。
• 否则，它会检查您的本地Hugging Face缓存（无需联网）。
• 如果仍然找不到，则会从Hugging Face Hub下载。

由于Wan2.1模型非常庞大，如果您的缓存中已经存在该模型，应用程序将避免重复下载。

提供本地目录（可选）

• 环境变量：
  • WAN21_I2V_DIR：本地Wan2.1模型目录路径
  • TOONCOMPOSER_DIR：本地ToonComposer目录路径，其中应包含480p/和/或608p/子目录。每个子目录都应包含tooncomposer.ckpt和config.json文件。
  • HF_TOKEN：如果需要访问受保护的下载内容，则需提供HF访问令牌（可选）

export WAN21_I2V_DIR=/abs/path/to/Wan2.1-I2V-14B-480P
export TOONCOMPOSER_DIR=/abs/path/to/TencentARC-ToonComposer
export HF_TOKEN=hf_xxx  # 可选
python app.py

• 命令行参数（优先于环境变量）：

python app.py \
  --wan_model_dir /abs/path/to/Wan2.1-I2V-14B-480P \
  --tooncomposer_dir /abs/path/to/TencentARC-ToonComposer \
  --hf_token hf_xxx \
  --resolution 480p \
  --device cuda:0

注意事项：

• ToonComposer的HF仓库按分辨率组织权重：480p/和608p/。应用程序会自动从所选分辨率目录中加载正确的config.json和tooncomposer.ckpt。
• 应用程序首先检查HF缓存（local_files_only=True），只有在未找到时才会下载。

📖 使用指南

启动选项

python app.py --help

• --resolution：480p或608p（默认：480p）
• --device：例如，cuda:0、cpu（默认：cuda:0）
• --wan_model_dir：本地Wan2.1目录（可选）
• --tooncomposer_dir：包含480p/608p的本地ToonComposer目录（可选）

在Gradio界面中

1. 设置文本提示、输出帧数和分辨率。
2. 至少提供一张关键帧彩色图像（通常放置在第0帧）。
3. 在选定的帧上添加一张或多张关键帧草图。您还可以选择性地绘制黑色笔刷区域作为运动遮罩，以允许在这些区域内自由运动。
4. 根据需要调整CFG缩放和位置感知残差缩放。
5. 点击“生成”以创建视频。

右下角面板显示状态和生成的视频。画廊中还提供了一组示例输入。

局限性

作为生成式模型，输出可能会有所不同。您可以尝试更改种子、步数、CFG缩放、位置感知残差缩放，或调整草图/遮罩输入，以获得不同的结果。

📑 引用

如果您觉得ToonComposer有用，请考虑引用以下文献：

@article{li2025tooncomposer,
  title={ToonComposer: Streamlining Cartoon Production with Generative Post-Keyframing},
  author={Li, Lingen and Wang, Guangzhi and Zhang, Zhaoyang and Li, Yaowei and Li, Xiaoyu and Dou, Qi and Gu, Jinwei and Xue, Tianfan and Shan, Ying},
  journal={arXiv preprint arXiv:2508.10881},
  year={2025}
}

📃 许可证

详细信息请参阅LICENSE文件。

ToonComposer 快速上手指南

ToonComposer 是一款基于生成式 AI 的卡通/动画制作工具，能够通过“生成式后期关键帧”技术，将传统耗时的中间画绘制和上色过程简化为一步完成的自动化流程。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐) 或 macOS/Windows (需配置相应 CUDA 环境)。
• Python 版本: 3.10。
• GPU 显存:
  • 生成 480p、61 帧视频约需 57GB VRAM。
  • 若本地显存不足，建议直接使用 Hugging Face Spaces 在线演示。
• 依赖管理: 需安装 conda 用于环境管理。
• 可选加速: Linux 用户强烈建议安装 flash-attn 以提升推理速度。

安装步骤

1. 克隆项目代码

git clone https://github.com/TencentARC/ToonComposer
cd ToonComposer

2. 创建并激活 Conda 环境

conda create -n tooncomposer python=3.10 -y
conda activate tooncomposer

3. 安装依赖库

安装基础依赖（注意：该项目强制要求 gradio==5.25.2）：

pip install -r requirements.txt

Linux 用户推荐安装 Flash Attention 加速：

pip install flash-attn==2.8.2 --no-build-isolation

国内开发者提示：若下载依赖较慢，可临时使用国内镜像源（如清华源）： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple pip install flash-attn==2.8.2 --no-build-isolation -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 模型权重说明

程序启动时会自动检查本地缓存或从 Hugging Face 下载所需权重。主要涉及两个模型：

1. 基础模型: Wan-AI/Wan2.1-I2V-14B-480P (体积较大)
2. ToonComposer 权重: TencentARC/ToonComposer

若需手动指定本地模型路径以避免重复下载，可通过环境变量或命令行参数配置（见下文“高级配置”）。

基本使用

启动应用

在终端运行以下命令启动 Gradio 界面（默认端口 7860）：

python app.py

启动成功后，在浏览器中访问 http://localhost:7860。

远程服务器用户：请将 localhost 替换为您的服务器 IP 地址，或通过 SSH 隧道映射端口。

操作流程 (Gradio 界面)

1. 设置参数：输入文本提示词 (Prompt)，设定输出帧数和分辨率 (480p/608p)。
2. 上传关键帧：
   • 至少提供一张上色后的关键帧图片（通常作为第 0 帧）。
   • 在指定帧位置上传线稿草图 (Sketch)。
   • (可选) 在线稿上使用黑色画笔涂抹区域作为运动掩码 (Motion Mask)，允许该区域自由运动。
3. 调整生成参数：根据需要微调 CFG Scale 和 Position-aware Residual Scale。
4. 生成视频：点击 Generate 按钮，右下角将显示生成状态及最终视频。

常用命令行参数

如需自定义启动配置，可使用以下参数：

python app.py \
  --resolution 480p \
  --device cuda:0 \
  --wan_model_dir /abs/path/to/Wan2.1-I2V-14B-480P \
  --tooncomposer_dir /abs/path/to/TencentARC-ToonComposer

• --resolution: 选择 480p 或 608p。
• --device: 指定设备，如 cuda:0 或 cpu。
• --wan_model_dir: 指定本地 Wan2.1 模型目录。
• --tooncomposer_dir: 指定本地 ToonComposer 权重目录（需包含 480p/ 或 608p/ 子文件夹）。