riffy-soundcloud 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ramkrishna-js
+
+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,43 @@
+# riffy-soundcloud
+
+> [!IMPORTANT]
+> This is an **unofficial** plugin and is not officially maintained or created by the [Riffy](https://riffy.js.org/) team.
+
+A robust and easy-to-use plugin for [Riffy](https://github.com/riffy-team/riffy) that enables seamless SoundCloud track and playlist resolution using the V2 API. Perfect for Discord music bots looking to expand their audio sources beyond Spotify and YouTube.
+
+## Installation
+
+```bash
+npm install riffy-soundcloud
+```
+
+## Usage
+
+```javascript
+const { Riffy } = require("riffy");
+const { SoundCloud } = require("riffy-soundcloud");
+
+const riffy = new Riffy(client, nodes, {
+    plugins: [
+        new SoundCloud({
+            clientId: "YOUR_SOUNDCLOUD_CLIENT_ID" // Required
+        })
+    ]
+});
+```
+
+## Features
+
+- Resolves SoundCloud Tracks
+- Resolves SoundCloud Playlists
+- Supports `soundcloud.com` and `on.soundcloud.com` URLs
+
+## Support
+
+For support, you can:
+- Create an [Issue](https://github.com/ramkrishna-js/riffy-soundcloud/issues)
+- DM me on Discord: `ramkrishna0`
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/plugin.js

@@ -0,0 +1,129 @@
+const { fetch } = require("undici");
+const { Plugin, Track } = require("riffy");
+
+const REGEX = /^https?:\/\/(?:www\.|m\.|on\.)?soundcloud\.com\/.+/;
+
+class SoundCloud extends Plugin {
+    constructor(options) {
+        super();
+        this.baseURL = 'https://api-v2.soundcloud.com';
+        this.options = options;
+        
+        if (!this.options?.clientId) {
+            throw new Error('SoundCloud Plugin: clientId is required.');
+        }
+    }
+
+    async load(riffy) {
+        this.riffy = riffy;
+        this._resolve = riffy.resolve.bind(riffy);
+        riffy.resolve = this.resolve.bind(this);
+    }
+
+    check(query) {
+        return REGEX.test(query);
+    }
+
+    async resolve({ query, requester }) {
+        let trackLoaded = "",
+            playlistLoaded = "",
+            loadFailed = "";
+
+        const node = this.riffy.leastUsedNodes[0];
+        
+        if (node.restVersion === "v4") {
+            trackLoaded = "track";
+            playlistLoaded = "playlist";
+            loadFailed = "error";
+        } else {
+            trackLoaded = "TRACK_LOADED";
+            playlistLoaded = "PLAYLIST_LOADED";
+            loadFailed = "LOAD_FAILED";
+        }
+
+        const finalQuery = query.query || query;
+        if (!this.check(finalQuery)) return this._resolve({ query, requester });
+
+        try {
+            const data = await this.fetchData(finalQuery);
+            if (!data) throw new Error("No data found");
+
+            if (data.kind === "track") {
+                 const track = await this.buildUnresolved(data, requester);
+                 return this.buildResponse(trackLoaded, [track], null, null);
+            } else if (data.kind === "playlist") {
+                 // Filter out tracks that might not be playable or full objects if necessary
+                 // But usually resolve returns enough info
+                 const tracks = await Promise.all(data.tracks.map(async t => {
+                    // Sometimes playlist tracks are incomplete?
+                    if (!t.title) return null; 
+                    return await this.buildUnresolved(t, requester);
+                 }));
+                 
+                 const validTracks = tracks.filter(t => t !== null);
+                 return this.buildResponse(playlistLoaded, validTracks, data.title, null);
+            } else {
+                return this.buildResponse(loadFailed, null, null, "Unsupported SoundCloud URL type");
+            }
+
+        } catch (e) {
+            return this.buildResponse(loadFailed, null, null, e.message || null);
+        }
+    }
+
+    async fetchData(url) {
+        // Handle short links by following redirects if necessary, but API resolve usually handles them.
+        const res = await fetch(`${this.baseURL}/resolve?url=${encodeURIComponent(url)}&client_id=${this.options.clientId}`);
+        if (!res.ok) {
+             // Try to read body for error
+             throw new Error(`SoundCloud API Error: ${res.status} ${res.statusText}`);
+        }
+        return await res.json();
+    }
+
+    async buildUnresolved(track, requester) {
+        if (!track) throw new ReferenceError('The SoundCloud track object was not provided');
+
+        const node = this.riffy.leastUsedNodes[0];
+        
+        const artwork = track.artwork_url ? track.artwork_url.replace('-large', '-t500x500') : null;
+
+        return new Track(
+          {
+            track: "",
+            info: {
+              identifier: String(track.id),
+              isSeekable: true,
+              author: track.user?.username || "Unknown",
+              length: track.duration,
+              isStream: false,
+              sourceName: "soundcloud",
+              title: track.title,
+              uri: track.permalink_url,
+              thumbnail: artwork,
+              position: 0,
+            },
+          },
+          requester,
+          node
+        );
+    }
+
+    async buildResponse(loadType, tracks, name, error) {
+        return Object.assign(
+            {
+                loadType,
+                tracks,
+                playlistInfo: name ? {
+                    name
+                } : null,
+                exception: error ? {
+                    message: error,
+                    severity: 'COMMON',
+                } : null
+            }
+        )
+    }
+}
+
+module.exports = { SoundCloud };

package/index.d.ts

@@ -0,0 +1,5 @@
+export declare class SoundCloud {
+    constructor(options: {
+        clientId: string;
+    });
+}

package/index.js

@@ -0,0 +1,3 @@
+const { SoundCloud } = require("./dist/plugin");
+
+module.exports = { SoundCloud };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "riffy-soundcloud",
+  "description": "A robust SoundCloud plugin for Riffy that enables seamless track and playlist resolution.",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "riffy": "^1.0.3",
+    "undici": "^5.0.0"
+  },
+  "keywords": [
+    "riffy",
+    "soundcloud",
+    "music",
+    "bot",
+    "discord",
+    "plugin",
+    "music-bot",
+    "lavalink"
+  ],
+  "author": "ramkrishna-js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ramkrishna-js/riffy-soundcloud.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ramkrishna-js/riffy-soundcloud/issues"
+  },
+  "homepage": "https://github.com/ramkrishna-js/riffy-soundcloud#readme"
+}
+