SoundCloud API Skill#

Overview#

This skill enables interaction with SoundCloud's API for music discovery, playlist management, user operations, and audio content analysis.

Quick Start#

Authentication Setup#

All API calls now require the Authorization: Bearer <token> header. The old ?client_id= query parameter is deprecated.

bash

# Required for ALL operations
export SOUNDCLOUD_CLIENT_ID="your_client_id"
export SOUNDCLOUD_CLIENT_SECRET="your_client_secret"

# Optional: For write operations (playlists, likes, follows)
# Run the OAuth helper to get one:
./scripts/auth_soundcloud.sh
# Or set manually:
export SOUNDCLOUD_USER_TOKEN="your_oauth_token"

Token System#

Two token types are managed automatically:

Token TypeGrantUsed ForManagedApp Tokenclient_credentialsSearch, track info, user profiles, playlists (read)Auto-acquired & cachedUser Tokenauthorization_codeCreate playlists, like tracks, follow usersVia auth_soundcloud.sh

Token cache: ~/.cache/soundcloud/

Basic Usage#

bash

# Search for tracks
./scripts/search_tracks.sh "lofi hip hop" --limit 10

# Get user info
./scripts/get_user_info.sh "nocopyrightsounds" --with-tracks 5

# Analyze a track
./scripts/analyze_track.sh "https://soundcloud.com/artist/track"

# Check token status
./scripts/auth_token.sh status

Scripts Reference#

Search & Discovery#

scripts/search_tracks.sh

Search tracks with filters and formatted output.

bash

./scripts/search_tracks.sh "search query" [options]

Options: --limit N, --genre "genre", --bpm-min N, --bpm-max N, --duration-min N, --duration-max N, --sort "field", --json, --csv

scripts/analyze_track.sh

Get detailed track information from ID or URL.

bash

./scripts/analyze_track.sh "track_id_or_url"

Output: Metadata, audio properties (BPM, key), engagement stats, license, stream/download URLs.

User Operations#

scripts/get_user_info.sh

Get user profile with stats, bio, and optional tracks/playlists.

bash

./scripts/get_user_info.sh "username_or_id" [--with-tracks N] [--with-playlists N] [--json]

scripts/get_user_playlists.sh

List playlists for a user.

bash

./scripts/get_user_playlists.sh "username_or_id" [--limit N] [--with-tracks] [--json]

scripts/follow_user.sh

Follow or unfollow a user (requires user token).

bash

./scripts/follow_user.sh "username_or_id" [--unfollow]

Track Interactions#

scripts/like_track.sh

Like or unlike a track (requires user token).

bash

./scripts/like_track.sh "track_id_or_url" [--unlike]

Playlist Management#

scripts/create_playlist.sh

Create a new playlist (requires user token).

bash

./scripts/create_playlist.sh "Playlist Name" [--description "text"] [--tracks "id1,id2"] [--sharing public|private] [--genre "genre"] [--tags "tag1,tag2"] [--no-confirm]

scripts/update_playlist.sh

Update playlist title, description, sharing, tracks (requires user token).

bash

./scripts/update_playlist.sh PLAYLIST_ID [--title "New Title"] [--description "text"] [--sharing public|private] [--add-tracks "id1,id2"] [--remove-tracks "id1,id2"] [--set-tracks "id1,id2"]

scripts/delete_playlist.sh

Delete a playlist (requires user token).

bash

./scripts/delete_playlist.sh PLAYLIST_ID [--force]

Batch Operations#

scripts/batch_operations.sh

Perform operations on multiple tracks from a file.

bash

./scripts/batch_operations.sh [action] [file] [options]

Actions:

• like-tracks — Like all tracks in file (requires user token)
• unlike-tracks — Unlike all tracks in file (requires user token)
• add-to-playlist — Add tracks to a playlist (requires user token + --playlist-id)
• download-metadata — Download full metadata JSON for all tracks
• check-availability — Check which tracks are still available

File format: One track ID per line, or CSV with IDs in first column.

Authentication#

scripts/auth_token.sh

Token manager — source'd by other scripts. Standalone usage:

bash

./scripts/auth_token.sh status    # Show token status
./scripts/auth_token.sh refresh   # Force app token refresh
./scripts/auth_token.sh test      # Test API connectivity
./scripts/auth_token.sh app       # Print app token
./scripts/auth_token.sh user      # Print user token (if available)

scripts/auth_soundcloud.sh

Interactive OAuth flow to get a user token for write operations.

bash

./scripts/auth_soundcloud.sh

Walks through: browser authorization → code exchange → token save.

Authentication Reference#

Client Credentials (App Token)#

Used automatically for all read operations. Requires SOUNDCLOUD_CLIENT_ID + SOUNDCLOUD_CLIENT_SECRET.

bash

curl -X POST https://api.soundcloud.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Authorization Code (User Token)#

Required for write operations. Run ./scripts/auth_soundcloud.sh for interactive setup, or:

1. Register app at https://soundcloud.com/you/apps
2. Redirect URI: http://localhost:8080/callback
3. Authorize via browser
4. Exchange code for token

Common Use Cases#

Music Discovery Pipeline#

bash

# 1. Search for tracks
./scripts/search_tracks.sh "study beats" --genre "lofi" --bpm-min 60 --bpm-max 80 --limit 50 --csv > candidates.csv

# 2. Analyze specific tracks
./scripts/analyze_track.sh "track_id"

# 3. Create playlist (requires user token)
./scripts/create_playlist.sh "Study Focus" --description "Concentration music" --tracks "id1,id2,id3"

User Profile Analysis#

bash

./scripts/get_user_info.sh "artistname" --with-tracks 10 --with-playlists 5

Batch Processing#

bash

# Download metadata for a list of tracks
echo -e "123\n456\n789" > track_ids.txt
./scripts/batch_operations.sh download-metadata track_ids.txt --delay 1

# Check which tracks are still available
./scripts/batch_operations.sh check-availability track_ids.txt

Error Handling#

Common HTTP Status Codes#

• 401 Unauthorized: Missing/invalid credentials or expired token
• 403 Forbidden: Insufficient permissions (trying to write without user token)
• 404 Not Found: Resource doesn't exist
• 429 Too Many Requests: Rate limit exceeded

Script Error Handling#

All scripts include:

• Automatic token acquisition and refresh
• HTTP status code checking
• JSON response parsing with error detection
• Graceful failure with informative messages

Token Issues#

bash

# Check token status
./scripts/auth_token.sh status

# Force refresh app token
./scripts/auth_token.sh refresh

# Re-run OAuth for user token
./scripts/auth_soundcloud.sh

References#

• SoundCloud API Reference
• Security Updates
• See references/ for: api_endpoints.md, oauth_flow.md, best_practices.md