{"id":19777032,"url":"https://github.com/iqbal-rashed/ytdlp-nodejs","last_synced_at":"2026-01-25T04:05:44.612Z","repository":{"id":144435610,"uuid":"612160071","full_name":"iqbal-rashed/ytdlp-nodejs","owner":"iqbal-rashed","description":"A Node.js library for download videos and getting video streams and thumbnails with strong TypeScript support.","archived":false,"fork":false,"pushed_at":"2025-12-22T16:57:48.000Z","size":216,"stargazers_count":170,"open_issues_count":7,"forks_count":29,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-18T16:58:52.636Z","etag":null,"topics":["child-process","nodejs","typescript","video-downloader","youtube-downloader","yt-dlp","ytdlp","ytdlp-nodejs"],"latest_commit_sha":null,"homepage":"https://github.com/iqbal-rashed/ytdlp-nodejs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iqbal-rashed.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-10T10:27:12.000Z","updated_at":"2026-01-16T20:54:10.000Z","dependencies_parsed_at":"2025-04-13T09:29:09.626Z","dependency_job_id":"d42a2787-74c0-48eb-9b89-365474b98dab","html_url":"https://github.com/iqbal-rashed/ytdlp-nodejs","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/iqbal-rashed/ytdlp-nodejs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqbal-rashed%2Fytdlp-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqbal-rashed%2Fytdlp-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqbal-rashed%2Fytdlp-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqbal-rashed%2Fytdlp-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iqbal-rashed","download_url":"https://codeload.github.com/iqbal-rashed/ytdlp-nodejs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iqbal-rashed%2Fytdlp-nodejs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28742983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T02:46:29.005Z","status":"ssl_error","status_checked_at":"2026-01-25T02:44:29.968Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["child-process","nodejs","typescript","video-downloader","youtube-downloader","yt-dlp","ytdlp","ytdlp-nodejs"],"created_at":"2024-11-12T05:22:53.994Z","updated_at":"2026-01-25T04:05:44.607Z","avatar_url":"https://github.com/iqbal-rashed.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **⚠️ Notice**: Version 3.4.0 is currently in beta. While we've thoroughly tested the new features, please report any issues you encounter on our [GitHub Issues](https://github.com/iqbal-rashed/ytdlp-nodejs/issues) page. Your feedback helps make this library better!\n\n# ytdlp-nodejs\n\n[![npm version](https://img.shields.io/npm/v/ytdlp-nodejs.svg)](https://www.npmjs.com/package/ytdlp-nodejs)\n[![License](https://img.shields.io/npm/l/ytdlp-nodejs.svg)](https://github.com/iqbal-rashed/ytdlp-nodejs/blob/main/LICENSE)\n[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://iqbal-rashed.github.io/ytdlp-nodejs)\n\nA powerful Node.js wrapper for [yt-dlp](https://github.com/yt-dlp/yt-dlp) that provides a simple, type-safe interface for downloading, streaming, and fetching metadata from videos across thousands of websites.\n\n📚 **[View Full Documentation](https://iqbal-rashed.github.io/ytdlp-nodejs)**\n\n## Features\n\n- 🚀 **Easy to use** - Simple API with TypeScript support\n- 📥 **Download \u0026 Stream** - Download videos or stream them directly\n- 📊 **Progress tracking** - Real-time download progress callbacks\n- 🎵 **Audio extraction** - Extract audio in various formats (MP3, FLAC, etc.)\n- 📋 **Metadata fetching** - Get video info, formats, thumbnails, and more\n- 🔄 **Auto-updates** - Built-in yt-dlp binary management\n- 💻 **CLI included** - Interactive and non-interactive command-line interface\n- 🌐 **Node.js runtime** - Uses Node.js as the default JavaScript runtime for yt-dlp\n\n## Installation\n\n```bash\nnpm install ytdlp-nodejs\n```\n\n\u003e **Note**: FFmpeg is recommended for full functionality. Install it manually or use the built-in `downloadFFmpeg()` method.\n\n## Quick Start\n\n```typescript\nimport { YtDlp } from 'ytdlp-nodejs';\n\nconst ytdlp = new YtDlp();\n\n// Download a video with fluent API\nconst result = await ytdlp\n  .download('https://youtube.com/watch?v=dQw4w9WgXcQ')\n  .format('mergevideo')\n  .quality('1080p')\n  .type('mp4')\n  .on('progress', (p) =\u003e console.log(`${p.percentage_str}`))\n  .run();\n\nconsole.log('Downloaded:', result.filePaths);\n\n// Get video info\nconst info = await ytdlp.getInfoAsync(\n  'https://youtube.com/watch?v=dQw4w9WgXcQ',\n);\nconsole.log(info.title);\n\n// Stream to file\nimport { createWriteStream } from 'fs';\nconst stream = ytdlp.stream('https://youtube.com/watch?v=dQw4w9WgXcQ');\nawait stream.pipeAsync(createWriteStream('video.mp4'));\n```\n\n## CLI Usage\n\n### Interactive Mode\n\nLaunch the interactive menu to access all features with guided prompts:\n\n```bash\nytdlp\n```\n\n### Commands\n\n#### Interactive Commands\n\nThese commands prompt for quality/format selection:\n\n```bash\n# Download video (interactive quality selection)\nytdlp download \u003curl\u003e\n\n# Download audio only (interactive format selection)\nytdlp audio \u003curl\u003e\n\n# Get video info (formatted display)\nytdlp info \u003curl\u003e\n```\n\n#### Direct Commands\n\nThese commands run without prompts:\n\n```bash\n# List available formats\nytdlp formats \u003curl\u003e\n\n# Download with specific quality (non-interactive)\nytdlp video \u003curl\u003e --quality 1080p\n\n# Download FFmpeg binaries\nytdlp ffmpeg\n\n# Update yt-dlp binary\nytdlp update\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nconst ytdlp = new YtDlp({\n  binaryPath?: string,  // Path to yt-dlp binary\n  ffmpegPath?: string,  // Path to ffmpeg binary\n});\n```\n\n### Download Methods\n\n#### `download(url, options?)`\n\nReturns a fluent builder for downloading with chainable methods.\n\n```typescript\n// Fluent builder API (recommended)\nconst result = await ytdlp\n  .download('https://youtube.com/watch?v=...')\n  .filter('mergevideo')\n  .quality('1080p')\n  .type('mp4')\n  .output('./downloads')\n  .embedThumbnail()\n  .on('progress', (p) =\u003e console.log(`${p.percentage_str}`))\n  .run();\n\nconsole.log('Files:', result.filePaths);\n\n// With initial options\nconst result = await ytdlp\n  .download(url, {\n    format: { filter: 'mergevideo', quality: '1080p', type: 'mp4' },\n  })\n  .embedThumbnail()\n  .on('progress', (p) =\u003e console.log(p))\n  .run();\n```\n\n##### Builder Methods\n\n| Category      | Methods                                                                                             |\n| ------------- | --------------------------------------------------------------------------------------------------- |\n| **Format**    | `.filter()`, `.quality()`, `.type()`, `.format()`                                                   |\n| **Output**    | `.output('./downloads')`, `.setOutputTemplate('%(title)s.%(ext)s')`                                 |\n| **Audio**     | `.extractAudio()`, `.audioFormat('mp3')`, `.audioQuality('0')`                                      |\n| **Embed**     | `.embedThumbnail()`, `.embedSubs()`, `.embedMetadata()`                                             |\n| **Subtitles** | `.writeSubs()`, `.writeAutoSubs()`, `.subLangs(['en', 'es'])`                                       |\n| **Thumbnail** | `.writeThumbnail()`                                                                                 |\n| **Auth**      | `.cookies(str)`, `.cookiesFromBrowser('chrome')`, `.username(user)`, `.password(pass)`              |\n| **Network**   | `.proxy(url)`, `.rateLimit('1M')`                                                                   |\n| **Playlist**  | `.playlistStart(1)`, `.playlistEnd(10)`, `.playlistItems('1,3,5')`                                  |\n| **Advanced**  | `.options(argsOptions)`, `.addOption(key, value)`, `.addArgs(...args)`, `.skipDownload()`           |\n| **Events**    | `.on('start' \\| 'progress' \\| 'beforeDownload' \\| 'stdout' \\| 'stderr' \\| 'error' \\| 'finish', fn)` |\n| **Execute**   | `.run()` - returns `Promise\u003cDownloadFinishResult\u003e` - Also directly `await`able                      |\n\n#### `downloadAsync(url, options?)`\n\nDownloads a video asynchronously with callback-style progress.\n\n```typescript\nconst result = await ytdlp.downloadAsync(url, {\n  format: { filter: 'mergevideo', type: 'mp4', quality: '1080p' },\n  output: './downloads/%(title)s.%(ext)s',\n  onProgress: (progress) =\u003e console.log(progress),\n});\n```\n\n#### `downloadAudio(url, format?, options?)`\n\nDownloads audio only.\n\n```typescript\nawait ytdlp.downloadAudio(url, 'mp3'); // 'aac', 'flac', 'mp3', 'm4a', 'opus', 'vorbis', 'wav', 'alac'\n```\n\n#### `downloadVideo(url, quality?, options?)`\n\nDownloads video with specific quality.\n\n```typescript\nawait ytdlp.downloadVideo(url, '1080p'); // 'best', '2160p', '1440p', '1080p', '720p', etc.\n```\n\n### Streaming\n\n#### `stream(url, options?)`\n\nReturns a fluent builder for streaming with chainable methods.\n\n```typescript\nimport { createWriteStream } from 'fs';\n\n// Fluent builder API\nconst result = await ytdlp\n  .stream('https://youtube.com/watch?v=...')\n  .format('audioandvideo')\n  .quality('highest')\n  .type('mp4')\n  .on('progress', (p) =\u003e console.log(p.percentage_str))\n  .pipeAsync(createWriteStream('video.mp4'));\n\nconsole.log(`Bytes: ${result.bytes}`);\n\n// Sync pipe\nytdlp.stream(url).format('audioandvideo').pipe(writableStream);\n\n// Stream to buffer\nconst buffer = await ytdlp.stream(url).format('audioonly').toBuffer();\n```\n\n##### Stream Builder Methods\n\n| Method                                                                             | Description                              |\n| ---------------------------------------------------------------------------------- | ---------------------------------------- |\n| `.filter()`, `.quality()`, `.type()`                                               | Set format options (same as Download)    |\n| `.pipe(dest, options?)`                                                            | Pipe to writable stream, returns Promise |\n| `.pipeAsync(dest, options?)`                                                       | Alias for `.pipe()`                      |\n| `.toBuffer()`                                                                      | Collect stream into Buffer               |\n| `.getStream()`                                                                     | Get underlying PassThrough stream        |\n| `.on('start' \\| 'progress' \\| 'beforeDownload' \\| 'data' \\| 'error' \\| 'end', fn)` | Event listeners                          |\n\n#### `getFileAsync(url, options?)`\n\nReturns a `File` object without saving to disk.\n\n```typescript\nconst file = await ytdlp.getFileAsync(url, {\n  format: { filter: 'audioonly', type: 'mp3' },\n  onProgress: (p) =\u003e console.log(p),\n});\nconsole.log(file.name, file.size);\n```\n\n### Information Methods\n\n#### `getInfoAsync(url, options?)`\n\nFetches video/playlist metadata.\n\n```typescript\nconst info = await ytdlp.getInfoAsync(url);\nconsole.log(info.title, info.duration, info.formats);\n```\n\n#### `getFormatsAsync(url, options?)`\n\nGets available formats using JSON output.\n\n```typescript\nconst result = await ytdlp.getFormatsAsync(url);\nconsole.log(`Found ${result.formats.length} formats`);\n```\n\n#### `getDirectUrlsAsync(url, options?)`\n\nReturns direct media URLs.\n\n```typescript\nconst urls = await ytdlp.getDirectUrlsAsync(url);\n```\n\n#### `getTitleAsync(url)`\n\n```typescript\nconst title = await ytdlp.getTitleAsync(url);\n```\n\n#### `getThumbnailsAsync(url)`\n\n```typescript\nconst thumbnails = await ytdlp.getThumbnailsAsync(url);\n```\n\n#### `getVersionAsync()`\n\n```typescript\nconst version = await ytdlp.getVersionAsync();\n```\n\n### Utility Methods\n\n#### `checkInstallationAsync(options?)`\n\n```typescript\nconst installed = await ytdlp.checkInstallationAsync({ ffmpeg: true });\n```\n\n#### `downloadFFmpeg()`\n\n```typescript\nawait ytdlp.downloadFFmpeg();\n```\n\n#### `updateYtDlpAsync(options?)`\n\n```typescript\nconst result = await ytdlp.updateYtDlpAsync();\nconsole.log(`Updated to ${result.version}`);\n```\n\n## Format Options\n\nUse structured format options for type-safe configuration:\n\n```typescript\n// Video only\n{ filter: 'videoonly', type: 'mp4', quality: '1080p' }\n\n// Audio only\n{ filter: 'audioonly', type: 'mp3', quality: 5 }\n\n// Audio and video (single file)\n{ filter: 'audioandvideo', type: 'mp4', quality: 'highest' }\n\n// Merge video and audio\n{ filter: 'mergevideo', type: 'mp4', quality: '1080p' }\n```\n\n### Quality Options\n\n| Filter                    | Quality Values                                                                                             |\n| ------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| `videoonly`, `mergevideo` | `'2160p'`, `'1440p'`, `'1080p'`, `'720p'`, `'480p'`, `'360p'`, `'240p'`, `'144p'`, `'highest'`, `'lowest'` |\n| `audioandvideo`           | `'highest'`, `'lowest'`                                                                                    |\n| `audioonly`               | `0` to `10` (VBR quality)                                                                                  |\n\n### Type Options\n\n| Filter                       | Type Values                                                                  |\n| ---------------------------- | ---------------------------------------------------------------------------- |\n| `videoonly`, `audioandvideo` | `'mp4'`, `'webm'`                                                            |\n| `audioonly`                  | `'aac'`, `'flac'`, `'mp3'`, `'m4a'`, `'opus'`, `'vorbis'`, `'wav'`, `'alac'` |\n| `mergevideo`                 | `'mkv'`, `'mp4'`, `'ogg'`, `'webm'`, `'flv'`                                 |\n\n## Advanced Options\n\n### JavaScript Runtime\n\nNode.js is used as the default JavaScript runtime for yt-dlp extractors:\n\n```typescript\nawait ytdlp.execAsync(url, {\n  jsRuntime: 'node', // default, or 'deno', 'phantomjs'\n});\n```\n\n### Raw Arguments\n\nPass any yt-dlp argument directly:\n\n```typescript\nawait ytdlp.downloadAsync(url, {\n  rawArgs: ['--match-filter', 'duration \u003e 60', '--geo-bypass'],\n});\n```\n\n### Debug Mode\n\n```typescript\nawait ytdlp.execAsync(url, {\n  debugPrintCommandLine: true,\n  verbose: true,\n});\n```\n\n## Troubleshooting\n\n### Binary not found\n\n```typescript\nimport { helpers } from 'ytdlp-nodejs';\nawait helpers.downloadYtDlp();\nawait helpers.downloadFFmpeg();\n```\n\nOr provide custom paths:\n\n```typescript\nconst ytdlp = new YtDlp({\n  binaryPath: '/path/to/yt-dlp',\n  ffmpegPath: '/path/to/ffmpeg',\n});\n```\n\n## Built With ytdlp-nodejs\n\n🚀 **[NextDownloader.com](https://nextdownloader.com/)** - A video downloader I built using this library. Check it out and let me know what you think! Your feedback is greatly appreciated.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request or open an issue on [GitHub](https://github.com/iqbal-rashed/ytdlp-nodejs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiqbal-rashed%2Fytdlp-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiqbal-rashed%2Fytdlp-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiqbal-rashed%2Fytdlp-nodejs/lists"}