矿井化

矿井化

一个Minecraft Fabric模组，支持全服务器音乐播放，玩家可以搜索YouTube、将歌曲添加到共享播放列表并一起收听。

游戏机制

Mineify - Minecraft 全服音乐播放器

一个 Minecraft Fabric 模组，支持全服音乐播放。玩家可以搜索 YouTube、将歌曲添加到共享播放列表，并在 Minecraft 内实时一起收听。

使用方法

  1. 加入运行 Mineify 的服务器
  2. 按下 N+M 打开 GUI
  3. 在搜索栏中输入歌曲名称并按回车
  4. 点击搜索结果将其添加到播放列表
  5. 歌曲会自动下载并为所有在线玩家播放

工作原理

所有内容都在 Minecraft 服务器进程内运行——无需配套服务，也无需额外开放端口。

┌─────────────────────────────────────────────────────────────────────┐
│                         MINECRAFT 服务器                            │
│  ┌─────────────────┐    ┌──────────────────┐                        │
│  │  Mineify 模组   │◄──►│ 播放列表管理器   │                        │
│  │  （服务端）     │    │ （曲目队列）     │                        │
│  └────────┬────────┘    └──────────────────┘                        │
│           │                                                         │
│           │  ┌─────────────────┐  ┌──────────────────────────────┐  │
│           ├─►│ YouTubeService  │  │   AudioDownloadService       │  │
│           │  │ （InnerTube API）│  │   yt-dlp 子进程              │  │
│           │  └─────────────────┘  └──────────────────────────────┘  │
│           │                                                         │
│           │  Minecraft 数据包（分块音频数据）                       │
│           ▼                                                         │
│  ┌─────────────────┐    ┌──────────────────┐                        │
│  │  Mineify 模组   │───►│  AudioPlayer     │                        │
│  │  （客户端）     │    │  （javax.sound） │                        │
│  └─────────────────┘    └──────────────────┘                        │
└─────────────────────────────────────────────────────────────────────┘
  1. YouTubeService 直接从 Java 调用 YouTube 的内部 InnerTube API——无需 API 密钥。
  2. AudioDownloadService 调用 yt-dlp 子进程下载音频并将其转换为 WAV。
  3. 服务器将 WAV 文件拆分为数据块，并通过现有的 Minecraft 连接发送给每个客户端——无需开放额外端口。
  4. 客户端在内存中重新组装数据块，并使用 javax.sound.sampled 在本地播放音频。

功能特点

  • N+M 键位 — 在游戏内任意位置打开 Mineify GUI
  • YouTube 搜索 — 直接在 Minecraft 内搜索歌曲
  • 共享播放列表 — 所有玩家都能看到并贡献到同一个队列
  • 自动播放 — 歌曲添加后自动播放，并按队列顺序推进
  • 中途加入同步 — 在歌曲播放中途加入的玩家会自动跳转到正确位置
  • 移除即停止 — 移除当前歌曲会立即停止所有玩家的播放
  • 会话缓存 — 已下载的文件在服务器会话期间可重复使用
  • 无额外端口 — 音频通过 Minecraft 连接传输；无需更改防火墙
  • 自包含 — 所有内容都在单个模组 JAR 内，无需配套服务

环境要求

要求
Minecraft 1.21.11
Fabric Loader 0.18.x+
Fabric API 适用于 1.21.11 的最新版本
Java 21+
仅服务端 系统 PATH 中的 yt-dlp
仅服务端 系统 PATH 中的 ffmpeg

客户端只需要模组 JAR——无需额外工具。

安装

服务端

  1. 为 Minecraft 1.21.11 安装 Fabric Loader。
  2. 在服务器机器上安装 yt-dlp 和 ffmpeg（参见下方指南）。
  3. 将 Fabric API 和 mineify-1.3.0.jar 放入服务器的 mods/ 文件夹。
  4. 启动服务器。Mineify 会自动初始化。

可选 — 创建 config/mineify.json 以自定义行为：

{
  "downloadDir": "./mineify-downloads",
  "maxPlaylistSize": 50
}

客户端

  1. 为 Minecraft 1.21.11 安装 Fabric Loader。
  2. 将 Fabric API 和 mineify-1.3.0.jar 放入 .minecraft/mods/。
  3. 使用 Fabric 配置启动 Minecraft。无需进一步设置。

安装 yt-dlp 和 ffmpeg

两个工具都仅在服务端需要。

Linux (Debian/Ubuntu)

sudo apt update && sudo apt install ffmpeg
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

Linux (Fedora/RHEL)

sudo dnf install ffmpeg
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

macOS

brew install ffmpeg yt-dlp

Windows（选择一个包管理器）

scoop install yt-dlp ffmpeg

choco install yt-dlp ffmpeg

winget install yt-dlp ffmpeg

Windows — 手动安装

yt-dlp：

  1. 从发布页面下载 yt-dlp.exe
  2. 将其放入一个文件夹，例如 C:\yt-dlp
  3. 将该文件夹添加到系统 PATH

ffmpeg：

  1. 从 gyan.dev 下载
  2. 解压到一个文件夹，例如 C:\ffmpeg
  3. 将 C:\ffmpeg\bin 添加到系统 PATH

添加到 PATH（Windows）：

  1. 按 Win + R，输入 sysdm.cpl，按回车
  2. 转到 高级 → 环境变量
  3. 在 系统变量 下，选择 Path → 编辑 → 新建
  4. 添加文件夹路径，并在所有对话框中点击 确定
  5. 重启终端/服务器

验证安装

yt-dlp --version
ffmpeg -version

两个命令都应打印版本信息且无错误。

项目结构

mine-ify/
├── fabric-mod/
│   └── src/
│       ├── main/java/com/mineify/
│       │   ├── Mineify.java                  # 服务端入口点与生命周期
│       │   ├── MineifyConfig.java            # 配置加载器 (mineify.json)
│       │   ├── server/
│       │   │   ├── PlaylistManager.java      # 播放列表状态与音频分发
│       │   │   ├── YouTubeService.java       # 通过 InnerTube API 进行 YouTube 搜索
│       │   │   └── AudioDownloadService.java # yt-dlp 下载封装
│       │   └── network/
│       │       ├── MineifyPackets.java       # 数据包注册
│       │       └── packets/
│       │           ├── SearchRequestPacket.java
│       │           ├── AddToPlaylistPacket.java
│       │           ├── SearchResultsPacket.java
│       │           ├── PlaylistSyncPacket.java
│       │           ├── AudioChunkPacket.java  # 分块音频传输
│       │           └── NowPlayingPacket.java
│       └── client/java/com/mineify/
│           ├── MineifyClient.java            # 客户端入口点与数据包处理器
│           └── client/
│               ├── MineifyScreen.java        # 游戏内 GUI
│               ├── MineifyKeybinds.java      # N 键位注册
│               └── audio/
│                   └── AudioPlayer.java      # 数据块缓冲与播放
└── README.md

开发

需要 Java 21。

cd fabric-mod
./gradlew build          # 构建模组 JAR
./gradlew runClient      # 启动测试 Minecraft 客户端
./gradlew runServer      # 启动无头测试服务器

法律

本模组仅供个人和教育用途。用户有责任遵守 YouTube 的服务条款和适用的版权法律。

许可证

MIT 许可证 — 详情请参阅 LICENSE。