search

distubejs / ytdl-core

YouTube video downloader in javascript.
MIT License
289 stars 50 forks source link

readme

@distube/ytdl-core

DisTube fork of ytdl-core. This fork is dedicated to fixing bugs and adding features that are not merged into the original repo as soon as possible.

Buy Me a Coffee at ko-fi.com

Installation

npm install @distube/ytdl-core@latest

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

Usage

const ytdl = require("@distube/ytdl-core");
// TypeScript: import ytdl from '@distube/ytdl-core'; with --esModuleInterop
// TypeScript: import * as ytdl from '@distube/ytdl-core'; with --allowSyntheticDefaultImports
// TypeScript: import ytdl = require('@distube/ytdl-core'); with neither of the above

// Download a video
ytdl("http://www.youtube.com/watch?v=aqz-KE-bpKQ").pipe(require("fs").createWriteStream("video.mp4"));

// Get video info
ytdl.getBasicInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ").then(info => {
  console.log(info.videoDetails.title);
});

// Get video info with download formats
ytdl.getInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ").then(info => {
  console.log(info.formats);
});

Cookies Support

const ytdl = require("@distube/ytdl-core");

// (Optional) Below are examples, NOT the recommended options
const cookies = [
  { name: "cookie1", value: "COOKIE1_HERE" },
  { name: "cookie2", value: "COOKIE2_HERE" },
];

// (Optional) http-cookie-agent / undici agent options
// Below are examples, NOT the recommended options
const agentOptions = {
  pipelining: 5,
  maxRedirections: 0,
  localAddress: "127.0.0.1",
};

// agent should be created once if you don't want to change your cookie
const agent = ytdl.createAgent(cookies, agentOptions);

ytdl.getBasicInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ", { agent });
ytdl.getInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ", { agent });

How to get cookies

[!WARNING] Don't logout it by clicking logout button on youtube/google account manager, it will expire your cookies. You can delete your browser's cookies to log it out on your browser. Or use incognito mode to get your cookies then close it.

[!WARNING] Paste all the cookies array from clipboard into createAgent function. Don't remove/edit any cookies if you don't know what you're doing.

[!WARNING] Make sure your account, which logged in when you getting your cookies, use 1 IP at the same time only. It will make your cookies alive longer.

const ytdl = require("@distube/ytdl-core");
const agent = ytdl.createAgent([
  {
    domain: ".youtube.com",
    expirationDate: 1234567890,
    hostOnly: false,
    httpOnly: true,
    name: "---xxx---",
    path: "/",
    sameSite: "no_restriction",
    secure: true,
    session: false,
    value: "---xxx---",
  },
  {
    "...": "...",
  },
]);
const ytdl = require("@distube/ytdl-core");
const fs = require("fs");
const agent = ytdl.createAgent(JSON.parse(fs.readFileSync("cookies.json")));

Proxy Support

const ytdl = require("@distube/ytdl-core");

const agent = ytdl.createProxyAgent({ uri: "my.proxy.server" });

ytdl.getBasicInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ", { agent });
ytdl.getInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ", { agent });

Use both proxy and cookies:

const ytdl = require("@distube/ytdl-core");

const agent = ytdl.createProxyAgent({ uri: "my.proxy.server" }, [{ name: "cookie", value: "COOKIE_HERE" }]);

ytdl.getBasicInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ", { agent });
ytdl.getInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ", { agent });

IP Rotation

Built-in ip rotation (getRandomIPv6) won't be updated and will be removed in the future, create your own ip rotation instead.

To implement IP rotation, you need to assign the desired IP address to the localAddress property within undici.Agent.Options. Therefore, you'll need to use a different ytdl.Agent for each IP address you want to use.

const ytdl = require("@distube/ytdl-core");
const { getRandomIPv6 } = require("@distube/ytdl-core/lib/utils");

const agentForARandomIP = ytdl.createAgent(undefined, {
  localAddress: getRandomIPv6("2001:2::/48"),
});

ytdl.getBasicInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ", { agent: agentForARandomIP });

const agentForAnotherRandomIP = ytdl.createAgent(undefined, {
  localAddress: getRandomIPv6("2001:2::/48"),
});

ytdl.getInfo("http://www.youtube.com/watch?v=aqz-KE-bpKQ", { agent: agentForAnotherRandomIP });

API

You can find the API documentation in the original repo. Except a few changes:

ytdl.getInfoOptions

ytdl.createAgent([cookies]): ytdl.Agent

cookies: an array of json cookies exported with EditThisCookie.

ytdl.createProxyAgent(proxy[, cookies]): ytdl.Agent

proxy: ProxyAgentOptions contains your proxy server information.

How to implement ytdl.Agent with your own Dispatcher

You can find the example here

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.

Rate Limiting

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:

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