核心用法
Spoticlaw 是一个专为 Nyx 代理设计的轻量级 Spotify Web API 客户端，采用纯 HTTP 请求实现，完全摆脱对 Spotipy 的依赖。其核心架构分为三大模块：搜索发现（track/artist/album/show/episode 多类型搜索）、播放控制（设备转移、播放/暂停、队列管理、进度跳转、音量调节、随机/循环模式）、库管理（歌单创建/编辑/删除、专辑收藏、最近播放追踪、个性化推荐）。
使用流程遵循「本地认证 → 复制令牌 → 代理执行」的安全模式：用户在本地机器运行 auth.py 完成 OAuth 授权，生成 .spotify_cache 文件后手动复制到代理环境，代理仅读取该文件进行 API 调用。令牌具备自动刷新机制，但要求代理环境配置一致的 SPOTIFY_CLIENT_ID 和 SPOTIFY_CLIENT_SECRET。
显著优点
- 安全隔离设计：OAuth 令牌全程不经过 AI 模型，从物理层面消除令牌泄露风险
- 零外部依赖：仅依赖
requests和python-dotenv，无重型 SDK 负担 - 完整功能覆盖：支持播放控制、歌单 CRUD、播客流、个性化数据（Top 曲目/艺人）等 Spotify Premium 核心功能
- 灵活工作流：模块化 API 设计支持组合搜索→筛选→播放/收藏等复杂自动化场景
- 设备感知：支持跨设备播放转移（手机/电脑/智能音箱）
潜在局限
- Premium 限制：播放控制、设备转移等功能需 Spotify Premium 订阅
- 令牌生命周期：Access token 约1小时过期，若自动刷新失败需人工重新授权复制
- 设备状态依赖：
NO_ACTIVE_DEVICE错误需用户预先用官方 App 打开 Spotify - 搜索硬限制：单次搜索最多返回10条结果（Spotify API 限制），大规模数据获取需多次分页
- 范围锁定：当前 scope 未包含
user-follow-modify，关注艺人需手动操作 - 文件传输摩擦：远程代理场景下需通过 scp/USB 等方式手动同步令牌文件
适合人群
- 需要音乐数据自动化的开发者（批量歌单生成、收听习惯分析）
- 智能家居/语音场景集成者（通过代理控制 Spotify 播放）
- 隐私敏感用户（拒绝将 OAuth 令牌暴露给第三方 AI 服务）
- 已具备 Spotify Premium 且熟悉 OAuth 配置的技术用户
常规风险
- 令牌泄露风险：
.spotify_cache文件若被未授权访问，可导致账户被恶意控制 - 凭证配置错误：Client ID/Secret 不匹配会导致刷新失败，需重新走完整认证流程
- API 速率限制：高频调用可能触发 Spotify 限流（429 错误）
- 设备切换异常：播放状态在不同设备间转移时可能出现同步延迟
- 权限继承问题：用户若后续修改 scope 需重新授权，旧令牌不自动升级权限