原创 娱乐 MapVideo-地图视频 1.4.1

MapVideo​

用物品展示框和地图，在 Minecraft 服务器里拼一面会播放视频的墙​

MapVideo 让你像搭影院一样，用物品展示框 + 地图拼出任意大小的屏幕，播放本地视频、B 站视频或HTTP(S) 直链视频。声音通过 Simple Voice Chat 的临时语音组播放，附近玩家自动入组，停止后恢复原来的语音组。

版本： 1.4.1
作者： 是小文呀
服务端： Paper / Leaves 1.21.11
Java： 21+
依赖： Simple Voice Chat
客户端 Mod： 不需要（只需安装 SVC 客户端）

点击展开...

⬇ 下载 MapVideo-1.4.1.jar · 完整文档

---

为什么选择 MapVideo？​

• 三种片源：本地 MP4、B 站 BV/链接、HTTP(S) 直链。
• 真正的游戏内屏幕：每个方块一个展示框、一张 128×128 地图，1×1 到 8×6（可配置）自由拼接。
• 最高 20 FPS：直接构造原版 Map 数据包，绕过 MapCanvas 每帧 16,384 次 setPixel，并只发送变化的矩形区域。
• 影院级声音：SVC 临时组 + Opus 高码率音频；音频是主时钟，画面主动追音频，不会为了画面去跳音频。
• 屏幕防破坏：展示框固定、无敌，拦截玩家破坏、爆炸、活塞和支撑墙破坏；只能 /mapvideo remove 删除。
• 防盗链直链：支持签名查询串、Referer、User-Agent、Cookie、自定义请求头；下载后缓存复用。
• 创世神式选区：木铲左键/右键两点选区，自动计算墙面、朝向和地图编号。
• 重启保留：屏幕、地图 ID、展示框 UUID 持久化到 screens.yml，重启自动补回缺失展示框。

---

<!-- 上传游戏内截图到 docs/screenshot.png 后取消下一行注释：  -->

环境要求​

JCodec 不支持 H.265/HEVC、AV1、VP9；B 站这些编码的流不会被选中。
直链不支持 m3u8/HLS/DASH/直播流。

点击展开...

---

安装​

1. 下载 MapVideo-1.4.1.jar，放入服务器 plugins/。
2. 安装 Simple Voice Chat 服务端插件（玩家也需要装 SVC 客户端）。
3. 重启服务器。
4. 给玩家权限（默认 mapvideo.use / create / play 已开放）。
5. 进入游戏，输入：

代码块

/mapvideo guide

---

快速开始​

1. 创建屏幕​

代码块

/mapvideo guide

• 左键点击墙面：位置 1
• 右键点击对角墙面：位置 2
• 输入：

代码块

/mapvideo create livingroom
屏幕只会生成物品展示框，不会生成或破坏任何方块。墙面必须已经存在。

2. 播放本地视频​

把视频放入：

代码块

plugins/MapVideo/videos/
然后：

代码块

/mapvideo play livingroom demo.mp4

3. 播放 B 站视频​

代码块

/mapvideo play livingroom BV1GJ411x7h7
/mapvideo play livingroom ”[ MEDIA=bilibilibv ]BILIBILIBV号[ /MEDIA ]“
支持 b23.tv 短链；首次下载并缓存，后续直接复用。

4. 播放 HTTP(S) 直链​

代码块

/mapvideo play livingroom https://cdn.example.com/video.mp4
/mapvideo play livingroom https://cdn.example.com/video.mp4?auth_key=...&expires=...
支持防盗链站点：

yaml

url:
referer: "https://example.com/page"
user-agent: "Mozilla/5.0 ..."
cookie: "session=..."
headers:
X-Requested-With: "XMLHttpRequest"
修改后 /mapvideo reload，再重新播放。直链下载后会缓存；聊天/日志只显示 host + 文件名，不会泄露签名 token。

5. 控制播放​

代码块

/mapvideo pause livingroom
/mapvideo resume livingroom
/mapvideo stop livingroom
/mapvideo remove livingroom

---

命令​

主命令：/mapvideo
别名：/mv、/mapv

---

权限​

mapvideo.admin 自动通过其他权限检查。

---

主要配置​

完整配置见插件目录 config.yml，常用项：

yaml

screen:
max-width: 8 # 最大宽度（方块/展示框）
max-height: 6 # 最大高度
max-tiles: 48 # 单屏最大地图数
view-distance: 48 # 画面推送距离
protect-support-blocks: true

video:
default-fps: 20
max-fps: 20
auto-fps: true
max-frame-lag-ms: 120
loop: false
keep-aspect-ratio: true
audio:
enabled: true
volume: 100
cache: true
high-quality: true
bitrate-kbps: 96

bilibili:
enabled: true
quality: 64
auto-quality: true
cookie: ""
cache-folder: cache/bilibili

url:
enabled: true
referer: ""
origin: ""
cookie: ""
headers: {}
max-size-mb: 2048
cache-folder: cache/url

voicechat:
auto-join: true
join-radius: 32
group-type: NORMAL
restore-previous-group: true
category-id: mapvideo
category-name: "MapVideo 视频"
group-name-format: "MapVideo-%s"
修改后执行 /mapvideo reload。voicechat.category-* 建议重启服务器生效。

---

性能与网络​

代码块

整图上限（未压缩） ≈ 地图数 × 帧率 × 16 KB / 秒
4×3 @ 20 FPS ≈ 3.8 MB/s / 每个观众
4×3 @ 10 FPS ≈ 1.9 MB/s / 每个观众
MapVideo 做了三层优化：

1. tile 去重：完全没变化的地图不发。
2. 变化矩形：只发变化像素的最小包围矩形，客户端立即应用。
3. 原版 zlib：Minecraft Netty 自动压缩，客户端自动解压，不需要客户端 Mod。

实测 4×3 测试视频：地图包总数 1251，其中 896 个矩形补丁（约 71.6%），数据量 14.46 MB（整图等价 20.50 MB），节省约 29.5%，还未计算 zlib 的进一步压缩。

请保持 server.properties 的 network-compression-threshold 不为 -1（默认 256 即可）。
地图画面受 20 TPS 限制，稳定上限是 20 FPS；大屏/多人/720P 主要受 CPU 限制。

点击展开...

---

常见问题​

没有声音？

1. 服务端和玩家客户端都需要安装 Simple Voice Chat。
2. 玩家要在 join-radius 内，且没有被手动切到别的语音组。
3. 检查 SVC 客户端音量分类 MapVideo 视频。
4. 视频没有 AAC 音轨时不会创建语音组。

B 站提示没有可下载 MP4？

• 可能是番剧、付费、地区限制或需要 Cookie。
• 在 bilibili.cookie 填入 SESSDATA=...。
• 确认服务器能访问 api.bilibili.com 和 B 站 CDN。

直链 403/401？

• 配置正确的 url.referer、url.user-agent、url.cookie。
• 部分站点还需要 url.origin 或自定义 url.headers。
• 修改后 /mapvideo reload，再重新播放。

帧率上不去？

• 确认 video.auto-fps: true、max-fps: 20。
• 降低源视频分辨率，或让 B 站使用 auto-quality。
• 大屏幕/多人服务器建议 8–10 FPS。
• 纯 Java JCodec 比 FFmpeg 更吃 CPU；这是软件解码的限制。

展示框能打掉吗？

• 玩家攻击、爆炸、活塞、支撑墙破坏会被拦截。
• 只能 /mapvideo remove <屏幕ID> 删除。

支持 HLS/m3u8/直播吗？

• 不支持。目前只支持 MP4/M4V/MOV 的 H.264 + AAC，以及 B 站普通投稿。

---

更新日志​

1.4.1​

• 修复部分卡顿BUG。
• /mapvideo version / about 显示作者和版本。

1.4.0​

• 新增 HTTP(S) 直链播放。
• 支持防盗链 Referer / User-Agent / Cookie / 自定义请求头。
• 支持签名查询串，直链缓存复用。
• 新增 /mapvideo version。
• 清理无用配置：voicechat.enabled、video.videos-folder、config-version。

1.3.0​

• 超大屏幕网络优化：地图 tile 去重 + 变化矩形补丁。
• 差异只计算一次，不再为每个观众复制整屏像素。

1.2.2​

• 同步策略改为音频主时钟：只跳视频帧/视频关键帧，不移动音频。

1.2.1​

• 修复 YUV 直通渲染导致的负色/反色问题。
• 修复视频卡在第一帧的问题。

1.2.0​

• B 站 BV/链接播放、缓存、WBI 兜底。
• 自适应清晰度 + 高质量音轨分离下载。
• 20 FPS、音画同步、快速地图包。

1.1.0 / 1.0.0​

• 地图墙、选区、屏幕持久化、展示框保护。
• SVC 临时语音组、Opus 高码率音频。

---

技术栈​

• Paper API 1.21.11
• Simple Voice Chat API 2.5.0（编译），测试 2.6.27
• JCodec 0.2.5（H.264/AAC 解码）
• Gson 2.11.0
• Java 21

JCodec、Gson 已 shade 进插件 jar；Paper/SVC API 为 provided 依赖。