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

README (SKILL.md)

SoundCloud API Skill

Name: Soundcloud
Author: leosaucedo

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 \x3Ctoken> 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\
456\
789" > 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

Usage Guidance

Install only if you are comfortable giving this skill SoundCloud API credentials and letting it cache OAuth tokens locally. Prefer a low-privilege or temporary SoundCloud app, avoid non-expiring or wildcard tokens, review the token files under ~/.cache/soundcloud, and require explicit human confirmation before playlist deletion, playlist replacement/removal, likes, follows, or batch account changes.

Capability Tags

requires-oauth-tokenrequires-sensitive-credentials

Capability Assessment

ℹ Purpose & Capability

The stated SoundCloud purpose matches the scripts: search/read operations, OAuth setup, playlist management, likes, follows, and batch processing. The concern is not hidden functionality, but that the skill includes authenticated write and delete operations on a user account.

⚠ Instruction Scope

Several state-changing operations are under-scoped for an agent context: update_playlist.sh can replace or remove playlist tracks without confirmation, like/follow actions run directly, batch operations can modify many tracks, and create/delete operations expose confirmation bypass flags.

✓ Install Mechanism

No package install hook or automatic execution was found. The artifact is a set of markdown instructions and shell scripts invoked by the user or agent.

ℹ Credentials

Network calls to SoundCloud and use of curl/jq are proportionate to the API-helper purpose. The skill requires SoundCloud client credentials and optionally a user OAuth token, which is disclosed in the README and SKILL.md.

⚠ Persistence & Privilege

The scripts persist app and user OAuth tokens under ~/.cache/soundcloud with chmod 600, while the README claims the cache is encrypted at rest even though the implementation writes plaintext JSON. Reference docs also encourage .env/token-file secret storage and broad/non-expiring OAuth scopes.

Version History

v1.0.1

Update ClawHub badge to Published in green, add onboarding docs, remove license stub, explain token caching

v1.0.0

Initial release: track search, analysis, user profiles, playlist management, batch operations with OAuth2 token management

Metadata

Slug soundcloud

Version 1.0.1

License MIT-0

All-time Installs 1

Active Installs 1

Total Versions 2

Frequently Asked Questions

What is Soundcloud?

Interact with SoundCloud API for searching tracks, managing playlists, user operations, and audio discovery. Use when the user asks to search for music on So... It is an AI Agent Skill for Claude Code / OpenClaw, with 39 downloads so far.

How do I install Soundcloud?

Run "/install soundcloud" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Soundcloud free?

Yes, Soundcloud is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Soundcloud support?

Soundcloud is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Soundcloud?

It is built and maintained by Carlos Saucedo (@leosaucedo); the current version is v1.0.1.

More Skills

Soundcloud