soundcloud-core 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 BlazeInferno64 --> https://github.com/blazeinferno64
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+[![NPM Version](http://img.shields.io/npm/v/soundcloud-core.svg?style=flat-square)](https://npmjs.com/package/soundcloud-core)
+[![Dependencies](https://img.shields.io/badge/dependencies-0-success?style=flat-square)](https://www.npmjs.com/package/soundcloud-core?activeTab=dependencies)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D%2018.0.0-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+[![NPM Downloads](https://img.shields.io/npm/dm/soundcloud-core.svg?style=flat-square)](https://npm-stat.com/charts.html?package=soundcloud-core)
+[![Install Size](https://packagephobia.com/badge?p=soundcloud-core&style=flat-square)](https://packagephobia.com/result?p=soundcloud-core)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/soundcloud-core?style=flat-square)](https://bundlephobia.com/package/soundcloud-core@latest)
+
+![GitHub last commit](https://img.shields.io/github/last-commit/blazeinferno64/soundcloud-core?style=flat-square)
+![GitHub issues](https://img.shields.io/github/issues/blazeinferno64/soundcloud-core?style=flat-square)
+[![Gitpod Ready-to-code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod&style=flat-square)](https://gitpod.io/#https://github.com/blazeinferno64/soundcloud-core)
+[![Author](https://img.shields.io/badge/author-BlazeInferno64-orange?style=flat-square&logo=github)](https://github.com/blazeinferno64)
+![GitHub Repo stars](https://img.shields.io/github/stars/blazeinferno64/soundcloud-core?style=social)
+
+# soundcloud-core
+
+> Fast, Minimalist, Unofficial SoundCloud v2 API client wrapper for [Node.js](https://nodejs.org)
+
+## Disclaimer & Terms of Use
+
+This project is an independent, unofficial wrapper for the **SoundCloud v2 API**. It is **not** affiliated, endorsed, sponsored, or officially connected with SoundCloud Limited in any way. 
+
+The author and contributors do not encourage, condone, or support any misuse of the [SoundCloud API](https://developers.soundcloud.com/), scraping practices, or any actions that violate [SoundCloud's Terms of Service](https://soundcloud.com/terms-of-use), [API Terms of Use](https://developers.soundcloud.com/docs/api/terms-of-use), or platform policies. This library is provided for educational and experimental purposes only. Users are solely responsible for ensuring that their usage of this software complies with **SoundCloud's official terms and applicable laws**.
+
+# Installation
+
+To get started with `soundcloud-core`, simply run the following command in your terminal:
+
+Using [npm](https://npmjs.com) installation command:
+
+```bash
+$ npm i soundcloud-core
+```
+
+Using [yarn](https://yarnpkg.com) installation command:
+
+```bash
+$ yarn add soundcloud-core
+```
+
+Using [bun](https://bun.sh) installation command:
+
+```bash
+$ bun add soundcloud-core
+```
+# Info
+
+New to Promises?
+
+If you're not familiar with promises, check out the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to learn more.
+
+## Built on Top of Node.js HTTP library
+
+Under the hood, `soundcloud-core` uses the native [Fetch API](https://nodejs.org/learn/getting-started/fetch) provided by Node.js (undici), ensuring a seamless and efficient experience without any third party packages.
+
+# Getting started
+
+First, require/import this library to your project as follows:
+
+```js
+const { SoundCloudClient } = require("soundcloud-core");
+```
+
+If it's an ES Module then import it to your project as follows:
+
+```js
+import { SoundCloudClient } from "soundcloud-core";
+```
+
+Then spin up a client and you're good to go:
+
+```js
+const client = new SoundCloudClient();
+```
+
+# Client Id
+
+As per [SoundCloud's v2 API](https://developers.soundcloud.com/), no client id is strictly necessary to use this library - if you don't pass one in, `soundcloud-core` will quietly go fetch a fresh one for you the first time it actually needs it (by pulling it straight off [soundcloud.com](https://soundcloud.com)), and reuse it for the lifetime of the client.
+
+That said, if you already have a `client_id` lying around (or you're hitting rate limits and want a bit more control over when/how it's fetched), you can just hand it to the constructor yourself:
+
+```js
+const client = new SoundCloudClient({
+    // Leave it empty, incase you don't have one!
+    clientId: "your_client_id"
+});
+```
+
+You can also grab whatever `client_id` the client ends up using, in case you want to cache it or reuse it elsewhere:
+
+```js
+const clientId = await client.getClientId();
+console.log(clientId);
+```
+
+# Usage
+
+Every method on `SoundCloudClient` returns a promise, so `await` them (or `.then()` them) inside an `async` function.
+
+## Fetching a track
+
+```js
+const client = new SoundCloudClient();
+
+const track = await client.getMetaData({
+    url: "https://soundcloud.com/martingarrix/martin-garrix-animals-original" // Martin Garrix - Animals
+});
+
+console.log(track.title);      // "Track Name"
+console.log(track.streamUrl);  // Playable HLS/progressive stream (Best for audio quality) URL (short-lived!)
+```
+
+Keep in mind `streamUrl` is short-lived and will expire after a while, so don't go caching it for later - fetch it fresh whenever you actually need to stream the track.
+
+## Fetching a playlist
+
+```js
+const playlist = await client.getPlaylist({
+    // Place your playlist url here, for example I'am placing my playlist url here
+    url: "https://soundcloud.com/blazeinferno64/sets/only-house",
+    limit: 20 // grab up to 20 tracks, or pass "max" for the whole playlist
+});
+
+console.log(playlist.title, playlist.trackCount);
+playlist.tracks.forEach(track => console.log(track.title));
+```
+
+## Fetching a user profile
+
+```js
+// A bare username works just as well as a full profile URL
+const profile = await client.getProfile({
+    // Your username here, for example I'am placing my username here
+    username: "BlazeInferno64"
+});
+
+console.log(profile.username, profile.stats.followers);
+```
+
+## Searching for tracks
+
+```js
+const results = await client.search({
+    query: "Martin Garrix - Animals", // Any song you want to search
+    limit: 15
+});
+
+results.forEach(track => console.log(track.title, "-", track.artist.username));
+```
+
+# LICENSE
+
+`soundcloud-core` is released under the MIT License.
+
+View the full license terms <a href="https://github.com/BlazeInferno64/soundcloud-core/blob/main/LICENSE">here</a>.
+
+# Bugs & Issues
+
+Found a bug or want a new feature?
+
+Report issues and request features on the [soundcloud-core issue tracker](https://github.com/blazeinferno64/soundcloud-core/issues).
+
+`Thanks for reading!`
+
+`Have a great day ahead :D`

package/index.js

@@ -0,0 +1,40 @@
+// Copyright (c) 2026 BlazeInferno64 --> https://github.com/blazeinferno64.
+//
+// Author(s) -> BlazeInferno64
+//
+// Last updated: 10/09/2026
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+"use strict";
+/**
+ * soundcloud-core is a Fast, Minimalist, Unofficial SoundCloud v2 API client wrapper for [Node.js](https://nodejs.org)
+ * 
+ * SoundCloud API Requests done right!
+ * 
+ * Learn more about it from [here](https://github.com/blazeinferno64/soundcloud-core)
+ * @example 
+ * // Require it in your project by doing -
+ * const { SoundCloudClient } = require("soundcloud-core");
+ * 
+ * // Or import it to your project if its an ES module by doing -
+ * import { SoundCloudClient } from "soundcloud-core";
+ */
+module.exports = require("./src/soundcloud-core");

package/package.json

@@ -0,0 +1,89 @@
+{
+  "dependencies": {
+    "cheerio": "^1.2.0"
+  },
+  "name": "soundcloud-core",
+  "version": "1.0.0",
+  "description": "Fast, Minimalist, Unofficial SoundCloud v2 API client wrapper for Node.js",
+  "main": "index.js",
+  "devDependencies": {},
+  "scripts": {
+    "test": "echo \"All success!\" && exit 1"
+  },
+  "types": "typings/index.d.ts",
+  "contributors": [
+    "BlazeInferno64",
+    "blazeinferno"
+  ],
+  "keywords": [
+    "blazed",
+    "blazed.js",
+    "HTTP-Client",
+    "blazed-http-client",
+    "nodejs",
+    "javascript",
+    "node-http",
+    "node-fetch",
+    "axios",
+    "gaxios",
+    "node",
+    "https",
+    "http",
+    "json",
+    "automatic-json-parser",
+    "json-server",
+    "http/2",
+    "ws",
+    "node-blazed.js",
+    "node-http/2",
+    "node-https",
+    "express",
+    "typescript",
+    "connect",
+    "got",
+    "git",
+    "htmx",
+    "www",
+    "npm",
+    "high-peformance",
+    "keep-Alive",
+    "apache",
+    "http/1.1",
+    "http/1",
+    "http/3",
+    "ai",
+    "openai",
+    "api",
+    "binary",
+    "microsoft",
+    "google",
+    "gemini",
+    "cloudflare",
+    "dns",
+    "dns-client",
+    "light-weight",
+    "fast-http-client",
+    "promise-based-http-client",
+    "eslint",
+    "openjs",
+    "regex",
+    "light-weight",
+    "babel__core",
+    "soundcloud",
+    "soundcloud-core",
+    "soundcloud.ts",
+    "soundcloud-core",
+    "youtube",
+    "ytdl-core",
+    "yt-music",
+    "yt"
+  ],
+  "author": "BlazeInferno64",
+  "license": "MIT",
+  "homepage": "https://github.com/blazeinferno64/soundcloud-core#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blazeinferno64/soundcloud-core.git"
+  },
+  "type": "commonjs"
+}

package/src/plugin/cdn.js

@@ -0,0 +1,69 @@
+// 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 cheerio = require("cheerio");
+
+const getCDNUrl = async (track, clientID, userAgent) => {
+    try {
+        if (!track) throw new Error("Track ID is required to fetch the CDN URL.");
+        if (!clientID) clientID = await getFreshClientID(userAgent);
+
+        if (!track.media?.transcodings?.length) return null;
+
+        const transcodings = track.media.transcodings;
+
+        // TOP PRIORITY: High Quality AAC (HLS)
+        let transcoding = transcodings.find(t =>
+            t.format.protocol === 'hls' &&
+            t.preset.includes('aac')
+        );
+
+        // SECOND PRIORITY: Standard Progressive MP3
+        if (!transcoding) {
+            transcoding = transcodings.find(t =>
+                t.format.protocol === 'progressive' &&
+                t.format.mime_type.includes('audio/mpeg')
+            );
+        }
+
+        // LAST RESORT: Anything that isn't Opus
+        if (!transcoding) {
+            transcoding = transcodings.find(t => !t.preset.includes('opus'));
+        }
+
+        if (!transcoding) return null;
+
+        // Construct the final URL with the client_id and optional track_authorization
+        let url = `${transcoding.url}?client_id=${clientID}`;
+        if (track.track_authorization) {
+            // Append the track_authorization parameter if it exists
+            url += `&track_authorization=${track.track_authorization}`;
+        }
+
+        // Here we make the request to get the actual CDN URL to stream the track. We use the provided userAgent or default to the one from user-agent.js.
+        const response = await fetch(url, {
+            headers: {
+                'User-Agent': userAgent || ua,
+                'Accept': 'application/json' // Requesting JSON response
+            }
+        })
+
+        const data = await response.json();
+        return data.url; // Return the actual CDN URL for streaming! If HLS, this will be a .m3u8 playlist URL; if progressive, it will be a direct .mp3 URL.
+
+    } catch (e) {
+        // If any error occurs during the process, we throw an error with a descriptive message.
+        throw new Error(`Cannot fetch CDN URL for track ${track}: ${e.message ? e.message : e}`);
+    }
+}
+
+// Export the functions
+module.exports = {
+    getCDNUrl
+}

package/src/plugin/client-id.js

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 BlazeInferno64 --> https://github.com/blazeinferno64.
+//
+// Author(s) -> BlazeInferno64
+//
+// Last updated: 09/05/2026
+
+"use strict";
+
+const { ua } = require('./user-agent');
+
+const cheerio = require("cheerio");
+
+const getFreshClientID = async (userAgent) => {
+    try {
+        const response = await fetch('https://soundcloud.com', {
+            headers: {
+                'User-Agent': userAgent || ua,
+            }
+        });
+
+        const html = await response.text();
+        const $ = cheerio.load(html);
+
+        // Find all script tags with src attributes that contain 'sndcdn.com/assets/'
+        const scriptUrls = [];
+        $('script[src]').each((i, el) => {
+            const src = $(el).attr('src');
+            // Search for the client_id pattern in the script content
+            if (src && src.includes('sndcdn.com/assets/')) {
+                scriptUrls.push(src);
+            }
+        });
+
+        // Iterate through the script URLs in reverse order to find the latest one
+        for (const url of scriptUrls.reverse()) {
+            const jsRes = await fetch(url, {
+                headers: {
+                    'User-Agent': userAgent || ua,
+                    // intentionally not forcing Content-Type to match original behavior
+                }
+            });
+            const jsContent = await jsRes.text();
+
+            // Yeps! We found the client_id in the script content
+            const match = jsContent.match(/client_id[:=]\s*["']([a-zA-Z0-9]{32})["']/);
+            if (match && match[1]) {
+                // FINALLY! Return the client_id if found or else skip it
+                return match[1];
+            }
+        }
+    } catch (e) {
+        // Well, SoundCloud might have changed their structure or something went wrong, so we throw an error or have blocked the request. 
+        // Either way, we can't get the client_id now :(
+        throw new Error(`Cannot fetch clientID from SoundCloud: ${e.message ? e.message : e}`);
+    }
+}
+
+
+module.exports = {
+    getFreshClientID
+}

package/src/plugin/playlist.js

@@ -0,0 +1,151 @@
+// 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');
+
+const CHUNK_SIZE = 50; // SoundCloud's batch tracks endpoint caps out around here - stay safely under it
+
+// `limit` accepts a positive integer (how many tracks to include) or the string "max" (every track in the playlist).
+// Returns Infinity for "max" so the slice() below just takes everything.
+const resolveLimit = (limit) => {
+    if (limit === 'max') return Infinity;
+    if (typeof limit === 'number' && Number.isInteger(limit) && limit > 0) return limit;
+    throw new Error(`Invalid limit provided! Expected a positive integer or "max", got: ${JSON.stringify(limit)}`);
+};
+
+// Turn a raw track (whether it came inline or from a batch fetch) into the same reduced shape.
+// track === null covers the case where a stub id couldn't be resolved (deleted/private/geo-blocked).
+const reduceTrack = (id, track) => {
+    if (!track) {
+        return { id, title: null, permalinkUrl: null, duration: null, genre: null, artworkUrl: null, artist: null };
+    }
+
+    return {
+        id: track.id,
+        title: track.title,
+        permalinkUrl: track.permalink_url,
+        duration: track.duration,
+        genre: track.genre,
+        artworkUrl: track.artwork_url
+            ? track.artwork_url.replace("-large.jpg", "-t500x500.jpg")
+            : (track.user?.avatar_url?.replace("-large.jpg", "-t500x500.jpg") || null),
+        artist: track.user ? {
+            id: track.user.id,
+            username: track.user.username,
+            profileUrl: track.user.permalink_url
+        } : null
+    };
+};
+
+// Fetches full track data for a batch of stub ids, chunked to stay under SoundCloud's per-request limit.
+// Returns a Map of id -> raw track so failed/missing ids can just fall back to null downstream.
+const resolveStubTracks = async (ids, userAgent, clientID) => {
+    const resolved = new Map();
+
+    for (let i = 0; i < ids.length; i += CHUNK_SIZE) {
+        const chunk = ids.slice(i, i + CHUNK_SIZE);
+        const idsUrl = `https://api-v2.soundcloud.com/tracks?ids=${chunk.join(',')}&client_id=${clientID}`;
+
+        const response = await fetch(idsUrl, {
+            headers: {
+                'User-Agent': userAgent || ua,
+            }
+        });
+
+        if (!response.ok) continue; // Skip a bad chunk rather than failing the whole playlist over a few tracks
+
+        const chunkTracks = await response.json();
+        for (const track of chunkTracks) {
+            resolved.set(track.id, track);
+        }
+    }
+
+    return resolved;
+};
+
+const fetchPlaylist = async (playlistUrl, userAgent, clientID, limit = 10) => {
+    try {
+        if (!playlistUrl || typeof playlistUrl !== "string") {
+            throw new Error("Invalid playlist URL provided!");
+        }
+
+        const maxTracks = resolveLimit(limit);
+
+        if (!clientID) clientID = await getFreshClientID(userAgent);
+
+        const resolveUrl = `https://api-v2.soundcloud.com/resolve?url=${encodeURIComponent(playlistUrl)}&client_id=${clientID}`;
+
+        const response = await fetch(resolveUrl, {
+            headers: {
+                'User-Agent': userAgent || ua,
+            }
+        });
+
+        if (!response.ok) {
+            throw new Error(`Failed to resolve playlist URL. Status: ${response.status}`);
+        }
+
+        const playlist = await response.json();
+
+        // The resolve endpoint can also return tracks/users - playlists and "sets" both come back as kind "playlist".
+        if (!playlist || playlist.kind !== "playlist") {
+            throw new Error(`Provided URL did not resolve to a playlist (kind: ${playlist?.kind || "unknown"}).`);
+        }
+
+        const rawTracks = (playlist.tracks || []).slice(0, maxTracks === Infinity ? undefined : maxTracks);
+
+        // SoundCloud only inlines full data for roughly the first 5 tracks - the rest come back as stubs (id only).
+        // Batch-fetch the missing ones so the playlist comes back fully populated, same as the web app does.
+        const stubIds = rawTracks.filter(t => !t.title).map(t => t.id);
+        const resolvedStubs = stubIds.length
+            ? await resolveStubTracks(stubIds, userAgent, clientID)
+            : new Map();
+
+        const tracks = rawTracks.map(t =>
+            reduceTrack(t.id, t.title ? t : resolvedStubs.get(t.id))
+        );
+
+        const playlistData = {
+            id: playlist.id,
+            title: playlist.title,
+            description: playlist.description,
+            permalinkUrl: playlist.permalink_url,
+            trackCount: playlist.track_count, // total tracks in the playlist - not affected by `limit`, see `tracks.length` for how many actually came back
+            duration: playlist.duration, // total duration in milliseconds
+            genre: playlist.genre,
+            createdAt: playlist.created_at,
+
+            // Curator metadata (the user who made the playlist)
+            curator: {
+                id: playlist.user.id,
+                username: playlist.user.username,
+                profileUrl: playlist.user.permalink_url,
+                avatarUrl: playlist.user.avatar_url?.replace("-large.jpg", "-t500x500.jpg")
+            },
+
+            artworkUrl: playlist.artwork_url
+                ? playlist.artwork_url.replace("-large.jpg", "-t500x500.jpg")
+                : playlist.user.avatar_url?.replace("-large.jpg", "-t500x500.jpg"),
+
+            // Engagement stats
+            stats: {
+                likes: playlist.likes_count,
+                reposts: playlist.reposts_count
+            },
+
+            tracks
+        };
+
+        return playlistData;
+    } catch (e) {
+        throw new Error("Failed to fetch playlist!");
+    }
+}
+
+module.exports = {
+    fetchPlaylist
+}