@ziplayer/plugin 0.0.5 → 0.1.1

package/YTSR_README.md

@@ -0,0 +1,310 @@
+# YTSRPlugin - Plugin Tìm Kiếm Nâng Cao YouTube
+
+YTSRPlugin là một plugin mạnh mẽ cho ZiPlayer, cung cấp khả năng tìm kiếm nâng cao trên YouTube mà không cần tạo stream. Plugin
+này sử dụng thư viện `youtube-sr` để tìm kiếm và trích xuất metadata từ YouTube.
+
+## ✨ Tính Năng
+
+- 🔍 **Tìm kiếm video nâng cao** với nhiều tùy chọn lọc
+- 📋 **Tìm kiếm playlist** và channel
+- 🎯 **Hỗ trợ nhiều loại tìm kiếm**: video, playlist, channel, hoặc tất cả
+- ⏱️ **Lọc theo thời lượng**: short (< 4 phút), medium (4-20 phút), long (> 20 phút)
+- 📅 **Lọc theo ngày upload**: hour, today, week, month, year
+- 📊 **Sắp xếp kết quả**: relevance, uploadDate, viewCount, rating
+- 🔗 **Hỗ trợ URL YouTube** trực tiếp
+- 📱 **Metadata phong phú**: tác giả, lượt xem, mô tả, ngày upload, v.v.
+- 🔄 **Video liên quan**: Tìm kiếm video liên quan cho một video cụ thể
+- 🎵 **Mix Playlist**: Hỗ trợ xử lý YouTube Mix playlists (RD)
+- ⚡ **Không streaming**: Chỉ trả về metadata, không tạo stream
+
+## 🚀 Cài Đặt
+
+```bash
+npm install youtube-sr
+```
+
+## 📖 Cách Sử Dụng
+
+### Khởi Tạo Plugin
+
+```javascript
+const { YTSRPlugin } = require("ziplayer/plugins");
+const plugin = new YTSRPlugin();
+```
+
+### Tìm Kiếm Video Cơ Bản
+
+```javascript
+// Tìm kiếm video đơn giản
+const result = await plugin.search("Never Gonna Give You Up", "user123");
+console.log(`Tìm thấy ${result.tracks.length} video`);
+
+result.tracks.forEach((track) => {
+	console.log(`${track.title} - ${track.metadata?.author}`);
+	console.log(`URL: ${track.url}`);
+	console.log(`Thời lượng: ${track.duration}s`);
+});
+```
+
+### Tìm Kiếm Với Tùy Chọn Nâng Cao
+
+```javascript
+// Tìm kiếm với các filter nâng cao
+const advancedResult = await plugin.search("chill music", "user123", {
+	limit: 10, // Số lượng kết quả tối đa
+	duration: "medium", // Thời lượng: short, medium, long, all
+	sortBy: "viewCount", // Sắp xếp: relevance, uploadDate, viewCount, rating
+	uploadDate: "month", // Ngày upload: hour, today, week, month, year, all
+	type: "video", // Loại: video, playlist, channel, all
+});
+```
+
+### Tìm Kiếm Playlist
+
+```javascript
+// Tìm kiếm playlist
+const playlistResult = await plugin.searchPlaylist("lofi hip hop", "user123", 5);
+playlistResult.tracks.forEach((track) => {
+	console.log(`Playlist: ${track.title}`);
+	console.log(`Channel: ${track.metadata?.author}`);
+	console.log(`Số video: ${track.metadata?.videoCount}`);
+});
+```
+
+### Tìm Kiếm Channel
+
+```javascript
+// Tìm kiếm channel
+const channelResult = await plugin.searchChannel("PewDiePie", "user123", 3);
+channelResult.tracks.forEach((track) => {
+	console.log(`Channel: ${track.title}`);
+	console.log(`Subscribers: ${track.metadata?.subscriberCount}`);
+	console.log(`URL: ${track.url}`);
+});
+```
+
+### Tìm Kiếm Tất Cả Loại
+
+```javascript
+// Tìm kiếm tất cả loại (video, playlist, channel)
+const allResult = await plugin.search("music", "user123", {
+	type: "all",
+	limit: 15,
+});
+
+allResult.tracks.forEach((track) => {
+	const type = track.metadata?.type || "video";
+	console.log(`[${type.toUpperCase()}] ${track.title}`);
+});
+```
+
+### Xử Lý URL YouTube
+
+```javascript
+// Xử lý URL YouTube trực tiếp
+const urlResult = await plugin.search("https://www.youtube.com/watch?v=dQw4w9WgXcQ", "user123");
+if (urlResult.tracks.length > 0) {
+	const track = urlResult.tracks[0];
+	console.log(`Video: ${track.title}`);
+	console.log(`Tác giả: ${track.metadata?.author}`);
+}
+```
+
+### Lấy Video Theo ID
+
+```javascript
+// Lấy video theo ID cụ thể
+const video = await plugin.getVideoById("dQw4w9WgXcQ", "user123");
+if (video) {
+	console.log(`Video: ${video.title}`);
+	console.log(`Tác giả: ${video.metadata?.author}`);
+	console.log(`URL: ${video.url}`);
+}
+```
+
+### Lấy Video Liên Quan
+
+```javascript
+// Lấy video liên quan cho một video cụ thể
+const relatedTracks = await plugin.getRelatedTracks("https://www.youtube.com/watch?v=dQw4w9WgXcQ", {
+	limit: 5, // Số lượng video liên quan tối đa
+	offset: 0, // Bỏ qua N video đầu tiên
+	history: [currentTrack], // Loại trừ các video đã phát
+});
+
+relatedTracks.forEach((track, index) => {
+	console.log(`${index + 1}. ${track.title} - ${track.metadata?.author}`);
+});
+```
+
+### Xử Lý Mix Playlist (RD)
+
+```javascript
+// Xử lý YouTube Mix playlist (RD)
+const mixResult = await plugin.handleMixPlaylist(
+	"https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=RDMWGnHCaqxdU&start_radio=1",
+	"user123",
+	10, // Số lượng track tối đa
+);
+
+console.log(`Mix playlist: ${mixResult.playlist?.name}`);
+console.log(`Tìm thấy ${mixResult.tracks.length} track trong Mix`);
+
+mixResult.tracks.forEach((track, index) => {
+	console.log(`${index + 1}. ${track.title} - ${track.metadata?.author}`);
+});
+```
+
+## 📋 API Reference
+
+### `search(query, requestedBy, options?)`
+
+Tìm kiếm nội dung trên YouTube với các tùy chọn nâng cao.
+
+**Tham số:**
+
+- `query` (string): Query tìm kiếm hoặc URL YouTube
+- `requestedBy` (string): ID của user yêu cầu tìm kiếm
+- `options` (object, tùy chọn):
+  - `limit` (number): Số lượng kết quả tối đa (mặc định: 10)
+  - `type` (string): Loại tìm kiếm - "video", "playlist", "channel", "all" (mặc định: "video")
+  - `duration` (string): Lọc theo thời lượng - "short", "medium", "long", "all" (mặc định: "all")
+  - `sortBy` (string): Sắp xếp - "relevance", "uploadDate", "viewCount", "rating" (mặc định: "relevance")
+  - `uploadDate` (string): Lọc theo ngày upload - "hour", "today", "week", "month", "year", "all" (mặc định: "all")
+
+**Trả về:** `Promise<SearchResult>`
+
+### `searchPlaylist(query, requestedBy, limit?)`
+
+Tìm kiếm playlist trên YouTube.
+
+**Tham số:**
+
+- `query` (string): Query tìm kiếm playlist
+- `requestedBy` (string): ID của user yêu cầu
+- `limit` (number, tùy chọn): Số lượng playlist tối đa (mặc định: 5)
+
+**Trả về:** `Promise<SearchResult>`
+
+### `searchChannel(query, requestedBy, limit?)`
+
+Tìm kiếm channel trên YouTube.
+
+**Tham số:**
+
+- `query` (string): Query tìm kiếm channel
+- `requestedBy` (string): ID của user yêu cầu
+- `limit` (number, tùy chọn): Số lượng channel tối đa (mặc định: 5)
+
+**Trả về:** `Promise<SearchResult>`
+
+### `getVideoById(videoId, requestedBy)`
+
+Lấy thông tin video theo ID cụ thể.
+
+**Tham số:**
+
+- `videoId` (string): ID của video YouTube
+- `requestedBy` (string): ID của user yêu cầu
+
+**Trả về:** `Promise<Track | null>`
+
+### `getRelatedTracks(trackURL, opts?)`
+
+Lấy các video liên quan cho một video YouTube cụ thể.
+
+**Tham số:**
+
+- `trackURL` (string): URL của video YouTube để lấy video liên quan
+- `opts` (object, tùy chọn):
+  - `limit` (number): Số lượng video liên quan tối đa (mặc định: 5)
+  - `offset` (number): Số lượng video bỏ qua từ đầu (mặc định: 0)
+  - `history` (Track[]): Mảng các track để loại trừ khỏi kết quả
+
+**Trả về:** `Promise<Track[]>`
+
+### `handleMixPlaylist(mixUrl, requestedBy, limit?)`
+
+Xử lý YouTube Mix playlist (RD) và tạo danh sách các video liên quan.
+
+**Tham số:**
+
+- `mixUrl` (string): URL của playlist Mix YouTube
+- `requestedBy` (string): ID của user yêu cầu
+- `limit` (number, tùy chọn): Số lượng track tối đa (mặc định: 10)
+
+**Trả về:** `Promise<SearchResult>`
+
+### `canHandle(query)`
+
+Kiểm tra xem plugin có thể xử lý query này không.
+
+**Tham số:**
+
+- `query` (string): Query để kiểm tra
+
+**Trả về:** `boolean`
+
+### `validate(url)`
+
+Xác thực URL YouTube.
+
+**Tham số:**
+
+- `url` (string): URL để xác thực
+
+**Trả về:** `boolean`
+
+## ⚠️ Lưu Ý Quan Trọng
+
+- **KHÔNG hỗ trợ streaming**: Plugin này chỉ dành cho tìm kiếm metadata, không tạo stream audio
+- **KHÔNG hỗ trợ fallback**: Không có phương thức fallback streaming
+- **Chỉ metadata**: Trả về thông tin về video/playlist/channel, không phải audio stream
+- **Sử dụng với plugin khác**: Có thể kết hợp với YouTubePlugin để có cả tìm kiếm nâng cao và streaming
+
+## 🔧 Tích Hợp Với Plugin Khác
+
+```javascript
+const { YTSRPlugin, YouTubePlugin } = require("ziplayer/plugins");
+
+// Sử dụng YTSRPlugin để tìm kiếm nâng cao
+const ytsrPlugin = new YTSRPlugin();
+const searchResult = await ytsrPlugin.search("music", "user123", {
+	duration: "medium",
+	sortBy: "viewCount",
+});
+
+// Lấy video liên quan
+const relatedTracks = await ytsrPlugin.getRelatedTracks(searchResult.tracks[0].url, {
+	limit: 3,
+	history: searchResult.tracks,
+});
+
+// Sử dụng YouTubePlugin để tạo stream
+const youtubePlugin = new YouTubePlugin();
+const stream = await youtubePlugin.getStream(searchResult.tracks[0]);
+```
+
+## 🧪 Testing
+
+```bash
+# Chạy test cho YTSRPlugin
+npm test tests/plugins/ytsrplugin.test.js
+```
+
+## 📝 Ví Dụ Hoàn Chỉnh
+
+Xem file `examples/ytsr-example.js` để có ví dụ chi tiết về cách sử dụng plugin.
+
+## 🤝 Đóng Góp
+
+Nếu bạn muốn đóng góp vào plugin này, vui lòng:
+
+1. Fork repository
+2. Tạo branch mới cho feature
+3. Commit changes
+4. Tạo Pull Request
+
+## 📄 License
+
+MIT License - xem file LICENSE để biết thêm chi tiết.

package/dist/SoundCloudPlugin.d.ts

@@ -1,21 +1,170 @@
 import { BasePlugin, Track, SearchResult, StreamInfo } from "ziplayer";
+/**
+ * A plugin for handling SoundCloud audio content including tracks, playlists, and search functionality.
+ *
+ * This plugin provides comprehensive support for:
+ * - SoundCloud track URLs (soundcloud.com)
+ * - SoundCloud playlist URLs
+ * - SoundCloud search queries
+ * - Audio stream extraction from SoundCloud tracks
+ * - Related track recommendations
+ *
+ * @example
+ *
+ * const soundcloudPlugin = new SoundCloudPlugin();
+ *
+ * // Add to PlayerManager
+ * const manager = new PlayerManager({
+ *   plugins: [soundcloudPlugin]
+ * });
+ *
+ * // Search for tracks
+ * const result = await soundcloudPlugin.search("chill music", "user123");
+ *
+ * // Get audio stream
+ * const stream = await soundcloudPlugin.getStream(result.tracks[0]);
+ *
+ * @since 1.0.0
+ */
 export declare class SoundCloudPlugin extends BasePlugin {
     name: string;
     version: string;
     private client;
     private ready;
+    /**
+     * Creates a new SoundCloudPlugin instance.
+     *
+     * The plugin will automatically initialize the SoundCloud client for track
+     * and playlist operations. Initialization is asynchronous and handled internally.
+     *
+     * @example
+     * const plugin = new SoundCloudPlugin();
+     * // Plugin is ready to use after initialization completes
+     */
     constructor();
     private init;
+    /**
+     * Determines if this plugin can handle the given query.
+     *
+     * @param query - The search query or URL to check
+     * @returns `true` if the plugin can handle the query, `false` otherwise
+     *
+     * @example
+     * plugin.canHandle("https://soundcloud.com/artist/track"); // true
+     * plugin.canHandle("chill music"); // true
+     * plugin.canHandle("spotify:track:123"); // false
+     */
     canHandle(query: string): boolean;
+    /**
+     * Validates if a URL is a valid SoundCloud URL.
+     *
+     * @param url - The URL to validate
+     * @returns `true` if the URL is a valid SoundCloud URL, `false` otherwise
+     *
+     * @example
+     * plugin.validate("https://soundcloud.com/artist/track"); // true
+     * plugin.validate("https://www.soundcloud.com/artist/track"); // true
+     * plugin.validate("https://youtube.com/watch?v=123"); // false
+     */
     validate(url: string): boolean;
+    /**
+     * Searches for SoundCloud content based on the given query.
+     *
+     * This method handles both URL-based queries (direct track/playlist links) and
+     * text-based search queries. For URLs, it will extract track or playlist information.
+     * For text queries, it will perform a SoundCloud search and return up to 10 results.
+     *
+     * @param query - The search query (URL or text)
+     * @param requestedBy - The user ID who requested the search
+     * @returns A SearchResult containing tracks and optional playlist information
+     *
+     * @example
+     * // Search by URL
+     * const result = await plugin.search("https://soundcloud.com/artist/track", "user123");
+     *
+     * // Search by text
+     * const searchResult = await plugin.search("chill music", "user123");
+     * console.log(searchResult.tracks); // Array of Track objects
+     */
     search(query: string, requestedBy: string): Promise<SearchResult>;
+    /**
+     * Retrieves the audio stream for a SoundCloud track.
+     *
+     * This method downloads the audio stream from SoundCloud using the track's URL.
+     * It handles the SoundCloud-specific download process and returns the stream
+     * in a format compatible with the player.
+     *
+     * @param track - The Track object to get the stream for
+     * @returns A StreamInfo object containing the audio stream and metadata
+     * @throws {Error} If the track URL is invalid or stream download fails
+     *
+     * @example
+     * const track = { id: "123", title: "Track Title", url: "https://soundcloud.com/artist/track", ... };
+     * const streamInfo = await plugin.getStream(track);
+     * console.log(streamInfo.type); // "arbitrary"
+     * console.log(streamInfo.stream); // Readable stream
+     */
     getStream(track: Track): Promise<StreamInfo>;
+    /**
+     * Gets related tracks for a given SoundCloud track.
+     *
+     * This method fetches related tracks from SoundCloud's recommendation system
+     * based on the provided track URL or ID. It can filter out tracks that are
+     * already in the history to avoid duplicates.
+     *
+     * @param trackURL - The SoundCloud track URL or ID to get related tracks for
+     * @param opts - Options for filtering and limiting results
+     * @param opts.limit - Maximum number of related tracks to return (default: 1)
+     * @param opts.offset - Number of tracks to skip from the beginning (default: 0)
+     * @param opts.history - Array of tracks to exclude from results
+     * @returns An array of related Track objects
+     *
+     * @example
+     * const related = await plugin.getRelatedTracks(
+     *   "https://soundcloud.com/artist/track",
+     *   { limit: 3, history: [currentTrack] }
+     * );
+     * console.log(`Found ${related.length} related tracks`);
+     */
     getRelatedTracks(trackURL: string | number, opts?: {
         limit?: number;
         offset?: number;
         history?: Track[];
     }): Promise<Track[]>;
+    /**
+     * Provides a fallback stream by searching for the track title.
+     *
+     * This method is used when the primary stream extraction fails. It performs
+     * a search using the track's title and attempts to get a stream from the
+     * first search result.
+     *
+     * @param track - The Track object to get a fallback stream for
+     * @returns A StreamInfo object containing the fallback audio stream
+     * @throws {Error} If no fallback track is found or stream extraction fails
+     *
+     * @example
+     * try {
+     *   const stream = await plugin.getStream(track);
+     * } catch (error) {
+     *   // Try fallback
+     *   const fallbackStream = await plugin.getFallback(track);
+     * }
+     */
     getFallback(track: Track): Promise<StreamInfo>;
+    /**
+     * Extracts tracks from a SoundCloud playlist URL.
+     *
+     * @param url - The SoundCloud playlist URL
+     * @param requestedBy - The user ID who requested the extraction
+     * @returns An array of Track objects from the playlist
+     *
+     * @example
+     * const tracks = await plugin.extractPlaylist(
+     *   "https://soundcloud.com/artist/sets/playlist-name",
+     *   "user123"
+     * );
+     * console.log(`Found ${tracks.length} tracks in playlist`);
+     */
     extractPlaylist(url: string, requestedBy: string): Promise<Track[]>;
 }
 //# sourceMappingURL=SoundCloudPlugin.d.ts.map

package/dist/SoundCloudPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoundCloudPlugin.d.ts","sourceRoot":"","sources":["../src/SoundCloudPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAgBvE,qBAAa,gBAAiB,SAAQ,UAAU;IAC/C,IAAI,SAAgB;IACpB,OAAO,SAAW;IAClB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,KAAK,CAAgB;;YAOf,IAAI;IAKlB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAgBjC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIxB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgFjE,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB5C,gBAAgB,CACrB,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAA;KAAO,GAC/D,OAAO,CAAC,KAAK,EAAE,CAAC;IAiCb,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IAS9C,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;CAsBzE"}
+{"version":3,"file":"SoundCloudPlugin.d.ts","sourceRoot":"","sources":["../src/SoundCloudPlugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAgBvE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,gBAAiB,SAAQ,UAAU;IAC/C,IAAI,SAAgB;IACpB,OAAO,SAAW;IAClB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,KAAK,CAAgB;IAE7B;;;;;;;;;OASG;;YAMW,IAAI;IAKlB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAgBjC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI9B;;;;;;;;;;;;;;;;;;OAkBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAgFvE;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IAmBlD;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,gBAAgB,CACrB,QAAQ,EAAE,MAAM,GAAG,MAAM,EACzB,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAA;KAAO,GAC/D,OAAO,CAAC,KAAK,EAAE,CAAC;IAiCnB;;;;;;;;;;;;;;;;;;OAkBG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IASpD;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;CAsBzE"}

package/dist/SoundCloudPlugin.js

@@ -15,7 +15,44 @@ function isValidSoundCloudHost(maybeUrl) {
         return false;
     }
 }
+/**
+ * A plugin for handling SoundCloud audio content including tracks, playlists, and search functionality.
+ *
+ * This plugin provides comprehensive support for:
+ * - SoundCloud track URLs (soundcloud.com)
+ * - SoundCloud playlist URLs
+ * - SoundCloud search queries
+ * - Audio stream extraction from SoundCloud tracks
+ * - Related track recommendations
+ *
+ * @example
+ *
+ * const soundcloudPlugin = new SoundCloudPlugin();
+ *
+ * // Add to PlayerManager
+ * const manager = new PlayerManager({
+ *   plugins: [soundcloudPlugin]
+ * });
+ *
+ * // Search for tracks
+ * const result = await soundcloudPlugin.search("chill music", "user123");
+ *
+ * // Get audio stream
+ * const stream = await soundcloudPlugin.getStream(result.tracks[0]);
+ *
+ * @since 1.0.0
+ */
 class SoundCloudPlugin extends ziplayer_1.BasePlugin {
+    /**
+     * Creates a new SoundCloudPlugin instance.
+     *
+     * The plugin will automatically initialize the SoundCloud client for track
+     * and playlist operations. Initialization is asynchronous and handled internally.
+     *
+     * @example
+     * const plugin = new SoundCloudPlugin();
+     * // Plugin is ready to use after initialization completes
+     */
     constructor() {
         super();
         this.name = "soundcloud";
@@ -26,6 +63,17 @@ class SoundCloudPlugin extends ziplayer_1.BasePlugin {
         this.client = new SoundCloud({ init: false });
         await this.client.init();
     }
+    /**
+     * Determines if this plugin can handle the given query.
+     *
+     * @param query - The search query or URL to check
+     * @returns `true` if the plugin can handle the query, `false` otherwise
+     *
+     * @example
+     * plugin.canHandle("https://soundcloud.com/artist/track"); // true
+     * plugin.canHandle("chill music"); // true
+     * plugin.canHandle("spotify:track:123"); // false
+     */
     canHandle(query) {
         const q = (query || "").trim().toLowerCase();
         const isUrl = q.startsWith("http://") || q.startsWith("https://");
@@ -42,9 +90,39 @@ class SoundCloudPlugin extends ziplayer_1.BasePlugin {
         // Treat remaining non-URL free text as searchable
         return true;
     }
+    /**
+     * Validates if a URL is a valid SoundCloud URL.
+     *
+     * @param url - The URL to validate
+     * @returns `true` if the URL is a valid SoundCloud URL, `false` otherwise
+     *
+     * @example
+     * plugin.validate("https://soundcloud.com/artist/track"); // true
+     * plugin.validate("https://www.soundcloud.com/artist/track"); // true
+     * plugin.validate("https://youtube.com/watch?v=123"); // false
+     */
     validate(url) {
         return isValidSoundCloudHost(url);
     }
+    /**
+     * Searches for SoundCloud content based on the given query.
+     *
+     * This method handles both URL-based queries (direct track/playlist links) and
+     * text-based search queries. For URLs, it will extract track or playlist information.
+     * For text queries, it will perform a SoundCloud search and return up to 10 results.
+     *
+     * @param query - The search query (URL or text)
+     * @param requestedBy - The user ID who requested the search
+     * @returns A SearchResult containing tracks and optional playlist information
+     *
+     * @example
+     * // Search by URL
+     * const result = await plugin.search("https://soundcloud.com/artist/track", "user123");
+     *
+     * // Search by text
+     * const searchResult = await plugin.search("chill music", "user123");
+     * console.log(searchResult.tracks); // Array of Track objects
+     */
     async search(query, requestedBy) {
         await this.ready;
         // If the query is a URL but not a SoundCloud URL, do not handle it here
@@ -122,6 +200,23 @@ class SoundCloudPlugin extends ziplayer_1.BasePlugin {
             throw new Error(`SoundCloud search failed: ${error?.message}`);
         }
     }
+    /**
+     * Retrieves the audio stream for a SoundCloud track.
+     *
+     * This method downloads the audio stream from SoundCloud using the track's URL.
+     * It handles the SoundCloud-specific download process and returns the stream
+     * in a format compatible with the player.
+     *
+     * @param track - The Track object to get the stream for
+     * @returns A StreamInfo object containing the audio stream and metadata
+     * @throws {Error} If the track URL is invalid or stream download fails
+     *
+     * @example
+     * const track = { id: "123", title: "Track Title", url: "https://soundcloud.com/artist/track", ... };
+     * const streamInfo = await plugin.getStream(track);
+     * console.log(streamInfo.type); // "arbitrary"
+     * console.log(streamInfo.stream); // Readable stream
+     */
     async getStream(track) {
         await this.ready;
         try {
@@ -139,6 +234,27 @@ class SoundCloudPlugin extends ziplayer_1.BasePlugin {
             throw new Error(`Failed to get SoundCloud stream: ${error.message}`);
         }
     }
+    /**
+     * Gets related tracks for a given SoundCloud track.
+     *
+     * This method fetches related tracks from SoundCloud's recommendation system
+     * based on the provided track URL or ID. It can filter out tracks that are
+     * already in the history to avoid duplicates.
+     *
+     * @param trackURL - The SoundCloud track URL or ID to get related tracks for
+     * @param opts - Options for filtering and limiting results
+     * @param opts.limit - Maximum number of related tracks to return (default: 1)
+     * @param opts.offset - Number of tracks to skip from the beginning (default: 0)
+     * @param opts.history - Array of tracks to exclude from results
+     * @returns An array of related Track objects
+     *
+     * @example
+     * const related = await plugin.getRelatedTracks(
+     *   "https://soundcloud.com/artist/track",
+     *   { limit: 3, history: [currentTrack] }
+     * );
+     * console.log(`Found ${related.length} related tracks`);
+     */
     async getRelatedTracks(trackURL, opts = {}) {
         await this.ready;
         try {
@@ -169,6 +285,25 @@ class SoundCloudPlugin extends ziplayer_1.BasePlugin {
             return [];
         }
     }
+    /**
+     * Provides a fallback stream by searching for the track title.
+     *
+     * This method is used when the primary stream extraction fails. It performs
+     * a search using the track's title and attempts to get a stream from the
+     * first search result.
+     *
+     * @param track - The Track object to get a fallback stream for
+     * @returns A StreamInfo object containing the fallback audio stream
+     * @throws {Error} If no fallback track is found or stream extraction fails
+     *
+     * @example
+     * try {
+     *   const stream = await plugin.getStream(track);
+     * } catch (error) {
+     *   // Try fallback
+     *   const fallbackStream = await plugin.getFallback(track);
+     * }
+     */
     async getFallback(track) {
         const trackfall = await this.search(track.title, track.requestedBy);
         const fallbackTrack = trackfall.tracks?.[0];
@@ -177,6 +312,20 @@ class SoundCloudPlugin extends ziplayer_1.BasePlugin {
         }
         return await this.getStream(fallbackTrack);
     }
+    /**
+     * Extracts tracks from a SoundCloud playlist URL.
+     *
+     * @param url - The SoundCloud playlist URL
+     * @param requestedBy - The user ID who requested the extraction
+     * @returns An array of Track objects from the playlist
+     *
+     * @example
+     * const tracks = await plugin.extractPlaylist(
+     *   "https://soundcloud.com/artist/sets/playlist-name",
+     *   "user123"
+     * );
+     * console.log(`Found ${tracks.length} tracks in playlist`);
+     */
     async extractPlaylist(url, requestedBy) {
         await this.ready;
         try {