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 taken into account when you perform a npm install in a project that contains youtube-dl-exec dependency.

These environment variables can also be set through "npm config", for example npm install --YOUTUBE_DL_HOST="Some URL", or store it in .npmrc file.

They setup the download configuration for getting the yt-dlp binary file.

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