Home

Awesome

[!IMPORTANT]
Active development on this repository has been paused since 2023-07-14. While it may still function for some scenarios, please be aware that support is now handled solely by the community, and PRs are currently not merged to the repo. For ongoing updates, we encourage you to explore forks like @distube/ytdl-core. We may revisit development in the future. Thank you for your interest and long-lasting support!
Best Regards TFAN, 2024-08-13

node-ytdl-core

Depfu codecov Discord

Yet another YouTube downloading module. Written with only Javascript and a node-friendly streaming interface.

Support

You can contact us for support on our chat server

Usage

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'));

API

ytdl(url, [options])

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.

Event: info

Emitted when the video's info is fetched, along with the chosen format to download.

Event: progress

Emitted whenever a new chunk is received. Passes values describing the download progress.

miniget events

All miniget events are forwarded and can be listened to from the returned stream.

Stream#destroy()

Call to abort and stop downloading a video.

async ytdl.getBasicInfo(url, [options])

Use this if you only want to get metainfo from a video.

async ytdl.getInfo(url, [options])

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

ytdl.downloadFromInfo(info, options)

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.

ytdl.chooseFormat(formats, options)

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

// 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);

ytdl.filterFormats(formats, filter)

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);

ytdl.validateID(id)

Returns true if the given string satisfies YouTube's ID format.

ytdl.validateURL(url)

Returns true if able to parse out a valid video ID.

ytdl.getURLVideoID(url)

Returns a video ID from a YouTube URL. Throws an Error if it fails to parse an ID.

ytdl.getVideoID(str)

Same as the above ytdl.getURLVideoID(), but can be called with the video ID directly, in which case it returns it. This is what ytdl uses internally. Throws an Error if it fails to parse an ID.

ytdl.version

The version string taken directly from the package.json.

Limitations

ytdl cannot download videos that fall into the following

Generated download links are valid for 6 hours, and may only be downloadable from the same IP address.

Ratelimits

When doing too many requests, YouTube might block. This will result in your requests getting denied with HTTP-StatusCode 429. The following Steps might help you:

How does using an IPv6 block help?

For request-intensive tasks it might be useful to spread your requests across multiple source IP-Addresses. Changing the source IP that you use is similar to using a proxy, except without bypassing restrictions such as a region lock. More IP-Addresses result in less requests per IP and therefor increase your ratelimit. Since IPv4 Addresses are a limited Resource we advise to use IPv6.

Using an IPv6 block is essentially having millions of IPv6 addresses at your request. In a /64 IPv6 block (which is usually the Block given to a single Household), there are 18,446,744,073,709,551,616 unique IPv6 addresses. This would allow you to make each request with a different IPv6 address.

Even though using an IP-Block does help against ratelimits it requires you to setup your host system to accept http traffic from every message in an IP-Block. We can not help you with the setup for any specific host / hosting provider but searching the internet most likely can.

Handling Separate Streams

Typically 1080p or better videos do not have audio encoded with it. The audio must be downloaded separately and merged via an encoding library. ffmpeg is the most widely used tool, with many Node.js modules available. Use the format objects returned from ytdl.getInfo to download specific streams to combine to fit your needs. Look at example/ffmpeg.js for an example on doing this.

What if it stops working?

YouTube updates their website all the time, it's not that rare for this to stop working. If it doesn't work for you and you're using the latest version, feel free to open up an issue. Make sure to check if there isn't one already with the same error.

Run the tests at test/irl-test.js to make sure this is really an issue with ytdl-core.

npm run test:irl

These tests are not mocked, they try to start downloading a few videos. If these fail, then it's time to debug. If the error you're getting is signature deciphering, check lib/sig.js. Otherwise, the error is likely within lib/info.js.

Install

npm install ytdl-core@latest

Or for Yarn users:

yarn add ytdl-core@latest

Make sure you're installing the latest version of ytdl-core to keep up with the latest fixes.

If you're using a bot or app that uses ytdl-core such as ytdl-core-discord or discord-player, it may be dependent on an older version. To update its ytdl-core version, that library has to update its package.json file, you can't simply change the version on your project's package.json, the app will still use its own older version of ytdl-core.

Look in their repo to see if they already have an active pull request that updates ytdl-core. If they don't, open an issue asking them to update ytdl-core, or better yet, fork the project and submit a pull request with the updated version.

While you wait for the pull reques to merge, you can point to its branch in your package.json

  "ytdl-core-discord": "amishshah/ytdl-core-discord#dependabot/npm_and_yarn/ytdl-core-2.0.1"

Update Checks

The issue of using an outdated version of ytdl-core became so prevalent, that ytdl-core now checks for updates at run time, and every 12 hours. If it finds an update, it will print a warning to the console advising you to update. Due to the nature of this library, it is important to always use the latest version as YouTube continues to update.

If you'd like to disable this update check, you can do so by providing the YTDL_NO_UPDATE env variable.

env YTDL_NO_UPDATE=1 node myapp.js

Related Projects

Tests

Tests are written with mocha

npm test