Metadata

name: soundcloud
description: Interact with SoundCloud API for searching tracks, managing playlists, user operations, and audio discovery. Use when the user asks to search for music on SoundCloud, create/edit playlists, get track information, find user profiles, manage favorites, or work with SoundCloud audio content. Requires SOUNDCLOUD_CLIENT_ID and SOUNDCLOUD_CLIENT_SECRET for all operations; SOUNDCLOUD_USER_TOKEN for write operations (playlists, likes, follows).
metadata: {"author":"github.com/LeoSaucedo"}

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:

Register app at https://soundcloud.com/you/apps
Redirect URI: http://localhost:8080/callback
Authorize via browser
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

Soundcloud

安装技能