npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ytdl/ytdl

v1.4.16

Published

A CLI/Library written in typescript/javascript, which allows you to download/play videos from YouTube onto your system.

Downloads

27

Readme

ytdl

ytdl-build ytdl-release ytdl-publish

ytdl provides a library to integrate a Youtube Downloader for Node.js projects, and a CLI to download content from Youtube. ytdl can also stream audio/video from YouTube, without downloading, directly to your locally installed media player!

Note: You need ffmpeg to be installed on your computer for complete functionality. Without it, you won't be able to some formats/qualities of videos. If ffmpeg is absent, ytdl will prompt you for installation, it is recommended that you install it.

Note: To use the inbuilt mp3 player ytdl-mp3 on Linux distros, <alsa/asoundlib.h> header file must be present. The preinstall script logs a warning if it is not present. Ubuntu/Debian users require to install the libasound2-dev package (sudo apt-get install libasound2-dev), if not present already; before installing the library.

Contents

Installation

Library

Via npm

npm install @ytdl/ytdl

CLI

Via npm (recommended)

Note: DO NOT use sudo to install global packages! The correct way to do it is to tell npm where to install it's global packages: npm config set prefix ~/.local. Make sure ~/.local/bin is added to PATH.

npm install @ytdl/ytdl -g

Via curl

  • As a single file (from latest Github Release):
# Needs both curl and wget
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ytdl-node/ytdl/master/bin/install-latest)"
  • From GitHub repository:
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ytdl-node/ytdl/master/bin/install)"

Via wget

  • As a single file (from latest Github Release):
# Needs both curl and wget
sh -c "$(wget -O- https://raw.githubusercontent.com/ytdl-node/ytdl/master/bin/install-latest)"
  • From GitHub repository:
sh -c "$(wget -O- https://raw.githubusercontent.com/ytdl-node/ytdl/master/bin/install)"

Via commands

git clone https://github.com/ytdl-node/ytdl.git
cd ytdl
npm install
./bin/ytdl -h
echo
echo "Add $(pwd)/bin to PATH"

API

Example

const ytdl = require('@ytdl/ytdl');

async function videoDownloader() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  await video.download('360p', 'ytdl.mp4');
}

videoDownloader();

OR

// Without using async-await.
const ytdl = require('@ytdl/ytdl');

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  video.download('360p', 'ytdl.mp4');
});

Brief

The function ytdl.init(link: string) or ytdl.default(link: string) returns a Promise which resolves with an object of type Ytdl.

A Ytdl object has the following properties:

  • info.videoId: string, stores the video ID.
  • info.videoTitle: string, stores the title of the video.
  • info.videoTime: string, stores the time of the video.
  • info.videoDescription: string, stores the description of the video.
  • info.size(quality[, options]): Number, stores the size of the stream in bytes.
  • info.all(): Object, returns an object consisting of id, title, time, description.
  • download(quality, filename[, options]): Promise<void>, downloads the video/audio from YouTube.
  • setLogLevel(level): void, allows you to enable or disable logging depending on the level.
  • downloadByItag(itag, filename): Promise<void>, downloads from YouTube using the itag property.
  • stream(quality[, options, headers]): Promise<any>, returns a Node.js stream.

Any reference to video refers to an object returned by ytdl.default('link').

options: object

  • audioOnly: true | false
  • videoOnly: true | false
// Example
const options = { audioOnly: true, videoOnly: false };

quality: string

  • For audio: low, medium, high, any.
  • For video: 144p, 360p, 480p, 720p, 1080p.
// Example
const quality = 'low';

video.download(quality, path[, options])

const ytdl = require('@ytdl/ytdl');

async function videoDownloader() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  await video.download('360p', 'ytdl.mp4');
}

videoDownloader();

OR

// Without using async-await.
const ytdl = require('@ytdl/ytdl');

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  video.download('360p', 'ytdl.mp4');
});
  • This function first searches for a stream which has both audio and video in it. If it doesn't find it, it will search for a separate audio and video stream and combine it using ffmpeg.

Currently ytdl uses the fluent-ffmpeg package which requires ffmpeg to be installed on the computer.

options:

  • audioOnly: true | false
  • videoOnly: true | false

audioOnly:

const ytdl = require('@ytdl/ytdl');

async function videoDownloader() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  await video.download('medium', 'audio.mp3', { audioOnly: true });

  // quality: 'low', 'medium', 'high', 'any'
}

videoDownloader();

videoOnly:

Note: There will be no sound.

const ytdl = require('@ytdl/ytdl');

async function videoDownloader() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  await video.download('720p', 'video.mp4', { videoOnly: true });

  // quality: '144p', '360p', '480p', '720p', '1080p'
}

videoDownloader();

video.downloadByItag(url, itag, path)

const ytdl = require('@ytdl/ytdl');

async function videoDownloader() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  await video.downloadByItag(396, 'ytdl.mp4');
}

videoDownloader();

OR

// Without using async-await.
const ytdl = require('@ytdl/ytdl');

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  video.downloadByItag(396, 'ytdl.mp4');
});

video.stream(quality[, options, headers])

  • This function returns a Node.js stream.
  • This may be piped to fs.createWriteStream(filename) to save the stream into a file.

Note: The download function merges separate audio-only and video-only stream when a combined stream is unavailable. This function however will return the appropriate stream if and only if it is available. You may require to pass options, having properties audioOnly and videoOnly to get the desired stream. E.G. video.stream('480p', { videoOnly: true }).

const ytdl = require('@ytdl/ytdl');
const fs = require('fs');

async function download() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  const stream = await video.stream('360p');
  // The variable stream now holds a Node.js stream.
  // Sample use of stream is as follows:
  stream
    .pipe(fs.createWriteStream('ytdl.mp4'))
    .on('finish', (err) => {
      if (err) console.log(err);
      else console.log('Stream saved successfully.');
    });
}

download();

OR

// Without using async-await.
const ytdl = require('@ytdl/ytdl');
const fs = require('fs');

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  video.stream('360p').then((stream) => {
    // The variable stream now holds a Node.js stream.
    // Sample use of stream is as follows:
    stream
      .pipe(fs.createWriteStream('ytdl.mp4'))
      .on('finish', (err) => {
        if (err) console.log(err);
        else console.log('Stream saved successfully.');
      });
  });
});

video.streamByItag(itag[, headers])

const ytdl = require('@ytdl/ytdl');
const fs = require('fs');

async function download() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  const stream = await video.stream(18);
  // The variable stream now holds a Node.js stream.
  // Sample use of stream is as follows:
  stream
    .pipe(fs.createWriteStream('ytdl.mp4'))
    .on('finish', (err) => {
      if (err) console.log(err);
      else console.log('Stream saved successfully.');
    });
}

download();

OR

// Without using async-await.
const ytdl = require('@ytdl/ytdl');
const fs = require('fs');

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  video.streamByItag(18).then((stream) => {
    // The variable stream now holds a Node.js stream.
    // Sample use of stream is as follows:
    stream
      .pipe(fs.createWriteStream('ytdl.mp4'))
      .on('finish', (err) => {
        if (err) console.log(err);
        else console.log('Stream saved successfully.');
      });
  });
});

video.play(quality[, options, player])

  • Play audio or video from YouTube in your local media player.
  • quality may be an itag or among the ones mentioned here.
  • Options are of this format. This is ignored if parameter quality is an itag.
  • The function returns a Player object, with attributes player and play(url, stream).

Audio

  • By default, audio is played on a cross-platform player integrated with ytdl.
  • However, if the parameter player is passed, it is played on the specified media player.

Video

  • cvlc is the default video player.
  • Allowed media players are: cvlc, vlc, mplayer, afplay, mpg123, mpg321, play, omxplayer, aplay, cmdmp3.

The media player set must be on your PATH or in your Environment Variables. On UNIX based systems, you can check if your media player is on your PATH by using the which command, e.g. which mplayer.

const ytdl = require('@ytdl/ytdl');

async function play() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  video.play('any', { audioOnly: true });

  // Play audio of any quality on ytdl-mp3 player.
}

play();

OR

const ytdl = require('@ytdl/ytdl');

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  video.play('any', { audioOnly: true });

  // Play audio of any quality on ytdl-mp3 player.
});
  • The Player object returned can be used to log the name of the player being used.
  • In this example, mplayer is being used.
async function playLocal() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=A7ry4cx6HfY');
  const player = await video.play('any', { audioOnly: true }, 'mplayer');
  console.log(`Player: ${player.player}`);

  // Logs the player on which media is being played.
}

playLocal();

OR

ytdl.init('https://www.youtube.com/watch?v=A7ry4cx6HfY').then((video) => {
  video.play('any', { audioOnly: true }, 'mplayer').then((player) => {
      console.log(`Player: ${player.player}`);

      // Logs the player on which media is being played.
  });
});

video.setLogLevel(level)

  • level can be one of the following:
    • error
    • warn
    • info
    • http
    • verbose
    • debug
    • silly
  • A level lower in the list also enables the levels before it.
  • E.G., a log level of debug will also enable verbose, http, info, warn, error.
const ytdl = require('@ytdl/ytdl');

async function videoDownloader() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');

  // This line will enable logging info to console while downloading content.
  video.setLogLevel('info');

  await video.downloadByItag(396, 'ytdl.mp4');
}

videoDownloader();

video.info.size(quality|itag[, options])

  • Returns size in bytes.
  • A number is treated as an itag whereas a string is treated as quality.
  • Options may be passed only with quality, else it will be ignored.
const ytdl = require('@ytdl/ytdl');

async function videoSize() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  
  const size = video.info.size('360p'); // can pass options: { audioOnly: boolean, videoOnly: boolean }
  const sizeItag = video.info.size(396);

  console.log(`Video Size for 360p: ${Math.round(size/(1024*1024))}M`);
  console.log(`Video Size for itag = 396: ${Math.round(sizeItag/(1024*1024))}M`);
}

videoSize();

OR

const ytdl = require('@ytdl/ytdl');

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  const size = video.info.size('360p'); // can pass options: { audioOnly: boolean, videoOnly: boolean}
  const sizeItag = video.info.size(396);

  console.log(`Video Size for 360p: ${Math.round(size/(1024*1024))}M`);
  console.log(`Video Size for itag = 396: ${Math.round(sizeItag/(1024*1024))}M`);
});

video.info.all()

const ytdl = require('@ytdl/ytdl');

async function videoInfo() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  
  const { id, title, time, description } = video.info.all();
  console.log(`Video Title: ${title}`);
}

videoInfo();

OR

// Without using async-await.
const ytdl = require('@ytdl/ytdl');

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  const { id, title, time, description } = video.info.all();
  console.log(`Video Title: ${title}`);
});

video.info.fetchFormatData(quality[, options])

  • Returns an object: { url: string, fmt: object }.
  • url holds the download URL for the video.
  • fmt holds other data about the format such as contentLength, fps, mimeType, etc.
  • options are same as in video.download.
const ytdl = require('@ytdl/ytdl');

async function getData() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  
  const { url, fmt } = video.info.fetchFormatData('360p');
  console.log(`Download url: ${url}`);
  console.log(`Format data: ${fmt}`);
}

getData();

OR

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  const { url, fmt } = video.info.fetchFormatData('360p');
  console.log(`Download url: ${url}`);
  console.log(`Format data: ${fmt}`);
});

video.info.fetchFormatDataByItag(itag)

  • Same as video.info.fetchFormatData(quality); except, it fetches data by itag instead of quality.
const ytdl = require('@ytdl/ytdl');

async function getData() {
  const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');
  
  const { url, fmt } = video.info.fetchFormatDataByItag(18);
  console.log(`Download url: ${url}`);
  console.log(`Format data: ${fmt}`);
}

getData();

OR

ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {
  const { url, fmt } = video.info.fetchFormatDataByItag(18);
  console.log(`Download url: ${url}`);
  console.log(`Format data: ${fmt}`);
});

ytdl.fromName(name)

  • Create a Ytdl object using the searched name.
const ytdl = require('..');

async function play() {
    const video = await ytdl.fromName('Another Day');
    video.play('any');
}

play();

OR

const ytdl = require('..');

ytdl.fromName('Another Day').then((video) => {
  video.play('any');
});

ytdl.cli()

  • This will create a CLI for YTDL.
  • You can run this by passing arguments.
    • node file.js -h OR npm start -h
const ytdl = require('@ytdl/ytdl');

ytdl.cli(process.argv);

CLI (ytdl)

Examples

  • Download only audio of any quality from "https://www.youtube.com/watch?v=fJ9rUzIMcZQ".
ytdl -d -l "https://www.youtube.com/watch?v=fJ9rUzIMcZQ" -fn "rhapsody.mp3" -ao
  • Play "https://www.youtube.com/watch?v=fJ9rUzIMcZQ", 360p, in your local media player.
ytdl -p -l "https://www.youtube.com/watch?v=fJ9rUzIMcZQ" -q "360p" --set-player "mplayer"

# Add -ao to play only audio from your command line.
  • Play "Another Day" from YouTube on your local media player.
ytdl -p -n "Another Day" -ao

# Searches "Another Day" on YouTube and plays the first result.

Usage

Usage: ytdl [options]

Options:
  -V, --version                output the version number
  -l, --link <url>             set the url for the YouTube video
  -n, --name <name>            search by name instead of link
  -i, --info                   info about YouTube link
  -d, --download               download from YouTube link
  -p, --play                   play YouTube media in your media player
  --set-player <media-player>  set the media player
  -fn, --filename <filename>   filename of downloaded content
  -q, --quality <quality>      quality of downloaded content
  -s, --size                   get the size of the video to be downloaded
  -ao, --audio-only            download only audio stream
  -vo, --video-only            download only video stream
  -h, --help                   display help for command

Contributing

Contributing guidelines have been established here.

License

MIT