@choewy/yt-dlp

A Node.js / TypeScript wrapper for yt-dlp.

This package runs a platform-specific yt-dlp binary and uses ffmpeg-static by default.

Features

• Fluent builder API
• Download video as file, buffer, or stream
• Fetch thumbnail URL
• Built-in yt-dlp binary (auto-installed)
• Built-in FFmpeg (ffmpeg-static)
• Fully typed API
• Debug mode support

Installation

npm install @choewy/yt-dlp

pnpm add @choewy/yt-dlp

pnpm users

This package requires install scripts.

pnpm approve-builds

Approve:

• @choewy/yt-dlp
• ffmpeg-static

Quick Start

import { YtDlp } from '@choewy/yt-dlp';

const result = await new YtDlp({
  url: 'https://www.youtube.com/watch?v=VIDEO_ID',
})
  .mergeFormat('mp4')
  .video()
  .download();

console.log(result.path);

Examples

Download video (file)

const result = await new YtDlp({ url }).mergeFormat('mp4').output('./video.mp4').video().download();

Download as buffer

const { buffer } = await new YtDlp({ url }).mergeFormat('mp4').video().buffer();

Download as stream

import { createWriteStream } from 'fs';

const { stream } = await new YtDlp({ url }).mergeFormat('mp4').video().stream();

stream.pipe(createWriteStream('./video.mp4'));

Extract audio

const result = await new YtDlp({ url }).audioOnly().audioFormat('mp3').output('./audio.%(ext)s').video().download();

Get thumbnail URL

const thumbnail = await new YtDlp({ url }).thumbnail().url();

Custom FFmpeg

new YtDlp({ url }).ffmpeg('/usr/local/bin/ffmpeg').video().download();

API

new YtDlp(options)

new YtDlp({
  url: string,
});

Builder Methods

All methods are chainable.

ytDlp
  .url(url)
  .format(format)
  .output(path)
  .mergeFormat('mp4')
  .audioOnly()
  .audioFormat('mp3')
  .ffmpeg(path)
  .quiet()
  .noWarnings()
  .noProgress()
  .retries(3)
  .fragmentRetries(3)
  .concurrentFragments(4)
  .debug(true);

Configuration Options

| Option | Type | Default | Description | | --------------------- | -------------------------- | --------------- | ----------------------------------------- | | url | string | required | Target media URL | | ffmpeg | string | ffmpeg-static | Path to ffmpeg binary | | format | string | mp4 optimized | yt-dlp format selector | | output | string | - | Output path or template (-o) | | playlist | boolean | false | Download playlist instead of single video | | mergeFormat | 'mp4' \| 'mkv' \| 'webm' | mp4 | Merge container format | | audioOnly | boolean | false | Extract audio only (-x) | | audioFormat | 'mp3' \| 'm4a' \| 'wav' | - | Audio format | | overwrite | boolean | true | Overwrite existing files | | quiet | boolean | true | Suppress output logs | | noWarnings | boolean | true | Suppress warnings | | noProgress | boolean | true | Disable progress output | | restrictFilenames | boolean | false | Use ASCII filenames only | | paths | string | - | Base output directory | | retries | number | 3 | Retry count | | fragmentRetries | number | 3 | Fragment retry count | | concurrentFragments | number | 4 | Parallel fragment downloads | | embedThumbnail | boolean | false | Embed thumbnail into media | | convertThumbnail | 'jpg' \| 'png' \| 'webp' | - | Convert thumbnail format | | printJson | boolean | false | Output metadata as JSON | | debug | boolean | false | Print yt-dlp stdout/stderr |

Video API

ytDlp.video();

download()

{
  origin: string;
  title: string;
  path: string;
}

buffer()

{
  origin: string;
  title: string;
  buffer: Buffer;
}

stream()

{
  origin: string;
  title: string;
  stream: Readable;
}

Thumbnail API

ytDlp.thumbnail().url();

Returns:

Promise<string | null>;

Constraints

• url is required
• output is required for .download()
• audioOnly and mergeFormat should not be used together
• FFmpeg must exist

Architecture

YtDlp
 ├─ YtDlpConfig
 ├─ YtDlpArgsBuilder
 ├─ YtDlpRunner
 ├─ YtDlpVideo
 └─ YtDlpThumbnail

Debug Mode

new YtDlp({ url }).debug(true).video().download();

Development

pnpm install
pnpm approve-builds
pnpm build
pnpm test

License

MIT License

Note

Recommended for stable MP4 downloads:

new YtDlp({ url }).mergeFormat('mp4').video().download();