From eb66d96ef373c4a8c0c37c2ab7d1741cc96bd8ce Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Sun, 12 Apr 2026 02:09:51 -0500 Subject: [PATCH] docs(spotify): implement milestone M5 install docs --- docs/spotify.md | 93 +++++++++++++++++++++++++++++++++++++++-- skills/spotify/SKILL.md | 38 +++++++++++++++++ 2 files changed, 127 insertions(+), 4 deletions(-) diff --git a/docs/spotify.md b/docs/spotify.md index 805eca4..f4c959a 100644 --- a/docs/spotify.md +++ b/docs/spotify.md @@ -1,8 +1,8 @@ # Spotify -The Spotify skill adds a local helper for Spotify Web API work from OpenClaw. +The Spotify skill adds a local helper for Spotify Web API playlist work from OpenClaw. -Current scope: +## Scope - search Spotify tracks - list the current user's playlists @@ -13,6 +13,91 @@ Current scope: The skill uses OAuth2 Authorization Code with PKCE. It does not need a Spotify client secret and does not use browser automation for Spotify operations. -Implementation is in `skills/spotify/`. +## Setup -Setup and live-smoke details will be completed with the auth and command implementation. +Create the local credential directory: + +```bash +mkdir -p ~/.openclaw/workspace/.clawdbot/credentials/spotify +chmod 700 ~/.openclaw/workspace/.clawdbot/credentials/spotify +$EDITOR ~/.openclaw/workspace/.clawdbot/credentials/spotify/config.json +``` + +Example `config.json`: + +```json +{ + "clientId": "your-spotify-client-id", + "redirectUri": "http://127.0.0.1:8888/callback" +} +``` + +Run auth from the active OpenClaw skill copy: + +```bash +cd ~/.openclaw/workspace/skills/spotify +scripts/setup.sh +``` + +Or run only the OAuth login after dependencies are installed: + +```bash +scripts/spotify auth +scripts/spotify status --json +``` + +Tokens are written to the local credentials directory as `token.json` with owner-only file mode when the filesystem supports it. Do not print token files. + +## Commands + +```bash +scripts/spotify status --json +scripts/spotify search "Radiohead Karma Police" --limit 3 --json +scripts/spotify list-playlists --limit 10 --json +scripts/spotify create-playlist "OpenClaw Mix" --description "Created by OpenClaw" --json +scripts/spotify add-to-playlist "" "spotify:track:..." --json +scripts/spotify remove-from-playlist "" "spotify:track:..." --json +scripts/spotify search-and-add "" "Radiohead Karma Police" --json +scripts/spotify import "/path/to/tracks.txt" --playlist "Imported Mix" --json +scripts/spotify import "/path/to/playlist.m3u8" --playlist-id "" --json +scripts/spotify import "/path/to/music-folder" --playlist "Folder Import" --json +``` + +`--playlist NAME` always creates a new playlist, private by default unless `--public` is provided. Spotify allows duplicate playlist names, so use `--playlist-id ID` when updating an existing playlist. + +## Import Behavior + +Text imports ignore blank lines and comment lines starting with `#` or `//`. + +M3U/M3U8 imports use `#EXTINF` metadata when present and fall back to the filename otherwise. + +Folder imports recursively scan supported audio filenames and ignore non-audio files. + +The importer searches Spotify once per parsed candidate, adds the first match, reports misses, and skips duplicate Spotify URI matches. + +## Endpoint Notes + +This skill uses the current Spotify playlist endpoints: + +```text +GET /v1/me +GET /v1/search?type=track&q=&limit=<1-10> +GET /v1/me/playlists?limit=&offset= +POST /v1/me/playlists +POST /v1/playlists/{id}/items +DELETE /v1/playlists/{id}/items +POST https://accounts.spotify.com/api/token +``` + +Do not use the removed 2026 endpoints: + +```text +POST /v1/users/{user_id}/playlists +GET /v1/users/{id}/playlists +POST /v1/playlists/{id}/tracks +DELETE /v1/playlists/{id}/tracks +``` + +## Live Smoke Caution + +Spotify does not offer a normal delete-playlist Web API operation. Any live smoke that creates a playlist must be explicitly approved because the playlist can only be manually cleaned up later. diff --git a/skills/spotify/SKILL.md b/skills/spotify/SKILL.md index db29874..f53965b 100644 --- a/skills/spotify/SKILL.md +++ b/skills/spotify/SKILL.md @@ -18,3 +18,41 @@ scripts/spotify --help This skill uses the Spotify Web API with OAuth2 Authorization Code + PKCE. It does not use browser automation for Spotify operations and does not need a Spotify client secret. Do not print token files or OAuth callback data. Use `--json` for machine-readable command output. + +## Setup + +```bash +mkdir -p ~/.openclaw/workspace/.clawdbot/credentials/spotify +chmod 700 ~/.openclaw/workspace/.clawdbot/credentials/spotify +$EDITOR ~/.openclaw/workspace/.clawdbot/credentials/spotify/config.json +cd ~/.openclaw/workspace/skills/spotify +scripts/setup.sh +``` + +`config.json`: + +```json +{ + "clientId": "your-spotify-client-id", + "redirectUri": "http://127.0.0.1:8888/callback" +} +``` + +## Commands + +```bash +scripts/spotify status --json +scripts/spotify search "Radiohead Karma Police" --limit 3 --json +scripts/spotify list-playlists --limit 10 --json +scripts/spotify create-playlist "OpenClaw Mix" --description "Created by OpenClaw" --public --json +scripts/spotify add-to-playlist "" "spotify:track:..." --json +scripts/spotify remove-from-playlist "" "spotify:track:..." --json +scripts/spotify search-and-add "" "Radiohead Karma Police" --json +scripts/spotify import "/path/to/tracks.txt" --playlist "Imported Mix" --json +``` + +`--playlist NAME` creates a new private playlist by default. Use `--playlist-id ID` to update an exact existing playlist. + +Current Spotify endpoints used by this skill include `/v1/me/playlists` and `/v1/playlists/{id}/items`; do not use the removed `/tracks` playlist mutation endpoints. + +Spotify has no normal delete-playlist Web API operation. Ask before running live smoke tests that create playlists.