贾马尔

Jammarr

Jammarr 为 Minecraft 提供一条由服务器权威管理的 Plex 音乐队列。玩家可以在游戏中浏览和排队音乐，管理员控制播放，所有收听客户端都跟随同一个服务器时间线。

Jammarr 有意设计为服务器和客户端双端必需的模组。仅服务器端模组无法通过未经修改的 Minecraft 客户端声音引擎解码任意的 Plex 音频。

需求

• 下方表格中一个受支持的 Minecraft/加载器组合及其所需的 Java 版本。
• 在专用服务器和每个连接的客户端上安装匹配的 Jammarr Minecraft 版本和加载器 JAR。
• 一个 Minecraft 服务器可以访问的 Plex 媒体服务器。客户端不需要网络访问 Plex。

Fabric、Quilt 和 NeoForge 不适用于 Minecraft 1.7.10。Quilt 在所有现代目标上均受支持，使用匹配的 -fabric.jar、Quilt Loader 0.30.0 和上游 Fabric API；无需 QSL、Quilted Fabric API 或单独的 -quilt.jar。不支持 Fabric 到 Quilt 的连接以及其他跨加载器或跨 Minecraft 的配对。每个工件都使用协议 5，并命名为 jammarr-<mod-version>+mc<version>-<loader>.jar；不存在跨 Minecraft 或 Forge 家族的通用 JAR。精确的固定依赖项列在 gradle/version-catalogs/ 下的家族目录中，并复制到生成的发布清单中。

不需要外部 FFmpeg 安装。Plex 准备 MP3 转码版本；如果某个 Plex 版本返回可变比特率数据，Jammarr 会使用其内置的纯 Java 编码器在进程中将其标准化为配置的恒定比特率。

服务器设置

1. 启动服务器一次以生成 world/serverconfig/jammarr-server.toml。
2. 将 plexUrl 设置为 Plex 基础 URL，并将 musicLibrary 设置为音乐库标题或数字分区键。留空库将选择第一个音乐库。
3. 通过 JAMMARR_PLEX_TOKEN 提供令牌（推荐），或将其放在服务器配置中的 plexToken 中。
4. 如果使用 plexToken，请将服务器配置文件限制为 Minecraft 服务器账户可访问，并防止备份/日志泄露它。编辑服务器配置后重启服务器。/jammarr reload 会针对当前加载的值重新运行连接和库验证。

重要的服务器选项和默认值：

Plex 元数据响应上限为 4 MiB，展开的专辑/艺术家/播放列表上限为剩余队列容量，单个转码上限为三小时和 256 MiB，停滞的转码正文在三分钟后中止。

允许在受信任的专用网络上使用纯 HTTP，并会发出警告。HTTPS 使用标准的 Java 证书验证。
比特率限制在 64–320 kbps，缓存大小限制在 64–16384 MiB；无效值在规范配置加载期间被拒绝，并在启动时报告。

客户端收听和音量设置与服务器文件分开。Forge 和 NeoForge 从 Mods 列表的 Config 条目中公开它们；Fabric 在 Jammarr 内部以及安装 Mod Menu 时通过其公开它们。

游戏内使用

• 默认按 J 键或运行 /jammarr 打开音乐界面。该键在 Controls 中显示为 Open Jammarr，可以在所有受支持的版本和加载器上重新绑定。这避免了现代 Minecraft 中原版社交菜单的 P 键绑定。
• 界面包括“正在播放”、“搜索”、“艺术家”、“专辑”、“播放列表”、“电台”、“冒险”和“队列”视图，支持服务器端分页。
• 每个玩家都可以浏览并添加曲目、专辑、艺术家或音频播放列表。
• 权限等级 2 的管理员可以暂停、恢复、跳过、清除、移除和重新排序队列条目。
• 每个玩家可以独立静音 Jammarr 并设置持久的本地音量。本地选择退出永远不会改变全局队列。
• 管理员可以运行一个共享的无限源：Sonic 自动播放、库随机播放、曲目电台、艺术家电台、专辑电台或 2–5 个种子 Sonic Mix。曲目、艺术家和专辑浏览行提供电台/混合操作。
• 冒险是一个单独的标签页。管理员构建一个包含 2–5 个曲目路径点的有序路线，预览 Plex 的声学路径，并正常或立即启动它。在最后一个路径点之后，Jammarr 会从该曲目继续使用曲目电台。
• 手动请求总是在当前歌曲之后、生成的电台曲目之前播放。队列视图将生成的预览条目标记为只读；它们不占用手动队列限制。
• “正在播放”界面报告服务器播放和本地音频状态。解码器或传输恢复有界限，可以在最终本地音频错误后从界面重试。
• 搜索报告短查询、搜索中、Plex 不可用和空结果状态；队列操作报告进度和完成情况，长标题在工具提示中显示完整文本。
• 主音量、音乐音量和 Jammarr 音量控制均适用。当 Jammarr 流激活时，原版背景音乐被抑制，之后恢复。

命令：

Plex Sonic 设置

Sonic 电台需要服务器所有者拥有有效的 Plex Pass 会员资格，并对所选音乐库完成声学分析。在 Plex 服务器库设置中启用 Analyze audio tracks for sonic features，并在音乐库的高级设置中启用 Sonic Analysis，然后让分析任务完成。

“电台”和“冒险”标签页会报告 Plex Pass 是否不可用、库/种子分析是否不完整、服务器是否缺少该操作、验证是否仍在运行或 Plex 是否离线。元数据回退默认故意关闭，绝不替代 Sonic Adventure。

播放和故障行为

• 每个加载器都将服务器播放委托给同一个 Java 8、独立于 Minecraft 的协调器。狭窄的运行时、玩家/权限、数据包传输和 schema-4 持久化契约使加载器 API 远离队列、电台、冒险、缓存、计时和传输策略。
• 服务器拥有队列、时间线、Plex 凭据、缓存和所有媒体请求。Plex 令牌永远不会发送给客户端。
• 曲目在原子缓存安装之前进行验证。在当前曲目播放时预取下一首曲目。
• MP3 数据仅在帧边界上分割成不大于 16 KiB 的有效负载。客户端一次拉取一个服务器授权的窗口，验证 SHA-256 哈希，确认完整窗口，并且只重试未完成的窗口。服务器拒绝乱序、未确认、过度缓冲和过多的请求。
• 新曲目使用经过过滤的客户端/服务器时钟估计提前五秒调度。晚加入者从权威位置附近开始。超过 500 ms 的漂移会导致本地重新缓冲，而不是延迟每个听众。
• 准备失败会以退避方式重试三次。缺失或永久无效的项目被跳过；身份验证、配置和中断故障等待 30 秒的 Plex 恢复检查，而不是在每个服务器 tick 重试。在临时 Plex 中断期间，缓存的播放继续。
• 客户端音频恢复在每个播放会话中重试三次。第四次失败会停止自动重试，并显示 Retry audio 操作，而不是让静音流无限运行。
• 队列和五秒播放检查点保存在世界存档数据中。优雅关闭会记录 RESUME_POSITION 的当前位置。
• 活动电台、自动播放开关、种子/路径点定义、当前源以及用于重复抑制的最后 100 首曲目也保存在世界存档数据中。重启后重新生成生成的预先计算。 RESTART_TRACK 和 RESUME_POSITION 保留源；CLEAR 移除它。
• 未修改的客户端和具有不兼容 Jammarr 网络协议的客户端在负载协商期间被拒绝。队列修改包含预期的曲目键，因此过期的操作员界面无法修改错误的条目。
• 服务器诊断命令报告 Plex 验证时间、缓存命中/未命中/安装/无效计数器、当前和下一曲目缓存状态、活动监听器传输计数器以及客户端报告的恢复/欠载/缓冲健康状态。

安全与隐私

• 优先使用 JAMMARR_PLEX_TOKEN，这样令牌不会写入配置文件。
• 库请求通过标头进行身份验证。Plex 的渐进式转码端点在某些服务器版本上需要查询身份验证；Jammarr 从不记录该请求 URI。
• 错误和管理员诊断会编辑掉明文和 URL 编码的令牌值。面向玩家的错误不包含服务器地址、请求 URI 或凭据详细信息。
• Jammarr 不会修改 Plex 评分、播放历史或播放列表。

构建与验证

./gradlew releaseMatrixGate --no-daemon --max-workers=1

releaseMatrixGate 运行共享测试、所有五个三加载器现代家族构建、感知清理的 GameTest 门、隔离的 Forge 1.7.10 Java 8 门、对每个最终 JAR 的集中检查（包括可重映射的菜单键注册），以及所有 21 个受支持的加载器/版本运行时的全新专用服务器检查。每个现代 Fabric 工件在 Fabric 和 Quilt 下都经过测试，同时保持一个发布文件。每个运行时必须首先拒绝无效的规范配置而不泄露其值，然后成功启动并针对确定性的环回 Plex 服务完成经过身份验证的库和声学能力调用。每个运行时都会启动一个真实的错误协议客户端，并要求双方都精确拒绝。现代目标将无依赖的缺失客户端探测与加载器的面向客户端的拒绝配对；Forge 1.7.10 启动一个真实匹配的客户端，其仅接受的问候被抑制，并要求显式的缺失问候超时。第二个真实客户端证明公共命令在提升前可见，操作员命令仅在提升后出现，并且 /jammarr diagnostics 到达玩家而不暴露 Plex 令牌或地址。最后，两个真实客户端提供隔离的音频输出，以便门可以测量晚加入、暂停/恢复、音量、静音、重新加载、缓存备份中断播放、库随机播放、Sonic Adventure、欠载和漂移恢复、重试耗尽/手动重试、重新连接和清除；仅状态或分配的 OpenAL 源不算通过。门在 build/releases/ 中放置恰好 16 个工件，以及 schema-2 manifest.json 和 SHA256SUMS，如果测试的服务器留下进程或游戏端口，则失败。

有用的更窄门是 verify1201Family、verify1202Family、verify1211Family、verify2612Family、verify262Family、verifyQuiltRuntimes、verifyLegacy1710 和 verifyGameTests。每个目标的 verifyRelease 检查加载器元数据、翻译、解码器依赖项、许可证声明、规范文件名和其他目标特定的不变量。遗留验证器还检查所有 Jammarr 类都是 Java 8 字节码。

发布检查清单：

• 从干净的检出运行 ./gradlew releaseMatrixGate --no-daemon --max-workers=1。
• 针对预期的部署服务器，对每个 Minecraft 家族运行一次经过凭据验证的 Plex 冒烟测试。
• 确认自动化的 21 运行时专用服务器门已通过，并保留 build/dedicated-server-gate/ 日志作为发布证据。
• 确认缺失客户端和故意不兼容协议的客户端收到明确的断开连接。
• 确认所有现代 Fabric JAR 都能在 Fabric Loader 0.19.2 和固定的 0.19.3 运行时下启动。
• 确认所有五个 Quilt 客户端场景在无 Mod Menu 和固定 Mod Menu 版本下均通过。
• 完成 docs/RELEASE_ACCEPTANCE.md 中可听到的双客户端矩阵；连接的客户端或分配的 OpenAL 源不足够。
• 在 Modrinth、CurseForge 和任何其他分发平台上，将每个现代 -fabric.jar 标记为与 Fabric 和 Quilt 兼容；切勿上传重复的 -quilt.jar。
• 一起发布 build/releases/ 中的 16 个 JAR、manifest.json 和 SHA256SUMS。

可选的实时 Plex 测试仅从其进程环境读取凭据：

JAMMARR_LIVE_TEST=true \
JAMMARR_PLEX_URL='https://plex.example.invalid:32400' \
JAMMARR_PLEX_TOKEN='...' \
./gradlew test --tests stonytark.jammarr.server.PlexLiveSmokeTest

经过凭据验证的实时测试结果故意不可缓存。测试凭据不是构建输入，也不会打包到模组 JAR 中。

Jammarr 根据 CC0-1.0 发布。其许可证、嵌入式 MP3 库的完整 LGPL-2.1-or-later 文本以及 THIRD_PARTY_NOTICES.md 被复制到构建的工件中。

有关目标特定详细信息，请参阅 兼容性、迁移 和 发布验收矩阵。