README

A PHP SDK for the SoundCloud Public API, built on Saloon.

Installation

composer require stanislavhannes/soundcloud

Authentication

SoundCloud supports two OAuth 2.1 flows. Which one you need depends on whether you want to access public data only or a specific user's private data.

Client Credentials

Use this for accessing public resources (tracks, playlists, public user profiles, search, URL resolution). The SDK automatically fetches an OAuth token and refreshes it when it expires (~1 hour).

Important: SoundCloud requires credentials to be sent as an HTTP Basic Auth header (Authorization: Basic Base64(client_id:client_secret)), not as form body fields. This SDK handles that automatically.

Important: The Me resource (/me/* endpoints) returns 401 Unauthorized with a client credentials token. These endpoints require a user-level token obtained via the Authorization Code flow. If you want to access your own followings, feed, likes etc., use the Users resource with your numeric user ID instead:

// Resolve your profile URL to get your numeric user ID
$userId = $client->miscellaneous()->resolveUrl('https://soundcloud.com/your-username')->json('id');

// Then use the public Users resource
$followings = $client->users()->userFollowings($userId, 200);

use Stanislavhannes\Soundcloud\Soundcloud;

$client = new Soundcloud();
$client->authenticateWithClientCredentials('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');

// All subsequent calls are automatically authenticated
$track = $client->tracks()->getTrack(123456789);

Authorization Code (OAuth 2.1 + PKCE)

Use this when you need to access or act on behalf of a specific user — their private tracks, feed, followings, likes, etc. This requires the user to log in via SoundCloud's connect screen. PKCE is required.

Once you have the user's access token, pass it directly:

use Stanislavhannes\Soundcloud\Soundcloud;
use Saloon\Http\Auth\TokenAuthenticator;

$client = new Soundcloud();
$client->authenticate(new TokenAuthenticator('USER_ACCESS_TOKEN'));

// Me resource now works
$profile   = $client->me()->userInfo();
$followings = $client->me()->userFollowings(50, null);

See the SoundCloud API guide for how to implement the full redirect + PKCE + token exchange flow.

Manual Token

If you already have an access token from any source:

use Stanislavhannes\Soundcloud\Soundcloud;
use Saloon\Http\Auth\TokenAuthenticator;

$client = new Soundcloud();
$client->authenticate(new TokenAuthenticator('YOUR_ACCESS_TOKEN'));

Internal Mode

SoundCloud's unofficial api-v2.soundcloud.com endpoint allows broader access using only a client_id. Useful for read-only use cases without user authentication.

use Stanislavhannes\Soundcloud\Soundcloud;

$client = new Soundcloud();
$client->enableInternalMode('YOUR_CLIENT_ID');

$track = $client->tracks()->getTrack(123456789);

Available Resources

Tracks

// Get a track
$client->tracks()->getTrack($trackId, $secretToken);

// Upload a track
$client->tracks()->uploadTrack();

// Update a track
$client->tracks()->updateTrack($trackId);

// Delete a track
$client->tracks()->deleteTrack($trackId);

// Start a track preview
$client->tracks()->trackPreview($trackId, $secretToken);

// Get streaming URLs
$client->tracks()->trackStreams($trackId, $secretToken);

// Get related tracks
$client->tracks()->relatedTracks($trackId, $access, $limit, $offset, $linkedPartitioning);

// Get comments
$client->tracks()->getTrackComments($trackId, $limit, $offset, $linkedPartitioning);

// Post a comment
$client->tracks()->createComment($trackId);

// Get playlists containing this track
$client->tracks()->getTrackPlaylists($trackId, $limit, $offset, $linkedPartitioning);

// Get users who liked the track
$client->tracks()->trackFavoriters($trackId, $limit, $linkedPartitioning);

// Get users who reposted the track
$client->tracks()->trackReposters($trackId, $limit);

Playlists

// Get a playlist
$client->playlists()->getPlaylist($playlistId, $secretToken, $access, $showTracks);

// Create a playlist
$client->playlists()->createPlaylist();

// Update a playlist
$client->playlists()->updatePlaylist($playlistId);

// Delete a playlist
$client->playlists()->deletePlaylist($playlistId);

// Get playlist tracks
$client->playlists()->playlistTracks($playlistId, $secretToken, $access, $linkedPartitioning);

// Get users who reposted the playlist
$client->playlists()->playlistReposters($playlistId, $limit);

Users

// Get a user
$client->users()->getUser($userId);

// Get user's tracks
$client->users()->userTracks($userId, $access, $limit, $linkedPartitioning);

// Get user's playlists
$client->users()->userPlaylists($userId, $access, $showTracks, $limit, $linkedPartitioning);

// Get user's liked tracks
$client->users()->userLikedTracks($userId, $access, $limit, $linkedPartitioning);

// Get user's liked playlists
$client->users()->userLikedPlaylists($userId, $limit, $linkedPartitioning);

// Get user's followers
$client->users()->userFollowers($userId, $limit);

// Get users the user is following
$client->users()->userFollowings($userId, $limit);

// Get user's web profiles / social links
$client->users()->userWebProfiles($userId, $limit);

Me (authenticated user)

Requires Authorization Code token. All /me endpoints return 401 Unauthorized when using a client credentials token. See the Authentication section for details.

// Get your profile
$client->me()->userInfo();

// Get your feed
$client->me()->userFeed($access, $limit);

// Get your track feed
$client->me()->userTrackFeed($access, $limit);

// Get your tracks
$client->me()->userTracks($limit, $linkedPartitioning);

// Get your playlists
$client->me()->userPlaylists($showTracks, $linkedPartitioning, $limit);

// Get your liked tracks
$client->me()->userLikedTracks($limit, $access, $linkedPartitioning);

// Get your liked playlists
$client->me()->userLikedPlaylists($limit, $linkedPartitioning);

// Get your followers
$client->me()->userFollowers($limit);

// Get users you follow
$client->me()->userFollowings($limit, $offset);

// Get recent tracks from users you follow
$client->me()->followingsRecentTracks($access, $limit, $offset);

// Follow / unfollow a user
$client->me()->followUser($userId);
$client->me()->unfollowUser($userId);

Search

// Search tracks
$client->search()->searchTracks($q, $ids, $genres, $tags, $bpm, $duration, $createdAt, $access, $limit, $offset, $linkedPartitioning);

// Search playlists
$client->search()->searchPlaylists($q, $access, $showTracks, $limit, $offset, $linkedPartitioning);

// Search users
$client->search()->searchUsers($q, $ids, $limit, $offset, $linkedPartitioning);

Likes

$client->likes()->likeTrack($trackId);
$client->likes()->unlikeTrack($trackId);
$client->likes()->likePlaylist($playlistId);
$client->likes()->unlikePlaylist($playlistId);

Reposts

$client->reposts()->repostTrack($trackId);
$client->reposts()->repostPlaylist($playlistId);
$client->reposts()->removePlaylistRepost($playlistId);

OAuth

// Fetch a token manually using client credentials
$response = $client->oauth()->clientCredentials($clientId, $clientSecret);
$token = $response->json('access_token');

// Sign out (invalidates the current session token)
$client->oauth()->signOut();

Miscellaneous

// Resolve a soundcloud.com URL to its API resource URL
$client->miscellaneous()->resolveUrl('https://soundcloud.com/artist/track-name');

License

This package is open-sourced software licensed under the MIT license.