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.

# 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 Type	Grant	Used For	Managed
App Token	client_credentials	Search, track info, user profiles, playlists (read)	Auto-acquired & cached
User Token	authorization_code	Create playlists, like tracks, follow users	Via auth_soundcloud.sh

Token cache: ~/.cache/soundcloud/

Basic Usage

# 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.

./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.

./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.

./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.

./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).

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

Track Interactions

scripts/like_track.sh

Like or unlike a track (requires user token).

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

Playlist Management

scripts/create_playlist.sh

Create a new playlist (requires user token).

./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).

./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).

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

Batch Operations

scripts/batch_operations.sh

Perform operations on multiple tracks from a file.

./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:

./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.

./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.

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

# 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

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

Batch Processing

# 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

# 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