Guangzhao Li · Yanming Yang · Chenxi Song · Chi Zhang

FlowDirector edits videos based on text prompts, preserving unedited regions and maintaining temporal coherence.

Version Notice: This repository provides the V1 implementation of FlowDirector.
The V2 version (with additional updates) will be open-sourced soon.

TL;DR: Here, we propose FlowDirector, a training- and inversion-free framework for text-guided video editing, enabling precise object edits and temporal consistency through new spatial correction and guidance mechanisms.

• 🌊 Inversion-Free Editing: Directly evolves video in data space, bypassing noisy and error-prone inversion processes.
• ⚙️ ODE-Driven Transformation: Smoothly transitions videos along their spatiotemporal manifold, preserving coherence and structural details.
• 🎨 Spatially Attentive Flow Correction (SAFC): An attention-guided masking mechanism precisely modulates the ODE velocity field, ensuring unedited regions remain unchanged both spatially and temporally.
• 🎯 Differential Averaging Guidance (DAG): A CFG-inspired strategy that leverages differential signals between multiple candidate flows to enhance semantic alignment with target prompts without compromising structural consistency.
• 🏆 State-of-the-Art Performance: Outperforms existing methods in instruction adherence, temporal consistency, and background preservation.

• [2023.05.30] FlowDirector is released! Check out the code and demos.
• [2025.05.29] Paper and project page released.

• Release the code
• Gradio demo

Download the Wan2.1-T2V-1.3B model checkpoints from their official sources (e.g., from the Wan2.1 GitHub or Hugging Face). You will need to provide the path to the directory containing these checkpoints using the --ckpt_dir argument when running the editing script (see examples below).

For instance, if you download them to ./checkpoints/Wan2.1-T2V-1.3B, you will use --ckpt_dir ./checkpoints/Wan2.1-T2V-1.3B.

1. Clone the repository (replace YOUR_USERNAME with the actual path if forked, or use the main repo URL):

   git clone https://github.com/YOUR_USERNAME/FlowDirector.git
   cd FlowDirector

2. Install dependencies:

   conda create -n flowdirector python=3.12
   conda activate flowdirector
   
   pip install -r requirements.txt

3. (Optional) Install flash_attention for Accelerated Editing: We strongly recommend installing flash_attention to accelerate editing (can be more than 5x faster):

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

   Alternatively, you can check the official flash_attention GitHub repository.

You can edit a video using the edit.py script. Ensure you have a source video, corresponding source/target text prompts, and have downloaded the pre-trained models.

Here's an example of how to run video editing on a single GPU:

bash script_edit_single_gpu.sh

For multi-GPU editing (e.g., 4 GPUs), run the following command:

bash script_edit_multi_gpu.sh

For detailed parameter explanations, please refer to the edit.py file.

You can also use the Gradio web interface for editing videos, run:

python app.py --ckpt ./checkpoints/Wan2.1-T2V-1.3B

FlowDirector achieves superior results across various editing tasks. Below are specific demonstrations:

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
large brown bear	large panda	large dinosaur

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
rabbit	Crochet rabbit	Origami rabbit

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
black swan	pink flamingo	white duck

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
woman in a black dress	a red baseball cap	woman in a blue shirt and jeans

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
silver jeep	Porsche car	Tractor

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
holding a flower	holding a flower	A golden retriever with a colorful collar

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
cats	dogs	kangaroo

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
wolf	fox	husky

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
sea turtle	dolphin	seal

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
sea lion	Seahorse	Clownfish

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
woman	chimpanzee	Spider-Man

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
red cockatiel	blue budgie	eagle

Original Video (Source Keyword)	Edited Video 1 (Target Keyword)	Edited Video 2 (Target Keyword)
puppy	chinchilla	cat

If you find FlowDirector useful for your research, please cite our paper:

@article{li2025flowdirector0,
  title   = {FlowDirector: Training-Free Flow Steering for Precise Text-to-Video Editing},
  author  = {Guangzhao Li and Yanming Yang and Chenxi Song and Chi Zhang},
  year    = {2025},
  journal = {arXiv preprint arXiv: 2506.05046}
}

This project is licensed under the MIT License - see the LICENSE file for details.

For questions or inquiries, please contact Guangzhao Li at [gzhao.cs@gmail.com] or open an issue in this repository.