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>

extractFromUrl(url, options)

Resolves a YouTube URL to extract video details and stream links.

• url (string, required): Full YouTube video URL.
• options (object, optional): Extractor options.

Returns: Promise

getStreamUrls(videoId, options)

Fetches streaming URLs directly for a given YouTube video ID.

• videoId (string, required): The 11-character YouTube video ID.
• options (object, optional): Extractor options.

Returns: Promise<{ audioUrl: string, videoUrl: string, playerResponse: object }>

getAutoplay(videoId, options)

Fetches a list of related/recommended videos for a given video ID to enable autoplay lists.

• videoId (string, required): The video ID to base recommendations on.
• options (object, optional): Extractor options.

Returns: Promise<Array>

getSearchSuggestions(query, options)

Fetches autocomplete search suggestions from YouTube.

• query (string, required): The text query entered by the user.

Returns: Promise<Array>

getPlaylist(playlistId, options)

Extracts info and all tracks/videos from a YouTube Playlist.

• playlistId (string, required): The YouTube playlist ID.
• options (object, optional): Extractor options.

Returns: Promise

License and Credits

Distributed under the MIT License. Developed and maintained by iy3k.