Antra Spotify认证全解：sp_dc Cookie、TOTP匿名令牌与播放列表抓取技巧指南-平芜编程栈

Antra Spotify认证全解：sp_dc Cookie、TOTP匿名令牌与播放列表抓取技巧指南

【免费下载链接】AntraA desktop music library builder that turns Spotify, Youtube Music Apple Music, Amazon Music, Tidal, Qobuz, and Deezer links into fully tagged local library in FLAC, ALAC, Dolby Atmos, AAC, or MP3.项目地址: https://gitcode.com/gh_mirrors/an/Antra

Antra 是一款桌面音乐库构建工具，能把 Spotify、YouTube Music、Apple Music、Amazon Music、Tidal、Qobuz、Deezer 的链接变成带完整标签的本地无损音乐库（FLAC / ALAC / AAC / MP3）。其中 Spotify 认证是整个流程的起点，而它背后的 sp_dc Cookie 与 TOTP 匿名令牌机制，正是 Antra 能无限制抓取你私有播放列表的关键。本文将带你从零看懂这三种认证方式，并掌握公开播放列表抓取的实用技巧。

什么是 Antra：一条链接到本地音乐库

在讲认证之前，先花 30 秒了解 Antra 的完整工作流：

粘贴链接— 在 URL 标签页粘贴 Spotify 播放列表/专辑链接
选择格式— 右上角一键切换 FLAC、ALAC、AAC、MP3
自动入库— 曲目被多音源解析、下载，并按艺术家/专辑结构归档
完整标签— 标题、艺人、专辑、封面、流派、歌词自动写入文件

最终你会得到一个可直接接入 Navidrome、Jellyfin、Plex 的本地音乐库。详见功能文档 FEATURES.md 与项目说明 README.md。

Antra 的三种 Spotify 认证方式

Antra 对 Spotify 的认证采用「优先级降级」策略，核心逻辑在 antra/core/spotify_fetcher.py：

优先级	方式	特点	配置项
⭐ 首选	sp_dc Cookie	无 API 限制，有效期约一年	`SPOTIFY_SP_DC`
备用	手动 Access Token	紧急通道，仅约 1 小时有效	`SPOTIFY_ACCESS_TOKEN`
兜底	PKCE OAuth 浏览器登录	无需开发者账号，首次授权后静默续期	本地缓存文件

三者实现均在 antra/core/spotify_auth.py，配置读取见 antra/core/config.py。

方式一：sp_dc Cookie（推荐）

如何获取（约 2 分钟）：

浏览器登录 open.spotify.com
打开开发者工具 → Application → Cookies → open.spotify.com
找到名为sp_dc的 Cookie，复制它的值（以AQ...开头）
在 Antra 的Settings → Spotify Account中粘贴，或用 CLI 保存：

antra spotify set-cookie <sp_dc值>

该 Cookie 有效期约一年，一次配置长期可用，并且不受开发者 API 的调用限制——这正是 Antra 推荐它的原因。若你的 IP 恰好被 Spotify 拦截校验，可加--force强制保存。

方式二：手动 Access Token（紧急备用）

打开 open.spotify.com 的网络请求面板，找到任意接口返回中的accessToken字段，然后：

antra spotify set-token <accessToken值>

注意：Token 通常只存活 1 小时，且无法自动刷新，只适合临时救急（见 antra/cli/spotify_cli.py）。

方式三：PKCE OAuth 浏览器登录

antra spotify login

首次运行会打开系统浏览器让你登录，Antra 自动捕获会话；此后每次运行都用缓存的 refresh token静默续期，无需再次登录。用户全程不需要注册 Spotify 开发者应用。授权范围（scope）定义在 antra/core/spotify_auth.py：私密播放列表读取、协作播放列表、已收藏歌曲、关注的艺人。

三种方式就绪后，随时用下面命令体检当前状态：

antra spotify status # 查看当前生效的认证方式 antra spotify test-cookie # 真实请求验证 Cookie 是否有效 antra spotify playlists # 列出你的全部播放列表

TOTP 匿名令牌：sp_dc Cookie 背后的原理

这是本文最硬核也最有趣的部分。为什么 Antra 拿到一个浏览器 Cookie 就能以「你」的身份访问 API？答案在 antra/core/spotify_auth.py 的SpotifyWebPlayerAuth类里。

第一步：绕开被封的接口。Spotify 官方网页版获取令牌的接口（/get_access_token）对所有脚本客户端做了 Cloudflare IP 封锁，直接返回 403。Antra 改走网页播放器专用端点/api/token，该端点对携带正确请求头的客户端开放。

第二步：TOTP 动态口令。每次请求令牌时，Antra 用内置的 TOTP 密钥（基于pyotp库）按当前时间生成一个动态验证码，连同productType=web-player、totpVer等参数一起提交——模拟真实网页播放器的心跳行为：

totp = pyotp.TOTP(_SP_TOTP_SECRET) code = totp.now() # 请求参数: reason=init, productType=web-player, totp=code ...

第三步：匿名令牌判定。服务端返回一个accessToken，并附带isAnonymous标志。Antra 会严格检查它（见 antra/core/spotify_auth.py）：

isAnonymous=False→ Cookie 有效，令牌绑定你的真实账号 ✅
isAnonymous=True→ Cookie 已过期，只拿到了匿名令牌，提示你从浏览器重新抓取 ❌

第四步：令牌保鲜与体检。令牌过期时间从响应中的时间戳解析；is_valid()方法还会真实请求/v1/me端点做心跳验证，遇到 429 限流会读取Retry-After并记录告警，让你知道是「账号问题」还是「被限速了」。

💡小结：sp_dc Cookie 是「钥匙」，TOTP 是「密码锁」，两者结合换回一个与你账号等价的访问令牌——这就是「匿名令牌」名字背后不匿名的玄机。

公开播放列表抓取技巧

认证就绪后，抓取环节的技巧体现在 antra/core/spotify_fetcher.py 中：

技巧一：自动分页。播放列表曲目走_paginate()循环，每页limit=100顺着next指针翻到底，几千首的歌单也能完整拉取，中途遇到 401（令牌过期）会自动强制刷新令牌后重试。

技巧二：字段裁剪（fields 参数）。请求时只索取需要的字段——歌名、艺人、专辑、时长、ISRC、封面——而不是完整的曲目对象。网络体积大幅下降，解析速度更快。

技巧三：链接格式全兼容。_extract_playlist_id()同时识别三种输入，粘贴任何格式都能用：

网页链接https://open.spotify.com/playlist/xxxx
协议 URIspotify:playlist:xxxx
裸 IDxxxx

技巧四：私有播放列表同样可抓。由于走的是你账号自己的令牌，fetch_playlist_tracks()对公开与私有播放列表一视同仁；私有列表在 CLI 的playlists命令输出中会标注PUBLIC: No。

技巧五：限流自愈。遇到 429 时按 Spotify 返回的Retry-After等待重试（上限 60 秒），配合 4 次重试窗口，大多数瞬时限流都能自动消化。

认证好的账号还可以直接在My Library标签页浏览你的已收藏歌曲、Discover Weekly、Daily Mixes、保存专辑与关注艺人，点击卡片即下载，无需复制粘贴任何 URL：

常见问题速查

症状	原因	处理
提示`sp_dc cookie produced an anonymous token`	Cookie 过期（约一年期限）	浏览器重新登录并复制新`sp_dc`
校验时返回 403 Blocked	当前 IP 被 Spotify 拦截	`set-cookie ... --force`强制保存，同步时再试
频繁 429	请求过快触发限流	等待后重试，Antra 会自动按`Retry-After`退避
想彻底登出	—	`antra spotify logout`清除 PKCE 缓存；Cookie 则删除`.env`中的`SPOTIFY_SP_DC`