untube

A lightweight, extremely fast YouTube video downloader and metadata scraper for Node.js. Ported from the core extraction logic of yt-dlp.

Table of Contents

• Installation
• Fetching Metadata (Basic Usage)
• Downloading Videos (Streaming)
• Configuration Options
• Format Selection & Merging
• Format Utilities
• YouTube Music Search
• Cookie Handling
• API Reference
• Disclaimer & License

Installation

npm

npm install untube

pnpm

pnpm add untube

yarn

yarn add untube

bun

bun add untube

Fetching Metadata (Basic Usage)

If you only need video details without downloading the stream, use untube.getVideoInfo(). This is the fastest way to get metadata.

import untube from 'untube';

// Basic usage
const info = await untube.getVideoInfo('dQw4w9WgXcQ');

console.log('Title:', info.title);
console.log('Views:', info.view_count);
console.log('Duration:', info.duration, 'seconds');

// With options (e.g., proxy or cookies)
const infoWithProxy = await untube.getVideoInfo('dQw4w9WgXcQ', {
    proxy: 'http://user:pass@host:port',
    cookies: './cookies.txt'
});

Downloading Videos (Streaming)

untube provides a readable stream that you can pipe anywhere (e.g., to a file, to fluent-ffmpeg, or an HTTP response).

import fs from 'node:fs';
import untube from 'untube';

// Setup AbortController to cancel download if needed
const controller = new AbortController();

// Start downloading a video
const stream = untube('dQw4w9WgXcQ', {
    format: 'highestvideo', // Select quality
    signal: controller.signal, // Optional: pass the abort signal
});

// Listen to events
stream.on('info', (info, format) => {
    console.log(`Downloading: ${info.title}`);
    console.log(`Selected Format: ${format.resolution} (${format.container})`);
});

stream.on('progress', (progress) => {
    // Progress event is only available in 'parallel' mode (default)
    console.log(`Progress: ${progress.percent}% (${progress.downloadedBytes} bytes)`);
});

stream.on('error', (err) => {
    console.error(`Error: ${err.message}`);
});

// Pipe the stream directly to a file
stream.pipe(fs.createWriteStream('video.mp4'));

Configuration Options

untube(id, options)

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | format | string | 'highest' | Quality preset (e.g., 'highestaudio', '1080p') or specific itag. | | filter | string \| function | undefined | Filter formats (e.g., 'audioonly', 'videoonly'). | | mode | 'parallel' \| 'sequential' | 'parallel' | Download strategy. 'parallel' is faster; 'sequential' is better for live playback. | | proxy | string | undefined | Proxy URL (HTTP/HTTPS). | | cookies | string \| RawCookie | undefined | Path to Netscape cookie file or RawCookie instance. | | signal | AbortSignal | undefined | Signal to abort the download. |

untube.getVideoInfo(id, options)

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | proxy | string | undefined | Proxy URL (HTTP/HTTPS). | | cookies | string \| RawCookie | undefined | Path to Netscape cookie file or RawCookie instance. |

Format Selection & Merging

⚠️ Important Note on Video & Audio:
YouTube separates most video and audio into different streams (DASH formats).

• If you choose a video-only format (like highestvideo), the resulting file will not have sound.
• If you want a single file with both video and audio, you must download the video and audio streams separately and merge them yourself using a tool like ffmpeg.

Common Presets

• Presets: 'highest', 'lowest', 'highestaudio', 'lowestaudio', 'highestvideo', 'lowestvideo'.
• Resolutions: '1080p', '720p', etc.
• Format ID / itag: Use specific itags like '137' (1080p video-only) or '140' (m4a audio).

Format Utilities

untube includes utility functions to help you manage and filter formats from the info object.

const info = await untube.getVideoInfo('videoId');

// 1. Filter formats using presets
// Available presets: 'audioandvideo', 'video', 'videoonly', 'audio', 'audioonly'
const audioOnly = untube.filterFormats(info.formats, 'audioonly');

// 2. Filter using custom logic
const mp4Only = untube.filterFormats(info.formats, f => f.container === 'mp4');

// 3. Choose a specific format manually
const bestAudio = untube.chooseFormat(info.formats, { quality: 'highestaudio' });

// 4. Sort formats from highest to lowest quality
const sorted = untube.sortFormats(info.formats);

untube.ytmusic(query, options)

Search for songs or videos directly from YouTube Music.

import untube from 'untube';

// Basic usage
const results = await untube.ytmusic('Never gonna give you up');

// With options (e.g., proxy or cookies)
const resultsWithProxy = await untube.ytmusic('Never gonna give you up', {
    proxy: 'http://user:pass@host:port',
    cookies: './cookies.txt'
});

console.log('Top Result:', results[0].title);
console.log('Artist:', results[0].artist);
console.log('Album:', results[0].album);
console.log('Duration:', results[0].duration, 'seconds');

Cookie Handling

Using cookies is highly recommended to avoid rate limits, access age-restricted videos, or bypass regional restrictions.

1. Using a File (Netscape format)

Export cookies in Netscape format from your browser (e.g., using "Get cookies.txt LOCALLY" extension) and provide the file path:

untube('videoId', { cookies: './cookies.txt' });

2. Advanced: Remote Storage (Database)

Use the RawCookie class for custom read/write logic (e.g., storing in a database):

const myRawCookie = new untube.RawCookie(
    async () => await fetchFromDB(), // Must return Netscape string
    async (newCookies) => await saveToDB(newCookies)
);
untube('videoId', { cookies: myRawCookie });

API Reference

VideoInfo

| Property | Type | Description | | :--- | :--- | :--- | | id | string | Video ID. | | title | string | Video title. | | description | string | Video description. | | duration | number | Duration in seconds. | | view_count | number | Total views. | | uploader | string | Channel name. | | thumbnail | string | Highest resolution thumbnail URL. | | formats | YouTubeFormat[] | Array of available formats. | | captions | YouTubeCaption[] | Array of available subtitles. |

YouTubeFormat

| Property | Type | Description | | :--- | :--- | :--- | | format_id | string | The itag of the format. | | ext | string | File extension (e.g., 'mp4', 'webm'). | | resolution | string | e.g., '1080p', 'audio only'. | | vcodec | string | Video codec. 'none' for audio-only. | | acodec | string | Audio codec. 'none' for video-only. | | filesize | number \| null | File size in bytes. | | url | string | Direct streaming URL (decrypted). |

Disclaimer

This project is created for educational purposes only. Users are responsible for complying with YouTube's Terms of Service and local copyright laws.

License

This project is licensed under the Unlicense (Public Domain).

Note: While the core codebase is released under the Unlicense, this project relies on open-source dependencies (e.g., tough-cookie, meriyah, astring, etc.) which have their own respective licenses (such as MIT, BSD, etc.). Please ensure compliance with the licenses of these dependencies if you intend to distribute or use this module in a commercial product.