StoryMem：基于记忆条件控制的开源多镜头长视频生成工具

一、StoryMem是什么？

StoryMem是一款开源的多镜头长视频叙事生成工具，依托记忆条件控制的单镜头视频扩散模型，能够根据含逐镜头文本描述的故事脚本，生成时长约一分钟、角色高度连贯且具备电影级视觉质量的叙事视频。该工具支持T2V（文本到视频）、M2V（记忆到视频）、MI2V（记忆+首帧图像）、MM2V（记忆+前5帧运动图像）等多种生成模式，配套发布了ST-Bench评估基准数据集，包含30个跨风格故事脚本与300个详细视频提示，降低了长视频叙事生成的技术门槛。用户通过简单的环境配置、模型下载与脚本运行，即可快速实现多镜头视频创作，适用于内容创作、影视前期预览、教育动画制作等多个场景，为开发者与创作者提供了高效、灵活的长视频生成解决方案。

StoryMem的核心定位是“基于记忆条件控制的多镜头长视频生成工具”，其核心目标是：给定一个包含逐镜头文本描述的故事脚本，自动生成时长约一分钟的多镜头叙事视频。这里的“多镜头”意味着视频由多个5秒左右的镜头片段组成，而“叙事性”则要求镜头之间具备逻辑关联、角色形象保持一致，同时整体视觉效果达到电影级水准。

该项目基于arXiv论文《StoryMem: Multi-shot Long Video Storytelling with Memory》（论文编号：2512.19539）开发，代码完全开源，依托Wan2.2基础模型与自定义微调的LoRA权重，实现了“逐镜头生成+记忆动态更新”的核心逻辑，让非专业开发者也能轻松打造高质量的长视频叙事内容。无论是想要快速制作动画短片、影视前期概念视频，还是教育领域的叙事动画，StoryMem都能提供高效、可靠的技术支持。

二、功能特色

StoryMem之所以能在长视频叙事生成领域脱颖而出，得益于其在功能设计上的诸多亮点，既兼顾了生成效果的专业性，又考虑了用户使用的便捷性：

1. 高质量视频生成，兼顾连贯性与视觉感

这是StoryMem最核心的特色。通过记忆条件控制技术，工具能够在多镜头生成过程中保持角色的一致性——包括角色的外貌、 attire、动作风格等，避免出现“换镜头换角色”的割裂感。同时，依托Wan2.2基础模型的MoE（混合专家）架构优势，生成的视频具备电影级的视觉质量，在场景细节、光影效果、动态流畅度等方面均有出色表现，远超普通视频生成工具的输出水准。

2. 多种生成模式适配不同场景需求

StoryMem提供了四种灵活的生成模式，覆盖不同的使用场景，满足用户多样化需求：

• T2V首镜头模式：通过Wan2.2 T2V（文本到视频）模型生成第一个镜头，作为整个视频的初始记忆，适用于没有参考图像、完全从零开始的创作场景；

• M2V首镜头模式：适用于MR2V（参考图像到视频）场景，用户提供参考图像作为初始记忆，通过M2V（记忆到视频）模型生成第一个镜头，确保视频与参考图像的风格、角色保持一致；

• MI2V模式：当镜头之间无场景切换（scene_cut=False）时，启用“记忆+首帧图像”的条件控制，让相邻镜头实现自然衔接，避免画面跳转感；

• MM2V模式：同样适用于无场景切换的场景，采用“记忆+前5帧运动图像”的条件控制，进一步提升镜头之间的动态连贯性，尤其适合动作场景的生成。

3. 配套ST-Bench评估基准，降低创作与测试门槛

为了解决多镜头长视频叙事生成领域缺乏标准化评估数据的问题，StoryMem团队专门建立并开源了ST-Bench基准数据集。该数据集位于项目的./story子文件夹中，包含30个跨多种风格的长故事脚本，每个脚本均由GPT-5生成，结构完整、细节丰富：

• 每个脚本包含故事概述（story_overview），让用户快速了解故事核心；

• 每个脚本包含8-12个镜头级文本提示（video_prompts），每个提示对应5秒的视频片段；

• 每个镜头提示均标注了场景切换标识（cut），明确该镜头是否为新场景的开始；

• 总计提供300个详细的视频提示，涵盖角色描述、场景背景、动态事件、镜头类型、相机运动等关键信息，可直接用于测试工具效果，也可作为用户自定义脚本的参考模板。

4. 高度灵活的参数配置，适配个性化需求

StoryMem支持多个关键参数的自定义配置，用户可根据自身需求调整生成效果：

• 输出分辨率：默认832*480，可根据实际使用场景（如短视频平台、高清展示）调整；

• 记忆容量：通过max_memory_size参数设置记忆中保留的最大镜头数（默认10个），平衡连贯性与生成效率；

• 随机种子：支持固定种子（默认0），确保生成结果的可复现性，方便用户微调优化；

• 输出目录：可自定义生成视频的保存路径，便于项目管理与文件整理。

5. 开源免费，易于二次开发

StoryMem的全部代码均开源在GitHub平台，遵循开源许可证（详见LICENSE.md），用户可自由下载、使用、修改。项目基于Python开发，代码结构清晰，核心文件（如pipeline.py、generate.py）的逻辑易于理解，同时依托Hugging Face平台提供模型下载，方便开发者进行二次开发与功能扩展，推动相关领域的技术创新。

三、技术细节

要深入理解StoryMem的工作原理，需从核心技术架构、模型依赖、生成流程三个方面展开，其技术设计的核心是“记忆条件控制”与“逐镜头生成”的结合：

1. 核心技术架构

StoryMem的核心技术是记忆条件控制的单镜头视频扩散模型。传统的多镜头视频生成工具往往直接对整个长视频进行端到端生成，不仅计算量巨大，且难以保证角色与场景的连贯性；而StoryMem采用“逐镜头生成+记忆动态更新”的思路，将长视频生成拆解为多个单镜头生成任务，通过“记忆”模块记录前序镜头的关键信息（如角色特征、场景风格、运动趋势），并将其作为条件输入到后续镜头的生成过程中，从而实现多镜头之间的连贯性。

具体来说，“记忆”模块的作用包括：

• 记录前序镜头的角色特征（外貌、 attire、动作风格），确保后续镜头中角色形象一致；

• 记录前序镜头的场景风格（色调、光影、布局），确保场景过渡自然；

• 记录前序镜头的运动趋势（如角色的动作方向、相机的运动轨迹），确保动态连贯。

2. 模型依赖与构成

StoryMem的模型架构由“基础模型+微调LoRA权重”组成，具体依赖如下表所示：

注：MoE（混合专家）架构是Wan2.2基础模型的核心优势，通过多个“专家网络”分别处理不同类型的生成任务（如角色生成、场景生成、动作生成），再通过门控机制整合结果，既能保证生成质量，又能提升生成效率。

3. 核心生成流程

StoryMem的生成流程遵循“初始化-逐镜头生成-记忆更新-视频拼接”的逻辑，以默认的“T2V首镜头模式”为例，具体流程如下：

1. 输入解析：读取用户提供的故事脚本JSON文件，解析每个镜头的文本提示、场景切换标识（cut）等信息；

2. 初始记忆生成：使用Wan2.2 T2V-A14B模型，根据第一个镜头的文本提示生成5秒左右的视频片段，该片段作为“初始记忆”存储到记忆模块中；

3. 逐镜头生成：

• 若cut=True（新场景）：以当前镜头的文本提示为主，结合记忆模块中保留的核心信息（如角色特征），使用M2V模型生成视频片段；

• 若cut=False（无场景切换）：根据用户启用的模式（MI2V/MM2V），结合记忆信息+首帧图像（或前5帧运动图像），生成与前一镜头自然衔接的视频片段；

• 对于第二个及后续镜头，首先判断场景切换标识（cut）：

4. 关键帧提取与记忆更新：每个镜头生成完成后，自动提取该镜头的关键帧（通过extract_keyframes.py脚本），并更新记忆模块——保留最新的镜头信息，同时删除超出max_memory_size限制的旧镜头信息，确保记忆模块的高效运行；

5. 视频拼接：所有镜头生成完成后，自动将各个5秒的视频片段拼接为完整的一分钟左右长视频，保存到用户指定的输出目录（默认./results）。

整个流程无需用户手动干预，从脚本解析到视频输出完全自动化，既保证了生成效率，又通过记忆模块与条件控制机制确保了视频的连贯性与视觉质量。

四、应用场景

StoryMem的核心优势是“低门槛、高质量、强叙事性”，其应用场景覆盖多个领域，无论是专业创作者还是非专业用户，都能找到合适的使用场景：

1. 内容创作领域

• 短视频/自媒体内容生产：自媒体创作者可利用StoryMem快速将文字脚本转化为多镜头叙事视频，适用于抖音、B站、视频号等平台的动画短片、故事类视频创作，无需专业的视频拍摄与剪辑技能，大幅提升创作效率；

• 广告创意视频制作：广告从业者可基于产品卖点设计故事脚本，通过StoryMem生成创意广告视频，尤其是适合需要虚构角色、奇幻场景的广告类型（如儿童产品广告、科幻类产品广告），降低制作成本与周期。

2. 影视与动画领域

• 前期概念预览：影视编剧、导演可将剧本拆解为镜头级脚本，通过StoryMem生成概念视频，直观呈现镜头语言、场景设计、角色形象等，辅助团队沟通与决策，减少后期拍摄/制作的修改成本；

• 动画短片创作：独立动画师或小型动画工作室可利用StoryMem快速生成动画短片的初稿，再基于初稿进行精细化调整，大幅缩短动画制作周期，尤其适合资金有限、人力不足的创作团队。

3. 教育与培训领域

• 教学动画制作：教师或教育机构可将知识点设计为叙事性故事脚本（如历史故事、科学原理讲解），通过StoryMem生成生动有趣的教学动画，提升学生的学习兴趣与理解效率；

• 培训视频制作：企业培训部门可基于培训内容（如产品操作指南、职场礼仪讲解）设计脚本，生成多镜头培训视频，视频的叙事性与连贯性有助于员工更好地吸收知识。

4. 游戏与虚拟资产领域

• 游戏剧情视频生成：游戏开发者可将游戏剧情拆解为镜头脚本，通过StoryMem生成剧情动画，用于游戏宣传、新手引导等场景，与游戏引擎生成的画面相比，制作成本更低、周期更短；

• 虚拟角色展示视频：设计师可通过脚本描述虚拟角色的外貌、动作、场景，生成角色展示视频，用于游戏角色预热、虚拟偶像宣传等。

5. 科研与开发领域

• 长视频生成技术研究：科研人员可基于StoryMem的开源代码与ST-Bench数据集，开展多镜头视频连贯性、记忆条件控制、视频叙事逻辑等方向的研究，推动相关技术的发展；

• 二次开发与功能扩展：开发者可基于StoryMem的核心架构，扩展新的功能（如支持更多分辨率、增加音频生成模块、优化角色一致性算法），打造个性化的视频生成工具。

五、使用方法

StoryMem的使用流程清晰，分为“环境配置-模型下载-脚本准备-运行生成”四个步骤，用户只需具备基础的Python环境操作能力，即可完成整个流程：

1. 环境配置

StoryMem的运行依赖Python 3.11环境与conda虚拟环境管理工具，具体步骤如下：

1. 克隆项目仓库：打开终端（Linux/Mac）或命令提示符（Windows），执行以下命令克隆项目到本地：

   git clone --single-branch --branch main git@github.com:Kevin-thu/StoryMem.git

   若未配置SSH密钥，可使用HTTPS链接克隆：

   git clone --single-branch --branch main https://github.com/Kevin-thu/StoryMem.git

2. 进入项目目录：

   cd StoryMem

3. 创建并激活conda虚拟环境：

   # 创建虚拟环境，指定Python版本为3.11
   conda create -n storymem python=3.11
   # 激活虚拟环境（Windows系统同样适用）
   conda activate storymem

4. 安装依赖包： 首先安装项目核心依赖：

   pip install -r requirements.txt

   然后安装flash_attn（提升注意力机制的计算效率，必装依赖）：

   pip install flash_attn

2. 模型下载

StoryMem需要下载三个核心模型（Wan2.2 T2V、Wan2.2 I2V、StoryMem LoRA），推荐使用Hugging Face CLI工具下载，步骤如下：

1. 安装Hugging Face CLI：

   pip install "huggingface_hub[cli]"

2. 下载Wan2.2 T2V-A14B模型：

   huggingface-cli download Wan-AI/Wan2.2-T2V-A14B --local-dir ./models/Wan2.2-T2V-A14B

3. 下载Wan2.2 I2V-A14B模型：

   huggingface-cli download Wan-AI/Wan2.2-I2V-A14B --local-dir ./models/Wan2.2-I2V-A14B

4. 下载StoryMem LoRA权重：

   huggingface-cli download Kevin-thu/StoryMem --local-dir ./models/StoryMem

注：模型文件较大（每个基础模型约数GB），下载过程需要稳定的网络环境，建议在高速网络下进行；若下载失败，可直接访问Hugging Face模型页面（链接见“相关官方链接”部分），手动下载并解压到对应目录。

3. 故事脚本准备

StoryMem支持两种脚本使用方式：直接使用ST-Bench数据集的现成脚本，或自定义脚本。

（1）使用现成脚本

项目的./story子文件夹中已包含30个现成的故事脚本（如black.json），用户可直接使用，无需额外修改。例如，black.json脚本包含了一个完整的故事概述、10个镜头级文本提示，以及对应的场景切换标识，可直接用于测试生成效果。

（2）自定义脚本

若用户需要生成个性化故事视频，可按照ST-Bench的规范编写JSON格式的脚本，具体要求如下：

1. 脚本结构：必须包含以下字段：

• story_overview：故事概述（1-2句话，简洁描述故事核心）；

• scene_num：场景序号（整数，按顺序递增）；

• cut：场景切换标识（布尔值，True表示新场景，False表示无场景切换，第一个镜头必须为True）；

• video_prompts：镜头级文本提示列表（每个提示对应5秒视频，1-4句话，需包含角色、动作、场景、镜头类型等关键信息）。

2. 脚本示例：

   {
    "story_overview": "一个勇敢的小机器人帮助森林里的动物寻找水源的故事",
    "scenes": [
     {
      "scene_num": 1,
      "cut": true,
      "video_prompts": [
       "宽镜头，阳光明媚的森林，小机器人（银色机身、蓝色眼睛、圆形轮子）正在草地上巡逻，好奇地观察周围的树木和花朵，镜头缓慢推进",
       "中镜头，小机器人遇到一只口渴的兔子，兔子蹦跳着向机器人求助，机器人弯腰倾听，表情温和，背景是茂密的灌木丛"
      ]
     },
     {
      "scene_num": 2,
      "cut": false,
      "video_prompts": [
       "跟拍镜头，小机器人带着兔子穿过森林，机器人的轮子在地面上留下轻微痕迹，兔子在前方带路，不时回头等待，阳光透过树叶形成光斑",
       "近景镜头，小机器人用胸前的探测器扫描地面，屏幕上显示水源方向，兔子兴奋地挥舞爪子，背景是潺潺流淌的小溪"
      ]
     }
    ]
   }

3. 注意事项：

• 每个视频提示避免过于复杂的文本渲染、极端动作或依赖音频的效果，确保生成的视频可独立理解；

• 非场景切换（cut=False）的镜头提示，需确保与前一镜头的画面能够自然衔接（如角色位置、动作趋势、场景元素一致）；

• 角色描述需明确（如外貌、 attire、动作风格），有助于模型保持角色一致性。

4. 运行生成

完成环境配置、模型下载与脚本准备后，即可运行命令生成视频：

（1）基础运行命令

项目提供了现成的运行脚本run_example.sh，用户可直接执行以下命令运行：

bash run_example.sh

（2）自定义参数运行

若用户需要调整参数（如使用自定义脚本、修改输出目录、启用MI2V/MM2V模式），可直接修改run_example.sh脚本中的参数，或在命令行中指定参数，核心参数说明如下表：

（3）运行结果

运行成功后，生成的视频文件（每个镜头的5秒片段+完整拼接视频）将保存到指定的输出目录中，用户可直接查看、编辑或发布。

六、常见问题解答（FAQ）

1. 运行时提示“模型文件缺失”怎么办？

• 首先检查模型下载路径是否正确：确保Wan2.2 T2V/I2V模型存放在./models/Wan2.2-T2V-A14B和./models/Wan2.2-I2V-A14B目录，LoRA权重存放在./models/StoryMem目录；

• 检查模型下载是否完整：若使用Hugging Face CLI下载中断，可重新执行下载命令，CLI会自动续传；若手动下载，需确保所有文件解压完整，无缺失或损坏；

• 若仍提示缺失，可在命令行中明确指定模型路径（通过t2v_model_path、i2v_model_path、lora_weight_path参数），避免路径配置错误。

2. 生成的视频角色不连贯（如换镜头后角色外貌变化）怎么解决？

• 优化脚本中的角色描述：在每个镜头的文本提示中明确角色的外貌、 attire、动作风格（如“银色机身、蓝色眼睛的小机器人”），避免模糊描述；

• 调整max_memory_size参数：适当增大记忆容量（如从10改为15），让模型保留更多前序镜头的角色信息；

• 启用MI2V或MM2V模式：对于无场景切换的镜头，启用这两种模式可增强角色与动作的连贯性；

• 固定随机种子：通过--seed参数固定种子，便于微调脚本与参数，找到最佳生成效果。

3. 运行时出现“内存不足”或“显存溢出”错误怎么办？

• 降低输出分辨率：将size参数从默认的832480改为更小的分辨率（如640360），减少显存占用；

• 减小max_memory_size参数：减少记忆中保留的镜头数（如从10改为5），降低内存压力；

• 关闭其他占用资源的程序：确保运行时没有其他大型软件（如视频编辑软件、游戏）占用内存或显存；

• 若使用GPU运行，确保GPU显存不低于16GB（推荐24GB及以上），若显存不足，可尝试使用CPU运行（速度较慢，但可避免显存溢出）。

4. 如何判断是否需要启用MI2V或MM2V模式？

• MI2V和MM2V模式仅适用于“无场景切换”（cut=False）的镜头，用于增强相邻镜头的连贯性；

• 若镜头之间是动作连续的场景（如角色走路、跑步、物体运动），建议启用MM2V模式（记忆+前5帧运动图像），提升动态连贯性；

• 若镜头之间是静态场景过渡（如角色从站立到坐下，场景不变），建议启用MI2V模式（记忆+首帧图像），保证画面衔接自然；

• 若为新场景（cut=True），无需启用这两种模式，模型会自动基于文本提示生成新场景的镜头。

5. 自定义脚本时，如何确保镜头之间自然衔接？

• 对于cut=False的镜头，确保前一镜头的结尾动作与当前镜头的开始动作逻辑连贯（如前一镜头“机器人走向小溪”，当前镜头“机器人弯腰喝水”）；

• 保持场景元素一致：同一组无场景切换的镜头，场景背景（如森林、房间）、光影效果（如阳光、灯光）应保持统一，避免突然变化；

• 避免镜头类型的突兀切换：如前一镜头是宽镜头，当前镜头可改为中镜头或近景镜头，避免直接从宽镜头切换到特写镜头，影响观感。

6. 生成的视频时长可以调整吗？

• 可以。StoryMem的视频时长由镜头数量决定（每个镜头约5秒），若需要更长的视频，可在脚本中增加镜头数量（如从12个镜头增加到20个，生成约100秒的视频）；

• 若需要更短的视频，可减少镜头数量（如6个镜头，生成约30秒的视频）；

• 目前不支持单个镜头时长的自定义（默认5秒），若需调整，需修改项目核心代码（generate.py）中的相关参数。

7. 项目支持Windows系统吗？

• 支持。StoryMem的代码兼容Windows、Linux、MacOS系统，核心区别在于运行命令：

• Linux/Mac系统：直接使用bash run_example.sh命令运行；

• Windows系统：需安装Git Bash或WSL（Windows Subsystem for Linux），通过Git Bash执行bash run_example.sh命令，或在命令提示符中手动执行脚本中的命令（替换bash语法为Windows兼容语法）。

8. 如何引用StoryMem的论文或代码？

• 若在研究中使用了StoryMem的论文或代码，需按照以下格式引用：

  @article{zhang2025storymem,
   title={{StoryMem}: Multi-shot Long Video Storytelling with Memory},
   author={Zhang, Kaiwen and Jiang, Liming and Wang, Angtian and Fang, Jacob Zhiyuan and Zhi, Tiancheng and Yan, Qing and Kang, Hao and Lu, Xin and Pan, Xingang},
   journal={arXiv preprint},
   volume={arXiv:2512.19539},
   year={2025}
  }

• 同时，建议在GitHub项目页面给项目点赞（Star），支持开发者的开源工作。

七、相关链接

• 项目GitHub仓库：https://github.com/Kevin-thu/StoryMem

• arXiv论文链接：https://arxiv.org/abs/2512.19539

• Hugging Face模型库（Wan2.2 T2V-A14B）：https://huggingface.co/Wan-AI/Wan2.2-T2V-A14B

• Hugging Face模型库（Wan2.2 I2V-A14B）：https://huggingface.co/Wan-AI/Wan2.2-I2V-A14B

• Hugging Face模型库（StoryMem LoRA）：https://huggingface.co/Kevin-thu/StoryMem

八、总结

StoryMem是一款聚焦多镜头长视频叙事生成的开源工具，通过记忆条件控制的单镜头视频扩散模型，成功解决了传统长视频生成中角色不连贯、镜头衔接生硬的核心痛点，能够基于含逐镜头文本描述的脚本，生成具备电影级视觉质量的一分钟左右长视频。该工具具备多种灵活的生成模式（T2V/M2V/MI2V/MM2V），配套开源了ST-Bench评估基准数据集，同时支持高度自定义的参数配置，兼顾了生成效果的专业性与使用的便捷性。其安装部署流程清晰，用户只需完成环境配置、模型下载与脚本准备，即可通过简单命令生成视频，无需复杂的专业技能。无论是内容创作者、影视从业者、教育工作者，还是科研人员与开发者，都能在StoryMem中找到适合自己的应用场景。作为一款开源项目，StoryMem不仅提供了高效的长视频生成解决方案，也为相关领域的技术研究与二次开发提供了丰富的资源与清晰的架构参考，具有重要的实用价值与技术意义。