soundcloud

Files (21)

• SKILL.md
• album-upload-workflow.md · references/
• cover-art-generation.md · references/
• oauth-quirks.md · references/
• playlist-api.md · references/
• playlist-artwork-quirk.md · references/
• playlist-artwork-update.md · references/
• publish-fallback-workflow.md · references/
• publish-release-pattern.md · references/
• release-directory.md · references/
• remove-track-from-existing-album.md · references/
• remove-track-from-published-album.md · references/
• replace-track-in-published-album.md · references/
• replacing-tracks.md · references/
• soundcloud-analyzer.md · references/
• soundcloud-api.md · references/
• track-replacement-workflow.md · references/
• oauth_flow.py · scripts/
• publish_release.py · scripts/
• soundcloud-analyzer.py · scripts/
• soundcloud_api.py · scripts/

SKILL.md (first lines)

# SoundCloud Manager

Upload, update, list, and manage SoundCloud tracks via OAuth 2.1 PKCE. Token refresh is automatic after one-time auth.

> **References:** `references/oauth-quirks.md` · `references/soundcloud-api.md` · `references/playlist-api.md` · `references/release-directory.md` · `references/track-replacement-workflow.md` · `references/replace-track-in-published-album.md` · `references/publish-fallback-workflow.md`

## 🚀 Publishing Albums (USE THIS)

For album/EP releases, **always use `publish_release.py`** — it handles upload, playlist, tags, artwork, and label in one command with user confirmation buttons:

```bash
# Review gate: sends summary + Publish/Preview/Edit/Cancel buttons to Telegram
python3 /opt/data/skills/music/soundcloud/scripts/publish_release.py --release mars-descent

# Send audio for user review first, then publish buttons
python3 /opt/data/skills/music/soundcloud/scripts/publish_release.py --release mars-descent --preview

# Skip gates, publish immediately
python3 /opt/data/skills/music/soundcloud/scripts/publish_release.py --release mars-descent --confirm

# List release-ready albums
python3 /opt/data/skills/music/soundcloud/scripts/publish_release.py --list
```

Reads `release.json` + `tracks_meta.json` from `/opt/data/music/releases/<album>/`, auto-discovers artwork. See `references/release-directory.md` for structure.

For full end-to-end album publishing with per-track artwork, tags, label, and playlist creation, see `references/publish-release-pattern.md` — it documents the proven Python subprocess script pattern used for CHERENKOV-HORIZON and subsequent releases.

**⛔ Do NOT manually piece together upload → tags → playlist → artwork. Use this script.**

**User preference — skip review gate on explicit "Publish":** When the user says "Publish" or "Promote and Publish", they mean upload to SoundCloud immediately. Skip the review-files-first step in that case. Only send files for review when the user hasn't explicitly requested publishing.

## CLI Commands

All via `python3 /opt/data/skills/music/soundcloud/scripts/soundcloud_api.py`:

| Command | Usage |
|---------|-------|
| `upload` | `upload --file track.flac --title "Title" --tags "tag1 tag2" --genre Electronic --artwork cover.png --sharing public --downloadable --label "VØIDRIDE"` |
| `update` | `update --track-id ID --title "New" --tags "new tags" --genre Bass --artwork new.png --sharing private` |
| `list` | `list [--limit 50] [--json]` |
| `status` | `status --track-id ID` (states: `finished`=live, `processing`=encoding, `failed`=re-upload) |
| `batch-upload` | `batch-upload --dir /path/ --genre Electronic --tags "tag1 tag2" [--artwork-dir /covers/]` |
| `create-playlist` | `create-playlist --title "Album" --track-ids "123,456,789" [--artwork cover.png]` |

## First-Time Auth

```bash
# Native Linux (browser redirect works):
python3 /opt/data/skills/music/soundcloud/scripts/oauth_flow.py --auth

# WSL/headless (browser can't reach WSL):
python3 /opt/data/skills/music/soundcloud/scripts/oauth_flow.py --auth-url
# → Copy URL to Windows browser → authorize → copy callback URL
python3 /opt/data/skills/music/soundcloud/scripts/oauth_flow.py --exchange-url 'http://127.0.0.1:8080/callback?code=XXXXX'
```

Requires `SOUNDCLOUD_CLIENT_ID` + `SOUNDCLOUD_CLIENT_SECRET` env vars. Redirect URI must be `http://127.0.0.1:8080/callback`.

Tokens stored at `~/.hermes/credentials/soundcloud_tokens.json` (auto-refreshed, single-use refresh tokens).

## Publishing Rules (HARD RULES)

1. **SEND AUDIO FOR REVIEW BEFORE UPLOADING.** Never publish without user approval. No exceptions.
   - **User preference — skip review gate on explicit "Publish":** When the user says "Publish" or "Promote and Publish" (or similar imperative), go straight to `--confirm`. Don't send previews first.
   - **No Telegram available?** Send files manually via `MEDIA:` paths in your response, then ask for approval. Once approved, use `--confirm` to publish.
2. **FLAC ONLY.** Always upload FLAC masters — never MP3. SC re-encodes; lossless source = best quality.
3. **NO production details in descriptions.** No version numbers, LUFS stats, stem info, or how-it-was-made notes. Description = track name + genre/vibe only.
4. **NO poems in descriptions** unless user explicitly asks.
5. **Track titles: plain ASCII.** "Entrywound" not "Ɇ₦₮ƦɎ₩ØɄ₦Đ". Unicode belongs on cover art and playlist titles only.
6. **Cover art: Unicode-styled titles.** "BLΔCK MΔSS" not "BLACK MASS". Use Open Sans Bold (not Helvetica).
7. **Re-mix stems before regenerating.** Remove/reduce a bad stem rather than regenerating the whole track.

## Replacing a Track in a Published Album

When a user asks to replace a track in a published album:

1. **Find playlist + track ID** from `release.json`'s `soundcloud.track_ids` array
2. **DELETE** the track via raw API call: `DELETE /tracks/{id}`
3. **PUT** the playlist with remaining track IDs (PUT replaces the entire list)
4. **Update** `release.json` with the new track ID array
5. **Produce** a replacement track using the SAME model as the original (`production_plan.json` → `stems.main.model`)
6. **DAWAGENT** — Demucs separation + session handoff
7. **Cover art** — title overlay for the new track
8. **Upload** new track + update playlist with new ID

See `references/replacing-tracks.md` for the full step-by-step workflow with API examples.

## Playlist Creation (JSON format required)

```python
import json, urllib.request

with open('/opt/data/home/.hermes/credentials/soundcloud_tokens.json') as f:
    tokens = json.load(f)

payload = json.dumps({
    "playlist": {
        "title": "Album Title",
        "sharing": "public",
        "tracks": [{"id": "123456"}, {"id": "789012"}]  # STRING IDs, not ints!
    }
}).encode('utf-8')

req = urllib.request.Request("https://api.soundcloud.com/playlists", data=payload, method='POST')
req.add_header('Authorization', f'OAuth {tokens["access_token"]}')
req.add_header('Content-Type', 'application/json; charset=utf-8')
req.add_header('Accept', 'application/json; charset=utf-8')  # REQUIRED — 422 without this
resp = urllib.request.urlopen(req)
```

**PUT replaces** the entire track list — include ALL track IDs, not just new ones.

### Playlist Artwork

Must use `playlist[artwork_data]` (not `track[artwork_data]` — that 500s on playlists):

```python
boundary = "----WebKitFormBoundary7MA4YWxkTrZu0gW"

From maximusmaximus/Mcmusic, MIT.

More from maximusmaximus/Mcmusic