Docs and examples updated

This commit is contained in:
killer069 2021-09-21 13:00:38 +05:30
parent c68a57aaf4
commit 3528f89607
14 changed files with 436 additions and 192 deletions

View File

@ -6,8 +6,8 @@
This is a **light-weight** youtube downloader and searcher.
- searches by video, playlist, channel
- obtains audio playback url
- searches by video, playlist, channel
- obtains audio playback url
### Installation
@ -16,6 +16,7 @@ npm install play-dl@latest
```
### Importing
```ts
import * as play from 'play-dl' // ES-6 import or TS import
@ -25,12 +26,14 @@ const play = require('play-dl') //JS importing
**Instructions for Spotify** are [here](https://github.com/play-dl/play-dl/discussions/64)
### Examples
- [YouTube](https://github.com/play-dl/play-dl/tree/main/examples/YouTube)
- [Spotify](https://github.com/play-dl/play-dl/tree/main/examples/Spotify)
- [YouTube](https://github.com/play-dl/play-dl/tree/main/examples/YouTube)
- [Spotify](https://github.com/play-dl/play-dl/tree/main/examples/Spotify)
- [SoundCloud]()
### Docs
- [Main](https://github.com/play-dl/play-dl/tree/main/docs#play-dl-commands)
- [YouTube](https://github.com/play-dl/play-dl/tree/main/docs/YouTube#youtube)
- [Spotify](https://github.com/play-dl/play-dl/tree/main/docs/Spotify#spotify)
- [Main](https://github.com/play-dl/play-dl/tree/main/docs#play-dl-commands)
- [YouTube](https://github.com/play-dl/play-dl/tree/main/docs/YouTube#youtube)
- [Spotify](https://github.com/play-dl/play-dl/tree/main/docs/Spotify#spotify)
- [SoundCloud]()

View File

@ -1,25 +1,74 @@
# Play-dl commands
For source specific commands :-
- [YouTube](https://github.com/play-dl/play-dl/tree/main/docs/YouTube#youtube)
- [Spotify](https://github.com/play-dl/play-dl/tree/main/docs/Spotify#spotify)
- [YouTube](https://github.com/play-dl/play-dl/tree/main/docs/YouTube#youtube)
- [Spotify](https://github.com/play-dl/play-dl/tree/main/docs/Spotify#spotify)
- [SoundCloud]()
### Validate
#### validate(url : `string`)
*This checks all type of urls that are supported by play-dl.*
**Returns :** `sp_track` | `sp_album` | `sp_playlist` | `yt_video` | `yt_playlist` | `false`
_This checks all type of urls that are supported by play-dl._
sp = Spotify
**Returns :** `so_playlist` | `so_track` | `sp_track` | `sp_album` | `sp_playlist` | `yt_video` | `yt_playlist` | `false`
`so` = **SoundCloud**
`sp` = **Spotify**
`yt` = **YouTube**
yt = YouTube
```js
let check = validate(url)
let check = await validate(url)
if(!check) // Invalid URL
if(check === 'yt_video') // YouTube Video
if(check === 'sp_track') // Spotify Track
if(check === 'so_track') // SoundCloud Track
```
### authorization()
_This creates basic spotify / soundcloud data to be stored locally._
```js
authorization() //After then you will be asked about type of data you want to create and then follow the steps properly.
```
### Stream
#### stream(url : `string`, cookie? : `string`)
_This is basic to create a stream from a youtube or soundcloud url._
**[Cookies](https://github.com/play-dl/play-dl/discussions/34) are optional and are required for playing age restricted videos.**
```js
let source = await stream("url") // This will create a stream Class.
let resource = createAudioResource(source, {
inputType : source.type
}) // This creates resource for playing
```
### stream_from_info(info : `infoData`, cookie? : `string`)
_This is basic to create a stream from a info [ from [video_info](https://github.com/play-dl/play-dl#video_infourl--string) function or [soundcloud]() function [**Only SoundCloudTrack class is allowed**] ]._
**[Cookies](https://github.com/play-dl/play-dl/discussions/34) are optional and are required for playing age restricted videos.**
**Note :** Here, cookies are required only for retrying purposes.
```js
let source = await stream_from_info(info) // This will create a stream Class from video_info or SoundCoudTrack Class.
/* OR
let source = await stream_from_info(info, cookie) This will create a stream Class and also give cookies if retrying.
*/
let resource = createAudioResource(source, {
inputType : source.type
}) // This creates resource for playing
```

99
docs/SoundCloud/README.md Normal file
View File

@ -0,0 +1,99 @@
# SoundCloud
## Main
### soundcloud(url : `string`)
_This returns data from a track | playlist url._
```js
let data = await soundcloud(url) //Gets the data
console.log(data.type) // Console logs the type of data that you got.
```
## Validate
### so_validate(url : `string`)
_This checks that given url is soundcloud url or not._
**Returns :** `track` | `playlist` | `false`
```js
let check = await so_validate(url)
if(!check) // Invalid SoundCloud URL
if(check === 'track') // SoundCloud Track URL
```
## Classes [ Returned by soundcloud() function ]
### SoundCloudTrack
_This is class for a soundcloud track._
##### type `property`
_This will always return as "track" for this class._
##### toJSON() `function`
_converts class into a json format_
### SoundCloudPlaylist
_This is a soundcloud playlist class._
##### fetch() `function`
_This will fetch tracks in a playlist._
```js
let data = await soundcloud(playlist_url)
await data.fetch() // Fetches all unfetched tracks in playlist
```
##### tracksCount `property`
_This will give no. of tracks in a playlist._
```js
let data = await soundcloud(playlist_url)
console.log(data.tracksCount) // Returns total tracks count in a playlist
```
#### tracks `property`
_This will give all tracks fetched as array._
```js
let data = await soundcloud(playlist_url)
console.log(data.tracks) // Tracks Array
data.tracks.forEach((track) => {
queue.push(track) // This will push every track in playlist to your queue
})
```
#### total_tracks `property`
_This give total videos that have been fetched so far._
```js
let data = await soundcloud(playlist_url)
console.log(data.total_tracks) // This will tell no. of videos that have been fetched so far.
```
##### type `property`
_This will always return as "playlist" for this class._
##### toJSON() `function`
_converts class into a json format_

View File

@ -1,8 +1,10 @@
# Spotify
## Main
### spotify(url : `string`)
*This returns data from a track | playlist | album url.*
_This returns data from a track | playlist | album url._
```js
let data = await spotify(url) //Gets the data
@ -10,15 +12,9 @@ let data = await spotify(url) //Gets the data
console.log(data.type) // Console logs the type of data that you got.
```
### Authorization()
*This creates basic spotify data to be stored locally.*
```js
Authorization() //After then you will be asked client-id, client-secret, redirect url, market, redirected URL.
```
### is_expired()
*This tells that whether the access token is expired or not*
_This tells that whether the access token is expired or not_
**Returns :** `boolean`
@ -28,30 +24,37 @@ if(is_expired()){
}
```
### RefreshToken()
*This refreshes the access token.*
### refreshToken()
_This refreshes the access token._
**Returns :** `boolean` for telling whether access token is refreshed or not
```js
await RefreshToken()
await refreshToken()
```
## Classes [ Returned by spotify() function ]
### SpotifyVideo
*Don't go by the name. This is class for a spotify track.*
_Don't go by the name. This is class for a spotify track._
##### type `property`
*This will always return as "track" for this class.*
_This will always return as "track" for this class._
##### toJSON() `function`
*converts class into a json format*
_converts class into a json format_
### SpotifyPlaylist
*This is a spotify playlist class.*
_This is a spotify playlist class._
##### fetch() `function`
*This will fetch tracks in a playlist upto 1000 tracks only.*
_This will fetch tracks in a playlist upto 1000 tracks only._
```js
let data = await spotify(playlist_url)
@ -60,15 +63,18 @@ await data.fetch() // Fetches tracks more than 100 tracks in playlist
```
##### tracksCount `property`
*This will give no. of tracks in a playlist.*
_This will give no. of tracks in a playlist._
```js
let data = await spotify(playlist_url)
console.log(data.tracksCount) // Returns total tracks count in a playlist
```
##### page(page_number : `number`)
*This will return array of tracks in that page.*
_This will return array of tracks in that page._
> Same as youtube playlist pages
@ -77,21 +83,25 @@ let data = await spotify(playlist_url)
console.log(data.page(1)) //This will give first 100 tracks in playlist.
```
- total_pages `property`
*This give total pages that have been fetched so far.*
```js
let data = await spotify(playlist_url)
console.log(data.total_pages) // This will tell no. of pages that have been fetched so far.
for(let i = 1; i <= data.total_pages; i++){
queue.push(data.page(i)) //This will push all tracks to your queue system
}
```
- total_tracks `property`
*This give total videos that have been fetched so far.*
- total_pages `property`
_This give total pages that have been fetched so far._
```js
let data = await spotify(playlist_url)
console.log(data.total_pages) // This will tell no. of pages that have been fetched so far.
for(let i = 1; i <= data.total_pages; i++){
queue.push(data.page(i)) //This will push all tracks to your queue system
}
```
- total_tracks `property`
_This give total videos that have been fetched so far._
```js
let data = await spotify(playlist_url)
@ -99,16 +109,20 @@ console.log(data.page(1)) //This will give first 100 tracks in playlist.
```
##### type `property`
*This will always return as "playlist" for this class.*
_This will always return as "playlist" for this class._
##### toJSON() `function`
*converts class into a json format*
_converts class into a json format_
### SpotifyAlbum
*This is a spotify albun class.*
_This is a spotify albun class._
##### fetch() `function`
*This will fetch tracks in a album upto 500 tracks only.*
_This will fetch tracks in a album upto 500 tracks only._
```js
let data = await spotify(playlist_url)
@ -117,15 +131,18 @@ await data.fetch() // Fetches tracks more than 50 tracks in album
```
##### tracksCount `property`
*This will give no. of tracks in a playlist.*
_This will give no. of tracks in a playlist._
```js
let data = await spotify(playlist_url)
console.log(data.tracksCount) // Returns total tracks count in a album
```
##### page(page_number : `number`)
*This will return array of tracks in that page.*
_This will return array of tracks in that page._
> Same as youtube playlist pages
@ -134,21 +151,25 @@ let data = await spotify(playlist_url)
console.log(data.page(1)) //This will give first 50 tracks in album.
```
- total_pages `property`
*This give total pages that have been fetched so far.*
```js
let data = await spotify(playlist_url)
console.log(data.total_pages) // This will tell no. of pages that have been fetched so far.
for(let i = 1; i <= data.total_pages; i++){
queue.push(data.page(i)) //This will push all tracks to your queue system
}
```
- total_tracks `property`
*This give total videos that have been fetched so far.*
- total_pages `property`
_This give total pages that have been fetched so far._
```js
let data = await spotify(playlist_url)
console.log(data.total_pages) // This will tell no. of pages that have been fetched so far.
for(let i = 1; i <= data.total_pages; i++){
queue.push(data.page(i)) //This will push all tracks to your queue system
}
```
- total_tracks `property`
_This give total videos that have been fetched so far._
```js
let data = await spotify(playlist_url)
@ -156,16 +177,21 @@ console.log(data.page(1)) //This will give first 50 tracks in album.
```
##### type `property`
*This will always return as "album" for this class.*
_This will always return as "album" for this class._
##### toJSON() `function`
*converts class into a json format*
_converts class into a json format_
## Validate
### sp_validate(url : `string`)
*This checks that given url is spotify url or not.*
_This checks that given url is spotify url or not._
**Returns :** `track` | `album` | `playlist` | `false`
```js
let check = sp_validate(url)

View File

@ -14,9 +14,11 @@ const results = await youtube.search('post malone sunflower', options);
## Validate
### yt_validate(url : `string`)
*This will validate url and return type or boolean*
_This will validate url and return type or boolean_
**Returns :** `video` | `playlist` | `false`
```js
let check = yt_validate(url)
@ -30,7 +32,8 @@ if(check === "playlist") //URL is a playlist url
## Extract ID
### extractID(url : `string`)
*This will return videoID or playlistID from a url*
_This will return videoID or playlistID from a url_
**Note :** URL like [this](https://www.youtube.com/watch?v=E2gHczUOCGI&list=PLUt3leKZfbZqLzLwcQMYPBdbe7i7KRCOP&index=2) will return a playlist ID only.
@ -38,42 +41,11 @@ if(check === "playlist") //URL is a playlist url
let id = extractID(url)
```
## Stream
### stream(url : `string`, cookie? : `string`)
*This is basic to create a youtube stream from a url or videoID.*
**[Cookies](https://github.com/play-dl/play-dl/discussions/34) are optional and are required for playing age restricted videos.**
```js
let source = await stream("url") // This will create a stream Class which contains type and stream to be played.
let resource = createAudioResource(source.stream, {
inputType : source.type
}) // This creates resource for playing
```
### stream_from_info(info : `infoData`, cookie? : `string`)
*This is basic to create a youtube stream from a info [ from [video_info](https://github.com/play-dl/play-dl#video_infourl--string) function ].*
**[Cookies](https://github.com/play-dl/play-dl/discussions/34) are optional and are required for playing age restricted videos.**
**Note :** Here, cookies are required only for retrying purposes.
```js
let info = await video_info("url")
let source = await stream_from_info(info) // This will create a stream Class which contains type and stream to be played.
/* OR
let source = await stream_from_info(info, cookie) This will create a stream Class which contains type and stream to be played and also give cookies if retrying.
*/
let resource = createAudioResource(source.stream, {
inputType : source.type
}) // This creates resource for playing
```
## Search
### search(url : `string`, options? : [SearchOptions](https://github.com/play-dl/play-dl/tree/main/play-dl/YouTube#searchoptions))
*This enables all searching mechanism (video, channel, playlist)*
_This enables all searching mechanism (video, channel, playlist)_
```js
const options = {
@ -83,46 +55,49 @@ const results = await youtube.search('never gonna give you up', options);
console.log(results[0].url);
```
- #### SearchOptions
- *type* : `video` | `channel` | `playlist`
- *limit* : `integer`
- #### SearchOptions
- _type_ : `video` | `channel` | `playlist`
- _limit_ : `integer`
## Video
### video_basic_info(url : `string`, cookie? : `string`)
*The basic video details `play-dl` fetches at first from url or videoID.*
_The basic video details `play-dl` fetches at first from url or videoID._
**[Cookies](https://github.com/play-dl/play-dl/discussions/34) are optional and are required for playing age restricted videos.**
```js
const video = await video_basic_info(url)
```
### video_info(url : `string`, cookie? : `string`)
*This contains everything with deciphered formats along with `video_details`. It can fetech data from url or videoID.*
_This contains everything with deciphered formats along with `video_details`. It can fetech data from url or videoID._
**[Cookies](https://github.com/play-dl/play-dl/discussions/34) are optional and are required for playing age restricted videos.**
```js
const video = await video_info(url)
```
- #### format `property`
*This returns all the formats available for a video.*
```js
const video = await video_info(url)
console.log(video.format)
```
- #### format `property`
_This returns all the formats available for a video._
```js
const video = await video_info(url)
console.log(video.format)
```
## Playlist
### playlist_info(url : `string`, parseIncomplete : `boolean`)
*This fetches all details about a playlist from a url or playlistID.*
_This fetches all details about a playlist from a url or playlistID._
**parseIncomplete** is optional parameter if you want to parse playlist with hidden videos.
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist
@ -131,77 +106,82 @@ const playlist = await playlist_info(url, true)
//This only fetches first 100 videos from a playlist and also parses playlist with hidden videos
```
- #### fetch() `method`
*This fetches and returns all videos from the whole provided playlist .*
- #### fetch() `method`
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist
await playlist.fetch()
// This one fetches all videos from a playlist.
```
_This fetches and returns all videos from the whole provided playlist ._
- #### page(page_number : `number`)
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist
*This returns no. of videos from a page.*
await playlist.fetch()
// This one fetches all videos from a playlist.
```
> Every 100 videos have been divided into pages.
> Example: There are 782 videos in a playlist, so there will be 8 pages.
- #### page(page_number : `number`)
```js
const playlist = await playlist_info(url);
// This only fetches first 100 videos from a playlist.
await playlist.fetch();
// This one fetches all videos from a playlist.
console.log(playlist.page(1));
// This displays first 100 videos of a playlist
_This returns no. of videos from a page._
- #### total_pages `property`
*This returns total no. of pages that have been fetched so far.*
> Every 100 videos have been divided into pages.
> Example: There are 782 videos in a playlist, so there will be 8 pages.
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist.
await playlist.fetch()
// This one fetches all videos from a playlist.
console.log(playlist.total_pages)
// This displays total no. of pages fetched so far.
```js
const playlist = await playlist_info(url);
// This only fetches first 100 videos from a playlist.
for(let i = 1; i <= playlist.total_pages; i++){
queue.push(...playlist.page(i))
} // This will push every video in that playlist to your queue
```
await playlist.fetch();
// This one fetches all videos from a playlist.
- #### total_videos `property`
*This returns total no. of videos that have been fetched so far.*
console.log(playlist.page(1));
// This displays first 100 videos of a playlist
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist.
await playlist.fetch()
// This one fetches all videos from a playlist.
console.log(playlist.total_videos)
// This displays total no. of videos fetched so far.
```
```
- #### videoCount `property`
- #### total_pages `property`
*This returns total no. of videos in the provided playlist.*
_This returns total no. of pages that have been fetched so far._
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist.
await playlist.fetch()
// This one fetches all videos from a playlist.
console.log(playlist.videoCount)
// This displays total no. of videos in a playlist.
```
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist.
await playlist.fetch()
// This one fetches all videos from a playlist.
console.log(playlist.total_pages)
// This displays total no. of pages fetched so far.
for(let i = 1; i <= playlist.total_pages; i++){
queue.push(...playlist.page(i))
} // This will push every video in that playlist to your queue
```
- #### total_videos `property`
_This returns total no. of videos that have been fetched so far._
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist.
await playlist.fetch()
// This one fetches all videos from a playlist.
console.log(playlist.total_videos)
// This displays total no. of videos fetched so far.
```
- #### videoCount `property`
_This returns total no. of videos in the provided playlist._
```js
const playlist = await playlist_info(url)
//This only fetches first 100 videos from a playlist.
await playlist.fetch()
// This one fetches all videos from a playlist.
console.log(playlist.videoCount)
// This displays total no. of videos in a playlist.
```

View File

@ -0,0 +1,47 @@
const discord = require('discord.js')
const { Intents } = require('discord.js')
const { createAudioPlayer, createAudioResource , StreamType, demuxProbe, joinVoiceChannel, NoSubscriberBehavior, AudioPlayerStatus, VoiceConnectionStatus, getVoiceConnection } = require('@discordjs/voice')
const play = require('play-dl')
const client = new discord.Client({ intents : [Intents.FLAGS.GUILDS, Intents.FLAGS.GUILD_MESSAGES, Intents.FLAGS.GUILD_VOICE_STATES, Intents.FLAGS.DIRECT_MESSAGES] , partials : ['CHANNEL', 'MESSAGE']})
const token = '< YOUR BOT TOKEN >'
client.on('messageCreate', async message => {
if(message.content.startsWith('!play')){
if(!message.member.voice?.channel) return message.channel.send('Connect to a Voice Channel')
const connection = joinVoiceChannel({
channelId : message.member.voice.channel.id,
guildId : message.guild.id,
adapterCreator: message.guild.voiceAdapterCreator
})
let args = message.content.split('play ')[1].split(' ')[0]
let stream = await play.stream(args)
/*
OR if you want to get info about soundcloud link and then stream it
let so_info = await play.soundcloud(args) // Make sure that url is track url only. For playlist, make some logic.
console.log(so_info.name)
let stream = await play.stream_from_info(so_info)
*/
let resource = createAudioResource(stream, {
inputType : stream.type
})
let player = createAudioPlayer({
behaviors: {
noSubscriber: NoSubscriberBehavior.Play
}
})
player.play(resource)
connection.subscribe(player)
}
})
client.on('ready', () => {
console.log(`We have logged in as ${client.user.tag}!`)
})
client.login(token);

View File

@ -1,3 +0,0 @@
const { Authorization } = require('play-dl');
Authorization()

View File

@ -22,7 +22,7 @@ client.on('messageCreate', async message => {
let searched = await play.search(`${sp_data.name}`, { limit : 1 }) // This will search the found track on youtube.
let stream = await play.stream(searched[0].url) // This will create stream from the above search
let resource = createAudioResource(stream.stream, {
let resource = createAudioResource(stream, {
inputType : stream.type
})
let player = createAudioPlayer({

View File

@ -26,7 +26,7 @@ client.on('messageCreate', async message => {
let stream = await play.stream_from_info(yt_info, COOKIE)
*/
let resource = createAudioResource(stream.stream, {
let resource = createAudioResource(stream, {
inputType : stream.type
})
let player = createAudioPlayer({

View File

@ -18,7 +18,7 @@ client.on('messageCreate', async message => {
let args = message.content.split('play')[1]
let yt_info = await play.search(args, { limit : 1 })
let stream = await play.stream(yt_info[0].url)
let resource = createAudioResource(stream.stream, {
let resource = createAudioResource(stream, {
inputType : stream.type
})
let player = createAudioPlayer({

View File

@ -25,7 +25,7 @@ client.on('messageCreate', async message => {
let stream = await play.stream_from_info(yt_info)
*/
let resource = createAudioResource(stream.stream, {
let resource = createAudioResource(stream, {
inputType : stream.type
})
let player = createAudioPlayer({

3
examples/authorize.js Normal file
View File

@ -0,0 +1,3 @@
const { authorization } = require('play-dl');
authorization()

View File

@ -49,7 +49,7 @@ export class SoundCloudTrack {
contains_music: boolean;
writer_composer: string;
} | null;
thumbanil: string;
thumbnail: string;
user: SoundCloudUser;
constructor(data: any) {
this.name = data.title;
@ -81,7 +81,23 @@ export class SoundCloudTrack {
last_name: data.user.last_name,
thumbnail: data.user.avatar_url
};
this.thumbanil = data.artwork_url;
this.thumbnail = data.artwork_url;
}
toJSON() {
return {
name: this.name,
id: this.id,
type: this.type,
url: this.url,
fetched : this.fetched,
durationInMs: this.durationInMs,
durationInSec: this.durationInSec,
publisher: this.publisher,
formats: this.formats,
thumbnail: this.thumbnail,
user : this.user
};
}
}
@ -152,6 +168,30 @@ export class SoundCloudPlaylist {
}
await Promise.allSettled(work);
}
get total_tracks(){
let count = 0
this.tracks.forEach((track) => {
if(track instanceof SoundCloudTrack) count++
else return
})
return count
}
toJSON() {
return {
name: this.name,
id: this.id,
type: this.type,
sub_type : this.sub_type,
url: this.url,
durationInMs: this.durationInMs,
durationInSec: this.durationInSec,
tracksCount : this.tracksCount,
user : this.user,
tracks : this.tracks
};
}
}
export class Stream extends PassThrough {

View File

@ -9,9 +9,9 @@ import { SpotifyAuthorize } from './Spotify';
import { check_id, stream as so_stream, stream_from_info as so_stream_info } from './SoundCloud';
import { InfoData, stream as yt_stream, stream_from_info as yt_stream_info } from './YouTube/stream';
import { SoundCloudTrack, Stream as SoStream } from './SoundCloud/classes';
import { LiveStreaming, Stream } from './YouTube/classes/LiveStream';
import { LiveStreaming, Stream as YTStream } from './YouTube/classes/LiveStream';
export async function stream(url: string, cookie?: string): Promise<Stream | LiveStreaming | SoStream> {
export async function stream(url: string, cookie?: string): Promise<YTStream | LiveStreaming | SoStream> {
if (url.indexOf('soundcloud') !== -1) return await so_stream(url);
else return await yt_stream(url, cookie);
}
@ -19,7 +19,7 @@ export async function stream(url: string, cookie?: string): Promise<Stream | Liv
export async function stream_from_info(
info: InfoData | SoundCloudTrack,
cookie?: string
): Promise<Stream | LiveStreaming | SoStream> {
): Promise<YTStream | LiveStreaming | SoStream> {
if (info instanceof SoundCloudTrack) return await so_stream_info(info);
else return await yt_stream_info(info, cookie);
}