WATERMeDIA: Multimedia API

📕 概述

WATERMeDIA 是一个拥有完善 API 的多媒体前置库：它可以播放视频、音乐、直播、图片和
动画，并对这些内容进行解码与编码，使用 OpenGL 和 Vulkan 进行渲染，并通过 OpenAL 播放声音。
图片由我们自研的纯 Java 解码器处理，其他内容则通过 _FFmpeg_ 处理，该组件已捆绑在配套模组
_WATERMeDIA: Binaries_ 中。无需编译或
安装，接入即可使用。

支持 Forge、NeoForge 和 Fabric，适用于所有能够运行在 Java 17 或更高版本上的 Minecraft 版本（1.18.2 至 26.2），
同时支持客户端和专用服务器。它也可以脱离 Minecraft 运行：打开 jar 文件即可启动完整的媒体播放器，
任何 Java 应用都可以嵌入该 API。

🛠️ 功能

\* 取决于你使用的模组，并且只有在该模组开发者接入 WATERMeDIA 后才能生效。如有疑问，请询问模组作者。

• 🎬 视频和音乐通过 _FFmpeg_ 9 播放，该组件随适用于 Windows (x64)、Linux (x64、ARM64) 和 macOS (Intel、Apple Silicon) 的 _WATERMeDIA: Binaries_ 一同提供
• 🖼️ 我们自研的纯 Java 图片解码器：PNG、APNG、JPEG、GIF、WebP（包括动画）、SVG 和 Netpbm。它们在设计上安全可靠，占用的 CPU 和显存远少于传统方案，即使同时播放多个动画，也不会让游戏卡顿
• ⚡ 支持 NVIDIA、AMD、Intel 和 macOS 的硬件视频解码；当 GPU 负载过高时，会自动回退到软件解码
• 🌋 在 OpenGL 之外支持 Vulkan，已为 Minecraft 26.x 做好准备。在 Vulkan 模式下，H.264、H.265 和 AV1 视频会直接在 GPU 上解码和绘制，不会占用内存
• 🌈 HDR 以及 10、12 和 16 位视频在普通屏幕上也能自然显示，每段视频都会保留真实色彩，从旧式 SD 片段到广色域视频，以及手机或摄像头录制的视频都不例外
• 💾 视频和图片磁盘缓存：加载快速可靠，还能节省带宽
• 📡 支持直播流（HLS 和 DASH）以及 IPTV 播放列表，并会以频道列表的形式打开
• 🌐 支持热门在线平台（YouTube、Twitch、Kick、BiliBili、TikTok、Twitter (X) 等）；如果平台提供成熟内容标记，还会启用相应的安全防护
• 🖥️ 支持在专用服务器上运行。只有在使用 WATERMeDIA 的模组要求服务端支持时，才需要在服务器上安装；它会提供可选的文件服务器，通过 water://remote/ 链接与玩家共享上传的媒体
• 🗣️ 带有独立音轨的视频可以保持音画同步，从而解锁 YouTube 等平台上的更高画质。配有配音的视频会播放原始语言，或播放你偏好的语言；观看时还可以切换语言*
• 🎚️ 选择画质、调整速度、精确拖动进度、循环播放，还可以降低远处屏幕的分辨率以节省显存*
• 🔊 支持随距离衰减的空间音频。立体声屏幕可以从各自边缘播放左右声道，额外的扬声器也能在任意位置播放屏幕声音，且不会重复加载音频*
• ⏱️ 通过服务器时钟同步播放，让所有人观看同一时刻的内容*
• 🔍 在 YouTube、Twitch、Kick 和 Imgur 上按关键词搜索视频*
• 🎥 将带声音的视频录制为 MP4、MOV、MKV、WebM 和 Ogg，并将图片和动画保存为 PNG、APNG 和 GIF（实验性功能）*
• 🔒 HTTPS 媒体会校验证书，令牌、密码和登录数据绝不会写入日志

🌐 支持的平台

• 📺 YouTube、Twitch、Kick、BiliBili、Odysee、D.Tube、VidLii
• 🐦 Twitter (X)、Bluesky、TikTok、Facebook、Instagram
• 🎵 SoundCloud、Newgrounds（电影、音乐和艺术）
• 🖼️ Imgur、Lightshot、Medal、Streamable、Sendvid
• 📁 Google Drive、Dropbox、MediaFire
• 🔞 PornHub（仅在设置中允许成熟内容时可用）
• 🔗 支持指向任意视频、音乐、图片或播放列表的直接链接、本地文件以及 water:// 资源

YouTube、SoundCloud、Facebook 和 Instagram 通过 _yt-dlp_ 播放，该组件需要 _WATERMeDIA: Binaries_。BiliBili
在设置中添加会话 Cookie 后最高支持 1080p（VIP 可达 8K）；不添加时最高支持 480p。

🧩 使用 WATERMeDIA 的模组

特别鸣谢

• VideoPlayer（已停止维护）

📦 WATERMeDIA: BINARIES

配套模组中包含 _FFmpeg_ 原生库以及一些额外的共享库
_WATERMeDIA: Binaries_。其源代码位于
此仓库的 binaries/ 目录下。

• Minecraft 客户端需要 Binaries，且两个模组都必须为 3.0 版本
• 专用服务器可以跳过它。CurseForge 和 Modrinth 将其列为必需项，是因为它们的依赖关系无法表达客户端/服务端条件，因此安装程序可能也会将其添加到服务器中
• 嵌入 Java API 的应用可以不使用它，同时保留图片支持，但会失去视频解码功能以及由 _yt-dlp_ 支持的平台

🎮 支持我们并享受 15% 折扣

我们的主机合作伙伴 KineticHosting 非常适合用来创建服务器，并与朋友一起分享多媒体内容，
以及使用上方列出的所有模组。

⁉️ 常见问题

• WATERMeDIA 能在服务器上运行吗？
• 可以，自 3.0 起它可在专用服务器上加载。WATERMeDIA: Binaries 在那里是可选的
• 我还需要 VLC 吗？
• 不需要。VLC 已被 FFmpeg 取代，后者捆绑在 WATERMeDIA: Binaries 中，卸载 VLC 是安全的
• 为什么视频会卡顿？
• 在 config/watermedia.toml 中关闭硬件解码
• 我可以使用自己的 FFmpeg 吗？
• 可以，FFmpeg 可以在设置中关闭，或替换为你自己的兼容版本
• 为什么有些视频被屏蔽了？
• 成人内容默认被屏蔽；你可以在设置中允许它
• 为什么使用 TLauncher 时游戏会在启动时停止？
• 不支持 TLauncher，检测到它时游戏会停止
• 我在哪里报告 bug？
• 在 GitHub Issues 或 Discord

💻 面向开发者

两个类完成这项工作：MRL（多媒体资源定位符）将链接解析为其来源、质量和
元数据，而 MediaPlayer 通过你选择的引擎（GLEngine、VKEngine、ALEngine 等）播放它。

MRL mrl = PlayerAPI.mrl(URI.create("https://imgur.com/gallery/snow-ducks-YcDd9x"));

// IN A TICK-LOOP METHOD
if (mrl.status() == MRL.Status.LOADED) {
    MediaPlayer player = PlayerAPI.player(mrl,
            () -> PlayerAPI.glEngine(renderThread, renderExecutor),
            () -> PlayerAPI.alEngine());
}

• PlayerAPI：媒体播放和显示
• PlatformAPI：用于加载和搜索媒体的网络平台支持
• NetworkAPI：用于私有媒体的主机和远程存储
• CodecsAPI（实验性，暂时不要在你的模组中使用它）：我们自己的图片和动画编解码器，以及由 _FFmpeg_ 支持的音频和视频

完整的 API 指南，包括 Vulkan 契约和 Minecraft 26.x 桥接，位于
English 和
Español (México)。构建产物位于
JitPack。

💰 捐赠

感谢你使用 WATERMeDIA！🫶 每一笔捐赠，无论大小，都帮助我们保持它免费、持续更新，并随着
每一个新的 Minecraft 版本不断成长。

也请考虑向 _FFmpeg_ 开发者捐赠。WATERMeDIA 播放的每一段视频

都离不开他们的工作；如果没有他们，这个项目也不会存在。

⚖️ 许可证

WATERMeDIA 和 _WATERMeDIA: Binaries_ 采用
_Defensive Public Source (Non-Commercial) License v1.0.1_。
版权所有 SrRapero720（https://github.com/SrRapero720）。

允许非商业用途（包括但不限于整合包或服务器整合包）。禁止商业使用；
如需将 WATERMeDIA 用于商业用途，请联系我们。

两个模组所附带的第三方库均保留其各自的许可证；在重新分发之前，请先阅读
WATERMeDIA 和
_WATERMeDIA: Binaries_ 仓库中的相关许可证。