const fs = require('fs');
const ytdl = require('ytdl-core');
// TypeScript: import ytdl from 'ytdl-core'; with --esModuleInterop
// TypeScript: import * as ytdl from 'ytdl-core'; with --allowSyntheticDefaultImports
// TypeScript: import ytdl = require('ytdl-core'); with neither of the above
ytdl('http://www.youtube.com/watch?v=aqz-KE-bpKQ')
.pipe(fs.createWriteStream('video.mp4'));
Attempts to download a video from the given url. Returns a readable stream. options
can have the following, in addition to any getInfo()
option and chooseFormat()
option.
ytdl.videoInfo
- Info.ytdl.videoFormat
- Video Format.
Emitted when the video's info
is fetched, along with the chosen format to download.
number
- Chunk length in bytes or segment number.number
- Total bytes or segments downloaded.number
- Total bytes or segments.
Emitted whenever a new chunk is received. Passes values describing the download progress.
All miniget events are forwarded and can be listened to from the returned stream.
Call to abort and stop downloading a video.
Use this if you only want to get metainfo from a video.
Gets metainfo from a video. Includes additional formats, and ready to download deciphered URL. This is what the ytdl()
function uses internally.
options
can have the following
requestOptions
- Anything to merge into the request options which miniget is called with, such asheaders
.requestCallback
- Provide a callback function that receives miniget request stream objects used while fetching metainfo.lang
- The 2 character symbol of a language. Default isen
.
Once you have received metadata from a video with the ytdl.getInfo
function, you may pass that information along with other options to this function.
Can be used if you'd like to choose a format yourself. Throws an Error if it fails to find any matching format.
options
can have the following
-
quality
- Video quality to download. Can be an itag value, a list of itag values, or one of these strings:highest
/lowest
/highestaudio
/lowestaudio
/highestvideo
/lowestvideo
.highestaudio
/lowestaudio
try to minimize video bitrate for equally good audio formats whilehighestvideo
/lowestvideo
try to minimize audio respectively. Defaults tohighest
, which prefers formats with both video and audio.A typical video's formats will be sorted in the following way using
quality: 'highest'
itag container quality codecs bitrate audio bitrate 18 mp4 360p avc1.42001E, mp4a.40.2 696.66KB 96KB 137 mp4 1080p avc1.640028 4.53MB 248 webm 1080p vp9 2.52MB 136 mp4 720p avc1.4d4016 2.2MB 247 webm 720p vp9 1.44MB 135 mp4 480p avc1.4d4014 1.1MB 134 mp4 360p avc1.4d401e 593.26KB 140 mp4 mp4a.40.2 128KB
format 18 at 360p will be chosen first since it's the highest quality format with both video and audio. If you'd like a higher quality format with both video and audio, see the section on handling separate streams.
-
filter
- Used to filter the list of formats to choose from. Can beaudioandvideo
orvideoandaudio
to filter formats that contain both video and audio,video
to filter for formats that contain video, orvideoonly
for formats that contain video and no additional audio track. Can also beaudio
oraudioonly
. You can give a filtering function that gets called with each format available. This function is given theformat
object as its first argument, and should return true if the format is preferable.// Example with custom function. ytdl(url, { filter: format => format.container === 'mp4' })
-
format
- Primarily used to download specific video or audio streams. This can be a specificformat
object returned fromgetInfo
.- Supplying this option will ignore the
filter
andquality
options since the format is explicitly provided.
- Supplying this option will ignore the
// Example of choosing a video format.
let info = await ytdl.getInfo(videoID);
let format = ytdl.chooseFormat(info.formats, { quality: '134' });
console.log('Format found!', format);
If you'd like to work with only some formats, you can use the filter
option above.
// Example of filtering the formats to audio only.
let info = await ytdl.getInfo(videoID);
let audioFormats = ytdl.filterFormats(info.formats, 'audioonly');
console.log('Formats with only audio: ' + audioFormats.length);
The version string taken directly from the package.json.
npm install ytdl-core@latest
Or for Yarn users:
yarn add ytdl-core@latest
Tests are written with mocha
npm test