Ytdl

One YouTube session: visitor data, blocked clients, account and PO tokens belong to the instance. Use one instance per network identity; setCookie switches its account in place.

Constructors

Constructor

new Ytdl(options?): Ytdl

Parameters

Parameter	Type
options?	YtdlOptions

Returns

Ytdl

Methods

download()

download(video, options?): Readable

Streams the format chooseFormat picks as a Node Readable. An unexpired info is used as is; otherwise the video is looked up again, with an explicit format until a client offers that same file. Readable.toWeb turns the stream into a web ReadableStream.

Parameters

Parameter	Type
video	string | VideoInfo
options?	DownloadOptions

Returns

Readable

---

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

Parameter	Type
video	string | VideoInfo
options?	CaptionOptions

Returns

Promise<string>

---

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

Parameter	Type
video	string
options?	LookupOptions

Returns

Promise<VideoInfo>

---

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

Parameter	Type
playlist	string
options?	ListOptions

Returns

Promise<PlaylistInfo>

---

getRelated()

getRelated(video, options?): Promise<readonly VideoSummary[]>

The related videos getInfo returns as relatedVideos, from one next request and no player lookup. With music, the video’s YouTube Music radio instead, without the video itself, artists as author. YouTube Music builds the radio for each request, so two calls can return different entries and orders. Takes the same input as getInfo.

Parameters

Parameter	Type
video	string
options?	RelatedOptions

Returns

Promise<readonly VideoSummary[]>

---

getSong()

getSong(video, options?): Promise<VideoSummary>

The video as YouTube Music lists it, from one next request and no player lookup: its title, its artists as author, its listed length and YouTube Music’s art. Rejects NOT_FOUND when YouTube Music lists no entry for it. Takes the same input as getInfo.

Parameters

Parameter	Type
video	string
options?	LookupOptions

Returns

Promise<VideoSummary>

---

getSuggestions()

getSuggestions(query, options?): Promise<readonly string[]>

YouTube’s autocomplete completions for query, or YouTube Music’s with music, in provider order, asked in the instance’s lang and country. YouTube Music’s song and artist suggestions are left out.

Parameters

Parameter	Type
query	string
options?	DiscoveryOptions

Returns

Promise<readonly string[]>

---

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

Parameter	Type
info	VideoInfo
format	VideoFormat

Returns

Media

---

search()

Call Signature

search(query, options?): Promise<readonly VideoSummary[]>

Videos, playlists with type: SearchType.Playlist, or YouTube Music songs with type: SearchType.Song, matching query in the provider’s rank order, at most limit (20 unless set), across as many result pages as that takes. Channels, shelves and mixes, and YouTube Music’s albums, artists, playlists and videos, are left out. Discovery requests share the instance’s visitor data and never send the cookie.

Parameters

Parameter	Type
query	string
options?	SearchOptions & object

Returns

Promise<readonly VideoSummary[]>

Call Signature

search(query, options): Promise<readonly PlaylistSummary[]>

Videos, playlists with type: SearchType.Playlist, or YouTube Music songs with type: SearchType.Song, matching query in the provider’s rank order, at most limit (20 unless set), across as many result pages as that takes. Channels, shelves and mixes, and YouTube Music’s albums, artists, playlists and videos, are left out. Discovery requests share the instance’s visitor data and never send the cookie.

Parameters

Parameter	Type
query	string
options	SearchOptions & object

Returns

Promise<readonly PlaylistSummary[]>

Call Signature

search(query, options?): Promise<readonly VideoSummary[] | readonly PlaylistSummary[]>

Videos, playlists with type: SearchType.Playlist, or YouTube Music songs with type: SearchType.Song, matching query in the provider’s rank order, at most limit (20 unless set), across as many result pages as that takes. Channels, shelves and mixes, and YouTube Music’s albums, artists, playlists and videos, are left out. Discovery requests share the instance’s visitor data and never send the cookie.

Parameters

Parameter	Type
query	string
options?	SearchOptions

Returns

Promise<readonly VideoSummary[] | readonly PlaylistSummary[]>

---

setCookie()

setCookie(cookie): void

Signs lookups that start from now on in with cookie, in any form the cookie option takes, or signs them out with undefined. Lookups already running finish with the previous cookie, and a running download or Media read re-resolves with the new one. Forgets the blocks of clients that can sign in. Throws INVALID_ARGUMENT and keeps the previous cookie when cookie is signed out, or when every listed client needs a cookie and it is undefined.

Parameters

Parameter	Type
cookie	string | undefined

Returns

void