SoundCloudX

A comprehensive, well-organized, and production-ready JavaScript package for interacting with the SoundCloud API using ES6 modules.

Author: HuyKaiser <@hksvn>

🚀 Features

• Modular Architecture: Clean separation of concerns with dedicated API modules
• ES6 Modules: Modern JavaScript with import/export syntax
• Comprehensive Coverage: All major SoundCloud API endpoints
• Robust Error Handling: Consistent error responses with retry logic
• TypeScript Ready: Full JSDoc documentation for better IDE support
• Production Ready: Configurable timeouts, retries, and performance optimizations
• Easy to Use: Simple API with both detailed and quick access methods

📦 Installation

npm install soundcloudx

🎯 Quick Start

import SoundCloudX from 'soundcloudx';

// Initialize with default settings
const soundcloud = new SoundCloudX();

// Get home page content
const homeContent = await soundcloud.discovery.getMixedSelections({ limit: 10 });

// Search for tracks
const searchResults = await soundcloud.search.searchTracks('electronic music', { limit: 20 });

// Get user profile
const userProfile = await soundcloud.users.getUser('603901965');

// Get track information
const trackInfo = await soundcloud.tracks.getTrackById('1345924513');

// Get playlist
const playlist = await soundcloud.playlists.getPlaylist('454981347');

🏗️ Architecture

src/
├── apis/                    # API modules
│   ├── discovery-api.js     # Home page and discovery features
│   ├── search-api.js        # Search functionality
│   ├── users-api.js         # User management
│   ├── tracks-api.js        # Track operations
│   └── playlists-api.js     # Playlist management
├── core/                    # Core functionality
│   └── http-client.js       # HTTP client with retry logic
├── config/                  # Configuration
│   └── api-config.js        # API constants and settings
└── index.js                 # Main entry point

📚 API Reference

Main Class: SoundCloudX

Constructor

const soundcloud = new SoundCloudX(options);

Options:

• clientId (string): Custom SoundCloud client ID
• timeout (number): Request timeout in milliseconds (default: 30000)
• maxRetries (number): Maximum retry attempts (default: 3)
• retryDelay (number): Delay between retries in milliseconds (default: 1000)

Methods

Configuration

• getInfo() - Get comprehensive API information
• getHeaders() - Get current HTTP headers
• setHeaders(headers) - Set custom HTTP headers
• setTimeout(timeout) - Set request timeout
• setRetryConfig(config) - Set retry configuration
• getConfig() - Get current configuration

Quick Access

// Quick access to popular endpoints
const home = await soundcloud.quick.home({ limit: 10 });
const search = await soundcloud.quick.searchTracks('query', { limit: 20 });
const user = await soundcloud.quick.user('userId');
const track = await soundcloud.quick.track('trackId');
const playlist = await soundcloud.quick.playlist('playlistId');

Discovery API

// Get mixed selections (home page content)
const mixedSelections = await soundcloud.discovery.getMixedSelections({ limit: 10 });

// Get recent tracks
const recentTracks = await soundcloud.discovery.getRecentTracks({ limit: 20 });

// Get recent tracks by genre
const genreTracks = await soundcloud.discovery.getRecentTracksByGenre('electronic', { limit: 15 });

// Get recent tracks by country
const countryTracks = await soundcloud.discovery.getRecentTracksCountry({ limit: 15 });

// Get available genres
const genres = await soundcloud.discovery.getAvailableGenres();

Search API

// Search tracks
const tracks = await soundcloud.search.searchTracks('query', { 
  limit: 20, 
  sort: 'hotness',
  filter: 'public' 
});

// Search users
const users = await soundcloud.search.searchUsers('artist', { 
  limit: 15,
  facet: 'place' 
});

// Search playlists
const playlists = await soundcloud.search.searchPlaylists('electronic', { limit: 10 });

// Search albums
const albums = await soundcloud.search.searchAlbums('rock', { limit: 10 });

// Search by genre
const genreTracks = await soundcloud.search.searchTracksByGenre('dance & edm', { 
  limit: 20,
  sort: 'popular' 
});

Users API

// Get user profile
const user = await soundcloud.users.getUser('userId');

// Get user spotlight
const spotlight = await soundcloud.users.getUserSpotlight('userId', { limit: 10 });

// Get user likes
const likes = await soundcloud.users.getUserLikes('userId', { limit: 20 });

// Get user followings
const followings = await soundcloud.users.getUserFollowings('userId', { limit: 15 });

// Get user tracks
const tracks = await soundcloud.users.getUserTracks('userId', { limit: 20 });

// Get user top tracks
const topTracks = await soundcloud.users.getUserTopTracks('userId', { limit: 10 });

// Get user playlists
const playlists = await soundcloud.users.getUserPlaylists('userId', { limit: 15 });

// Get comprehensive user information
const userInfo = await soundcloud.users.getUserInfo('userId', {
  includeSpotlight: true,
  includeLikes: true,
  includeFollowings: true,
  includeTracks: true,
  includePlaylists: true
});

Tracks API

// Get track by ID
const track = await soundcloud.tracks.getTrackById('trackId');

// Get multiple tracks by IDs
const tracks = await soundcloud.tracks.getTracksByIds(['id1', 'id2', 'id3']);

// Get track comments
const comments = await soundcloud.tracks.getTrackComments('trackId', { 
  limit: 50,
  threaded: 0 
});

// Get related tracks
const related = await soundcloud.tracks.getRelatedTracks('trackId', { 
  limit: 15,
  anonUserId: '14380503' 
});

// Get track media stream
const media = await soundcloud.tracks.getTrackMedia(
  'soundcloud:tracks:trackId',
  'uuid',
  'trackAuthorization'
);

// Get user tracks
const userTracks = await soundcloud.tracks.getUserTracks('userId', { 
  limit: 20,
  representation: 'full' 
});

// Get comprehensive track information
const trackInfo = await soundcloud.tracks.getTrackInfo('trackId', {
  includeComments: true,
  includeRelatedTracks: true,
  commentsLimit: 50,
  relatedTracksLimit: 15
});

Playlists API

// Get playlist by ID
const playlist = await soundcloud.playlists.getPlaylist('playlistId', { 
  representation: 'full' 
});

// Get playlist likers
const likers = await soundcloud.playlists.getPlaylistLikers('playlistId', { limit: 20 });

// Get playlist reposters
const reposters = await soundcloud.playlists.getPlaylistReposters('playlistId', { limit: 20 });

// Get playlist discovery by tag
const discovery = await soundcloud.playlists.getPlaylistDiscovery('country', { limit: 15 });

// Get user playlists
const userPlaylists = await soundcloud.playlists.getUserPlaylists('userId', { limit: 20 });

// Get comprehensive playlist information
const playlistInfo = await soundcloud.playlists.getPlaylistInfo('playlistId', {
  includeLikers: true,
  includeReposters: true,
  likersLimit: 20,
  repostersLimit: 20
});

// Get playlist statistics
const stats = await soundcloud.playlists.getPlaylistStats('playlistId');

🔧 Configuration

Custom Client ID

const soundcloud = new SoundCloudX({
  clientId: 'your-custom-client-id'
});

Custom Headers

soundcloud.setHeaders({
  'Custom-Header': 'value',
  'Authorization': 'Bearer your-token'
});

Timeout and Retry Settings

const soundcloud = new SoundCloudX({
  timeout: 60000,        // 60 seconds
  maxRetries: 5,         // 5 retry attempts
  retryDelay: 2000       // 2 seconds between retries
});

📝 Response Format

All API methods return a consistent response format:

{
  success: boolean,           // Whether the request was successful
  data: any,                 // Response data
  error: string | null,      // Error message if failed
  status: number,            // HTTP status code
  timestamp: string          // ISO timestamp
}

🧪 Testing

Run the test suite:

npm test

Run examples:

# Basic usage examples
npm run example:basic

# Advanced usage examples
npm run example:advanced

📖 Examples

Basic Usage

import SoundCloudX from 'soundcloudx';

const soundcloud = new SoundCloudX();

// Get trending content
const trending = await soundcloud.discovery.getMixedSelections({ limit: 10 });

// Search for your favorite artist
const results = await soundcloud.search.searchTracks('Alan Walker', { limit: 20 });

// Get user profile
const user = await soundcloud.users.getUser('603901965');
console.log(`${user.data.username} has ${user.data.followers_count} followers`);

Advanced Usage

// Comprehensive user analysis
const userAnalysis = await soundcloud.users.getUserInfo('603901965', {
  includeSpotlight: true,
  includeLikes: true,
  includeFollowings: true,
  includeTracks: true,
  includePlaylists: true
});

// Track analysis with comments and related tracks
const trackAnalysis = await soundcloud.tracks.getTrackInfo('2135043114', {
  includeComments: true,
  includeRelatedTracks: true,
  commentsLimit: 50,
  relatedTracksLimit: 15
});

// Playlist analysis with engagement metrics
const playlistAnalysis = await soundcloud.playlists.getPlaylistInfo('454981347', {
  includeLikers: true,
  includeReposters: true,
  likersLimit: 20,
  repostersLimit: 20
});

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• SoundCloud for providing the API
• The open-source community for inspiration and tools
• Contributors and users of this package

📞 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Discussions: GitHub Discussions

Made with ❤️ by HuyKaiser for the SoundCloud community