world-execute-me-dsh-pv 快速上手:一条命令渲染完整PV的终极教程(Python 3.12 / Node 20 / ffmpeg 环境全配置)
world-execute-me-dsh-pv 快速上手:一条命令渲染完整PV的终极教程(Python 3.12 / Node 20 / ffmpeg 环境全配置)
world-execute-me-dsh-pv 是一个用代码逐帧渲染 TUI 风格 PV 的开源项目:左侧是 DeepSeek Harness(dsh)聊天窗口,右侧是她所处"世界"的模型可视化引擎,全部画面由 Python 按歌曲时间 t 纯函数计算得出,没有任何手工关键帧。你只需自备歌曲,运行 python build.py all 一条命令,就能从头渲染出完整成片 out/film.mp4。本文带你完成 Python 3.12 / Node 20 / ffmpeg 的环境全配置,快速上手整条出片流程。
📦 这支 PV 渲染的是什么
这是一支非官方同人 PV,对应 Mili 的《world.execute(me);》:
- 左半边:每一帧都是一张静态 HTML 页面,用 dsh 自己的 CSS 拼出聊天界面,再由 Playwright 无头 Chromium 逐帧截图;
- 右半边:一台 TUI 风格模型可视化引擎(Transformer、注意力、KV cache、RLHF……),用 PIL 逐字符绘制;
- 合成:由 dsh_her.py 在内存中把两边合成,全程 24 fps、1280×720。
完整制作原理见 docs/HOW_IT_WORKS.md。
🧰 环境要求一览
渲染这条 PV 需要三种工具同时就位,缺一不可:
| 组件 | 版本要求 | 用途 |
|---|---|---|
| Python | 3.12+(requirements.txt:Pillow ≥10、NumPy ≥1.26) | 逐帧渲染、歌词合成、替身舞者 |
| Node.js | 20+(package.json:Playwright 1.63) | 把逐帧 HTML 页面截成 PNG |
| ffmpeg | 任意较新版,且在 PATH 里 | 混音、BT.709 转码出片 |
| 字体 | Windows 自带(其他系统需替代) | 终端字与中文字形 |
💡
build.py check会自动检查上述所有项(工具、字体、歌曲),出问题时直接告诉你缺什么,建议每次构建前都跑一遍。
🚀 一键安装:环境全配置步骤
第一步:克隆仓库并安装 Python 依赖
git clone https://gitcode.com/gh_mirrors/wo/world-execute-me-dsh-pv
cd world-execute-me-dsh-pv
pip install -r requirements.txt
第二步:安装 Node 依赖与 Chromium
dsh 聊天窗口需要 Playwright 驱动的无头浏览器逐帧截图,这一步最容易被新手漏掉:
npm install
npx playwright install chromium
第三步:确认 ffmpeg 在 PATH 中
ffmpeg -version
ffprobe -version
只要两条命令都能打印版本号即可(构建时会用到 ffprobe 核对媒体信息)。
第四步(非 Windows):设置替代字体
仓库默认按 Windows 字体路径查找 Consolas、微软雅黑、Segoe UI Symbol。在 Linux / macOS 上,通过环境变量指向本机字体即可,变量名与替代建议见 docs/FONTS.md:
export PV_F_MONO=/path/to/JetBrainsMono-Regular.ttf # 等宽正文
export PV_F_CJK=/usr/share/fonts/noto/NotoSansSC-Regular.otf # 中文
注意:build.py 代码靠目录间的相对位置互相引用,请不要改动 film/ 下的目录名。
🎵 准备输入文件:歌曲是唯一的必选项
出于版权原因,歌曲音频和歌词文字不随仓库分发,需要你自己准备(详见 input/README.md):
input/song.mp3(必需):《world.execute(me);》完整音频。构建脚本会用 sha256 与 data/song.json 中记录的指纹核对——指纹不一致也能渲染,但你的文件片头静音时长若不同,唱词与镜头会整体漂移;input/lyrics.lrc(可选):不提供时,build.py lyrics会自动从 LRCLIB 下载同步歌词到本机(由 tools/lyrics.py 完成),再与仓库中"不含文字的逐词时间"合成。
⚡ 一条命令渲染完整 PV
所有输入就位后,出片就是一条命令:
python build.py all
它会按顺序执行 build.py 中的五步流水线,每步也可单独运行:
| 步骤 | 命令 | 做了什么 |
|---|---|---|
| 1. 检查 | python build.py check |
校验 ffmpeg、Node、字体、歌曲指纹 |
| 2. 歌词 | python build.py lyrics |
下载/合并逐词时间轴 |
| 3. 替身舞者 | python build.py dancer |
用鲸鱼娘立绘生成同名同帧数的替身帧(原片舞者帧不分发,机制见 docs/HOW_IT_WORKS.md) |
| 4. 页面截图 | python build.py pages |
各组 batch_*.py 生成逐帧 HTML,seg_shot.mjs 截成 PNG |
| 5. 渲染 | python build.py render |
并行渲染无损 720p 母版,混入结尾提示音后转码出片 |
🎬 查看输出:成片与母版
构建完成后在 out/ 目录得到:
out/film.mp4:1280×720 播放版(H.264,含歌曲与结尾提示音混音);out/film_master.mp4:无损 RGB 720p 母版,后续任何导出都基于它;- 加
--4k参数则另出out/film_4k.mp4(3840×2160,像素级 3 倍放大):
python build.py all --4k
耗时预期:CPU 渲染全片大约十几分钟到半小时,取决于核数;--workers N 可手动指定并行度。如果你有 CUDA 版 torch,用 python build.py render --gpu --python <那个 python> 把辉光、残影、扫描线后期挪到 GPU 上会快很多。
🛠 常见问题快速排查
missing: node_modules/playwright→ 没跑npm install和npx playwright install chromium;missing font: ...→ 非 Windows 系统没设PV_F_*环境变量,对照 docs/FONTS.md 配置;input/song.mp3 is not the file the film was timed on→ 只是提示,你的音频与对齐用版本指纹不同,渲染仍会继续,注意片头静音对齐即可;- 构建中断后重跑 → 直接单独执行断掉的步骤(如
python build.py render),无需从头再来。
📚 延伸阅读
- 时间线与九组镜头的完整剧情表:docs/HOW_IT_WORKS.md
- 用 FFmpeg 运动补偿插帧导出 1080p / 2K 60fps 播放版:docs/60FPS_EXPORT.md
- 字体替换细则:docs/FONTS.md
- 第三方素材与许可(代码 MIT,美术 CC BY-NC-SA 4.0):NOTICE.md
🎬 十几分钟后,你就能看到一支完全由代码"画"出来的 PV——每一帧,都是歌曲时间的纯函数。
