1.1.0 • Published yesterday

youtube-stream-extractor

Licence

MIT

Version

1.1.0

Deps

Size

59 kB

Vulns

Weekly

Summary Dependency Versions

YouTube Audio and Video Stream Extractor

An ultra-fast, zero-dependency, lightweight JavaScript library built to extract direct audio and video stream URLs from YouTube. It utilizes YouTube's InnerTube player API (ANDROID_VR client payload) with a watch-page scraping fallback to deliver instant, high-quality media links (up to 320kbps audio).

Works out-of-the-box in Node.js (version 18+), browsers, and modern serverless/edge environments.

Documentation: Read the comprehensive General API Guide for full details on parameters and return types.

Discord Bot Integration: Want to use this in a Discord Music Bot without Lavalink? Check out our Discord Bot Guide.

Installation

Install the package via npm:

npm install youtube-stream-extractor

Features

Zero-Dependency and Fast: Extremely lightweight and fast.
No API Keys Required: Operates entirely without Google API keys, avoiding rate limits and setup friction.
High Quality Streams: Automatically resolves the best available formats, prioritizing 320kbps / 251 itag streams for crystal clear audio.
Integrated Keyword Search: Perform keyword searches that immediately resolve titles, durations, channel names, view counts, thumbnails, and direct streaming links.
Direct URL Resolver: Pass any standard or short YouTube URL to get parsed media streams in seconds.
Dual Build: Fully supports both ES Modules (import) and CommonJS (require).

Usage Examples

1. Search YouTube by Keyword

Search for videos and extract their metadata along with stream links:

ES Modules (ESM):

import { searchYouTube } from 'youtube-stream-extractor';

const results = await searchYouTube('lofi hip hop', { limit: 3 });
console.log(results);

CommonJS (CJS):

const { searchYouTube } = require('youtube-stream-extractor');

async function run() {
  const results = await searchYouTube('lofi hip hop', { limit: 3 });
  console.log(results);
}
run();

2. Extract Streams from YouTube URL

Extract information and direct audio/video streams from a specific YouTube watch URL:

import { extractFromUrl } from 'youtube-stream-extractor';

const info = await extractFromUrl('https://www.youtube.com/watch?v=dQw4w9WgXcQ');

console.log(info.title);      // "Rick Astley - Never Gonna Give You Up"
console.log(info.audioUrl);   // Direct Google Video audio stream URL
console.log(info.videoUrl);   // Direct Google Video video stream URL

3. Get Stream URLs directly by Video ID

If you already have the 11-character YouTube video ID, you can fetch its stream URLs directly:

import { getStreamUrls } from 'youtube-stream-extractor';

const streams = await getStreamUrls('dQw4w9WgXcQ');
console.log(streams.audioUrl);
console.log(streams.videoUrl);

API Reference

ExtractorOptions

Many functions accept an optional options object with the following parameters:

poToken (string, optional): A Proof of Origin token used to bypass bot enforcement on copyrighted/VEVO videos.
visitorData (string, optional): A unique session identifier.
client (string, optional): Innertube client layout, e.g. 'WEB', 'ANDROID', 'TVHTML5', or 'YTM'.
fetchStreams (boolean, optional): Set to false in searches to speed up queries by skipping immediate stream resolution.

searchYouTube(query, options)

Searches for videos on YouTube.

query (string, required): The search keyword (e.g. lofi hip hop).
options (object, optional):
- limit (number, default 3): Number of search results to return (Min 1, Max 20).
- Extractor options (poToken, visitorData, fetchStreams).

Returns: Promise<Array>