More Docs Added

play-dl/SoundCloud/classes.ts

@@ -3,7 +3,7 @@ import { Readable } from 'node:stream';
 import { IncomingMessage } from 'node:http';
 import { StreamType } from '../YouTube/stream';
 import { Timer } from '../YouTube/classes/LiveStream';
-import { SoundTrackJSON } from './constants';
+import { PlaylistJSON, SoundTrackJSON } from './constants';
 
 export interface SoundCloudUser {
     /**
@@ -178,7 +178,10 @@ export class SoundCloudTrack {
         };
         this.thumbnail = data.artwork_url;
     }
-
+    /**
+     * Converts class to JSON
+     * @returns JSON parsed Data
+     */
     toJSON() : SoundTrackJSON {
         return {
             name: this.name,
@@ -198,17 +201,56 @@ export class SoundCloudTrack {
  * SoundCloud Playlist Class
  */
 export class SoundCloudPlaylist {
+    /**
+     * SoundCloud Playlist Name
+     */
     name: string;
+    /**
+     * SoundCloud Playlist ID
+     */
     id: number;
+    /**
+     * SoundCloud Playlist URL
+     */
     url: string;
+    /**
+     * SoundCloud Class type. == "playlist"
+     */
     type: 'track' | 'playlist' | 'user';
+    /**
+     * SoundCloud Playlist Sub type. == "album" for soundcloud albums
+     */
     sub_type: string;
+    /**
+     * SoundCloud Playlist Total Duration in seconds
+     */
     durationInSec: number;
+    /**
+     * SoundCloud Playlist Total Duration in milli seconds
+     */
     durationInMs: number;
-    client_id: string;
+    /**
+     * SoundCloud Playlist user data
+     */
     user: SoundCloudUser;
+    /**
+     * SoundCloud Playlist tracks [ It can be fetched or not fetched ]
+     */
     tracks: SoundCloudTrack[] | SoundCloudTrackDeprecated[];
+    /**
+     * SoundCloud Playlist tracks number
+     */
     tracksCount: number;
+    /**
+     * SoundCloud Client ID provided by user
+     * @private
+     */
+    private client_id: string;
+    /**
+     * Constructor for SoundCloud Playlist
+     * @param data JSON parsed SoundCloud playlist data
+     * @param client_id Provided SoundCloud Client ID
+     */
     constructor(data: any, client_id: string) {
         this.name = data.title;
         this.id = data.id;
@@ -244,8 +286,13 @@ export class SoundCloudPlaylist {
         });
         this.tracks = tracks;
     }
-
-    async fetch(): Promise<void> {
+    /**
+     * Fetches all unfetched songs in a playlist.
+     * 
+     * For fetching songs and getting all songs, see `fetched_tracks` property.
+     * @returns playlist class
+     */
+    async fetch(): Promise<SoundCloudPlaylist> {
         const work: any[] = [];
         for (let i = 0; i < this.tracks.length; i++) {
             if (!this.tracks[i].fetched) {
@@ -263,9 +310,12 @@ export class SoundCloudPlaylist {
             }
         }
         await Promise.allSettled(work);
+        return this;
     }
-
-    get total_tracks() {
+    /**
+     * Get total no. of fetched tracks
+     */
+    get total_tracks(): number {
         let count = 0;
         this.tracks.forEach((track) => {
             if (track instanceof SoundCloudTrack) count++;
@@ -273,12 +323,35 @@ export class SoundCloudPlaylist {
         });
         return count;
     }
-
-    toJSON() {
+    /**
+     * Get all fetched tracks as a array.
+     * 
+     * For getting all feetched tracks
+     * 
+     * ```ts
+     * const playlist = await play.soundcloud("playlist url")
+     * 
+     * await playlist.fetch()
+     * 
+     * const result = playlist.fetched_tracks
+     * ```
+     */
+    get fetched_tracks(): SoundCloudTrack[] {
+        let result: SoundCloudTrack[] = [];
+        this.tracks.forEach((track) => {
+            if (track instanceof SoundCloudTrack) result.push(track);
+            else return;
+        });
+        return result;
+    }
+    /**
+     * Converts Class to JSON data
+     * @returns JSON parsed data
+     */
+    toJSON(): PlaylistJSON {
         return {
             name: this.name,
             id: this.id,
-            type: this.type,
             sub_type: this.sub_type,
             url: this.url,
             durationInMs: this.durationInMs,
@@ -293,17 +366,57 @@ export class SoundCloudPlaylist {
  * SoundCloud Stream class
  */
 export class SoundCloudStream {
+    /**
+     * Readable Stream through which data passes
+     */
     stream: Readable;
+     /**
+      * Type of audio data that we recieved from normal youtube url.
+      */
     type: StreamType;
+    /**
+     * Dash Url containing segment urls.
+     * @private
+     */
     private url: string;
+    /**
+     * Total time of downloaded segments data.
+     * @private
+     */
     private downloaded_time: number;
+    /**
+     * Timer for looping code every 5 minutes
+     * @private
+     */
     private timer: Timer;
+    /**
+     * Total segments Downloaded so far
+     * @private
+     */
     private downloaded_segments: number;
+    /**
+     * Incoming message that we recieve.
+     * 
+     * Storing this is essential.
+     * This helps to destroy the TCP connection completely if you stopped player in between the stream
+     * @private
+     */
     private request: IncomingMessage | null;
+    /**
+     * Array of segment time. Useful for calculating downloaded_time.
+     */
     private time: number[];
+    /**
+     * Array of segment_urls in dash file.
+     */
     private segment_urls: string[];
+    /**
+     * Constructor for SoundCloud Stream
+     * @param url Dash url containing dash file.
+     * @param type Stream Type
+     */
     constructor(url: string, type: StreamType = StreamType.Arbitrary) {
-        this.stream = new Readable({ highWaterMark: 10 * 1000 * 1000, read() {} });
+        this.stream = new Readable({ highWaterMark: 5 * 1000 * 1000, read() {} });
         this.type = type;
         this.url = url;
         this.downloaded_time = 0;
@@ -320,7 +433,10 @@ export class SoundCloudStream {
         });
         this.start();
     }
-
+    /**
+     * Parses SoundCloud dash file.
+     * @private
+     */
     private async parser() {
         const response = await request(this.url).catch((err: Error) => {
             return err;
@@ -336,7 +452,9 @@ export class SoundCloudStream {
         });
         return;
     }
-
+    /**
+     * Starts looping of code for getting all segments urls data
+     */
     private async start() {
         if (this.stream.destroyed) {
             this.cleanup();
@@ -344,12 +462,14 @@ export class SoundCloudStream {
         }
         this.time = [];
         this.segment_urls = [];
-        await this.parser();
         this.downloaded_time = 0;
+        await this.parser();
         this.segment_urls.splice(0, this.downloaded_segments);
         this.loop();
     }
-
+    /**
+     * Main Loop function for getting all segments urls data
+     */
     private async loop() {
         if (this.stream.destroyed) {
             this.cleanup();
@@ -381,7 +501,11 @@ export class SoundCloudStream {
             this.stream.emit('error', err);
         });
     }
-
+    /**
+     * This cleans every used variable in class.
+     * 
+     * This is used to prevent re-use of this class and helping garbage collector to collect it.
+     */
     private cleanup() {
         this.timer.destroy();
         this.request?.destroy();
@@ -392,11 +516,19 @@ export class SoundCloudStream {
         this.time = [];
         this.segment_urls = [];
     }
-
+    /**
+     * Pauses timer.
+     * Stops running of loop.
+     * 
+     * Useful if you don't want to get excess data to be stored in stream.
+     */
     pause() {
         this.timer.pause();
     }
-
+    /**
+     * Resumes timer.
+     * Starts running of loop.
+     */
     resume() {
         this.timer.resume();
     }