{"_id":"@codepilotbot/ytdlp-nodejs-fc","name":"@codepilotbot/ytdlp-nodejs-fc","dist-tags":{"latest":"3.4.2"},"versions":{"3.4.2":{"name":"@codepilotbot/ytdlp-nodejs-fc","version":"3.4.2","description":"A TypeScript wrapper for the yt-dlp executable","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","bin":{"ytdlp":"dist/cli/index.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js","default":"./dist/index.js"}},"scripts":{"build":"tsup","test":"jest","lint":"eslint","format":"prettier --ignore-path .gitignore --write \"./src/**/*.+(js|ts|json)\"","download:ytdlp":"tsx ./src/scripts/downloadYtdlp.ts","download:ffmpeg":"tsx ./src/scripts/downloadFFmpeg.ts","postdownload":"node ./dist/scripts/downloadYtdlp.js","postinstall":"node -e \"process.env.INIT_CWD !== process.cwd() && require('child_process').execSync('npm run postdownload', { stdio: 'inherit' });\"","prepare":"npm run build && (husky || true)","docs:dev":"rspress dev","docs:build":"rspress build","docs:preview":"rspress preview"},"keywords":["yt-dlp","youtube","video","download","wrapper","typescript","ytdlp","youtube downloader","ytdlp-nodejs","youtube-thumbnails","typescript","nodejs","youtube video","video","video downloader"],"author":{"name":"Fix CodePilotbot"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/CodePilotBot/ytdlp-nodejs-fc.git"},"bugs":{"url":"https://github.com/CodePilotBot/ytdlp-nodejs-fc/issues"},"homepage":"https://iqbal-rashed.github.io/ytdlp-nodejs","devDependencies":{"@eslint/js":"^9.23.0","@rspress/plugin-shiki":"^1.47.0","@types/jest":"^29.5.14","@types/node":"^22.13.11","eslint":"^9.23.0","globals":"^16.0.0","husky":"^9.1.7","jest":"^29.7.0","rspress":"^1.47.0","ts-jest":"^29.2.6","tsup":"^8.4.0","tsx":"^4.19.3","typescript":"^5.8.2","typescript-eslint":"^8.27.0"},"engines":{"node":">=16.0.0"},"_id":"@codepilotbot/ytdlp-nodejs-fc@3.4.2","_nodeVersion":"24.17.0","_npmVersion":"11.18.0","dist":{"integrity":"sha512-Uzz7h/CFcCYmSVjcWAUQ/VcqPZopL89BTcwrgQw8OYawBGfKUheEqeKMvU9fBb/O+hZN0zwk66ruQpZGGp6WRA==","shasum":"7eb386bdaf00f99678bcb54830f095ab15b77277","tarball":"https://registry.npmjs.org/@codepilotbot/ytdlp-nodejs-fc/-/ytdlp-nodejs-fc-3.4.2.tgz","fileCount":8,"unpackedSize":196258,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIB24dj1NtZhnkjHaq18086VAfLQEiJpsI4C3llsBEgwwAiB/VmZA0r1+UAk/S7PXaZpdC+JSf+juCQuZUekHOgdRwA=="}]},"_npmUser":{"name":"codepilotbot","email":"mynameanonymous3@gmail.com"},"directories":{},"maintainers":[{"name":"codepilotbot","email":"mynameanonymous3@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ytdlp-nodejs-fc_3.4.2_1784528799091_0.48861417861186784"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-20T06:26:38.930Z","3.4.2":"2026-07-20T06:26:39.219Z","modified":"2026-07-20T06:26:39.418Z"},"maintainers":[{"name":"codepilotbot","email":"mynameanonymous3@gmail.com"}],"description":"A TypeScript wrapper for the yt-dlp executable","homepage":"https://iqbal-rashed.github.io/ytdlp-nodejs","keywords":["yt-dlp","youtube","video","download","wrapper","typescript","ytdlp","youtube downloader","ytdlp-nodejs","youtube-thumbnails","typescript","nodejs","youtube video","video","video downloader"],"repository":{"type":"git","url":"git+https://github.com/CodePilotBot/ytdlp-nodejs-fc.git"},"author":{"name":"Fix CodePilotbot"},"bugs":{"url":"https://github.com/CodePilotBot/ytdlp-nodejs-fc/issues"},"license":"MIT","readme":"> **⚠️ 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 & 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> **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  .filter('mergevideo')\n  .quality('1080p')\n  .type('mp4')\n  .on('progress', (p) => 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#### Direct Commands\n\nThese commands run without prompts:\n\n```bash\n# List available formats\nytdlp formats <url>\n\n# Download with specific quality (non-interactive)\nytdlp video <url> --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  .format({ filter: 'mergevideo', quality: '1080p', type: 'mp4' })\n  .output('./downloads')\n  .embedThumbnail()\n  .on('progress', (p) => 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) => 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<DownloadFinishResult>` - 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) => 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  .filter('audioandvideo')\n  .quality('highest')\n  .type('mp4')\n  .on('progress', (p) => console.log(p.percentage_str))\n  .pipeAsync(createWriteStream('video.mp4'));\n\nconsole.log(`Bytes: ${result.bytes}`);\n\n// Sync pipe\nytdlp.stream(url).filter('audioandvideo').pipe(writableStream);\n\n// Stream to buffer\nconst buffer = await ytdlp.stream(url).filter('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) => 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 > 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","readmeFilename":"readme.md","_rev":"1-16ece2de9d740befdade937f8595918d"}