spotify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spotify Control

Spotify 控制

Quick Start

快速开始

bash

undefined

bash

undefined

Play a song (handles search, device wake, everything)

播放歌曲（支持搜索、唤醒设备等操作）

./scripts/spotify-play.sh "l'amour toujours"

Play a playlist

播放播放列表

./scripts/spotify-play.sh "today's top hits" --type playlist

Pause/resume/skip

暂停/继续/跳过

./scripts/spotify-ctl.sh pause ./scripts/spotify-ctl.sh play ./scripts/spotify-ctl.sh next

undefined

./scripts/spotify-ctl.sh pause ./scripts/spotify-ctl.sh play ./scripts/spotify-ctl.sh next

undefined

Setup

设置

Spotify Developer Account (one-time)

Spotify 开发者账户（一次性操作）

Go to https://developer.spotify.com/dashboard
Log in with your Spotify account
Click Create App → name it anything → select "Web API"
Add redirect URI:
```
http://127.0.0.1:17823/callback
```
Copy your Client ID and Client Secret

Note: Requires Spotify Premium for playback control. Free accounts can only search.

访问 https://developer.spotify.com/dashboard
使用Spotify账户登录
点击Create App → 任意填写名称 → 选择“Web API”
添加重定向URI：
```
http://127.0.0.1:17823/callback
```
复制你的Client ID和Client Secret

注意：播放控制功能需要Spotify Premium会员。免费账户仅支持搜索功能。

First Run

首次运行

First run prompts for credentials interactively:

bash

./scripts/spotify-auth.sh login

Credentials loaded from: env vars →

~/.spotify/credentials.json

→ interactive prompt

首次运行会交互式提示输入凭证：

bash

./scripts/spotify-auth.sh login

凭证加载优先级：环境变量 →

~/.spotify/credentials.json

→ 交互式提示

Helper Scripts

辅助脚本

Script	Purpose
`spotify-play.sh <query>`	Search and play (handles device wake)
`spotify-ctl.sh <cmd>`	Playback control (pause, play, next, prev, volume, shuffle, repeat)
`spotify-auth.sh login`	OAuth setup
`spotify-auth.sh token`	Get valid token (auto-refreshes)

脚本	用途
`spotify-play.sh <query>`	搜索并播放（支持唤醒设备）
`spotify-ctl.sh <cmd>`	播放控制（暂停、播放、下一首、上一首、音量、随机播放、重复播放）
`spotify-auth.sh login`	OAuth 授权设置
`spotify-auth.sh token`	获取有效令牌（自动刷新）

spotify-play.sh

bash

undefined

bash

undefined

Play track (default)

播放单曲（默认类型）

./scripts/spotify-play.sh "bohemian rhapsody"

Play playlist

播放播放列表

./scripts/spotify-play.sh "workout" --type playlist

Play album

播放专辑

./scripts/spotify-play.sh "thriller" --type album

Play artist

播放歌手作品

./scripts/spotify-play.sh "queen" --type artist

Play on specific device

在指定设备播放

./scripts/spotify-play.sh "song" --device "Kitchen Echo"

Set default device

设置默认播放设备

./scripts/spotify-play.sh --set-device "Kitchen Echo"

undefined

./scripts/spotify-play.sh --set-device "Kitchen Echo"

undefined

spotify-ctl.sh

bash

./scripts/spotify-ctl.sh pause
./scripts/spotify-ctl.sh play
./scripts/spotify-ctl.sh next
./scripts/spotify-ctl.sh prev
./scripts/spotify-ctl.sh volume 50
./scripts/spotify-ctl.sh shuffle on|off
./scripts/spotify-ctl.sh repeat track|context|off
./scripts/spotify-ctl.sh devices        # list devices
./scripts/spotify-ctl.sh transfer Echo  # move playback to device
./scripts/spotify-ctl.sh now            # what's playing
./scripts/spotify-ctl.sh queue          # show queue
./scripts/spotify-ctl.sh add-queue <uri> # add to queue

bash

./scripts/spotify-ctl.sh pause
./scripts/spotify-ctl.sh play
./scripts/spotify-ctl.sh next
./scripts/spotify-ctl.sh prev
./scripts/spotify-ctl.sh volume 50
./scripts/spotify-ctl.sh shuffle on|off
./scripts/spotify-ctl.sh repeat track|context|off
./scripts/spotify-ctl.sh devices        # 列出所有设备
./scripts/spotify-ctl.sh transfer Echo  # 转移播放至指定设备
./scripts/spotify-ctl.sh now            # 查看当前播放内容
./scripts/spotify-ctl.sh queue          # 查看播放队列
./scripts/spotify-ctl.sh add-queue <uri> # 添加内容至队列

Direct API Access

直接调用API

For advanced use, get token and call API directly:

bash

TOKEN=$(./scripts/spotify-auth.sh token)

进阶使用场景：获取令牌后直接调用API：

bash

TOKEN=$(./scripts/spotify-auth.sh token)

Search

搜索

curl -s "https://api.spotify.com/v1/search?q=despacito&type=track&limit=5"
-H "Authorization: Bearer $TOKEN" | jq '.tracks.items[] | {name, uri}'

Play URI

播放指定URI内容

curl -s -X PUT "https://api.spotify.com/v1/me/player/play"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"uris": ["spotify:track:xxx"]}'

undefined

curl -s -X PUT "https://api.spotify.com/v1/me/player/play"
-H "Authorization: Bearer $TOKEN"
-H "Content-Type: application/json"
-d '{"uris": ["spotify:track:xxx"]}'

undefined

Common Patterns

常用操作示例

Search and play first result

搜索并播放首个结果

bash

./scripts/spotify-play.sh "song name"

bash

./scripts/spotify-play.sh "song name"

Play on specific device

在指定设备播放

bash

./scripts/spotify-play.sh "song" --device "Echo"

bash

./scripts/spotify-play.sh "song" --device "Echo"

Control playback

控制播放状态

bash

./scripts/spotify-ctl.sh pause
./scripts/spotify-ctl.sh volume 30
./scripts/spotify-ctl.sh shuffle on

bash

./scripts/spotify-ctl.sh pause
./scripts/spotify-ctl.sh volume 30
./scripts/spotify-ctl.sh shuffle on

Error Handling

错误处理

Error	Solution
No token	Run `./scripts/spotify-auth.sh login`
No active device	Script auto-wakes default device, or use `--device`
403 Premium required	Playback needs Spotify Premium
401 Unauthorized	Token auto-refreshes; if persists, re-run login

错误	解决方法
无有效令牌	运行 `./scripts/spotify-auth.sh login`
无活跃播放设备	脚本会自动唤醒默认设备，或使用 `--device` 指定设备
403 需Premium会员	播放控制功能需要Spotify Premium会员
401 未授权	令牌会自动刷新；若问题持续，重新运行登录命令

Files

文件

~/.config/spotify/          # or $XDG_CONFIG_HOME/spotify/
├── credentials.json        # Client ID/Secret (chmod 600)
├── tokens.json             # Access/refresh tokens (chmod 600)  
└── config.json             # Default device, preferences

~/.config/spotify/          # 或 $XDG_CONFIG_HOME/spotify/
├── credentials.json        # Client ID/密钥（需设置权限chmod 600）
├── tokens.json             # 访问/刷新令牌（需设置权限chmod 600）  
└── config.json             # 默认设备、偏好设置

API Limits (Feb 2026)

API 限制（2026年2月）

Search: max 10 results per request
Batch endpoints removed (fetch individually)
Normalize playlist URIs:
```
playlist_v2
```
→
```
playlist
```

搜索：单次请求最多返回10条结果
批量端点已移除（需单独获取）
播放列表URI标准化：
```
playlist_v2
```
→
```
playlist
```