@ybd-project/ytdl-core - v6

YBD Project fork of ytdl-core. This fork is dedicated to developing a YouTube downloader that is fast, stable, and takes into account various use cases, with reference to LuanRT/YouTube.js and yt-dlp.

[!NOTE] If you are looking for v5 documentation for @ybd-project/ytdl-core, please click here.

Table of Contents

1. ℹ️Announcements at this timeℹ️
2. Prerequisite
3. Operating Environment
   • Default (Node.js)
   • Browser
   • Serverless
4. Installation
5. API Documentation
6. Basic Usage
7. Examples
8. Precautions
   • Limitations
   • Rate Limiting
9. License

ℹ️Announcements at this timeℹ️

[!CAUTION] Currently, the account that manages this ytdl-core repository has been flagged as spam, so we are accepting issues, etc. at ybd-project-ver1/ytdl-core instead. Thank you for your cooperation.

Prerequisite

To use @ybd-project/ytdl-core without problems, use Node.js 16 or higher. (Recommended is Node.js 18 or higher.)

[!IMPORTANT] Use with Node.js 16 is not recommended, but will be supported as much as possible.

Operating Environment

[!IMPORTANT] @ybd-project/ytdl-core has not been tested in non-Node.js environments such as Deno. If you need ytdl-core optimized for these environments, please create an issue.

Default (Node.js)

As usual, when using Node.js, as noted in the prerequisites, v16 or higher will work fine. If you have an example that does not work with 16 or higher versions, please create an issue.

[!NOTE] If the Node.js version is less than v16, an error will occur when creating an instance of YtdlCore. To disable it, set the option disableVersionCheck to true. (Deprecated)

Browser

When using a browser, the latest version is preferred due to the API used. However, when operating a website or other site, it is unknown which version and browser the client will use, so the following are the main browsers (Chrome, Edge, Firefox, Brave, Opera, Safari) that are currently confirmed to work.

[!NOTE] In @ybd-project/ytdl-core, if a browser is determined to be not in line with the following versions, an error will be raised when instantiating the YtdlCore class, stating that the version is not supported. To disable it, set the option disableVersionCheck to true. (Deprecated)

List

Live demo used for testing: ytdlcore.static.jp

(Tested with BrowserStack)

Serverless

We have confirmed that ytdl-core for serverless functions works properly in the following environment.

[!TIP] We recommend deploying to Cloudflare Workers because of its simplicity and lower cost compared to other platforms.

Installation

npm install @ybd-project/ytdl-core@latest

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

API Documentation

For details API documentation, see the Wiki.

Basic Usage

Only a simple example is given in the README. For a list of options and other advanced usage, please refer to the API Documentation.

import fs from 'fs';
import { YtdlCore } from '@ybd-project/ytdl-core';
// For browser: import { YtdlCore } from '@ybd-project/ytdl-core/browser';
// For serverless functions: import { YtdlCore } from '@ybd-project/ytdl-core/serverless';

// JavaScript: const { YtdlCore } = require('@ybd-project/ytdl-core');

const ytdl = new YtdlCore({
    // The options specified here will be the default values when functions such as getFullInfo are executed.
});

// Download a video
ytdl.download('https://www.youtube.com/watch?v=dQw4w9WgXcQ', {
    streamType: 'nodejs', // Note: If you do not set the `streamType` to `nodejs`, a pipable stream will not be returned.
}).then((stream) => stream.pipe(fs.createWriteStream('video.mp4')));

// Get video info
ytdl.getBasicInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ').then((info) => {
    console.log(info.videoDetails.title);
});

OAuth2 Support

@ybd-project/ytdl-core supports OAuth2 Token.

These can be used to avoid age restrictions and bot errors. See below for instructions on how to use them.

[!IMPORTANT] Be sure to generate tokens with accounts that can be banned, as accounts may be banned. Note that OAuth2 may expire soon these days. In this case, do not use OAuth2.

[!NOTE] The specified OAuth2 token is automatically updated by ytdl-core, so you do not need to update it yourself.

import { YtdlCore } from '@ybd-project/ytdl-core';

/* Normal usage */
const ytdl = new YtdlCore({
    oauth2Credentials: {
        accessToken: '...',
        refreshToken: '...',
        expiryDate: 'yyyy-MM-ddThh-mm-ssZ',
    },
});

/* If you need to specify a client ID and secret */
const ytdl = new YtdlCore({
    oauth2Credentials: {
        accessToken: '...',
        refreshToken: '...',
        expiryDate: 'yyyy-MM-ddThh-mm-ssZ',
        clientData: {
            clientId: '...',
            clientSecret: '...',
        },
    },
});

/* Specify to the function if there is a need to override what was specified during class initialization. */
// This `ytdl` is already initialized as in the other examples.
ytdl.getFullInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ', {
    oauth2Credentials: {
        accessToken: '...',
        refreshToken: '...',
        expiryDate: 'yyyy-MM-ddThh-mm-ssZ',
    },
});

Oauth2 Access Token generation

There are two recommended methods for generating OAuth2 tokens.

1. Generate using imputnet/cobalt
2. Generate using your own client ID and secret

[!TIP] The method of production with cobalt is very stable and is recommended. Tokens generated using cobalt can be used in the normal way.

[!IMPORTANT] If you generate it yourself, specify the client ID and secret in clientData. This is required to refresh the token.

To generate tokens using Cobalt, execute the following command.

git clone https://github.com/imputnet/cobalt
cd cobalt/api/src
npm install -g pnpm
pnpm install
npm run token:youtube

If you wish to generate your own, please refer to the example folder for an example.

PoToken Support

@ybd-project/ytdl-core supports PoToken.

The PoToken can be used to avoid bot errors and must be specified with VisitorData. If you need to obtain PoToken or VisitorData, please use the following repository to generate them.

1. https://github.com/iv-org/youtube-trusted-session-generator
2. https://github.com/LuanRT/BgUtils
3. https://github.com/fsholehan/scrape-youtube

import { YtdlCore } from '@ybd-project/ytdl-core';

/* Basic Method */
const ytdl = new YtdlCore({ poToken: 'PO_TOKEN', visitorData: 'VISITOR_DATA' });

// PoToken, etc. specified at the time of class instantiation will be used.
// PoToken used: PO_TOKEN
ytdl.getFullInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ');

// Specified as function arguments take precedence over those specified at the time of class instantiation.
// PoToken used: OVERRIDE_PO_TOKEN
ytdl.getFullInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ', { poToken: 'OVERRIDE_PO_TOKEN', visitorData: 'OVERRIDE_VISITOR_DATA' });

Disable automatic PoToken generation

The PoToken is automatically generated if not specified by default. To disable this, set the option disablePoTokenAutoGeneration to true.

import { YtdlCore } from '@ybd-project/ytdl-core';

const ytdl = new YtdlCore({ disablePoTokenAutoGeneration: true });

Proxy Support

@ybd-project/ytdl-core supports proxies.

[!IMPORTANT] Try PoToken or OAuth2 before using a proxy. These may have the same effect as proxies.

Starting with v6.0.0, the createProxyAgent function and others are obsolete. Proxies must be implemented independently through the fetcher function.

import { YtdlCore } from '@ybd-project/ytdl-core';
import { fetch, ProxyAgent } from 'undici';

const AGENT = new ProxyAgent('http://xxx.xxx.xxx.xxx:PORT'),
    ytdl = new YtdlCore({
        fetcher: (url, options) => {
            const REQUEST_OPTIONS: RequestInit = {
                ...options,
                dispatcher: AGENT,
            };

            return fetch(url, REQUEST_OPTIONS);
        },
    });

ytdl.getFullInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ');

Build and use your own proxy

Using a proxy sold by one service may not work. In such cases, you can deploy your own proxy, e.g., to Cloudflare Workers.

See the example for a proxy server implementation.

Use of proprietary proxies

import { YtdlCore } from '@ybd-project/ytdl-core';

const ytdl = new YtdlCore({
    originalProxy: {
        base: 'http://localhost:6543',
        download: 'http://localhost:6543/video-download',
        urlQueryName: 'apiUrl',
    },
});

/* With rewriteRequest, you can specify various things. (e.g., random selection of multiple proxies) */
const ytdl = new YtdlCore({
    rewriteRequest: (url, options, { isDownloadUrl }) => {
        if (isDownloadUrl) {
            // URL is like: https://***.googlevideo.com/playbackvideo?...

            return {
                url: `https://your-video-proxy.server.com/?url=${encodeURIComponent(url)}`,
                options,
            };
        }

        return {
            url: `https://your-proxy.server.com/?url=${encodeURIComponent(url)}`,
            options,
        };
    },
});

ytdl.getFullInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ');

Examples

See the Examples folder for examples of using @ybd-project/ytdl-core.

Precautions

Limitations

@ybd-project/ytdl-core is unable to retrieve or download information from the following videos.

• Regionally restricted (requires a proxy)
• Private (if you have access, requires OAuth2)
• Rentals (if you have access, requires OAuth2)
• YouTube Premium content (if you have access, requires OAuth2)
• Only HLS Livestreams are currently supported. Other formats will get filtered out in ytdl.chooseFormats

The URL to view the retrieved video is valid for 6 hours. (In some cases, downloading may only be possible from the same IP.)

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 @ybd-project/ytdl-core to the latest version
• Use OAuth2 (you can find an example here)
• Use proxies (you can find an example here)
• Extend the Proxy Idea by rotating (IPv6-)Addresses
  • read this for more information about this
• Wait it out (it usually goes away within a few days)

License

Distributed under the MIT License.