misiektoja/spotify_monitor
GitHub: misiektoja/spotify_monitor
一款功能丰富的Spotify好友音乐活动实时监控工具，支持自动同步播放、跳过检测和多渠道通知。
Stars: 94 | Forks: 13
# spotify_monitor
-u "your_sp_dc_cookie_value" -r "your_spotify_app_client_id:your_spotify_app_client_secret"
```
或者如果你是[手动安装](#manual-installation)：
```
python3 spotify_monitor.py -u "your_sp_dc_cookie_value" -r "your_spotify_app_client_id:your_spotify_app_client_secret"
```
获取所有支持的命令行参数/标志列表：
```
spotify_monitor --help
```
## 配置
### 配置文件
大多数设置可以通过命令行参数进行配置。
如果你想持久存储配置，生成一个默认配置模板并将其保存到名为 `spotify_monitor.conf` 的文件中：
```
# 在 macOS、Linux 或 Windows Command Prompt (cmd.exe) 上
spotify_monitor --generate-config > spotify_monitor.conf
# 在 Windows PowerShell 上（推荐以避免编码问题）
spotify_monitor --generate-config spotify_monitor.conf
```
编辑 `spotify_monitor.conf` 文件并更改所需的任何配置选项（每个选项都提供了详细注释）。
**v2.7 新增：** 该工具现在使用混合认证方式。当使用 `cookie` 或 `client` token 源方法时，需要 OAuth app credentials（`SP_APP_CLIENT_ID`, `SP_APP_CLIENT_SECRET`）来检索曲目和用户信息。有关设置说明，请参阅 [Spotify OAuth App](#spotify-oauth-app) 部分。
**v2.6 新增：** 配置文件包含用于在控制台和邮件输出中启用/禁用音乐服务 URL（Apple Music、YouTube Music、Amazon Music、Deezer、Tidal）和歌词服务 URL（Genius、AZLyrics、Tekstowo.pl、Musixmatch、Lyrics.com）的选项。你还可以配置 crossfade 检测阈值以及非活动邮件中包含的最近歌曲数量。
### Spotify access token 来源
该工具使用**混合认证方式**。
对于好友活动监控，你需要配置 `cookie` 或 `client` token 源方法。
此外，你还需要配置 **OAuth app credentials**（`SP_APP_CLIENT_ID`, `SP_APP_CLIENT_SECRET`）以检索曲目和用户信息，如 [Spotify OAuth App](#spotify-oauth-app) 中所述。
Token 源方法可以通过 `TOKEN_SOURCE` 配置选项或 `--token-source` 标志进行配置。
**推荐：`cookie`**
使用 `sp_dc` cookie 从 Spotify web 端点检索 token。此方法易于设置，推荐大多数用户使用。
**替代方案：`client`**
使用从 Spotify desktop client 捕获的凭据和基于 Protobuf 的登录流程。设置起来比较复杂，适合那些希望获得具有最广泛访问权限的长期 token 的高级用户。
如果未指定方法，工具默认使用 `cookie` 方法。
**重要**：强烈建议为此工具使用单独的 Spotify 账户。它的核心功能（如获取好友活动）不依赖于官方 Spotify Web API，因为公共 API 不支持此功能。话虽如此，虽然我从未在自己的账户上遇到过任何问题，但我无法保证 Spotify 将来不会施加限制——特此告知。
#### Spotify sp_dc Cookie
这是获取 Spotify access token 的默认方法。
- 在网络浏览器中登录 [https://open.spotify.com/](https://open.spotify.com/)。
- 找到并复制 `sp_dc` cookie 的值。
- 使用你的网络浏览器的开发者控制台或 cgagnier 的 **Cookie-Editor** 轻松提取它：[https://cookie-editor.com/](https://cookie-editor.com/)
- 使用以下方法之一提供 `SP_DC_COOKIE` 密钥：
- 在运行时使用 `-u` / `--spotify-dc-cookie` 传递
- 将其设置为[环境变量](#storing-secrets)（例如 `export SP_DC_COOKIE=...`）
- 将其添加到 [.env file](#storing-secrets)（`SP_DC_COOKIE=...`）以供持久使用
- 后备方案：在代码或配置文件中硬编码
如果你的 `sp_dc` cookie 过期，工具将通过控制台和邮件通知你。在这种情况下，你需要获取新的 `sp_dc` cookie 值。
如果你将 `SP_DC_COOKIE` 存储在 dotenv 文件中，你可以更新其值并发送 `SIGHUP` 信号来重新加载包含新 `sp_dc` cookie 的文件，而无需重启工具。更多信息请参阅 [存储密钥](#storing-secrets) 和 [信号控制](#signal-controls-macoslinuxunix)。
#### Spotify Desktop Client
这是获取 Spotify access token 的替代方法，它模拟从真实的 Spotify 桌面应用程序登录，使用从真实会话中拦截的凭据。
- 运行你选择的拦截代理（如 [Proxyman](https://proxyman.com) - 试用版就足够了）
- 为 `spotify.com` 域启用 SSL 流量解密
- 在 Proxyman 中：点击 **Tools → SSL Proxying List → + button → Add Domain → 粘贴 `*.spotify.com` → Add**
- 启动 Spotify desktop client，然后切换到你的拦截代理（如 Proxyman）并查找发往 `https://login5.spotify.com/v3/login` 的 POST 请求
- 如果你没有看到此请求，请尝试以下步骤（一旦成功即停止）：
- 重启 Spotify desktop client
- 从 Spotify desktop client 注销并重新登录
- 在其设置中直接将 Spotify 指向拦截代理，即在 **Spotify → Settings → Proxy Settings** 中，设置：
- **proxy type**: `HTTP`
- **host**: `127.0.0.1`（你代理的 IP/FQDN，对于 Proxyman 使用你在顶部栏看到的 IP）
- **port**: `9090`（你代理的端口，对于 Proxyman 使用你在顶部栏看到的端口）
- 重启应用；由于 QUIC (HTTP/3) 需要原始 UDP 且无法通过 HTTP CONNECT 隧道传输，Spotify 将降级为仅 TCP 的 HTTP/2 或 1.1，拦截代理可以对其进行解密
- 使用你选择的防火墙在操作系统级别阻止 Spotify 的 UDP 端口 443 - 这可以防止 QUIC (HTTP/3)，强制通过 TCP 进行 TLS，从而允许拦截代理执行 MITM
- 尝试旧版本的 Spotify desktop client
- 将登录请求体（二进制 Protobuf payload）导出到文件（例如 ***login-request-body-file***）
- 在 Proxyman 中：**右键单击请求 → Export → Request Body → Save File**。
` 运行工具：
```
spotify_monitor --token-source client -w
```
如果成功，工具将自动提取必要的字段并开始监控。
你不必每次都使用 `-w` 标志，可以通过设置 `LOGIN_REQUEST_BODY_FILE` 配置选项来持久化 Protobuf 登录请求文件路径。
这同样适用于 `--token-source client` 标志 - 你可以通过将 `TOKEN_SOURCE` 配置选项设置为 `client` 来持久化它。
工具将使用拦截到的 refresh token 自动刷新 access token 和 client token。
如果你的 refresh token 过期，工具将通过控制台和邮件通知你。在这种情况下，你需要重新导出登录请求体。
如果你将登录请求体重新导出到相同的文件名，你可以发送 `SIGHUP` 信号来重新加载包含新 refresh token 的文件，而无需重启工具。更多信息请参阅 [信号控制](#signal-controls-macoslinuxunix)。
高级选项可用于进一步自定义 - 请参阅配置文件注释。但是，默认设置适用于大多数用户，通常不建议其他值。
### Spotify OAuth App
由于 Spotify 于 2025 年 12 月 22 日引入的限制，该工具现在除了 `cookie` 或 `client` token 源方法外，还需要此方法来检索曲目和用户信息。
此方法使用官方 Spotify Web API（Client Credentials OAuth 流程）。
获取凭据：
- 登录 [Spotify Developer dashboard](https://developer.spotify.com/dashboard)
- 创建一个新应用
- 对于 **Redirect URL**，使用：`http://127.0.0.1:1234`
- URL 必须与显示的完全一致，包括末尾没有 `/`
- 通过右键单击复制链接时，某些浏览器可能会在 URL 中添加额外的 `/`
- 选择 **Web API** 作为预期的 API
- 复制 **Client ID** 和 **Client Secret**
- 使用以下方法之一提供 `SP_APP_CLIENT_ID` 和 `SP_APP_CLIENT_SECRET` 密钥：
- 在运行时使用 `-r` / `--oauth-app-creds` 传递（使用 `SP_APP_CLIENT_ID:SP_APP_CLIENT_SECRET` 格式 - 注意冒号分隔符）
- 将其设置为[环境变量](#storing-secrets)（例如 `export SP_APP_CLIENT_ID=...; export SP_APP_CLIENT_SECRET=...`）
- 将其添加到 [.env file](#storing-secrets)（`SP_APP_CLIENT_ID=...` 和 `SP_APP_CLIENT_SECRET=...`）以供持久使用
- 后备方案：在代码或配置文件中硬编码
示例：
```
spotify_monitor -r "your_spotify_app_client_id:your_spotify_app_client_secret"
```
工具会自动刷新 OAuth app access token，因此它可以无限期保持有效。Token 缓存在由 `SP_APP_TOKENS_FILE` 配置选项指定的文件中（默认：`.spotify-monitor-oauth-app.json`）。
如果你将 `SP_APP_CLIENT_ID` 和 `SP_APP_CLIENT_SECRET` 存储在 dotenv 文件中，你可以更新它们的值并发送 `SIGHUP` 信号来重新加载包含新密钥值的文件，而无需重启工具。更多信息请参阅 [存储密钥](#storing-secrets) 和 [信号控制](#signal-controls-macoslinuxunix)。
### 关注被监控用户
要监控用户的活动，你必须从与 `sp_dc` cookie 或 `client` 凭据关联的 Spotify 账户关注他们。
此外，用户必须在其 Spotify 客户端设置中启用收听活动共享。否则，将无法看到任何活动数据。
### 如何获取好友的 User URI ID
最简单的方法是通过 Spotify 桌面或移动客户端：
- 转到你好友的个人资料
- 点击 **三个点** (•••) 或按 **Share** 按钮
- 复制个人资料链接
你会得到一个像这样的 URL：[https://open.spotify.com/user/spotify_user_uri_id?si=tracking_id](https://open.spotify.com/user/spotify_user_uri_id?si=tracking_id)
提取 `/user/` 和 `?si=` 之间的部分 - 在本例中为：`spotify_user_uri_id`
将其用作工具中的 user URI ID（`spotify_user_uri_id`）。
或者，你可以通过使用[列表模式](#listing-mode)列出你关注的所有账户的 user URI ID。
### SMTP 设置
如果你想使用邮件通知功能，请在 `spotify_monitor.conf` 文件中配置 SMTP 设置。
使用 `--send-test-email` 标志验证你的 SMTP 设置（工具将尝试发送测试邮件通知）：
```
spotify_monitor --send-test-email
```
### 存储密钥
建议将 `SP_DC_COOKIE`、`REFRESH_TOKEN`、`SP_APP_CLIENT_ID`、`SP_APP_CLIENT_SECRET` 或 `SMTP_PASSWORD` 等密钥存储为环境变量或 dotenv 文件。
在 **Linux/Unix/macOS/WSL** 系统上使用 `export` 设置所需的环境变量：
```
export SP_DC_COOKIE="your_sp_dc_cookie_value"
export REFRESH_TOKEN="your_spotify_app_refresh_token"
export SP_APP_CLIENT_ID="your_spotify_app_client_id"
export SP_APP_CLIENT_SECRET="your_spotify_app_client_secret"
export SMTP_PASSWORD="your_smtp_password"
```
在 **Windows Command Prompt** 上使用 `set` 代替 `export`，在 **Windows PowerShell** 上使用 `$env`。
或者将它们持久存储在 dotenv 文件中（推荐）：
```
SP_DC_COOKIE="your_sp_dc_cookie_value"
REFRESH_TOKEN="your_spotify_app_refresh_token"
SP_APP_CLIENT_ID="your_spotify_app_client_id"
SP_APP_CLIENT_SECRET="your_spotify_app_client_secret"
SMTP_PASSWORD="your_smtp_password"
```
默认情况下，工具将自动在当前目录及其上层目录中搜索名为 `.env` 的 dotenv 文件。
你可以使用 `DOTENV_FILE` 或 `--env-file` 标志指定自定义文件：
```
spotify_monitor --env-file /path/.env-spotify_monitor
```
你也可以使用 `DOTENV_FILE = "none"` 或 `--env-file none` 禁用 `.env` 自动搜索：
```
spotify_monitor --env-file none
```
作为后备方案，你也可以将密钥存储在配置文件或源代码中。
## 用法
### 监控模式
要监控特定用户活动，只需将 [Spotify user URI ID](#how-to-get-a-friends-user-uri-id) 作为命令行参数输入（下面示例中的 `spotify_user_uri_id`）：
```
spotify_monitor
```
如果你使用默认方法获取 Spotify access token（`cookie`）且尚未设置 `SP_DC_COOKIE` 密钥，可以使用 `-u` 标志：
```
spotify_monitor -u "your_sp_dc_cookie_value"
```
**注意：** 现在检索曲目和用户信息需要 OAuth app credentials。如果你尚未通过环境变量或 `.env` 文件设置 `SP_APP_CLIENT_ID` 和 `SP_APP_CLIENT_SECRET`，可以使用 `-r` 标志：
```
spotify_monitor -u "your_sp_dc_cookie_value" -r "your_spotify_app_client_id:your_spotify_app_client_secret"
```
有关详细的设置说明，请参阅 [Spotify OAuth App](#spotify-oauth-app)。
默认情况下，工具会在以下位置查找名为 `spotify_monitor.conf` 的配置文件：
- 当前目录
- 主目录（`~`）
- 脚本目录
如果你按照[配置](#configuration)中的描述生成了配置文件，但以不同的名称或保存在不同的目录中，可以使用 `--config-file` 标志指定其位置：
```
spotify_monitor --config-file /path/spotify_monitor_new.conf
```
工具会一直运行直到被中断（`Ctrl+C`）。使用 `tmux` 或 `screen` 以保持持久性。
你可以通过运行多个脚本副本来监控多个 Spotify 好友。
工具会自动将其输出保存到 `spotify_monitor_.log` 文件。日志文件名可以通过 `SP_LOGFILE` 配置选项更改，其后缀可以通过 `FILE_SUFFIX` / `-y` 标志更改。可以通过 `DISABLE_LOGGING` / `-d` 标志完全禁用日志记录。
请记住，监控是在用户听完曲目**后**报告收听的曲目。这就是 Spotify 报告活动的方式。
### 列表模式
工具还有另一种模式，用于显示各种请求的信息。
如果你想显示你关注的所有好友及其最近收听曲目的列表（`-l` 标志）：
```
spotify_monitor -l
```
它还会显示你好友的 Spotify 用户名（通常是用户的名字和姓氏）和 user URI ID（通常是随机字符串）。后者应用作工具的命令行参数来监控该用户。
-a
```
要在用户变为非活动状态时收到通知：
- 将 `INACTIVE_NOTIFICATION` 设置为 `True`
- 或使用 `-i` 标志
```
spotify_monitor -i
```
非活动邮件包含会话中的最近歌曲及其跳过状态。通过 `INACTIVE_EMAIL_RECENT_SONGS_COUNT` 配置选项配置要包含的最近歌曲数量。
要在播放监控的曲目/播放列表/专辑时获得邮件通知：
- 将 `TRACK_NOTIFICATION` 设置为 `True`
- 或使用 `-t` 标志
对于该功能，你还需要创建一个包含要监控的歌曲列表的文件（每行一首曲目、专辑或播放列表）。使用 `MONITOR_LIST_FILE` 或 `-s` 标志指定文件：
```
spotify_monitor -t -s spotify_tracks_spotify_user_uri_id
```
示例文件 `spotify_tracks_spotify_user_uri_id`：
```
we fell in love in october
Like a Stone
Half Believing
Something Changed
I Will Be There
```
如果需要，你可以使用 # 注释掉特定行。
要为用户收听的每首歌曲启用邮件通知：
- 将 `SONG_NOTIFICATION` 设置为 `True`
- 或使用 `-j` 标志
```
spotify_monitor -j
```
要在用户循环播放同一首歌曲时收到通知：
- 将 `SONG_ON_LOOP_NOTIFICATION` 设置为 `True`
- 或使用 `-x` 标志
```
spotify_monitor -x
```
要在出错时禁用发送邮件（默认启用）：
- 将 `ERROR_NOTIFICATION` 设置为 `False`
- 或使用 `-e` 标志
```
spotify_monitor -e
```
确保你之前已定义 SMTP 设置（请参阅 [SMTP settings](#smtp-settings))。
示例邮件：
-b spotify_tracks_user_uri_id.csv
```
如果文件不存在，将自动创建。
### 在 Spotify 客户端自动播放收听的曲目
如果你希望工具在本地 Spotify 客户端中自动播放用户收听的曲目：
- 将 `TRACK_SONGS` 设置为 `True`
- 或使用 `-g` 标志
```
spotify_monitor -g
```
你的 Spotify 客户端需要安装并运行才能使用此功能。
该工具在 **Linux** 和 **macOS** 上完全支持自动播放。这意味着它将自动播放更改的曲目，并且一旦用户变为非活动状态，还可以暂停或播放指定的曲目（请参阅 `SP_USER_GOT_OFFLINE_TRACK_ID` 配置选项）。
对于 **Windows**，它以半自动方式工作：如果你运行了 Spotify 客户端并且没有收听任何歌曲，那么第一首曲目将自动播放。但是，后续曲目将在客户端中定位，你需要手动按播放按钮。
你可以使用相应的配置选项更改每个平台的播放方式。
对于 **macOS**，将 `SPOTIFY_MACOS_PLAYING_METHOD` 设置为以下值之一：
- "**apple-script**"（推荐，**默认**）
- "trigger-url"
对于 **Linux**，将 `SPOTIFY_LINUX_PLAYING_METHOD` 设置为以下值之一：
- "**dbus-send**"（最常见，**默认**）
- "qdbus"（如果 dbus-send 不起作用，请尝试此项）
- "trigger-url"
对于 **Windows**，将 `SPOTIFY_WINDOWS_PLAYING_METHOD` 设置为以下值之一：
- "**start-uri**"（推荐，**默认**）
- "spotify-cmd"
- "trigger-url"
推荐的默认设置应该适用于大多数人。
注意：监控是在用户听完曲目后报告收听的曲目。这就是 Spotify 报告活动的方式。这意味着你将比被监控用户落后一首歌，如果被追踪用户当前收听的歌曲比上一首长，那么之前收听的歌曲可能会在你的 Spotify 客户端中重复播放（如果较短，可能会在当前播放的歌曲中间更改）。
要实时追踪用户的音乐播放活动，请让你的朋友将其 Spotify 账户与 [Last.fm](https://www.last.fm/) 连接。然后使用我的另一个工具：[lastfm_monitor](https://github.com/misiektoja/lastfm_monitor)。
### 检查间隔
如果要自定义轮询间隔，请使用 `-c` 标志（或 `SPOTIFY_CHECK_INTERVAL` 配置选项）：
```
spotify_monitor -c 20
```
如果要更改将用户标记为非活动状态所需的时间（计时器从上次报告的曲目开始），请使用 `-o` 标志（或 `SPOTIFY_INACTIVITY_CHECK` 配置选项）：
```
spotify_monitor -o 900
```
### 信号控制
该工具实现了多个信号处理程序，允许更改工具的行为而无需使用新的配置选项/标志重新启动它。
支持的信号列表：
| Signal | 描述 |
| ----------- | ----------- |
| USR1 | 切换用户变为活动/非活动时的邮件通知 |
| USR2 | 切换每首歌曲的邮件通知 |
| CONT | 切换追踪歌曲的邮件通知 |
| PIPE | 切换用户循环播放歌曲时的邮件通知 |
| TRAP | 增加非活动检查计时器（增加 30 秒） |
| ABRT | 减少非活动检查计时器（减少 30 秒） |
| HUP | 从 .env 文件重新加载密钥，并从 Protobuf 文件重新加载 token 源凭据 |
使用 `kill` 或 `pkill` 发送信号，例如：
```
pkill -USR1 -f "spotify_monitor "
```
由于 Windows 支持的信号数量有限，此功能仅在 Linux/Unix/macOS 上可用。
### 使用 GRC 为日志输出着色
你可以使用 [GRC](https://github.com/garabik/grc) 为日志着色。
添加到你的 GRC 配置（`~/.grc/grc.conf`）：
```
# 监控日志文件
.*_monitor_.*\.log
conf.monitor_logs
```
现在将 [conf.monitor_logs](https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/grc/conf.monitor_logs) 复制到你的 `~/.grc/`，使用 `grc` 工具时日志文件应该会有漂亮的颜色。
示例：
```
grc tail -F -n 100 spotify_monitor_.log
```
## 调试工具
为了帮助进行故障排除和开发，[debug](https://github.com/misiektoja/spotify_monitor/tree/dev/debug) 目录中提供了两个调试实用程序。
### 通过 sp_dc Cookie 和 TOTP 获取 Access Token
[spotify_monitor_totp_test](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_totp_test.py) 工具使用 Web Player `sp_dc` cookie 和 TOTP 参数检索 Spotify access token。
从[这里](https://github.com/misiektoja/spotify_monitor/blob/dev/debug/spotify_monitor_totp_test.py)下载或：
```
wget https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/dev/debug/spotify_monitor_totp_test.py
```
安装依赖项：
```
pip install requests python-dateutil pyotp
```
运行：
```
python3 spotify_monitor_totp_test.py --sp-dc "your_sp_dc_cookie_value"
```
你应该获得一个有效的 Spotify access token，示例输出：
标签：DNS解析, Python, Spotify, 个人情报收集, 在线状态检测, 好友活动, 娱乐工具, 媒体工具, 媒体流, 实时追踪, 开源项目, 数据洞察, 无后门, 歌曲跳过检测, 用户行为分析, 社交监听, 自动播放, 逆向工具, 通知系统, 音乐监控, 音频同步