A simple Node.js wrapper for yt-dlp.

Why

• Auto install the latest yt-dlp version available.
• Executes any command in an efficient way.
• Promise & Stream interface support.

Install

Note: It requires Python 3.7 or above available in your system as python3. Otherwise, the library will throw an error.

$ npm install youtube-dl-exec --save

By default, the library will auto-install the latest yt-dlp available that will downloaded on build time.

Usage

Any yt-dlp flags is supported:

const youtubedl = require('youtube-dl-exec')

youtubedl('https://www.youtube.com/watch?v=6xKWiCMKKJg', {
  dumpSingleJson: true,
  noCheckCertificates: true,
  noWarnings: true,
  preferFreeFormats: true,
  addHeader: ['referer:youtube.com', 'user-agent:googlebot']
}).then(output => console.log(output))

It's equivalent to:

$ ./bin/yt-dlp \
  --dump-single-json \
  --no-check-certificates \
  --no-warnings \
  --prefer-free-formats \
  --add-header='user-agent:googlebot' \
  --add-header='referer:youtube.com' \
  'https://www.youtube.com/watch?v=6xKWiCMKKJg'

Type yt-dlp --help for seeing all of them.

Custom binary

In case you need, you can specify your own binary path using .create:

const { create: createYoutubeDl } = require('youtube-dl-exec')
const youtubedl = createYoutubeDl('/my/binary/path')

Progress bar

Since the library is returning a promise, you can use any library that makes a progress estimation taking a promise as input:

const logger = require('progress-estimator')()
const youtubedl = require('youtube-dl-exec')

const url = 'https://www.youtube.com/watch?v=6xKWiCMKKJg'
const promise = youtubedl(url, { dumpSingleJson: true })
const result = await logger(promise, `Obtaining ${url}`)

console.log(result)

Alternatively, you can access to the subprocess to have more granular control. See youtubedl.exec.

Also, combine that with YOUTUBE_DL_SKIP_DOWNLOAD. See environment variables to know more.

Timeout & cancellation

You can customize spawn#options by passing a third argument:

const url = 'https://www.youtube.com/watch?v=6xKWiCMKKJg'
const result = await youtubedl.exec(url, ,{ dumpSingleJson: true }, {
  timeout: 5000,
  killSignal: 'SIGKILL'
})

console.log(result)

You can also interact with the subprocess programmatically:

const url = 'https://www.youtube.com/watch?v=6xKWiCMKKJg'
const subprocess = youtubedl.exec(url, { dumpSingleJson: true })

setTimeout(() => {
  subprocess.kill('SIGKILL')
}, 5000)

const result = await subprocess
console.log(result)

API

youtubedl(url, [flags], [options])

It execs any yt-dlp command, returning back the output.

url

Required
Type: string

The URL to target.

flags

Type: object

Any flag supported by yt-dlp.

options

Any option provided here will passed to spawn#options.

youtubedl.exec(url, [flags], [options])

Similar to main method but instead of a parsed output, it will return the internal subprocess object:

const youtubedl = require('youtube-dl-exec')
const fs = require('fs')

const subprocess = youtubedl.exec(
  'https://www.youtube.com/watch?v=6xKWiCMKKJg',
  {
    dumpSingleJson: true
  }
)

console.log(`Running subprocess as ${subprocess.pid}`)

subprocess.stdout.pipe(fs.createWriteStream('stdout.txt'))
subprocess.stderr.pipe(fs.createWriteStream('stderr.txt'))

setTimeout(subprocess.cancel, 30000)

youtubedl.create(binaryPath)

It creates a yt-dlp using the binaryPath provided.

Environment variables

The environment variables are used to customize the postinstall script behavior that will be triggered after npm install is performed.

This is mostly for backward compatibility or debugging purposes. You don't need to do anything by default.

DEBUG

Set DEBUG="youtube-dl-exec*" to enable debug mode. This will enable log additional information during the post-install script.

YOUTUBE_DL_DIR

It determines the folder where to put the binary file.

The default folder is bin.

YOUTUBE_DL_FILENAME

It determines the binary filename.

The default binary file could be yt-dlp or youtube-dl.exe, depending of the YOUTUBE_DL_PLATFORM value.

YOUTUBE_DL_HOST

It determines the remote URL for getting the yt-dlp binary file.

The default URL is yt-dlp/yt-dlp latest release.

YOUTUBE_DL_PLATFORM

It determines the architecture of the machine that will use the yt-dlp binary.

The default value will computed from process.platform, being 'unix' or 'win32'.

YOUTUBE_DL_SKIP_DOWNLOAD

When is present, it will skip the postinstall script for fetching the latest yt-dlp version.

That variable should be set before performing the installation command, such as:

YOUTUBE_DL_SKIP_DOWNLOAD=true npm install

YOUTUBE_DL_SKIP_PYTHON_CHECK

When is present, it skip the python step on installation.

License

youtube-dl-exec © microlink.io, released under the MIT License.
Authored and maintained by Kiko Beats with help from contributors.

microlink.io · GitHub microlink.io · X @microlinkhq