跳到正文

Spotify Control

作者:Emil_Deu

Minecraft 的 Spotify 悬浮窗:搜索、浏览和管理音乐库,控制播放,还能举办一起听活动,让整个服务器通过 Simple Voice Chat 听到相同的音乐。

收藏

截图

介绍

介绍由机器翻译自 Modrinth 原页面,仅供参考。

SpotifyControl

一款 Fabric 模组,可将 Spotify 客户端接入 Minecraft。按 Ctrl + M 打开完整覆盖界面,采用
Spotify 配色主题;登录你自己的 Spotify 账号,浏览曲库、搜索、管理
播放列表,并在游戏中控制播放。派对聆听功能可让服务器上的其他玩家一起听同一首音乐:他们可以使用自己的 Spotify 账号,也可以通过 Simple Voice Chat 收听实时音频流。

本模组通过 Spotify 官方 Web API 进行交互。在同步模式下,它不会解码、下载或重新托管 Spotify 音频;广播模式则会捕获操作系统当前正在播放的声音:Windows 上可直接从扬声器捕获,无需安装任何东西;其他系统则需要你自行选择回环设备。

世界歌词来自免费的开放歌词数据库 LRCLIB,因为
Spotify Web API 不提供歌词。发送到该数据库的只有曲目名称和第一位艺人;在设置中关闭“世界歌词”后,则不会发送任何内容。

The now playing HUD and the player bar in game

可在屏幕任意角落显示正在播放信息,也能在不离开世界的情况下使用完整播放器栏

Synced lyrics floating word by word as 3D text in the world

实时歌词:歌曲唱到哪里,歌词中的每个词就会立刻出现在世界里

功能

  • 采用 Spotify 配色主题(底色 #121212,强调色 #1DB954)的全屏覆盖界面,包含侧边栏、搜索、曲库、播放列表详情页和底部播放器栏
  • 使用 OAuth 2.0 和 PKCE 登录,无需客户端密钥;令牌保存在本地并自动刷新
  • 播放控制:播放、暂停、下一首、上一首、跳转进度、音量、随机播放、循环、队列和切换设备
  • 如果没有正在运行的播放设备,会在后台最小化启动 Spotify 桌面应用,无需你手动打开
  • 曲库:你的播放列表、已点赞的歌曲、最近播放、热门曲目,以及每个播放列表中的曲目列表
  • 队列视图将当前曲目置顶,每 5 秒刷新一次;点击任意条目即可跳转播放
  • 搜索曲目、播放列表、专辑和艺人,并按结果类型切换标签页
  • 播放列表管理:创建播放列表、添加和移除曲目、点赞和取消点赞
  • 在游戏中显示专辑封面,按需下载并缓存为 GPU 纹理;图片采用圆角
  • 矢量图标和面板圆角会以屏幕原生分辨率进行抗锯齿栅格化,因此无论 GUI 缩放比例是多少,画面都不会显得粗糙
  • 可在屏幕任意角落显示正在播放信息,包括曲目、艺人和进度条
  • 世界歌词:正在播放歌曲的同步歌词会以 3D 文字逐词出现在你面前,每个词各占一格;文字只转向你一次,之后便留在原地。歌词不会相互重叠,会为地形让路;在森林和洞穴中会靠近你并缩小,疾跑时则会移到更远处。每行歌词结束、超过设定时长或达到设定数量后,文字会淡出
  • 曲目列表中每首歌的标题后会显示歌词标记,标明该歌曲是否有同步歌词;队列按钮旁的歌词按钮可开关世界歌词
  • 派对聆听支持两种模式:SYNC 会让每位成员自己的 Spotify 播放器播放同一首歌并保持进度一致;BROADCAST 则通过 Simple Voice Chat 将主机电脑的音频流传给派对成员
  • 支持定位广播:可设置方块范围,让附近所有玩家听到主机音频;也可使用固定频道,让派对成员无论身处世界何处都能收听
  • Windows 上的 BROADCAST 会直接通过音频系统捕获扬声器声音,无需启用“立体声混音”,也不用安装虚拟音频线
  • 覆盖界面使用独立的 GUI 缩放比例(默认 2),因此即使游戏缩放比例设为 3 或 4,界面也不会过大
  • 集成 Mod Menu:点击“配置”按钮即可打开覆盖界面设置,也可在标题界面使用
  • 支持七种语言:英语、德语、俄语、西班牙语、法语、日语和中文

Library, search, listening party and settings

曲库、搜索、派对聆听和设置,全都能在游戏内使用

安装设置

本模组需要你自己的 Spotify 应用,因为 Spotify 不允许在公开发布的模组中附带客户端 ID。

  1. 打开 developer.spotify.com/dashboard 并创建一个应用。
  2. 将 http://127.0.0.1:8888/callback 添加为重定向 URI。如果你在配置中更改了 callbackPort,则应使用对应的端口。
  3. 从应用页面复制客户端 ID。
  4. 在 Minecraft 中按 Ctrl + M,打开侧边栏中的“设置”,然后粘贴客户端 ID。
  5. 点击“连接 Spotify”。浏览器标签页会打开;授权所需权限后,标签页会自动关闭。

播放控制需要 Spotify Premium。免费账号仍可在覆盖界面中查看曲库、
搜索结果和当前正在播放的内容,但 Spotify API 会对播放、暂停、跳转进度和音量控制请求返回 HTTP 403 错误。

Spotify 还需要一个播放设备,因为 Web API 控制的是 Spotify 播放器,本身并不是播放器。
不过你无需自行管理设备:按下播放键时,如果没有正在运行的播放器,本模组会在后台最小化启动 Spotify 桌面应用,等待它显示为可用设备后,再将播放切换到该设备。

其他设备也都能使用,例如网页播放器、手机或音箱;可在播放器栏的设备菜单中选择。

派对聆听

SYNC 模式为默认模式。主机会将当前曲目的 URI 和播放进度发送给服务器;服务器再转发给派对中的每位成员,由各成员的客户端调用 Spotify API,在各自的账号上从相同进度播放同一首歌。每位成员都需要自己的 Premium 账号。音质与 Spotify 平常提供的相同,音频不会经过 Minecraft 服务器传输。

BROADCAST 模式适合没有 Spotify 的其他玩家。客户端会从主机的音频源读取 48 kHz 立体声音频,每帧 20 毫秒,将其混合为单声道,再使用 Simple Voice Chat 提供的 Opus 编码器进行编码,并将音频帧发送到服务器。服务器会将这些音频帧推送到 Simple Voice Chat 音频频道。

Windows 上无需安装或启用任何东西。本模组会直接从音频系统捕获即将输出到扬声器的混音,因此音频源默认设为“系统声音(自动)”;即使电脑从未进行过相关设置,也能直接使用。需要注意的是,捕获的是整个混音:Minecraft 游戏音效、通知提示音和其他应用的语音聊天都会随音乐一起广播。开始串流前,请先静音所有不想传出去的声音。

如果只想广播 Spotify 音乐,仍可手动选择设备。安装 VB-Audio Virtual Cable 等虚拟音频线,在 Windows 应用音量设置中将 Spotify 单独设为输出到该设备,然后在本模组中选择它的输入端;这样只有 Spotify 会经过音频线,其他声音不会传入派对。“声音控制面板”中的“立体声混音”也是一种手动方案,但和自动捕获一样,它会广播整个桌面的声音。

Linux 和 macOS 不支持自动捕获;在这些系统上使用广播模式仍需要回环设备,也就是能传送电脑正在播放的声音、而不是麦克风所听到声音的输入源。Linux 上可直接使用 PipeWire 或 PulseAudio 的“监视器”音源;macOS 上则需要安装 BlackHole 等回环驱动。麦克风不能替代回环设备:如果选择麦克风,派对听到的会是你的房间声音,而不是音乐;在语音聊天中静音也无济于事,因为音频是从音频系统的另一条线路直接捕获的。本模组会优先列出回环设备,并标明哪些设备看起来是输出设备、哪些像是麦克风;如果串流时使用了麦克风,也会发出警告,而不会误称正在广播桌面音频。

配置

服务端,config/spotifycontrol/server.json:

{
  "enabled": true,
  "language": "en",
  "allowListeningParties": true,
  "allowAudioBroadcast": true,
  "maxPartySize": 20,
  "broadcastRangeBlocks": 0,
  "requireSameDimension": true,
  "maxAudioKilobitsPerSecond": 96,
  "announcePartyInChat": true,
  "broadcastNowPlayingToParty": true,
  "partyIdleTimeoutSeconds": 120
}

| 键 | 含义 |
|—|—|
| enabled | 总开关,与 /spotifycontrol off 相同 |
| language | 服务器聊天消息使用的语言文件 |
| allowListeningParties | 是否允许玩家创建听歌派对 |
| allowAudioBroadcast | 是否允许使用 BROADCAST 模式;缺少 Simple Voice Chat 时此项无效 |
| maxPartySize | 房主及成员 |
| broadcastRangeBlocks | 设为 0 时,仅通过固定频道向派对成员发送音频;设为大于 0 的值时,会在房主所在位置开启指定半径的定位频道,让附近玩家也能听到 |
| requireSameDimension | 跳过位于其他维度的派对成员(仅适用于固定频道) |
| maxAudioKilobitsPerSecond | 向客户端报告的广播预算 |
| announcePartyInChat | 是否向派对发送加入和离开提示 |
| broadcastNowPlayingToParty | 是否转发曲目信息;SYNC 模式必需 |
| partyIdleTimeoutSeconds | 广播派对无音频时,等待多久后关闭;设为 0 可禁用 |

客户端,config/spotifycontrol/client.json:

{
  "language": "en",
  "spotifyClientId": "",
  "callbackPort": 8888,
  "requireModifierKey": true,
  "modifierKey": "CONTROL",
  "playbackPollMillis": 2000,
  "showNowPlayingHud": true,
  "hudCorner": "TOP_RIGHT",
  "hudGuiScale": 2,
  "appMargin": 10,
  "startView": "HOME",
  "smoothGraphics": true,
  "hudMargin": 4,
  "overlayGuiScale": 2,
  "pauseGameOnOverlay": false,
  "blurBackground": true,
  "overlayVolumeStep": 5,
  "autoLaunchSpotify": true,
  "minimizeSpotifyWindow": true,
  "preferredDeviceName": "",
  "captureDeviceName": "",
  "captureVolumePercent": 100,
  "muteMinecraftMusicWhileListening": true,
  "showAlbumArt": true,
  "albumArtCacheSize": 128,
  "backgroundDim": 50,
  "accentColor": 0,
  "overlayKeyCode": -1,
  "scrollingTitles": true,
  "dimUnavailableTracks": true,
  "showTrackTime": true,
  "showShuffleRepeat": true,
  "showVolumeSlider": true,
  "showQueueButton": true,
  "showDeviceButton": true,
  "showLikeButton": true,
  "hudShowAlbumArt": true,
  "hudShowProgress": true,
  "hudShowArtist": true,
  "hudOnlyWhilePlaying": false,
  "pauseOnLeave": true,
  "closeSpotifyOnQuit": true,
  "worldLyrics": true,
  "lyricsWordsPerPiece": 1,
  "lyricsMinDistance": 10,
  "lyricsMaxDistance": 20,
  "lyricsSprintExtraDistance": 15,
  "lyricsTilt": true,
  "lyricsTextSize": 75,
  "showLyricsButton": true,
  "lyricsKept": 40,
  "lyricsKeepMode": "LINE",
  "lyricsSeconds": 5
}

| 键 | 含义 |

|—|—|

| spotifyClientId | 你自己的 Spotify 应用客户端 ID |

| callbackPort | 本地 OAuth 回调服务器的端口,必须与重定向 URI 相符 |
| requireModifierKey / modifierKey | 使用按键绑定时必须同时按住的修饰键,可选 CONTROL、SHIFT、ALT、NONE |

| playbackPollMillis | 应用或叠加界面显示时,客户端向 Spotify 查询播放状态的频率,范围为 1000 到 5000。暂停时查询间隔会延长至 8 秒;模组界面都不可见时则延长至 30 秒,以确保远低于 Spotify 的速率限制 |

| hudCorner | TOP_LEFT、TOP_RIGHT、BOTTOM_LEFT 或 BOTTOM_RIGHT |

| hudMargin | 小型叠加界面与所在角落的距离,横纵方向相同 |

| appMargin | 应用窗口与屏幕边缘的距离,横纵方向相同 |

| startView | 应用打开时显示的页面:HOME、SEARCH、LIBRARY 或 LIKED |

| smoothGraphics | 关闭后,仍会以较低分辨率绘制相同的矢量图形,但边缘会变得生硬;每个方块占 2 个屏幕像素 |

| overlayGuiScale | 叠加界面的 GUI 缩放比例,独立于游戏设置:设为 2 时,在 1080p 和 1440p 分辨率下保持紧凑;设为 0 时跟随游戏缩放比例,且不会大于游戏缩放比例 |

| pauseGameOnOverlay | 打开叠加界面时暂停单人游戏 |

| autoLaunchSpotify | 按下播放键且没有设备正在运行时,启动 Spotify 桌面应用,并将播放切换到该应用 |

| minimizeSpotifyWindow | 以最小化状态启动应用,避免遮挡游戏 |

| preferredDeviceName | 有多个设备可用时优先使用的设备。留空时优先选择电脑,其次选择当前正在播放的设备;只有在此处指定名称时才会使用扬声器、电视或扬声器组 |

| captureDeviceName | BROADCAST 模式的音频来源,可在叠加界面的设置中选择;在 Windows 上留空则自动捕获扬声器音频 |

| captureVolumePercent | Opus 编码前应用的增益,范围为 0 到 200 |

| muteMinecraftMusicWhileListening | Spotify 播放时停止原版音乐管理器 |

| albumArtCacheSize | 以 GPU 纹理形式缓存的专辑封面数量 |

| backgroundDim | 叠加界面后方游戏画面的变暗程度,范围为 0 到 100 |

| accentColor | 强调色调色板:0 绿色,1 蓝色,2 紫色,3 橙色,4 粉色,5 红色 |

| hudGuiScale | HUD 的 GUI 缩放比例,与 overlayGuiScale 使用相同的档位 |

| overlayKeyCode | 打开叠加界面的按键 GLFW 代码;设为 -1 时沿用游戏内的按键绑定 |

| scrollingTitles | 标题超出显示范围时来回滚动,而不是直接截断 |

| dimUnavailableTracks | 将 Spotify 标记为所在国家/地区无法播放的曲目置灰并禁止播放 |

| showTrackTime, showShuffleRepeat, showVolumeSlider, showQueueButton, showDeviceButton, showLikeButton | 播放器栏中的各个独立部分,均可在叠加界面的设置中单独开关 |

| hudShowAlbumArt, hudShowProgress, hudShowArtist, hudOnlyWhilePlaying | 小型“正在播放”叠加界面的组成部分及其行为 |

| pauseOnLeave | 离开地图或服务器时暂停 Spotify |

| closeSpotifyOnQuit | 关闭 Minecraft 时退出 Spotify 桌面应用 |

| worldLyrics | 在游戏世界中以 3D 文字显示当前播放歌曲的歌词。歌词通过 LRCLIB 查找 |

| lyricsWordsPerPiece | 每个方块中显示的单词数 |

| lyricsMinDistance / lyricsMaxDistance | 你前方的显示范围,单位为方块;范围内会出现新的歌词 |

| lyricsSprintExtraDistance | 冲刺时(无论步行还是飞行)在两个距离上增加的数值 |

| lyricsTilt | 让每个单词随机轻微倾斜,方向为横向或朝向你 |

| lyricsTextSize | 文字大小,单位为百分比 |

| showLyricsButton | 在队列按钮旁显示歌词按钮 |
| lyricsKeepMode | 文字何时淡出:LINE 表示该行结束,COUNT 表示超过 lyricsKept 个词,SECONDS 表示经过 lyricsSeconds 秒 |

| lyricsKept / lyricsSeconds | 上述模式使用的字数和显示时长 |

令牌保存在 config/spotifycontrol/tokens.json。删除该文件,或在浮层中使用 Log out
设置来断开账号连接。

The same view in six accent colours

六种强调色方案,可在设置中切换,无需重启

按键绑定

所有按键都可以在原版控制设置的 SpotifyControl 分类下重新绑定。启用
requireModifierKey后,还必须按住设置的辅助按键。

| 按键绑定 | 默认按键 | 操作 |
|—|—|—|
| 打开 Spotify 浮层 | Ctrl + M | 打开浮层 |
| 播放 / 暂停 | Ctrl + K | 切换播放状态 |
| 下一首 | Ctrl + . | 切换到下一首 |
| 上一首 | Ctrl + , | 切换到上一首 |
| 提高音量 | Ctrl + Page Up | 提高音量 overlayVolumeStep |
| 降低音量 | Ctrl + Page Down | 降低音量 overlayVolumeStep |
| 切换正在播放 HUD | Ctrl + H | 显示或隐藏 HUD |

权限

| 权限 | 说明 | 默认 |
|—|—|—|
| 权限等级 2(OP) | /spotifycontrol on、off、reload | OP |
| 权限等级 0 | /spotifycontrol status及所有 party子命令 | 所有人 |

权限采用原版的 0 至 4 级权限等级。若要按权限节点进行控制,请使用 Fabric Permissions
API 或 LuckPerms Fabric。

命令

| 命令 | 说明 |
|—|—|
| /spotifycontrol on | 全局启用模组 |
| /spotifycontrol off | 全局禁用模组并关闭所有派对 |
| /spotifycontrol status | 显示当前状态、派对数量、监听者数量和语音聊天状态 |
| /spotifycontrol reload | 重新加载服务端配置并推送给所有客户端 |
| /spotifycontrol party start [sync\|broadcast] | 开启一个聆听派对;未指定模式时使用 SYNC |
| /spotifycontrol party stop | 关闭你的聆听派对 |
| /spotifycontrol party join <host> | 加入其他玩家的聆听派对 |
| /spotifycontrol party leave | 离开当前所在的派对 |
| /spotifycontrol party invite <player> | 向玩家发送邀请信息 |

别名:/sc,完整命令:/spotifycontrol

支持的版本

一个 jar 文件兼容 1.21 至 1.21.11。Minecraft 在这一版本系列中六次更改了客户端 API,因此
本模组为每一代 API 都提供了一个实现,并会在启动时选择正确的实现。

| Minecraft 版本 | 实现 | 该代版本的变更 |
|—|—|—|
| 1.21、1.21.1 | platform.impl.a | 基准版本 |
| 1.21.2 至 1.21.4 | platform.impl.b | GuiGraphics.blit需要一个 RenderType工厂 |
| 1.21.5 | platform.impl.c | DynamicTexture需要一个标签提供器 |
| 1.21.6 至 1.21.8 | platform.impl.d | 渲染管线;Matrix3x2fStack取代 PoseStack |
| 1.21.9、1.21.10 | platform.impl.e | 输入事件改为记录类型,按键绑定需要一个 KeyMapping.Category |
| 1.21.11 | platform.impl.f | ResourceLocation更名为 Identifier,Util移至其他位置,并加入权限集合 |

每个实现仅包含两个类。其余约 60 个类都是共享的,在每一代版本中编译出的代码都
完全一致。最终发布为一个文件:SpotifyControl_1.0_1.21.x_BETA.jar。

要求

| | |
|—|—|
| Minecraft | 1.21 至 1.21.11,一个通用 jar |
| Fabric Loader | 0.16+ |
| Fabric API | 适用于你的 Minecraft 版本的最新版本 |
| Java | 21+ |
| Simple Voice Chat | 2.5+,可选,仅用于 BROADCAST 模式 |
| Mod Menu | 可选,可添加“配置”按钮 |
| Spotify | 播放控制需要 Premium,浏览内容可使用任意账户 |

将 SpotifyControl_1.0_1.21.x_BETA.jar 与 Fabric API 一起放入 mods/。它支持从 1.21 到 1.21.11 的所有
Minecraft 版本。举办多人聆听派对时,服务器上也必须安装此模组;BROADCAST 模式则需要两端都安装 Simple Voice Chat。Forge、NeoForge 和 Quilt 均不受
支持。

工作原理

身份验证采用带 PKCE 的 OAuth 2.0 授权码流程。客户端会生成一个 verifier,
通过 Util.getPlatform().openUri 打开 Spotify 授权页面,并运行一个绑定到 127.0.0.1 的
com.sun.net.httpserver.HttpServer,用于接收单次回调请求。访问令牌会在 SpotifyApi.raw 中按需刷新;该方法还会在 HTTP 401 时重试一次,并在 HTTP 429 时遵循
Retry-After 标头。所有 API 通信都在同一个守护线程上运行,因此渲染线程不会
因网络调用而阻塞。

渲染过程不使用纹理图集,也不附带任何图标 PNG。每个图标都是有符号距离场,
由 IconShapes 使用圆形、胶囊形、方框、圆弧和三角形组合而成。RasterCache 会根据图标在屏幕上实际占用的像素尺寸(GUI 尺寸乘以 GUI 缩放比例)计算
距离场,将距离转换为抗锯齿覆盖率,再将结果编码为内存中的 PNG,并传递给
NativeImage.read。在整个 1.21 系列版本中,这是唯一保持稳定的图像入口。
随后,纹理会按一比一的像素映射绘制,因此不会重采样,也不会模糊。
圆角面板也采用相同方法处理四个角,其余部分则使用纯色填充;专辑封面的圆角则通过在上方绘制反转的角落遮罩实现。专辑封面本身使用 NativeImage.read 解码,并注册为 DynamicTexture。Minecraft 在 1.21 系列中六次更改了客户端 API 的这一部分,因此
所有发生变化的调用都封装在 PlatformApi 接口之后。六种实现位于
src/platform-a 到 src/platform-f,分别针对各自的 Minecraft 版本编译;通用 jar 则将六种实现全部打包在 xx.xxxx.spotifycontrol.platform.impl 下。首次使用时,Platform
会从 Fabric Loader 读取 Minecraft 版本,并按名称加载匹配的实现。
其余五种实现不会被加载类,因此不会验证其中不兼容的字节码。

这种拆分之所以可行,是因为其余代码确实与版本无关。在共享类调用的 69 个不同
Minecraft 方法中,有 66 个在全部十二个版本中保持相同的中间名称和描述符。其余三个方法——GuiGraphics.drawString(返回类型发生变化)、
ServerPlayer.sendSystemMessage(名称变更)和 ServerPlayer.level(返回类型发生变化)——也通过平台层调用。将这些方法封装后,共享类在
每一代版本中编译出的结果都完全一致;构建过程会通过对重映射后的 jar 进行差异比较来验证这一点。

派对状态通过使用 PayloadTypeRegistry 注册的三个自定义数据包传输。主持人的
客户端会在曲目切换时或每五秒发送一次 now_playing,服务器再将其转发给
派对成员。在 SYNC 模式下,如果偏差超过 2.5 秒,成员端会调用 Spotify API,使曲目和播放进度保持同步。
在 BROADCAST 模式下,客户端使用 Simple Voice Chat 客户端 API 中的编码器,将 960 个采样的 Opus 音频帧编码后作为
数据包发送。服务器audio_frame
会将每一帧直接转发到每位听众对应的
,或者在 broadcastRangeBlocks 大于 0 时,转发到主持人位置处的一个StaticAudioChannel。
LocationalAudioChannelSimple Voice
Chat 的类仅在通过 FabricLoader.isModLoaded("voicechat") 检查后才会被调用,因此即使未安装它,模组也能
正常运行。

Spotify 是 Spotify AB 的商标,该公司与本项目无关联。

常见问题

Spotify Control 支持哪些 Minecraft 版本?

Spotify Control 支持 Minecraft Java 版 1.21–1.21.11,共 12 个版本,可用的加载器:Fabric。下载时注意选择和你游戏版本一致的文件。

Spotify Control 怎么安装?

先用 PCL2 或 HMCL 启动器安装对应版本的 Fabric,再把下载的 .jar 文件放进游戏目录的 mods 文件夹,重新启动游戏即可。开启了版本隔离的,mods 文件夹在 versions/版本名 下面。运行环境:仅客户端。

评论

登录后评论和评分

Emil_Deu 的其他作品

查看全部 →