📕 概述

WATERMeDIA 是一个多媒体前置库，拥有设计良好的 API：它可以播放视频、音乐、直播流、图片和
动画，并对它们进行解码和编码，使用 OpenGL 和 Vulkan 渲染，并通过 OpenAL 播放声音。
图片使用我们自研的纯 Java 解码器处理，其他内容则通过 _FFmpeg_ 处理，后者打包在配套模组
_WATERMeDIA: Binaries_ 中。无需编译或
安装，即插即用。

支持 Forge、NeoForge 和 Fabric，覆盖从 1.18.2 到 26.2 的所有运行在 Java 17 或更新版本上的 Minecraft 版本，
适用于客户端和专用服务器。它也能在 Minecraft 之外运行：打开该 jar 即可启动完整的媒体播放器，
任何 Java 应用都可以嵌入该 API。

🛠️ 特性

\* 取决于你使用的模组，且仅当其开发者接入后才有效。请询问其作者。

• 🎬 视频和音乐通过 _FFmpeg_ 9 播放，_WATERMeDIA: Binaries_ 中已为 Windows (x64)、Linux (x64、ARM64) 和 macOS (Intel、Apple Silicon) 捆绑了该组件
• 🖼️ 我们自研的纯 Java 图片解码器：PNG、APNG、JPEG、GIF、WebP（同样支持动图）、SVG 和 Netpbm。设计上安全可靠，占用更少的 CPU 和 VRAM，并且可以同时播放多个动画而不会让游戏卡顿
• ⚡ 在 NVIDIA、AMD、Intel 和 macOS 上支持硬件视频解码，当 GPU 吃力时回退到软件解码
• 🌋 在 OpenGL 之外提供 Vulkan 渲染，为 Minecraft 26.x 做好准备。在 Vulkan 下，H.264、H.265 和 AV1 视频直接在 GPU 上解码和绘制，完全不经过 RAM
• 🌈 HDR 以及 10、12、16 位视频在普通屏幕上也能自然呈现，每个视频都保留其真实色彩，从老式标清片段到广色域视频以及手机或网络摄像头录制的内容
• 💾 视频和图片的磁盘缓存：加载快速可靠，节省带宽
• 📡 直播流（HLS 和 DASH）和 IPTV 播放列表，会以频道列表的形式打开
• 🌐 支持主流在线平台（YouTube、Twitch、Kick、BiliBili、TikTok、Twitter (X) 等），并在平台提供相应信息时对成人内容设有防护措施
• 🖥️ 可在专用服务器上运行。仅当使用 WATERMeDIA 的模组在服务端需要它时才在那里安装；它会附带一个可选的文件服务器，通过 water://remote/ 链接与玩家共享上传的媒体
• 🗣️ 带有独立音轨的视频可同步播放，从而在 YouTube 等平台上解锁更高画质。配音视频会播放其原始语言或你偏好的语言，并且你可以在观看时切换语言\*
• 🎚️ 选择画质、改变速度、精确跳转、循环播放，并降低远处屏幕的分辨率以节省 VRAM\*
• 🔊 随距离衰减的定位音频。立体声屏幕可以让每一侧从各自的边缘发声，额外的扬声器可以在任意位置播放某块屏幕的声音，而无需重复加载\*
• ⏱️ 通过服务器时钟同步播放，让所有人观看同一时刻\*
• 🔍 在 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（大会员可 8K）；不添加则最高 480p。

🧩 使用 WATERMeDIA 的模组

特别鸣谢

• VideoPlayer（已停止维护）

📦 WATERMeDIA: BINARIES

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

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

🎮 以低价创建你的服务器

我们的托管解决方案合作伙伴 KineticHosting 非常适合用来创建服务器，
并与好友分享多媒体内容，同时使用上方列出的所有模组。

⁉️ 常见问题

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

💻 面向开发者

两个类完成这项工作：MRL（Multimedia Resource Location）将链接解析为其来源、画质和
元数据，而 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_ 仓库中阅读相关许可证。