soundcloud-core 1.0.0

package/src/plugin/profile.js

@@ -0,0 +1,127 @@
+// Copyright (c) 2026 BlazeInferno64 --> https://github.com/blazeinferno64.
+//
+// Author(s) -> BlazeInferno64
+//
+// Last updated: 09/07/2026
+
+const { ua } = require('./user-agent');
+const { getFreshClientID } = require('./client-id');
+
+// Accepts either a bare username ("BlazeInferno64") or a full profile URL and normalizes it into
+// something the resolve endpoint can work with either way.
+const normalizeProfileUrl = (input) => {
+    if (/^https?:\/\//i.test(input)) return input;
+    return `https://soundcloud.com/${input.trim().toLowerCase()}`;
+};
+
+const fetchProfile = async (profileInput, userAgent, clientID) => {
+    try {
+        if (!profileInput || typeof profileInput !== "string") {
+            throw new Error("Invalid username or profile URL provided!");
+        }
+
+        if (!clientID) clientID = await getFreshClientID(userAgent);
+
+        const profileUrl = normalizeProfileUrl(profileInput);
+        const resolveUrl = `https://api-v2.soundcloud.com/resolve?url=${encodeURIComponent(profileUrl)}&client_id=${clientID}`;
+
+        const response = await fetch(resolveUrl, {
+            headers: {
+                'User-Agent': userAgent || ua,
+            }
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to resolve profile. Status: ${response.status}`);
+        }
+
+        const user = await response.json();
+
+        //console.log("Resolved user data:", user); // Debugging log to inspect the resolved user object
+
+        // The resolve endpoint can also return tracks/playlists depending on what the URL points to -
+        // we only want an actual user profile here.
+        if (!user || user.kind !== "user") {
+            throw new Error(`Provided username/URL did not resolve to a profile (kind: ${user?.kind || "unknown"}).`);
+        }
+
+        // The banner image at the top of a profile page lives under visuals, not avatar_url - falls back
+        // to null since plenty of profiles don't have one set.
+        const headerUrl = user.visuals?.visuals?.[0]?.visual_url || null;
+
+        const profileData = {
+            id: user.id,
+            urn: user.urn || null, // internal stable identifier, e.g. "soundcloud:users:1197971329" - useful if you're caching/de-duping across requests
+            username: user.username,
+            firstName: user.first_name || null,
+            lastName: user.last_name || null,
+            fullName: user.full_name || null,
+            permalink: user.permalink || null, // short slug ("blazeinferno64"), as opposed to the full permalinkUrl below
+            permalinkUrl: user.permalink_url,
+            description: user.description || null,
+
+            kind: user.kind || null, // should always be "user" for a profile, but included for completeness
+
+            location: {
+                city: user.city || null,
+                country: user.country_code || null
+            },
+
+            avatarUrl: user.avatar_url?.replace("-large.jpg", "-t500x500.jpg"),
+            headerUrl,
+
+            // Pro/Pro Unlimited/verified badges - shown next to the username on the real profile page
+            badges: {
+                verified: !!user.badges?.verified,
+                pro: !!user.badges?.pro,
+                proUnlimited: !!user.badges?.pro_unlimited
+            },
+
+            subscriptions: {
+                creatorSubscriptions: user.creator_subscriptions.products || [], // array of subscription product IDs the user is subscribed to (e.g. "creator_subscription:premium")
+                // The `creator_subscription` field is a newer addition to SoundCloud's subscription model, allowing users to support specific creators directly. The `product.id` can be used to identify the specific subscription product.
+                creatorSubscription: user.creator_subscription.product?.id,
+            },
+
+            // External links from the profile's "Links" section (personal site, Instagram, Twitter/X, etc.)
+            webProfiles: (user.web_profiles || []).map(link => ({
+                network: link.network,
+                title: link.title || null,
+                url: link.url
+            })),
+
+            // A user's "station" is what SoundCloud autoplays after their tracks finish (their own radio mix) -
+            // both fields are internal identifiers, not directly a browsable page URL.
+            station: {
+                urn: user.station_urn || null,
+                permalink: user.station_permalink || null
+            },
+
+            // Stats you'd see laid out on the profile page itself
+            stats: {
+                followers: user.followers_count,
+                following: user.followings_count,
+                tracks: user.track_count,
+                playlists: user.playlist_count,
+                playlistLikes: user.playlist_likes_count,
+                likes: user.public_favorites_count ?? user.likes_count,
+                reposts: user.reposts_count,
+                comments: user.comments_count,
+                groups: user.groups_count,
+                dateOfBirth: user.date_of_birth || null,
+                // Note: SoundCloud doesn't provide a "total plays" stat for a user profile, only per-track plays.
+            },
+
+            createdAt: user.created_at,
+            lastModified: user.last_modified || null // last time this profile's data changed on SoundCloud's end
+        };
+
+        return profileData;
+    } catch (e) {
+        throw new Error("Failed to fetch profile!");
+    }
+}
+
+module.exports = {
+    fetchProfile
+}

package/src/plugin/search.js

@@ -0,0 +1,74 @@
+// Copyright (c) 2026 BlazeInferno64 --> https://github.com/blazeinferno64.
+//
+// Author(s) -> BlazeInferno64
+//
+// Last updated: 09/05/2026
+
+const { ua } = require('./user-agent');
+const { getFreshClientID } = require('./client-id');
+
+const search = async (query, userAgent, clientID, options = {}) => {
+    try {
+        if (!query || typeof query !== "string") {
+            throw new Error("Invalid search query provided!");
+        }
+
+        if (!clientID) clientID = await getFreshClientID(userAgent);
+
+        const limit = options.limit || 10; // How many results to return - defaults to 10, same as the web app's initial batch
+
+        const searchUrl = `https://api-v2.soundcloud.com/search/tracks?q=${encodeURIComponent(query)}&client_id=${clientID}&limit=${limit}`;
+
+        const response = await fetch(searchUrl, {
+            headers: {
+                'User-Agent': userAgent || ua,
+            }
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to search tracks. Status: ${response.status}`);
+        }
+
+        const data = await response.json();
+
+        // The search endpoint wraps results in a "collection" array - bail out early if it's missing/empty
+        if (!data || !Array.isArray(data.collection)) {
+            return [];
+        }
+
+        // Trim each track down to what you'd actually want from a search result (not the full track.js payload -
+        // no streamUrl/trackAuthorization here since these are just candidates, not a resolved track yet)
+        const results = data.collection.map(track => ({
+            id: track.id,
+            title: track.title,
+            permalinkUrl: track.permalink_url,
+            duration: track.duration, // in milliseconds
+            genre: track.genre,
+
+            artworkUrl: track.artwork_url
+                ? track.artwork_url.replace("-large.jpg", "-t500x500.jpg")
+                : track.user?.avatar_url?.replace("-large.jpg", "-t500x500.jpg"),
+
+            artist: {
+                id: track.user?.id,
+                username: track.user?.username,
+                profileUrl: track.user?.permalink_url
+            },
+
+            stats: {
+                plays: track.playback_count,
+                likes: track.likes_count,
+                comments: track.comment_count,
+                reposts: track.reposts_count
+            }
+        }));
+
+        return results;
+    } catch (e) {
+        throw new Error("Failed to search tracks!");
+    }
+}
+
+module.exports = {
+    search
+}

package/src/plugin/track.js

@@ -0,0 +1,102 @@
+// Copyright (c) 2026 BlazeInferno64 --> https://github.com/blazeinferno64.
+//
+// Author(s) -> BlazeInferno64
+//
+// Last updated: 09/05/2026
+
+const { ua } = require('./user-agent');
+const { getFreshClientID } = require('./client-id');
+const { getCDNUrl } = require('./cdn');
+
+const cheerio = require("cheerio");
+
+const fetchSong = async (songUrl, userAgent, clientID) => {
+    try {
+        if (!songUrl || typeof songUrl !== "string") {
+            throw new Error("Invalid song URL provided!");
+        }
+
+        const resolveUrl = `https://api-v2.soundcloud.com/resolve?url=${encodeURIComponent(songUrl)}&client_id=${clientID}`;
+
+        const response = await fetch(resolveUrl, {
+            headers: {
+                'User-Agent': userAgent || ua,
+            }
+        })
+
+        if (!response.ok) {
+            throw new Error(`Failed to resolve song URL. Status: ${response.status}`);
+        }
+
+        let track = await response.json();
+
+        // The resolve endpoint can also return sets/users/playlists - we only want single tracks here.
+        if (!track || track.kind !== "track") {
+            throw new Error(`Provided URL did not resolve to a single track (kind: ${track?.kind || "unknown"}).`);
+        }
+
+        // Some resolved tracks omit media/track_authorization - fetch the full track record.
+        if (!track.media || !track.track_authorization) {
+            const trackRes = await fetch(`https://api-v2.soundcloud.com/tracks/${track.id}?client_id=${clientID}`, {
+                headers: {
+                    'User-Agent': userAgent || ua,
+                }
+            });
+            track = await trackRes.json();
+        }
+
+        const cdnUrl = await getCDNUrl(track, clientID, userAgent || ua);
+
+        if (!cdnUrl) {
+            throw new Error(`No playable stream found for track: ${track.title}`);
+        }
+
+        const songData = {
+            id: track.id,
+            title: track.title,
+            description: track.description,
+            duration: track.duration, // in milliseconds
+            genre: track.genre,
+            createdAt: track.created_at,
+
+            // Artist Metadata
+            artist: {
+                id: track.user.id,
+                username: track.user.username,
+                profileUrl: track.user.permalink_url,
+                avatarUrl: track.user.avatar_url?.replace("-large.jpg", "-t500x500.jpg")
+            },
+
+            // Visual Assets (Upgraded to high-res, falling back to avatar)
+            artworkUrl: track.artwork_url
+                ? track.artwork_url.replace("-large.jpg", "-t500x500.jpg")
+                : track.user.avatar_url?.replace("-large.jpg", "-t500x500.jpg"),
+
+            // Album / Publisher Info
+            album: track.publisher_metadata?.album_title || null,
+            label: track.publisher_metadata?.label_name || null,
+
+            // Playback & CDN (The crucial part for your client)
+            streamUrl: cdnUrl, // The final resolved HLS or progressive MP3 link
+            trackAuthorization: track.track_authorization || null,
+
+            // Engagement Stats (What you see on the web page)
+            stats: {
+                plays: track.playback_count,
+                likes: track.likes_count,
+                reposts: track.reposts_count,
+                comments: track.comment_count
+            }
+        }
+
+        return songData;
+    } catch (e) {
+        throw new Error("Failed to fetch song!");
+    }
+}
+
+
+module.exports = {
+    fetchSong
+}
+

package/src/plugin/user-agent.js

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 BlazeInferno64 --> https://github.com/blazeinferno64.
+//
+// Author(s) -> BlazeInferno64
+//
+// Last updated: 09/05/2026
+"use strict";
+
+/**
+ * Keep a consistent user-agent for all requests to avoid detection and rate limiting.
+ * This is especially important for SoundCloud API requests.
+ */
+const ua = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36';
+
+
+module.exports = {
+    ua
+}

package/src/soundcloud.js

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 BlazeInferno64 --> https://github.com/blazeinferno64.
+//
+// Author(s) -> BlazeInferno64
+//
+// Last updated: 07/09/2026
+"use strict";
+
+const { ua } = require('./plugin/user-agent');
+const { getFreshClientID } = require('./plugin/client-id');
+const { fetchSong } = require('./plugin/track');
+const { search } = require('./plugin/search');
+const { fetchPlaylist } = require('./plugin/playlist');
+const { fetchProfile } = require('./plugin/profile');
+
+//const cheerio = require("cheerio");
+
+class SoundCloudClient {
+    constructor(options = {}) {
+        this._useragent = options ? options.userAgent : ua; // Use the provided user agent or default to the one from user-agent.js
+        this._clientId = options ? options.clientId : getFreshClientID(this._useragent); // Fetch one if not provided!
+    }
+
+    async getClientId() {
+        if (!this._clientId) {
+            this._clientId = await getFreshClientID(this._useragent);
+        }
+        return this._clientId;
+    }
+
+    async getMetaData(songOptions) {
+        const { url, userAgent } = songOptions;
+        const clientId = await this._clientId || await this.getClientId(this._useragent);
+        const finalUserAgent = userAgent || this._useragent;
+        
+        // Validate inputs
+        if (!url) throw new Error("No song URL provided!");
+        if (!clientId) throw new Error("No client ID available! Please provide one or allow the client to fetch it.");
+        
+        // Fetch the song metadata using the provided URL, user agent, and client ID
+        return await fetchSong(url, finalUserAgent, clientId);
+    }
+
+    async getPlaylist(playlistOptions) {
+        const { url, userAgent, limit = 10 } = playlistOptions;
+        const clientId = await this._clientId || await this.getClientId(this._useragent);
+        const finalUserAgent = userAgent || this._useragent;
+
+        // Validate inputs
+        if (!url) throw new Error("No playlist URL provided!");
+        if (!clientId) throw new Error("No client ID available! Please provide one or allow the client to fetch it.");
+
+        // Fetch the playlist metadata using the provided URL, user agent, and client ID.
+        // `limit` caps how many tracks come back - a positive integer, or "max" for the whole playlist.
+        return await fetchPlaylist(url, finalUserAgent, clientId, limit);
+    }
+
+    async getProfile(profileOptions) {
+        const { username, userAgent } = profileOptions;
+        const clientId = await this._clientId || await this.getClientId(this._useragent);
+        const finalUserAgent = userAgent || this._useragent;
+
+        // Validate inputs
+        if (!username) throw new Error("No username or profile URL provided!");
+        if (!clientId) throw new Error("No client ID available! Please provide one or allow the client to fetch it.");
+
+        // `username` accepts either a bare username ("BlazeInferno64") or a full profile URL
+        return await fetchProfile(username, finalUserAgent, clientId);
+    }
+
+    async search(searchOptions = {}) {
+        const { query, userAgent, ...options } = searchOptions;
+        const clientId = await this._clientId || await this.getClientId(this._useragent);
+        const finalUserAgent = userAgent || this._useragent;
+
+        // Validate inputs
+        if (!query) throw new Error("No search query provided!");
+        if (!clientId) throw new Error("No client ID available! Please provide one or allow the client to fetch it.");
+
+        // Search for tracks matching the query, using the provided user agent and client ID
+        return await search(query, finalUserAgent, clientId, options);
+    }
+}
+
+
+module.exports = {
+    SoundCloudClient
+}