YouTube Video Downloader (ytdl-core)

Common errors

• Error: Video is unavailable

  cause YouTube has made changes to its video embedding or streaming API, or the video itself is geo-restricted/private/deleted.
  fix Ensure `ytdl-core` is the latest version. Check if the video is genuinely available and not restricted. For geo-restricted or private videos you have access to, consider using proxy or cookie options.

• Error: No video formats found

  cause Often linked to YouTube API changes that prevent `ytdl-core` from correctly parsing available formats, or potentially due to age-restriction/account requirements.
  fix Update `ytdl-core` to the latest version to get the newest parsing fixes. If the problem persists, check for existing issues on the GitHub repository or create a new one, providing the video URL.

• TypeError: Cannot read properties of undefined (reading 'pipe') or stream hangs indefinitely

  cause Typically caused by throttling from YouTube due to too many requests from a single IP, or outdated signature deciphering logic.
  fix Ensure `ytdl-core` is updated. Implement IPv6 rotation via the `IPv6Block` option or use a proxy to circumvent throttling. Adjust `dlChunkSize` if large files are being throttled.

• TS2307: Cannot find module 'ytdl-core' or its corresponding type declarations.

  cause Incorrect TypeScript configuration or import syntax for a package that might not explicitly define default exports for CommonJS `require` when `esModuleInterop` is off.
  fix In `tsconfig.json`, set `"esModuleInterop": true` or `"allowSyntheticDefaultImports": true`. Then use `import ytdl from 'ytdl-core';`. Alternatively, use `import * as ytdl from 'ytdl-core';`.

Warnings

• breaking YouTube frequently updates its website and API, which can lead to `ytdl-core` breaking or requiring updates to continue functioning. Developers should ensure they are using the latest version.
  Fix: Regularly update `ytdl-core` to the latest version. If using a wrapper library, ensure it has updated its `ytdl-core` dependency.
• gotcha The `begin` option for starting a video download at a specific timestamp is known to be unreliable for non-live videos, as documented in issues #129 and #219.
  Fix: For precise segment downloads, consider manually seeking or processing the full download with a tool like FFmpeg, or using the `range` option if applicable.
• gotcha Higher quality video formats (1080p and above) are often delivered without an accompanying audio track. Downloading such formats requires separate audio and video streams to be downloaded and then merged, typically with an external tool like FFmpeg.
  Fix: Utilize `ytdl.getInfo()` to get available formats, select separate audio-only and video-only streams, download them, and then use a library (e.g., `fluent-ffmpeg`) to merge them. See the `example/ffmpeg.js` in the official repository.
• deprecated The primary maintainer has paused active development on `fent/node-ytdl-core` since July 14, 2023, with support now community-driven and PRs not currently merged. Users are encouraged to explore forks like `@distube/ytdl-core` for ongoing updates.
  Fix: For active development and guaranteed fixes, consider migrating to a actively maintained fork like `@distube/ytdl-core` if you encounter persistent issues or require new features.

Install

• npm install ytdl-core npm
• yarn add ytdl-core yarn
• pnpm add ytdl-core pnpm

Imports

• ytdl
  wrong:

  const ytdl = require('ytdl-core'); // CommonJS is supported, but ESM is preferred for modern Node.js and TypeScript projects.

  correct:

  import ytdl from 'ytdl-core';

  For TypeScript, use `import ytdl from 'ytdl-core';` with `--esModuleInterop` or `import * as ytdl from 'ytdl-core';` with `--allowSyntheticDefaultImports`.
• getInfo
  wrong:

  import { getInfo } from 'ytdl-core'; // getInfo is a method on the default export, not a named export.

  correct:

  import ytdl from 'ytdl-core';
  await ytdl.getInfo(url);

  getInfo is an asynchronous function available as a method on the default `ytdl` export. It returns a Promise with detailed video metadata and format information.
• getBasicInfo
  wrong:

  import { getBasicInfo } from 'ytdl-core'; // getBasicInfo is a method on the default export, not a named export.

  correct:

  import ytdl from 'ytdl-core';
  await ytdl.getBasicInfo(url);

  Similar to getInfo, getBasicInfo is a method on the default `ytdl` export, providing lighter metadata without detailed format information.

Quickstart

This quickstart demonstrates how to download a YouTube video using `ytdl-core` and pipe it directly to a file. It also shows a commented-out example of how to retrieve video metadata using `getInfo`.

import * as fs from 'fs';
import ytdl from 'ytdl-core';

const videoUrl = 'http://www.youtube.com/watch?v=aqz-KE-bpKQ'; // Example video ID
const outputFileName = process.env.VIDEO_OUTPUT_PATH ?? 'video.mp4';

console.log(`Downloading video from ${videoUrl} to ${outputFileName}...`);

ytdl(videoUrl, { quality: 'highestaudio' })
  .pipe(fs.createWriteStream(outputFileName))
  .on('finish', () => {
    console.log('Download complete!');
  })
  .on('error', (err) => {
    console.error('Error during download:', err.message);
    // Optionally delete partially downloaded file on error
    if (fs.existsSync(outputFileName)) {
      fs.unlinkSync(outputFileName);
    }
  });

// Example of fetching video information
// ytdl.getInfo(videoUrl).then(info => {
//   console.log('Title:', info.videoDetails.title);
//   console.log('Formats:', info.formats.length);
// }).catch(err => console.error('Error fetching info:', err.message));