简单语音聊天音乐附加组件

简单语音聊天音乐附加组件

为Simple Voice Chat模组添加音乐功能

冒险

Music

Music 是一个服务端 Fabric 模组，通过 Simple Voice Chat 流式播放 URL 音乐。它专为服务器共享音乐而设计，支持队列、保存的播放列表、YouTube 播放列表导入、玩家定向、个人退出以及通过 Lavaplayer/youtube-source 实现的 YouTube OAuth 支持。

功能特性

  • 通过 Simple Voice Chat 静态音频通道流式播放音乐。
  • 支持 YouTube、YouTube Music、YouTube 播放列表链接以及其他 Lavaplayer 支持的远程源。
  • 将粘贴的 YouTube 播放列表链接展开为单首歌曲。
  • 显示标题、创作者、请求者、时长、队列位置和播放诊断信息。
  • 清理 YouTube 主题频道的创作者名称，使 Artist - Topic 显示为 Artist。
  • 一个全服共享的音乐流。
  • 全局队列，支持跳过、重复和随机播放。
  • 持久化保存的播放列表。
  • 按秒前进/后退跳转。
  • 玩家定向和排除控制。
  • 玩家自助 /music leave 和 /music join。
  • Simple Voice Chat 的 "Music" 音量类别，用于个人客户端音量。
  • 全局服务器音量控制。

前置要求

  • Fabric Loader。
  • 服务端安装了 Simple Voice Chat。
  • 希望听到音乐流的客户端安装了 Simple Voice Chat。
  • 你所安装的模组文件支持的 Minecraft 版本。

此模组在服务端控制音乐，但玩家只能通过其 Simple Voice Chat 连接听到音乐。

安装

  1. 在服务端安装 Fabric Loader。
  2. 在服务端安装 Simple Voice Chat。
  3. 将此模组安装到服务端的 mods 文件夹中。
  4. 希望听到音乐流的玩家必须在其客户端安装 Simple Voice Chat。
  5. 启动服务器并运行 /music help。

快速开始

/music now
/music play https://www.youtube.com/watch?v=VIDEO_ID 10
/music queue add https://music.youtube.com/watch?v=NEXT_VIDEO_ID
/music queue add https://www.youtube.com/playlist?list=PLAYLIST_ID
/music queue list

如果 YouTube 要求登录或阻止播放，请完成服务器日志中显示的 OAuth 设备登录。

工作原理

  1. 玩家运行 /music play、将 URL 加入队列，或启动已保存的播放列表。
  2. Lavaplayer 加载 URL。
  3. YouTube 链接由 youtube-source 处理。
  4. 模组将编码的音频帧发送到 Simple Voice Chat 静态音频通道。
  5. 选定的听众听到相同的音乐流。

每个服务器只有一个活跃的全局音乐流。使用 /music play 开始新曲目会替换当前播放并清空运行时队列。

YouTube OAuth

YouTube 可能会阻止自动播放客户端。此模组通过 youtube-source 支持 YouTube OAuth。

配置文件：

config/music.json

重要字段：

{
  "youtubeOAuthEnabled": true,
  "youtubeOAuthRefreshToken": "",
  "youtubeOAuthSkipInitialization": false
}

首次登录流程：

  1. 启动服务器。
  2. 运行 /music play <youtube-url>。
  3. 查看服务器日志中的 Google 设备登录代码。
  4. 在浏览器中完成登录。
  5. 刷新令牌将保存到 config/music.json。

YouTube 登录是服务器全局的，而非每个玩家独立。请勿泄露 music.json，因为它可能包含 OAuth 刷新令牌。建议使用备用 YouTube 账号。

命令

运行：

/music help
/music help queue
/music help playlist
/music help target
/music help volume

所有人

/music help
/music now
/music queue list
/music leave
/music join
  • /music leave 使玩家退出音乐流。
  • /music join 移除个人退出设置。
  • 个人音量通过 Simple Voice Chat 客户端的 "Music" 滑块控制。

播放

所有玩家：

/music play <url>
/music play <url> <volume>
/music stop
/music pause
/music resume
/music skip
/music forward <seconds>
/music backward <seconds>
/music volume <1-100>
/music repeat off
/music repeat one
/music repeat queue
/music shuffle on
/music shuffle off

行为：

  • /music play <url> 立即开始播放并清空运行时队列。
  • /music play <youtube-playlist-url> 开始播放播放列表的第一首曲目并将其余曲目加入队列。
  • /music play <url> <volume> 开始播放并将全局音量设置为 1 到 100。
  • /music forward <seconds> 在当前曲目中向前跳转。
  • /music backward <seconds> 在当前曲目中向后跳转。
  • /music repeat one 重复当前曲目。
  • /music repeat queue 循环播放队列。
  • /music shuffle on 随机选择队列中的曲目。

队列

所有玩家：

/music queue add <url>
/music queue remove <index>
/music queue clear
/music skip

所有人都可以查看：

/music queue list

队列行为：

  • 运行时队列在服务器重启后不会保存。
  • /music queue add <url> 追加一首曲目。
  • /music queue add <youtube-playlist-url> 展开播放列表并追加每首歌曲。
  • 队列元数据在后台加载，因此新项目可能会短暂显示为 title loading。
  • 以 - Topic 结尾的 YouTube 创作者名称显示时会去掉该后缀。
  • 如果元数据获取失败，URL 仍会保留在队列中，播放时仍会尝试该 URL。

示例输出：

[Music] Queue:
1. Song Title - Creator Name | 3:22 | requested by PlayerName | added 16:21:05
2. title loading: https://www.youtube.com/watch?v=... | requested by PlayerName

保存的播放列表

所有玩家：

/music playlist list
/music playlist create <name>
/music playlist delete <name>
/music playlist show <name>
/music playlist add <name> <url>
/music playlist remove <name> <index>
/music playlist play <name>
/music playlist queue <name>

播放列表行为：

  • 播放列表保存在 config/music-playlists.json 中。
  • 播放列表名称为单个单词。
  • /music playlist add <name> <url> 添加一首曲目。
  • /music playlist add <name> <youtube-playlist-url> 导入 YouTube 播放列表中的每首歌曲。
  • /music playlist play <name> 替换当前播放并启动播放列表。
  • /music playlist queue <name> 将保存的播放列表追加到当前队列之后。

示例：

/music playlist create lobby
/music playlist add lobby https://www.youtube.com/watch?v=SONG_1
/music playlist add lobby https://www.youtube.com/playlist?list=PLAYLIST_ID
/music playlist play lobby

定向

所有玩家：

/music target all
/music target only <players>
/music target add <players>
/music target remove <players>
/music target show
/music exclude add <players>
/music exclude remove <players>
/music exclude clear

定向顺序：

  1. 已连接的 Simple Voice Chat 客户端。
  2. 包含过滤器（如果已设置）。
  3. 排除过滤器。
  4. 玩家通过 /music leave 进行的个人退出。

个人退出始终优先。/music target all 不会强制已退出的玩家收听。

示例：

/music target all
/music target only Steve
/music target add Alex
/music exclude add Steve
/music exclude clear

配置文件

主配置：

config/music.json

存储 YouTube OAuth 设置、重复/随机播放设置、定向过滤器、排除列表和玩家退出设置。

播放列表配置：

config/music-playlists.json

存储保存的播放列表名称和曲目条目。

播放列表结构示例：

{
  "playlists": {
    "lobby": [
      {
        "url": "https://www.youtube.com/watch?v=SONG_1",
        "title": "Song Title",
        "creator": "Creator Name",
        "requestedByName": "server",
        "durationMillis": 202000
      }
    ]
  }
}

服务器运行期间，请使用命令而不是直接编辑播放列表文件。

URL 支持

推荐的来源：

  • 普通 YouTube 观看链接。
  • YouTube Music 观看链接。
  • YouTube 和 YouTube Music 播放列表链接。
  • Lavaplayer 支持的直接音频文件 URL。
  • 部分可提取音频的直接视频 URL。

不太可靠的来源：

  • Spotify 页面链接。
  • 私密或年龄限制视频。
  • 区域限制视频。
  • 被机器人检测阻止的 YouTube 链接。

不支持的 URL 应通过聊天错误提示失败，而不是导致服务器崩溃。

命令权限

所有玩家都可以使用所有 /music 命令，包括更改服务器播放状态的命令：

  • 播放、停止、暂停、恢复、跳过、前进、后退。
  • 队列添加/移除/清空。
  • 播放列表创建/删除/添加/移除/播放/加入队列。
  • 定向和排除过滤器。
  • 重复、随机播放、全局音量。

自助和查看命令：

  • /music help
  • /music now
  • /music queue list
  • /music leave
  • /music join

故障排除

音乐显示正在播放，但没有人听到

运行：

/music now
/music target show

检查：

  • Simple Voice Chat 已连接。
  • 语音目标/听众数量不为 0。
  • 玩家没有运行 /music leave。
  • 玩家没有被 /music exclude 排除。
  • 客户端 Simple Voice Chat 的 "Music" 滑块不在 0%。
  • 全局音量不是太低。

YouTube 提示登录或机器人检查

在 config/music.json 中启用 OAuth，重启，然后运行：

/music play <youtube-url>

完成服务器日志中显示的设备登录。之后，youtubeOAuthRefreshToken 应该会被保存。

队列名称显示为加载中或未知

元数据是异步加载的。等待几秒钟并运行：

/music queue list

如果元数据仍显示未知，说明 Lavaplayer 无法解析该 URL 的元数据。模组仍会在轮到该曲目时尝试播放该 URL。

执行 target all 后玩家听不到音乐

检查该玩家是否已退出：

/music target show

该玩家可以通过以下命令重新加入：

/music join

个人退出优先于定向过滤器。

备注

  • 此模组不会将歌曲下载到磁盘。
  • 如果 YouTube 阻止客户端或更改播放器行为，YouTube 播放仍可能失败。
  • YouTube 主题频道作者名称会被清理以用于显示；例如 Artist - Topic 变为 Artist。
  • OAuth 提高了 YouTube 的可靠性，但应使用备用 YouTube 账号。
  • 未实现服务端逐玩家音量；请使用 Simple Voice Chat 客户端的 "Music" 滑块设置个人音量。