将视频转换为 Minecraft Java 1.21.1 的地图数据,通过多个展示框拼接成大屏幕在游戏内播放。
https://github.com/eaginilir/video2mc/assets/效果展示.mp4
8×5 展示框屏幕(1024×640 像素),使用数据包驱动播放
- 多进程并行转换,充分利用多核 CPU
- LUT(查找表)加速颜色量化,构建一次、查询极快
- **抖动(Floyd-Steinberg)**模式,画质更细腻
- GPU 加速(可选,需 CuPy)构建颜色 LUT
- 自动生成数据包,游戏内无需安装 Mod,纯 Vanilla/NeoForge 可用
- 数据包支持预加载、播放/暂停/重置/速度调节
- Python 3.10+
- Minecraft Java Edition 1.21.1(含 NeoForge 等加载器)
- 命令方块权限 / 作弊模式开启
pip install opencv-python numpy
# GPU 加速(可选,需要 CUDA 12.x):
pip install cupy-cuda12x
# 默认设置(8×5 屏幕,20fps)
python main.py video.mp4
# 自定义参数
python main.py video.mp4 --cols 8 --rows 5 --fps 10 --output my_output
# 更多选项
python main.py video.mp4 --dither # 启用抖动(画质更好,稍慢)
python main.py video.mp4 --workers 12 # 指定并行进程数
python main.py video.mp4 --gpu # GPU 加速 LUT 构建| 参数 | 说明 | 默认值 |
|---|---|---|
--cols |
屏幕列数(展示框横向数量) | 8 |
--rows |
屏幕行数(展示框纵向数量) | 5 |
--fps |
提取帧率 | 20 |
--start-id |
起始地图 ID(多个视频时避免冲突) | 0 |
--dither |
启用 Floyd-Steinberg 抖动 | 关 |
--workers |
并行进程数 | CPU 核心数 |
--gpu |
GPU 加速 LUT 构建 | 关 |
-o |
输出目录 | output |
转换完成后 output/ 目录结构:
output/
├── data/ ← 地图数据文件 (map_0.dat, map_1.dat, ...)
├── video2mc_datapack/ ← Minecraft 数据包
└── commands.mcfunction
-
将
output/data/下所有map_*.dat文件复制到:.minecraft/saves/<存档名>/data/ -
将
output/video2mc_datapack/整个文件夹复制到:.minecraft/saves/<存档名>/datapacks/
进入存档后执行:
/reload
然后在墙上放好展示框(左上角为锚点),站在展示框 5 格以内运行:
/function v2mc:auto_setup
程序会自动检测展示框朝向并完成标记。
/function v2mc:play
首次播放会自动预加载所有地图数据(actionbar 显示进度),预加载完成后自动开始播放。
| 命令 | 说明 |
|---|---|
/function v2mc:auto_setup |
自动标记展示框网格(站在 5 格内,无需对准方向) |
/function v2mc:play |
播放(首次自动预加载) |
/function v2mc:pause |
暂停 |
/function v2mc:reset |
重置到第一帧 |
/function v2mc:faster |
加速(减少每帧 tick 数) |
/function v2mc:slower |
减速(增加每帧 tick 数) |
/function v2mc:remove |
移除所有屏幕标记 |
/function v2mc:debug |
显示当前状态(用于排查问题) |
使用 --start-id 错开 ID 范围,避免地图文件冲突:
# 第一个视频(8×5=40 个展示框,319 帧 → 使用 ID 0~12759)
python main.py video1.mp4 --start-id 0 -o output1
# 第二个视频(从 20000 开始)
python main.py video2.mp4 --start-id 20000 -o output2展示框按行从左到右、从上到下排列,auto_setup 执行时最靠近你的那个展示框会被设为左上角锚点。
[0,0] [0,1] [0,2] ... [0,cols-1]
[1,0] [1,1] ...
...
[rows-1,0] ... [rows-1,cols-1]
支持四个朝向(南/北/东/西),自动检测,无需手动配置。
| 文件 | 说明 |
|---|---|
main.py |
主程序:视频读取、帧提取、并行转换 |
mc_colors.py |
Minecraft 地图调色板 + LUT / 抖动颜色量化 |
map_writer.py |
写入 map_N.dat 和 idcounts.dat |
datapack.py |
生成 Minecraft 数据包(所有 mcfunction 文件) |
展示框全部空白
先运行 /function v2mc:debug,确认 预加载:1。如果仍然空白,尝试 /function v2mc:slower 降低播放速度。
auto_setup 标记数量不对 确认展示框都在同一面墙上,且相互紧邻(没有间隔)。确认站在展示框 5 格以内再执行。
地图显示棕色/空白
检查 map_*.dat 文件是否正确复制到存档的 data/ 目录,且执行了 /reload。
转换太慢
增加 --workers 数量,或使用 --gpu(需要 CUDA 环境)。