告别线缆：cli3/cli实现Spotify手机远程控制的完整方案
项目地址: https://gitcode.com/gh_mirrors/cli3/cli 你是否曾在做饭时想切歌却找不到手机？在电脑前工作时想调整音量还要拿起设备？本文将带你通过cli3/cli工具实现Spotify客户端与手机的无缝同步，打造真正的跨设备音乐控制体验。读完本文后，你将能够：
- 理解cli3/cli的远程控制原理
- 配置WebSocket本地服务实现设备通信
- 使用手机控制电脑端Spotify播放状态
- 解决常见的同步延迟与连接问题
方案原理与架构
cli3/cli（项目路径）作为Spotify客户端的定制工具，通过WebSocket（Web套接字）技术实现设备间通信。其核心原理是在电脑端建立本地服务器，手机端通过专用应用或网页界面发送控制指令，实现播放状态同步与远程操作。
核心技术组件
- WebSocket服务：Extensions/webnowplaying.js实现本地WebSocket服务器（默认端口8974），负责设备间实时通信
- 状态同步模块：通过Spicetify.Player API监听播放状态变化，如webnowplaying.js#L47-L49所示
- 远程配置解析：jsHelper/expFeatures.js提供远程配置管理，支持动态参数调整
数据传输流程
环境配置步骤
1. 安装cli3/cli工具
首先确保已安装cli3/cli工具，可通过项目提供的安装脚本快速部署：
# Linux/macOS系统
bash install.sh
# Windows系统
powershell -ExecutionPolicy Bypass -File install.ps1
安装完成后，验证安装状态：
spicetify -v
2. 启用WebNowPlaying扩展
WebNowPlaying扩展是实现远程控制的核心组件，位于Extensions/webnowplaying.js。启用该扩展：
# 复制扩展到Spicetify扩展目录
spicetify config extensions webnowplaying.js
spicetify apply
扩展启动后会自动创建WebSocket服务，默认监听本地8974端口。可在代码中修改端口配置：
// 修改[webnowplaying.js#L79](https://link.gitcode.com/i/8e0172fce7e3a9d9f6d41f68a27c16da#L79)
this._ws = new WebSocket("ws://localhost:8974"); // 可修改端口号
3. 配置手机控制端
目前有两种手机控制方案可供选择：
方案A：专用控制应用
推荐使用支持WebNowPlaying协议的应用，如：
- Android: "WebNowPlaying Controller"
- iOS: "Remote for Spotify"
配置步骤：
- 在同一局域网内确保手机与电脑连接
- 应用内输入电脑IP地址和端口（如
192.168.1.100:8974） - 点击连接，等待状态同步
方案B：自建网页控制器
可基于项目中的CustomApps模板创建简易网页控制器，核心代码示例：
<!DOCTYPE html>
<html>
<body>
<button onclick="sendCommand('PLAYPAUSE')">播放/暂停</button>
<button onclick="sendCommand('NEXT')">下一首</button>
<button onclick="sendCommand('PREVIOUS')">上一首</button>
<script>
const socket = new WebSocket('ws://电脑IP:8974');
function sendCommand(cmd) {
socket.send(cmd);
}
socket.onmessage = function(event) {
// 更新播放状态显示
document.getElementById('status').innerText = event.data;
};
</script>
</body>
</html>
功能实现详解
播放状态同步
webnowplaying.js通过监听Spicetify.Player事件实现状态同步：
// [webnowplaying.js#L47-L49](https://link.gitcode.com/i/8e0172fce7e3a9d9f6d41f68a27c16da#L47-L49)
Spicetify.Player.addEventListener("songchange", ({ data }) => this.updateSpicetifyInfo(data));
Spicetify.Player.addEventListener("onplaypause", ({ data }) => this.updateSpicetifyInfo(data));
当歌曲变化或播放状态改变时，updateSpicetifyInfo方法会更新元数据并通过WebSocket发送到手机端：
// [webnowplaying.js#L51-L75](https://link.gitcode.com/i/8e0172fce7e3a9d9f6d41f68a27c16da#L51-L75)
updateSpicetifyInfo(data) {
if (!data?.item?.metadata) return;
const meta = data.item.metadata;
this.spicetifyInfo.title = meta.title;
this.spicetifyInfo.album = meta.album_title;
this.spicetifyInfo.duration = timeInSecondsToString(Math.round(Number.parseInt(meta.duration) / 1000));
this.spicetifyInfo.state = !data.isPaused ? "PLAYING" : "PAUSED";
// 其他元数据处理...
}
核心控制功能
远程控制功能在webnowplaying.js中实现，主要包括：
播放/暂停控制
// [webnowplaying.js#L185](https://link.gitcode.com/i/8e0172fce7e3a9d9f6d41f68a27c16da#L185)
case "PLAYPAUSE": {
Spicetify.Player.togglePlay();
self.spicetifyInfo.state = self.spicetifyInfo.state === "PLAYING" ? "PAUSED" : "PLAYING";
break;
}
音量调节
// [webnowplaying.js#L201-L203](https://link.gitcode.com/i/8e0172fce7e3a9d9f6d41f68a27c16da#L201-L203)
case "SETVOLUME":
Spicetify.Player.setVolume(Number.parseInt(data) / 100);
break;
进度控制
// [webnowplaying.js#L197-L199](https://link.gitcode.com/i/8e0172fce7e3a9d9f6d41f68a27c16da#L197-L199)
const [, positionPercentage] = message.toUpperCase().split(":")[1].split("SETPROGRESS ");
Spicetify.Player.seek(Number.parseFloat(positionPercentage.replace(",", ".")));
高级配置与优化
1. 自定义端口与安全设置
默认WebSocket端口为8974，可修改为其他端口避免冲突：
// 修改[webnowplaying.js#L79](https://link.gitcode.com/i/8e0172fce7e3a9d9f6d41f68a27c16da#L79)
this._ws = new WebSocket("ws://localhost:8080"); // 修改为8080端口
对于公网访问需求，建议配合反向代理实现HTTPS加密，可使用Nginx配置示例：
server {
listen 443 ssl;
server_name yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location /ws {
proxy_pass http://localhost:8974;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
2. 优化连接稳定性
针对网络不稳定环境，webnowplaying.js实现了自动重连机制：
// [webnowplaying.js#L102-L113](https://link.gitcode.com/i/8e0172fce7e3a9d9f6d41f68a27c16da#L102-L113)
retry() {
if (this.isClosed) return;
this.close(true);
// 指数退避重连策略
this.reconnectTimeout = setTimeout(
() => {
this.init();
this.reconnectAttempts += 1;
},
Math.min(1000 * (this.reconnectAttempts <= 30 ? 1 : 2 ** (this.reconnectAttempts - 30)), 60000)
);
}
可根据网络环境调整重连参数，平衡实时性与资源消耗。
3. 实验性功能配置
jsHelper/expFeatures.js提供了远程配置解析功能，支持动态调整参数：
// [expFeatures.js#L140](https://link.gitcode.com/i/c4e1f74cb8141fd29b06e766f8932160#L140)
let remoteConfiguration = Spicetify.RemoteConfigResolver?.value.remoteConfiguration || Spicetify.Platform?.RemoteConfiguration;
通过修改远程配置，可以调整同步频率、数据缓存策略等高级参数。
常见问题解决
连接失败问题
-
端口占用：检查8974端口是否被占用
# Linux/macOS lsof -i :8974 # Windows netstat -ano | findstr :8974 -
防火墙设置：确保防火墙允许8974端口通信
# Ubuntu示例 sudo ufw allow 8974/tcp -
网络问题：验证手机与电脑在同一局域网，可尝试直接访问电脑IP:端口测试连接
状态同步延迟
如遇到播放状态不同步问题，可尝试：
-
调整更新频率：修改webnowplaying.js#L122中的更新间隔
this.updateInterval = setInterval(this.sendUpdate.bind(this), 300); // 减少到300ms -
优化网络环境：避免网络拥堵，或考虑使用5GHz WiFi减少干扰
-
清理缓存：
spicetify clear spicetify apply
功能不响应
当远程控制指令无响应时，检查：
- WebSocket服务状态：查看webnowplaying.js是否正常加载
- 扩展是否启用：
spicetify config extensions确认webnowplaying.js已列出 - 日志信息：查看Spotify控制台输出
spicetify enable-devtools # 在开发者工具Console标签查看错误信息
总结与扩展
通过cli3/cli的WebNowPlaying扩展，我们实现了Spotify客户端的手机远程控制功能，核心优势包括：
- 低延迟的状态同步（默认500ms更新间隔）
- 完整的控制功能集（播放/暂停/切歌/音量等）
- 跨平台兼容性（支持Windows/macOS/Linux）
- 可自定义扩展的开放架构
未来扩展方向
- 语音控制：集成语音识别API，实现语音指令控制
- 多设备同步：支持多手机同时控制，实现家庭共享控制
- 高级自动化：结合Extensions/autoSkipVideo.js等扩展实现场景化自动控制
- 移动端Web界面：基于CustomApps开发专用控制界面，无需额外安装应用
完整项目代码可通过以下地址获取：
https://gitcode.com/gh_mirrors/cli3/cli
若在使用过程中遇到问题，可参考项目README.md或提交Issue获取帮助。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
