From bfbcc69e92ee7335c4fa0d12c8be1b43a190bf8a Mon Sep 17 00:00:00 2001 From: killer069 <65385476+killer069@users.noreply.github.com> Date: Tue, 23 Nov 2021 11:05:13 +0530 Subject: [PATCH] Documentation 100% complete --- play-dl/index.ts | 144 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 125 insertions(+), 19 deletions(-) diff --git a/play-dl/index.ts b/play-dl/index.ts index e318e5c..cafc997 100644 --- a/play-dl/index.ts +++ b/play-dl/index.ts @@ -87,10 +87,25 @@ import { SpotifyAlbum, SpotifyPlaylist, SpotifyTrack } from './Spotify/classes'; import { DeezerAlbum, DeezerPlaylist, DeezerTrack } from './Deezer/classes'; /** - * Main stream Command for streaming through various sources - * @param url The video / track url to make stream of - * @param options contains quality, cookie and proxy to set for stream - * @returns YouTube / SoundCloud Stream to play + * Creates a Stream [ YouTube or SoundCloud ] class from a url for playing. + * + * Example + * ```ts + * const source = await play.stream('youtube video URL') // YouTube Video Stream + * + * const source = await play.stream('soundcloud track URL') // SoundCloud Track Stream + * + * const resource = createAudioResource(source.stream, { + * inputType : source.type + * }) // Use discordjs voice createAudioResource function. + * ``` + * @param url Video / Track URL + * @param options + * + * - `number` quality : Quality number. [ 0 = Lowest, 1 = Medium, 2 = Highest ] + * - `Proxy[]` proxy : sends data through a proxy + * - `boolean` htmldata : given data is html data or not + * @returns A {@link YouTubeStream} or {@link SoundCloudStream} Stream to play */ export async function stream(url: string, options: StreamOptions = {}): Promise { if (url.length === 0) throw new Error('Stream URL has a length of 0. Check your url again.'); @@ -108,6 +123,35 @@ export async function stream(url: string, options: StreamOptions = {}): Promise< else return await yt_stream(url, options); } +/** + * Searches through a particular source and gives respective info. + * + * Example + * ```ts + * const searched = await play.search('Rick Roll', { source : { youtube : "video" } }) // YouTube Video Search + * + * const searched = await play.search('Rick Roll', { limit : 1 }) // YouTube Video Search but returns only 1 video. + * + * const searched = await play.search('Rick Roll', { source : { spotify : "track" } }) // Spotify Track Search + * + * const searched = await play.search('Rick Roll', { source : { soundcloud : "tracks" } }) // SoundCloud Track Search + * + * const searched = await play.search('Rick Roll', { source : { deezer : "track" } }) // Deezer Track Search + * ``` + * @param query string to search. + * @param options + * + * - `number` limit : No of searches you want to have. + * - `boolean` fuzzy : Whether the search should be fuzzy or only return exact matches. Defaults to `true`. [ for `Deezer` Only ] + * - `Object` source : Contains type of source and type of result you want to have + * ```ts + * - youtube : 'video' | 'playlist' | 'channel'; + - spotify : 'album' | 'playlist' | 'track'; + - soundcloud : 'tracks' | 'playlists' | 'albums'; + - deezer : 'track' | 'playlist' | 'album'; + ``` + * @returns Array of {@link YouTube} or {@link Spotify} or {@link SoundCloud} or {@link Deezer} type + */ export async function search( query: string, options: { source: { deezer: 'album' } } & SearchOptions @@ -157,13 +201,35 @@ export async function search( options: { source: { youtube: 'video' } } & SearchOptions ): Promise; export async function search(query: string, options: { limit: number } & SearchOptions): Promise; -export async function search(query: string, options?: SearchOptions): Promise; +export async function search(query: string, options? : SearchOptions ): Promise; /** - * Main Search Command for searching through various sources + * Searches through a particular source and gives respective info. + * + * Example + * ```ts + * const searched = await play.search('Rick Roll', { source : { youtube : "video" } }) // YouTube Video Search + * + * const searched = await play.search('Rick Roll', { limit : 1 }) // YouTube Video Search but returns only 1 video. + * + * const searched = await play.search('Rick Roll', { source : { spotify : "track" } }) // Spotify Track Search + * + * const searched = await play.search('Rick Roll', { source : { soundcloud : "tracks" } }) // SoundCloud Track Search + * + * const searched = await play.search('Rick Roll', { source : { deezer : "track" } }) // Deezer Track Search + * ``` * @param query string to search. - * @param options contains limit and source to choose. - * @returns Array of YouTube or Spotify or SoundCloud or Deezer - deezer?: 'track' | 'playlist' | 'album'; + * @param options + * + * - `number` limit : No of searches you want to have. + * - `boolean` fuzzy : Whether the search should be fuzzy or only return exact matches. Defaults to `true`. [ for `Deezer` Only ] + * - `Object` source : Contains type of source and type of result you want to have + * ```ts + * - youtube : 'video' | 'playlist' | 'channel'; + - spotify : 'album' | 'playlist' | 'track'; + - soundcloud : 'tracks' | 'playlists' | 'albums'; + - deezer : 'track' | 'playlist' | 'album'; + ``` + * @returns Array of {@link YouTube} or {@link Spotify} or {@link SoundCloud} or {@link Deezer} type */ export async function search( query: string, @@ -180,11 +246,27 @@ export async function search( } /** - * stream Command for streaming through various sources using data from video_info or soundcloud - * SoundCloud Track is only supported - * @param info video_info data or SoundCloud Track data. - * @param options contains quality, cookie and proxy to set for stream - * @returns YouTube / SoundCloud Stream to play + * Creates a Stream [ YouTube or SoundCloud ] class from video or track info for playing. + * + * Example + * ```ts + * const info = await video_info('youtube URL') + * const source = await play.stream_from_info(info) // YouTube Video Stream + * + * const soundInfo = await play.soundcloud('SoundCloud URL') + * const source = await play.stream_from_info(soundInfo) // SoundCloud Track Stream + * + * const resource = createAudioResource(source.stream, { + * inputType : source.type + * }) // Use discordjs voice createAudioResource function. + * ``` + * @param info YouTube video info OR SoundCloud track Class + * @param options + * + * - `number` quality : Quality number. [ 0 = Lowest, 1 = Medium, 2 = Highest ] + * - `Proxy[]` proxy : sends data through a proxy + * - `boolean` htmldata : given data is html data or not + * @returns A {@link YouTubeStream} or {@link SoundCloudStream} Stream to play */ export async function stream_from_info( info: InfoData | SoundCloudTrack, @@ -194,9 +276,17 @@ export async function stream_from_info( else return await yt_stream_info(info, options); } /** - * Command to validate the provided url. It checks whether it supports play-dl or not. - * @param url url to validate - * @returns On failure, returns false else type of url. + * Validates url that play-dl supports. + * + * - `so` - SoundCloud + * - `sp` - Spotify + * - `dz` - Deezer + * - `yt` - YouTube + * @param url URL + * @returns + * ```ts + * 'so_playlist' / 'so_track' | 'sp_track' | 'sp_album' | 'sp_playlist' | 'dz_track' | 'dz_playlist' | 'dz_album' | 'yt_video' | 'yt_playlist' | 'search' | false + * ``` */ export async function validate( url: string @@ -231,7 +321,17 @@ export async function validate( } } /** - * Authorization interface for Spotify and SoundCloud. + * Authorization interface for Spotify, SoundCloud and YouTube. + * + * Either stores info in `.data` folder or shows relevant data to be used in `setToken` function. + * + * ```ts + * const play = require('play-dl) + * + * play.authorization() + * ``` + * + * Just run the above command and you will get a interface asking some questions. */ export function authorization(): void { const ask = readline.createInterface({ @@ -345,7 +445,13 @@ export function authorization(): void { }); }); } - +/** + * Attaches paused, playing, autoPaused Listeners to discordjs voice AudioPlayer. + * + * Useful if you don't want extra data to be downloaded by play-dl. + * @param player discordjs voice AudioPlayer + * @param resource A {@link YouTubeStream} or {@link SoundCloudStream} + */ export function attachListeners(player: EventEmitter, resource: YouTubeStream | SoundCloudStream) { const pauseListener = () => resource.pause(); const resumeListener = () => resource.resume();