{"analyzedAt":"2022-07-04T19:36:55.027Z","collected":{"metadata":{"name":"@ytdl/ytdl","scope":"ytdl","version":"1.4.16","description":"A CLI/Library written in typescript/javascript, which allows you to download/play videos from YouTube onto your system.","keywords":["youtube","download","video","audio","mp4","mp3","cli","player","ytdl"],"date":"2020-06-26T18:30:20.681Z","publisher":{"username":"ytdl","email":"ytdl-ts@protonmail.com"},"maintainers":[{"username":"ytdl","email":"ytdl-ts@protonmail.com"}],"repository":{"type":"git","url":"git+https://github.com/ytdl-node/ytdl.git"},"links":{"npm":"https://www.npmjs.com/package/%40ytdl%2Fytdl","homepage":"https://github.com/ytdl-node/ytdl#readme","repository":"https://github.com/ytdl-node/ytdl","bugs":"https://github.com/ytdl-node/ytdl/issues"},"license":"MIT","dependencies":{"axios":"^0.19.2","cli-progress":"^3.8.2","commander":"^5.0.0","ffbinaries":"^1.1.4","fluent-ffmpeg":"^2.1.2","npm-path":"^2.0.4","winston":"^3.2.1","speaker":"^0.5.1"},"devDependencies":{"@types/axios":"^0.14.0","@types/chai":"^4.2.11","@types/commander":"^2.12.2","@types/eslint":"^6.1.9","@types/fluent-ffmpeg":"^2.1.14","@types/mocha":"^7.0.2","@types/node":"^13.9.8","@types/winston":"^2.4.4","@typescript-eslint/eslint-plugin":"^2.26.0","@typescript-eslint/parser":"^2.26.0","@zeit/ncc":"^0.22.1","chai":"^4.2.0","eslint":"^6.8.0","eslint-config-airbnb-typescript":"^7.2.0","eslint-plugin-import":"^2.20.2","husky":"^4.2.3","mocha":"^7.1.1","ts-node":"^8.8.1","typescript":"^3.8.3"},"optionalDependencies":{"speaker":"^0.5.1"},"releases":[{"from":"2022-06-04T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":0},{"from":"2022-04-05T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":1},{"from":"2022-01-05T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":1},{"from":"2021-07-04T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":1},{"from":"2020-07-04T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":1}],"hasTestScript":true,"readme":"# ytdl\n\n  \n\n**ytdl** provides a library to integrate a Youtube Downloader for `Node.js` projects, and a CLI to download content from [Youtube](https://www.youtube.com). **ytdl** can also stream audio/video from YouTube, **without downloading**, directly to your locally installed media player!\n\n> Note: You need [ffmpeg](https://ffmpeg.org/download.html) 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.\n
\n\n> Note: To use the inbuilt mp3 player `ytdl-mp3` on Linux distros, `` 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.\n\n# Contents\n\n- [Installation](#installation)\n * [Library](#library)\n * [CLI](#cli)\n- [API](#api)\n- [CLI](#cli-ytdl)\n\n# Installation\n\n## Library\n\n### Via npm\n\n```bash\nnpm install @ytdl/ytdl\n```\n\n## CLI\n\n### Via npm (recommended)\n\n> 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`.\n\n```bash\nnpm install @ytdl/ytdl -g\n```\n\n### Via curl\n\n- As a single file (from latest Github Release):\n```bash\n# Needs both curl and wget\nsh -c \"$(curl -fsSL https://raw.githubusercontent.com/ytdl-node/ytdl/master/bin/install-latest)\"\n```\n\n- From GitHub repository:\n```bash\nsh -c \"$(curl -fsSL https://raw.githubusercontent.com/ytdl-node/ytdl/master/bin/install)\"\n```\n\n### Via wget\n\n- As a single file (from latest Github Release):\n```bash\n# Needs both curl and wget\nsh -c \"$(wget -O- https://raw.githubusercontent.com/ytdl-node/ytdl/master/bin/install-latest)\"\n```\n\n- From GitHub repository:\n```bash\nsh -c \"$(wget -O- https://raw.githubusercontent.com/ytdl-node/ytdl/master/bin/install)\"\n```\n\n### Via commands\n\n```bash\ngit clone https://github.com/ytdl-node/ytdl.git\ncd ytdl\nnpm install\n./bin/ytdl -h\necho\necho \"Add $(pwd)/bin to PATH\"\n```\n\n# API\n\n## Example\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function videoDownloader() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n await video.download('360p', 'ytdl.mp4');\n}\n\nvideoDownloader();\n```\n\n### OR\n\n```javascript\n// Without using async-await.\nconst ytdl = require('@ytdl/ytdl');\n\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n video.download('360p', 'ytdl.mp4');\n});\n```\n\n## Brief\n\nThe function `ytdl.init(link: string)` or `ytdl.default(link: string)` returns a Promise which resolves with an object of type `Ytdl`.\n\nA `Ytdl` object has the following properties:\n- **info.videoId**: *string*, stores the video ID.\n- **info.videoTitle**: *string*, stores the title of the video.\n- **info.videoTime**: *string*, stores the time of the video.\n- **info.videoDescription**: *string*, stores the description of the video.\n- **info.size(quality[, options])**: *Number*, stores the size of the stream in *bytes*.\n- **info.all()**: *Object*, returns an object consisting of id, title, time, description.\n- **download(quality, filename[, options])**: *Promise\\*, downloads the video/audio from YouTube.\n- **setLogLevel(level)**: *void*, allows you to enable or disable logging depending on the level.\n- **downloadByItag(itag, filename)**: *Promise\\*, downloads from YouTube using the itag property.\n- **stream(quality[, options, headers])**: *Promise\\*, returns a `Node.js` stream.\n\n> Any reference to `video` refers to an object returned by `ytdl.default('link')`.\n\n### options: object\n- audioOnly: true | false\n- videoOnly: true | false\n\n```javascript\n// Example\nconst options = { audioOnly: true, videoOnly: false };\n```\n\n### quality: string\n- For audio: low, medium, high, any.\n- For video: 144p, 360p, 480p, 720p, 1080p.\n\n```javascript\n// Example\nconst quality = 'low';\n```\n\n## video.download(quality, path[, options])\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function videoDownloader() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n await video.download('360p', 'ytdl.mp4');\n}\n\nvideoDownloader();\n```\n\n### OR\n\n```javascript\n// Without using async-await.\nconst ytdl = require('@ytdl/ytdl');\n\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n video.download('360p', 'ytdl.mp4');\n});\n```\n\n- 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.\n\n> Currently **ytdl** uses the [fluent-ffmpeg](https://www.npmjs.com/package/fluent-ffmpeg) package which requires ffmpeg to be installed on the computer.\n\n### options:\n- audioOnly: true | false\n- videoOnly: true | false\n\n### audioOnly:\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function videoDownloader() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n await video.download('medium', 'audio.mp3', { audioOnly: true });\n\n // quality: 'low', 'medium', 'high', 'any'\n}\n\nvideoDownloader();\n```\n\n### videoOnly:\n\n> Note: There will be no sound.\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function videoDownloader() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n await video.download('720p', 'video.mp4', { videoOnly: true });\n\n // quality: '144p', '360p', '480p', '720p', '1080p'\n}\n\nvideoDownloader();\n```\n\n## video.downloadByItag(url, itag, path)\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function videoDownloader() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n await video.downloadByItag(396, 'ytdl.mp4');\n}\n\nvideoDownloader();\n```\n\n### OR\n\n```javascript\n// Without using async-await.\nconst ytdl = require('@ytdl/ytdl');\n\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n video.downloadByItag(396, 'ytdl.mp4');\n});\n```\n\n## video.stream(quality[, options, headers])\n\n- This function returns a Node.js stream.\n- This may be piped to `fs.createWriteStream(filename)` to save the stream into a file.\n\n> 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 })`.\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\nconst fs = require('fs');\n\nasync function download() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n const stream = await video.stream('360p');\n // The variable stream now holds a Node.js stream.\n // Sample use of stream is as follows:\n stream\n .pipe(fs.createWriteStream('ytdl.mp4'))\n .on('finish', (err) => {\n if (err) console.log(err);\n else console.log('Stream saved successfully.');\n });\n}\n\ndownload();\n```\n\n### OR\n\n```javascript\n// Without using async-await.\nconst ytdl = require('@ytdl/ytdl');\nconst fs = require('fs');\n\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n video.stream('360p').then((stream) => {\n // The variable stream now holds a Node.js stream.\n // Sample use of stream is as follows:\n stream\n .pipe(fs.createWriteStream('ytdl.mp4'))\n .on('finish', (err) => {\n if (err) console.log(err);\n else console.log('Stream saved successfully.');\n });\n });\n});\n```\n\n## video.streamByItag(itag[, headers])\n\n- Same functionality as [`video.stream(quality)`](#videostreamquality-options-headers), uses `itag` instead of `quality`.\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\nconst fs = require('fs');\n\nasync function download() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n const stream = await video.stream(18);\n // The variable stream now holds a Node.js stream.\n // Sample use of stream is as follows:\n stream\n .pipe(fs.createWriteStream('ytdl.mp4'))\n .on('finish', (err) => {\n if (err) console.log(err);\n else console.log('Stream saved successfully.');\n });\n}\n\ndownload();\n```\n\n### OR\n\n```javascript\n// Without using async-await.\nconst ytdl = require('@ytdl/ytdl');\nconst fs = require('fs');\n\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n video.streamByItag(18).then((stream) => {\n // The variable stream now holds a Node.js stream.\n // Sample use of stream is as follows:\n stream\n .pipe(fs.createWriteStream('ytdl.mp4'))\n .on('finish', (err) => {\n if (err) console.log(err);\n else console.log('Stream saved successfully.');\n });\n });\n});\n```\n\n## video.play(quality[, options, player])\n\n- Play audio or video from YouTube in your local media player.\n- `quality` may be an `itag` or among the ones mentioned [here](#quality-string).\n- Options are of [this](#options-object) format. This is ignored if parameter `quality` is an `itag`.\n- The function returns a `Player` object, with attributes `player` and `play(url, stream)`.\n\n### Audio\n- By default, audio is played on a cross-platform player integrated with ytdl.\n- However, if the parameter `player` is passed, it is played on the specified media player.\n\n### Video\n- `cvlc` is the default video player.\n- Allowed media players are: `cvlc`, `vlc`, `mplayer`, `afplay`, `mpg123`, `mpg321`, `play`, `omxplayer`, `aplay`, `cmdmp3`.\n\n> The media player set must be on your [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) 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`.\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function play() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n video.play('any', { audioOnly: true });\n\n // Play audio of any quality on ytdl-mp3 player.\n}\n\nplay();\n```\n\n### OR\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n video.play('any', { audioOnly: true });\n\n // Play audio of any quality on ytdl-mp3 player.\n});\n```\n\n- The `Player` object returned can be used to log the name of the player being used.\n- In this example, `mplayer` is being used.\n\n```javascript\nasync function playLocal() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=A7ry4cx6HfY');\n const player = await video.play('any', { audioOnly: true }, 'mplayer');\n console.log(`Player: ${player.player}`);\n\n // Logs the player on which media is being played.\n}\n\nplayLocal();\n```\n\n### OR\n\n```javascript\nytdl.init('https://www.youtube.com/watch?v=A7ry4cx6HfY').then((video) => {\n video.play('any', { audioOnly: true }, 'mplayer').then((player) => {\n console.log(`Player: ${player.player}`);\n\n // Logs the player on which media is being played.\n });\n});\n```\n\n## video.setLogLevel(level)\n\n- `level` can be one of the following:\n * error \n * warn\n * info\n * http\n * verbose\n * debug\n * silly\n- A level lower in the list also enables the levels before it.\n- E.G., a log level of debug will also enable `verbose, http, info, warn, error`.\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function videoDownloader() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n\n // This line will enable logging info to console while downloading content.\n video.setLogLevel('info');\n\n await video.downloadByItag(396, 'ytdl.mp4');\n}\n\nvideoDownloader();\n```\n\n## video.info.size(quality|itag[, options])\n\n- Returns size in bytes.\n- A number is treated as an `itag` whereas a string is treated as `quality`.\n- Options may be passed only with `quality`, else it will be ignored.\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function videoSize() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n \n const size = video.info.size('360p'); // can pass options: { audioOnly: boolean, videoOnly: boolean }\n const sizeItag = video.info.size(396);\n\n console.log(`Video Size for 360p: ${Math.round(size/(1024*1024))}M`);\n console.log(`Video Size for itag = 396: ${Math.round(sizeItag/(1024*1024))}M`);\n}\n\nvideoSize();\n```\n\n### OR\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n const size = video.info.size('360p'); // can pass options: { audioOnly: boolean, videoOnly: boolean}\n const sizeItag = video.info.size(396);\n\n console.log(`Video Size for 360p: ${Math.round(size/(1024*1024))}M`);\n console.log(`Video Size for itag = 396: ${Math.round(sizeItag/(1024*1024))}M`);\n});\n```\n\n## video.info.all()\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function videoInfo() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n \n const { id, title, time, description } = video.info.all();\n console.log(`Video Title: ${title}`);\n}\n\nvideoInfo();\n```\n\n### OR\n\n```javascript\n// Without using async-await.\nconst ytdl = require('@ytdl/ytdl');\n\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n const { id, title, time, description } = video.info.all();\n console.log(`Video Title: ${title}`);\n});\n```\n\n## video.info.fetchFormatData(quality[, options])\n\n- Returns an object: `{ url: string, fmt: object }`.\n- `url` holds the download URL for the video.\n- `fmt` holds other data about the format such as `contentLength`, `fps`, `mimeType`, etc.\n- options are same as in [video.download](#options).\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function getData() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n \n const { url, fmt } = video.info.fetchFormatData('360p');\n console.log(`Download url: ${url}`);\n console.log(`Format data: ${fmt}`);\n}\n\ngetData();\n```\n\n### OR\n\n```javascript\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n const { url, fmt } = video.info.fetchFormatData('360p');\n console.log(`Download url: ${url}`);\n console.log(`Format data: ${fmt}`);\n});\n```\n\n## video.info.fetchFormatDataByItag(itag)\n\n- Same as `video.info.fetchFormatData(quality)`; except, it fetches data by itag instead of quality.\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nasync function getData() {\n const video = await ytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ');\n \n const { url, fmt } = video.info.fetchFormatDataByItag(18);\n console.log(`Download url: ${url}`);\n console.log(`Format data: ${fmt}`);\n}\n\ngetData();\n```\n\n### OR\n\n```javascript\nytdl.init('https://www.youtube.com/watch?v=fJ9rUzIMcZQ').then((video) => {\n const { url, fmt } = video.info.fetchFormatDataByItag(18);\n console.log(`Download url: ${url}`);\n console.log(`Format data: ${fmt}`);\n});\n```\n\n## ytdl.fromName(name)\n\n- Create a `Ytdl` object using the searched name.\n\n```javascript\nconst ytdl = require('..');\n\nasync function play() {\n const video = await ytdl.fromName('Another Day');\n video.play('any');\n}\n\nplay();\n```\n\n### OR\n\n```javascript\nconst ytdl = require('..');\n\nytdl.fromName('Another Day').then((video) => {\n video.play('any');\n});\n```\n\n## ytdl.cli()\n\n- This will create a CLI for YTDL.\n- You can run this by passing arguments.\n * `node file.js -h` OR `npm start -h`\n\n```javascript\nconst ytdl = require('@ytdl/ytdl');\n\nytdl.cli(process.argv);\n```\n\n# CLI (ytdl)\n\n## Examples\n\n- Download only audio of any quality from \"https://www.youtube.com/watch?v=fJ9rUzIMcZQ\".\n```bash\nytdl -d -l \"https://www.youtube.com/watch?v=fJ9rUzIMcZQ\" -fn \"rhapsody.mp3\" -ao\n```\n\n- Play \"https://www.youtube.com/watch?v=fJ9rUzIMcZQ\", 360p, in your local media player.\n```bash\nytdl -p -l \"https://www.youtube.com/watch?v=fJ9rUzIMcZQ\" -q \"360p\" --set-player \"mplayer\"\n\n# Add -ao to play only audio from your command line.\n```\n\n- Play \"Another Day\" from YouTube on your local media player.\n```bash\nytdl -p -n \"Another Day\" -ao\n\n# Searches \"Another Day\" on YouTube and plays the first result.\n```\n\n## Usage\n```\nUsage: ytdl [options]\n\nOptions:\n -V, --version output the version number\n -l, --link set the url for the YouTube video\n -n, --name search by name instead of link\n -i, --info info about YouTube link\n -d, --download download from YouTube link\n -p, --play play YouTube media in your media player\n --set-player set the media player\n -fn, --filename filename of downloaded content\n -q, --quality quality of downloaded content\n -s, --size get the size of the video to be downloaded\n -ao, --audio-only download only audio stream\n -vo, --video-only download only video stream\n -h, --help display help for command\n```\n\n# Contributing\n\nContributing guidelines have been established [here](./CONTRIBUTING.md).\n\n# License\n\n[MIT](./LICENSE)"},"npm":{"downloads":[{"from":"2022-07-03T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":9},{"from":"2022-06-27T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":80},{"from":"2022-06-04T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":104},{"from":"2022-04-05T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":554},{"from":"2022-01-05T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":1565},{"from":"2021-07-04T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":3888}],"starsCount":0},"github":{"homepage":"https://www.npmjs.com/package/@ytdl/ytdl","starsCount":18,"forksCount":5,"subscribersCount":3,"issues":{"count":39,"openCount":0,"distribution":{"3600":33,"10800":0,"32400":0,"97200":4,"291600":0,"874800":2,"2624400":0,"7873200":0,"23619600":0,"70858800":0,"212576400":0},"isDisabled":false},"contributors":[{"username":"namsnath","commitsCount":3},{"username":"thebongy","commitsCount":7},{"username":"AJ1479","commitsCount":2},{"username":"roerohan","commitsCount":340}],"commits":[{"from":"2022-06-27T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":0},{"from":"2022-06-04T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":0},{"from":"2022-04-05T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":0},{"from":"2022-01-05T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":0},{"from":"2021-07-04T00:00:00.000Z","to":"2022-07-04T00:00:00.000Z","count":0}]},"source":{"files":{"readmeSize":17541,"testsSize":3420,"hasNpmIgnore":true},"linters":["eslint"],"outdatedDependencies":{"axios":{"required":"^0.19.2","stable":"0.27.2","latest":"1.0.0-alpha.1"},"commander":{"required":"^5.0.0","stable":"9.3.0","latest":"9.3.0"}}}},"evaluation":{"quality":{"carefulness":0.9199999999999999,"tests":0.6,"health":0.5,"branding":0},"popularity":{"communityInterest":30,"downloadsCount":184.66666666666666,"downloadsAcceleration":-2.2857496194824964,"dependentsCount":0},"maintenance":{"releasesFrequency":0.9,"commitsFrequency":0.9,"openIssues":1,"issuesDistribution":1}},"score":{"final":0.6058312932309731,"detail":{"quality":0.7771796610682786,"popularity":0.0648481194463622,"maintenance":0.9999444374407507}}}