Spotify Player

# Spogo - Spotify CLI for Linux Servers

使用基于 Cookie 的身份验证从无头 Linux 服务器控制 Spotify。无需 OAuth 回调 —— 非常适合远程服务器。

## 为什么需要此技能？

ClawHub 上由 `steipete` 开发的原始 `spotify-player` 技能假设拥有本地浏览器访问权限以便导入 Cookie（`spogo auth import --browser chrome`）。在没有本地浏览器的无头 Linux 服务器上，这是行不通的。

此技能记录了基于 Cookie 的变通方法 —— 复制 2 个浏览器 Cookie 即可完成。无需 OAuth，无需 localhost。

## 要求 - Spotify Premium 账户 - 已安装 Go 1.21+ - 用户的 Spotify 浏览器 Cookie

## 安装 (Linux)

### 1. 安装 Go（如果尚未安装）

```bash # Ubuntu/Debian sudo apt update && sudo apt install -y golang-go

# Or download latest from https://go.dev/dl/ wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz sudo tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz echo 'export PATH=$PATH:/usr/local/go/bin:~/go/bin' >> ~/.bashrc source ~/.bashrc ```

### 2. 安装 spogo

```bash go install github.com/steipete/spogo/cmd/spogo@latest ```

这将安装到 `~/go/bin/spogo`。如有需要，请将其添加到 PATH： ```bash sudo ln -s ~/go/bin/spogo /usr/local/bin/spogo ```

### 3. 验证

```bash spogo --version # spogo v0.2.0 ```

## 设置（Cookie 认证）

由于 OAuth 需要 localhost 回调（这在远程服务器上是不可能的），因此我们改用 Cookie 认证。

### 1. 从浏览器获取 Cookie

让用户打开 DevTools（开发者工具） → Application（应用程序） → Cookies → `open.spotify.com` 并复制： - `sp_dc` - 主要认证令牌（长字符串，必需） - `sp_t` - 设备 ID（UUID 格式，播放时必需）

### 2. 创建配置

创建 `~/.config/spogo/config.toml`： ```toml default_profile = "default"

[profile.default] cookie_path = "/root/.config/spogo/cookies/default.json" market = "IL" language = "en" ```

### 3. 创建 Cookie 文件

创建 `~/.config/spogo/cookies/default.json`： ```json [ { "name": "sp_dc", "value": "USER_SP_DC_VALUE", "domain": ".spotify.com", "path": "/", "expires": "2027-01-01T00:00:00Z", "secure": true, "http_only": true }, { "name": "sp_t", "value": "USER_SP_T_VALUE", "domain": ".spotify.com", "path": "/", "expires": "2027-01-01T00:00:00Z", "secure": false, "http_only": false } ] ```

### 4. 验证

```bash spogo auth status # → "Cookies: 2 (file)" ```

## 命令

```bash # Search spogo search track "query" spogo search track "query" --json --limit 5

# Play spogo play spotify:track:ID spogo play # Resume spogo pause spogo next / spogo prev

# Devices spogo device list --json spogo device set "DEVICE_ID"

# Status spogo status spogo status --json ```

## "missing device id" 错误 - 浏览器回退

spogo 需要一个活跃的 Spotify 会话。如果没有设备最近播放过：

1. **在浏览器中打开曲目**： ``` browser open https://open.spotify.com/track/TRACK_ID profile=openclaw ```

2. **通过浏览器自动化点击播放**

3. **转移到目标设备**： ```bash spogo device set "DEVICE_ID" ```

浏览器配置文件将保持登录状态（Cookie 持久化）。播放结束后，会话将保持活跃数小时。

## 速率限制

- Connect API（默认）：无速率限制 ✓ - Web API (`--engine web`)：受速率限制（429 错误） - 当受到速率限制时访问媒体库 → 使用浏览器自动化

## 故障排除

### "missing device id"

没有活跃的 Spotify 会话。使用浏览器回退（见上文）先开始播放。

### "401 Unauthorized"

Cookie 已过期。从浏览器获取新的 Cookie 并更新 JSON 文件。

### 命令有效但没有声音

检查 `spogo device list` —— 播放可能发生在错误的设备上。使用 `spogo device set "DEVICE_ID"` 进行切换。

## 安全与隐私

- **Cookie 处理**：`sp_dc` 和 `sp_t` 本地存储在 `~/.config/spogo/cookies/` 中 —— 请将它们视为机密信息，切勿记录或分享 - **网络访问**：spogo 仅与 Spotify API（`api.spotify.com`、`open.spotify.com`）通信 - **浏览器回退**：可选 —— 仅当不存在活跃的 Spotify 设备时使用。它使用 Agent 的浏览器配置文件打开 `open.spotify.com` 并点击播放。这不会提取额外的 Cookie 或访问其他浏览器状态 - **安装来源**：从官方 [steipete/spogo](https://github.com/steipete/spogo) GitHub 仓库进行 `go install` —— 开源，可审计

## 注意事项

- **Cookie 有效期**：约 1 年，但如果用户注销或更改密码，可能会失效 - **需要 Premium**：免费帐户无法使用 Connect API - **市场设置**：在配置中更改 `market` 以获得正确的区域可用性（IL, US 等）