DreamX-World输入JSON格式逐字段详解:读懂image、caption、action_seq的奥秘
DreamX-World输入JSON格式逐字段详解:读懂image、caption、action_seq的奥秘
DreamX-World 是一个通用交互式世界模型,输入一张图、一段描述和几个字母命令,就能生成可控镜头的交互视频。它的推理输入是一个简单的 JSON 文件,其中 image_path、caption、action_seq 三个核心字段分别决定视频的开场画面、视觉风格和镜头运动轨迹。本文带你逐字段读懂这份 JSON 的奥秘。
一、输入 JSON 在哪里?如何被读取?
整个仓库的示例输入都放在 configs/dreamx/eval.json 中。推理脚本通过 INPUT_DIR 参数指向它,例如 inference_dreamx_5b.sh 中的这一行:
INPUT_DIR="./configs/dreamx/eval.json"
两个推理入口读取方式相同:
- 5B-Cam 双向模型:inference_dreamx5b.py#L318-L320 用
json.load读取整个数组 - AR-Forcing 自回归模型:inference_ar_forcing.py#L257-L258 同样读取数组
关键点:文件顶层是一个 JSON 数组,数组里每个对象 = 一条独立的生成任务 = 一个输出视频。 想生成多少个视频,就写多少个对象。
二、核心三件套:逐字段详解
一条任务的最小完整结构如下(摘自 inference_README.md 的 Step1):
{
"image_path": "./demo/your_image.png",
"caption": "Style: Photorealistic. A description of the scene...",
"action_seq": ["w", "wj"],
"action_speed_list": [4, 6]
}
2.1 image_path:开场帧图片
- 字符串类型,指向视频第一帧的图片(PNG/JPG 均可)
- 代码会取它的文件名作为输出视频名的一部分,见 inference_dreamx5b.py#L337-L346
- 推荐尺寸与脚本中的
SAMPLE_WIDTH=1280、SAMPLE_HEIGHT=704保持一致(约 16:9 横版)
2.2 caption:风格与内容的文字描述
caption 是喂给文本编码器的正向提示词,它决定生成画面的风格与细节。从官方示例可以看出两个写作惯例:
- 以
Style: xxx开头声明风格,如Style: Photorealistic(写实)、Style: Minecraft(体素游戏风)、Style: 3D Rendering / CGI; - 正文按"前景—中景—远景—光线—情绪"的顺序描述,长镜头任务里还会直接写出镜头运动,例如 "The camera moves forward while panning left..."
读取时会自动清理换行符(inference_dreamx5b.py#L335),所以 caption 写成一行长文本即可。脚本中还有一个默认 negative_prompt 负向提示词抑制低质量画面,无需在 JSON 中配置。
2.3 action_seq:镜头运动命令
这是 DreamX-World 最有意思的字段:用几个小写字母描述整段镜头运动。单个字母的含义在 utils/inference_utils.py#L12 的 ACTION_DICT 中定义:
| 字母 | 含义 | 说明 |
|---|---|---|
w |
推进 | 相机向前移动(Push in) |
s |
拉远 | 相机向后移动(Pull out) |
a |
左移 | 相机向左侧平移 |
d |
右移 | 相机向右侧平移 |
i |
仰视 | 镜头向上抬起(Tilt up) |
k |
俯视 | 镜头向下压(Tilt down) |
j |
左摇 | 镜头向左旋转(Pan left) |
l |
右摇 | 镜头向右旋转(Pan right) |
命令可以组合:把两个字母写在一起表示同时进行两种运动,例如 wj = 前进的同时向左摇镜、dj = 右移的同时向左摇镜。action_seq 是一个数组,数组里的每一项是一段连续运动,按顺序依次执行,构成整条镜头轨迹。在 AR-Forcing 管线的轨迹处理器中,甚至可以用空格表示"静止",见 utils/trajectory_processor.py#L845-L852。
2.4 action_speed_list:速度/时长参数
action_speed_list 是与 action_seq 一一对应的数字数组,个数必须相同。它的含义随管线略有不同,这正是"奥秘"所在:
- 5B-Cam 管线:数值表示运动幅度——平移量 =
speed × 1.0、总旋转角 =speed × 10°,数字越大镜头运动越快、越剧烈(utils/inference_utils.py#L267-L272)。 - AR-Forcing 管线:数值表示该段动作占整段视频时长的相对权重。例如
<a href="https://link.gitcode.com/i/e21f06c5806cc1b22a0e38c6d22cfbe8" target="_blank">["w", 3], ["i", 5]]表示 37.5% 时间前进、62.5% 时间仰视([utils/trajectory_processor.py#L852 的注释)。
官方示例中常用 4(舒缓)和 6(明显)两档,新手照抄即可。
三、可选字段:task_id
部分条目带有 task_id(如 configs/dreamx/eval.json#L149)。它只在 AR-Forcing 推理中起作用:作为输出视频文件名前缀,见 inference_ar_forcing.py#L277-L282。不写时默认用条目序号,属于完全可选字段。
四、实战示例:三个字段如何配合
以 configs/dreamx/eval.json 中的"霍格沃茨"条目为例:
image_path指向case2_01_..._shot_05_l_w.png,提供雾中石拱河的开场画面caption以Style: 3D Rendering / CGI开头,并写明"先左摇、再前进"的镜头叙事action_seq: ["wj", "w"]精确落地了文字描述:第一段前进+左摇,第二段纯前进action_speed_list: [6, 4]:摇镜段稍快(6),收尾段放缓(4)
三个字段互相印证,最终得到一条风格统一、镜头平滑的视频。生成完成后,视频会自动命名为"图片名_动作序列.mp4",例如 xxx_wj_w.mp4。
上图为 action_seq: ["wi"](前进+仰视)对应的示例开场,可以看到构图预留了向上的极光空间——开场图的构图方向最好与镜头运动方向相匹配,这是让视频"好看"的实用技巧。
五、常见问题速查
| 问题 | 解答 |
|---|---|
| 视频时长在哪里控制? | 不在 JSON 里,由脚本参数 VIDEO_LENGTH / NUM_OUTPUT_FRAMES 决定 |
action_seq 和 action_speed_list 能不等长吗? |
不能,必须一一对应 |
| 能只写字母组合吗? | 能,如 wk = 前进+俯视 |
| 分辨率写在哪? | 由 --sample_size(默认 704×1280)控制,建议开场图同比例 |
字段速查表:
| 字段 | 必填 | 类型 | 作用 |
|---|---|---|---|
image_path |
✅ | 字符串 | 开场帧图片路径 |
caption |
✅ | 字符串 | 风格与画面描述 |
action_seq |
✅ | 字符串数组 | 分段镜头命令 |
action_speed_list |
✅ | 数字数组 | 各段幅度/时长权重 |
task_id |
❌ | 字符串 | 输出文件前缀(仅 AR 管线) |
读懂了这份 JSON,你就拥有了指挥 DreamX-World 的"导赏棒"——换一张图、改一句 caption、调几个字母,就能生成属于自己的交互世界。
(说明:文中图片均使用仓库内相对路径、每张仅出现一次,且位于概要文字之后;demo/005.png 用于展示 wi 镜头组合的开场构图。)




