功能描述

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

使用说明 (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

安全使用建议

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.

能力标签

requires-oauth-tokenrequires-sensitive-credentials

能力评估

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

版本历史

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

元数据

Slug soundcloud

版本 1.0.1

许可证 MIT-0

累计安装 1

当前安装数 1

历史版本数 2

常见问题

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... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 39 次。

如何安装 Soundcloud？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install soundcloud」即可一键安装，无需额外配置。

Soundcloud 是免费的吗？

是的，Soundcloud 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

Soundcloud 支持哪些平台？

Soundcloud 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Soundcloud？

由 Carlos Saucedo（@leosaucedo）开发并维护，当前版本 v1.0.1。

Soundcloud