Ytdl
One YouTube session: visitor data, blocked clients, account and PO tokens belong to the instance. Use one instance per account or network identity.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new Ytdl(
options?):Ytdl
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
options? |
YtdlOptions |
Returns
Section titled “Returns”Ytdl
Methods
Section titled “Methods”download()
Section titled “download()”download(
video,options?):Readable
Streams the format chooseFormat picks as a Node Readable. An unexpired info is used as is; Readable.toWeb
turns the stream into a web ReadableStream.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
video |
string | VideoInfo |
options? |
DownloadOptions |
Returns
Section titled “Returns”Readable
getCaptions()
Section titled “getCaptions()”getCaptions(
video,options?):Promise<string>
YouTube’s own text for one caption track, not parsed into cues. The format is CaptionFormat.Vtt unless
format says otherwise. lang must equal a track’s languageCode, so de does not match de-DE.
YouTube’s timedtext endpoint answers HTTP 429 after a few quick requests from one IP, which rejects with
RATE_LIMITED and is not retried, so cache the text.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
video |
string | VideoInfo |
options? |
CaptionOptions |
Returns
Section titled “Returns”Promise<string>
getInfo()
Section titled “getInfo()”getInfo(
video,options?):Promise<VideoInfo>
Video details, related videos and formats whose URLs are ready to request. A channel’s live URL,
such as https://www.youtube.com/@NASA/live, looks up the stream it plays now.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
video |
string |
options? |
LookupOptions |
Returns
Section titled “Returns”Promise<VideoInfo>
getPlaylist()
Section titled “getPlaylist()”getPlaylist(
playlist,options?):Promise<PlaylistInfo>
A playlist by ID or by a YouTube URL with a list parameter, or a channel’s uploads by channel ID or channel URL,
with its entries in playlist order across pages: all of them, or the first limit. Entries YouTube marks
unplayable are left out.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
playlist |
string |
options? |
ListOptions |
Returns
Section titled “Returns”Promise<PlaylistInfo>
getRelated()
Section titled “getRelated()”getRelated(
video,options?):Promise<readonlyVideoSummary[]>
The related videos getInfo returns as relatedVideos, from one next request and no player lookup.
Takes the same input as getInfo.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
video |
string |
options? |
LookupOptions |
Returns
Section titled “Returns”Promise<readonly VideoSummary[]>
getSuggestions()
Section titled “getSuggestions()”getSuggestions(
query,options?):Promise<readonlystring[]>
YouTube’s autocomplete completions for query in provider order, asked in the instance’s lang and country.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
query |
string |
options? |
LookupOptions |
Returns
Section titled “Returns”Promise<readonly string[]>
open()
Section titled “open()”open(
info,format):Media
One format of info, read as often as needed without another lookup. A read that re-resolves after a 403 or
an expired URL refreshes Media#info, and later reads start from it.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
info |
VideoInfo |
format |
VideoFormat |
Returns
Section titled “Returns”search()
Section titled “search()”Call Signature
Section titled “Call Signature”search(
query,options?):Promise<readonlyVideoSummary[]>
Videos, or playlists with type: SearchType.Playlist, matching query in YouTube’s rank order, at most limit
(20 unless set), across as many result pages as that takes. Channels, shelves and mixes are left out.
Discovery requests share the instance’s visitor data and never send the cookie.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
query |
string |
options? |
SearchOptions & object |
Returns
Section titled “Returns”Promise<readonly VideoSummary[]>
Call Signature
Section titled “Call Signature”search(
query,options):Promise<readonlyPlaylistSummary[]>
Videos, or playlists with type: SearchType.Playlist, matching query in YouTube’s rank order, at most limit
(20 unless set), across as many result pages as that takes. Channels, shelves and mixes are left out.
Discovery requests share the instance’s visitor data and never send the cookie.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
query |
string |
options |
SearchOptions & object |
Returns
Section titled “Returns”Promise<readonly PlaylistSummary[]>
Call Signature
Section titled “Call Signature”search(
query,options?):Promise<readonlyVideoSummary[] | readonlyPlaylistSummary[]>
Videos, or playlists with type: SearchType.Playlist, matching query in YouTube’s rank order, at most limit
(20 unless set), across as many result pages as that takes. Channels, shelves and mixes are left out.
Discovery requests share the instance’s visitor data and never send the cookie.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
query |
string |
options? |
SearchOptions |
Returns
Section titled “Returns”Promise<readonly VideoSummary[] | readonly PlaylistSummary[]>