newpipe-extractor-js/README.md

JavaScript/Node.js port of NewPipeExtractor

# NewPipe Extractor JS

[![npm version](https://badge.fury.io/js/newpipe-extractor-js.svg)](https://badge.fury.io/js/newpipe-extractor-js)
[![npm downloads](https://img.shields.io/npm/dm/newpipe-extractor-js.svg)](https://www.npmjs.com/package/newpipe-extractor-js)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)


A comprehensive JavaScript/TypeScript port of the [NewPipeExtractor](https://github.com/TeamNewPipe/NewPipeExtractor) library for extracting data from YouTube and other video streaming services.

> **🚀 NEW:** Now includes comprehensive YouTube search functionality without requiring API keys!

## Features

- 🎵 **Audio Stream Extraction** - Extract high-quality audio streams from YouTube videos
- 🎬 **Video Stream Extraction** - Extract video streams in various qualities and formats
- 🔍 **YouTube Search** - Search YouTube content without API keys (videos, channels, playlists)
- 💡 **Search Suggestions** - Get search autocomplete suggestions
- 🔓 **Signature Decryption** - Automatic handling of YouTube's signature/cipher decryption
- 🍪 **Cookie Support** - Support for authentication cookies (JSON format)
- 🌍 **Localization** - Multi-language and region support
- 📱 **Multiple Services** - Extensible architecture (currently supports YouTube)
- 🚀 **High Performance** - Efficient caching and parallel processing
- 📦 **TypeScript Support** - Full TypeScript definitions included
- 🔧 **No API Keys Required** - Uses Android client simulation like NewPipe app

## Installation

```bash
npm install newpipe-extractor-js
```

## Quick Start

### Basic Stream Extraction

```typescript
import { initializeNewPipe, extractStreamInfo, getBestAudioStream } from 'newpipe-extractor-js';

// Initialize the extractor
initializeNewPipe();

// Extract stream information
const streamInfo = await extractStreamInfo('https://www.youtube.com/watch?v=dQw4w9WgXcQ');

console.log('Title:', streamInfo.name);
console.log('Uploader:', streamInfo.uploaderName);
console.log('Duration:', streamInfo.length);

// Get the best quality audio stream
const bestAudio = getBestAudioStream(streamInfo);
if (bestAudio) {
  console.log('Best audio URL:', bestAudio.url);
  console.log('Format:', bestAudio.format);
  console.log('Bitrate:', bestAudio.bitrate);
}
```

### YouTube Search (No API Key Required!)

```typescript
import { searchYoutube, getYoutubeSearchSuggestions } from 'newpipe-extractor-js';

// Initialize first
initializeNewPipe();

// Search for videos
const searchResults = await searchYoutube('JavaScript tutorial', ['videos']);
console.log(`Found ${searchResults.items.length} videos:`);

searchResults.items.forEach((item, index) => {
  console.log(`${index + 1}. ${item.name} by ${item.uploaderName}`);
  console.log(`   Views: ${item.viewCount} | Duration: ${item.duration}s`);
  console.log(`   URL: ${item.url}`);
});

// Get search suggestions
const suggestions = await getYoutubeSearchSuggestions('javascript');
console.log('Suggestions:', suggestions);
```

## Advanced Usage

### Using Cookies for Authentication

```typescript
import { initializeNewPipe, DefaultDownloader } from 'newpipe-extractor-js';
import * as fs from 'fs';

// Load cookies from JSON file
const cookieJson = JSON.parse(fs.readFileSync('cookies.json', 'utf-8'));

// Initialize with cookies
initializeNewPipe(cookieJson);

// Now you can access age-restricted or premium content
const streamInfo = await extractStreamInfo('https://www.youtube.com/watch?v=VIDEO_ID');
```

### Custom Downloader Configuration

```typescript
import { NewPipe, DefaultDownloader, YoutubeService } from 'newpipe-extractor-js';

// Create custom downloader with user agent
const downloader = new DefaultDownloader(
  undefined, // CookieJar (optional)
  'Custom-User-Agent/1.0' // Custom user agent
);

// Initialize NewPipe
NewPipe.init(downloader);
NewPipe.registerService(new YoutubeService());

// Load cookies manually
await downloader.loadCookiesFromJson(cookieArray);
```

### Setting Localization

```typescript
import { setPreferredLocalization, setPreferredContentCountry } from 'newpipe-extractor-js';

// Set language preference
setPreferredLocalization({ languageCode: 'en', countryCode: 'US' });

// Set content country (affects trending, etc.)
setPreferredContentCountry({ languageCode: 'en', countryCode: 'GB' });
```

## API Reference

### Core Functions

#### `initializeNewPipe(cookieJson?, userAgent?)`
Initialize the NewPipe extractor with optional cookies and user agent.

#### `extractStreamInfo(url: string): Promise<StreamInfo>`
Extract complete stream information from a video URL.

#### `isUrlSupported(url: string): boolean`
Check if a URL is supported by any registered service.

#### `getBestAudioStream(streamInfo: StreamInfo)`
Get the highest quality audio stream from extracted stream info.

#### `getBestVideoStream(streamInfo: StreamInfo)`
Get the highest quality video stream from extracted stream info.

### Types

```typescript
interface StreamInfo {
  id: string;
  name: string;
  url: string;
  uploaderName?: string;
  uploaderUrl?: string;
  thumbnails: Image[];
  description?: string;
  length: number;
  viewCount: number;
  uploadDate?: string;
  audioStreams: AudioStream[];
  videoStreams: VideoStream[];
  videoOnlyStreams: VideoStream[];
  dashMpdUrl?: string;
  hlsUrl?: string;
  // ... and more
}

interface AudioStream {
  url?: string;
  itag?: number;
  bitrate?: number;
  format: MediaFormat;
  quality?: string;
  codec?: string;
  // ... and more
}

interface VideoStream {
  url?: string;
  itag?: number;
  bitrate?: number;
  format: MediaFormat;
  resolution?: string;
  fps?: number;
  width?: number;
  height?: number;
  isVideoOnly?: boolean;
  // ... and more
}
```

## Supported Services

- ✅ **YouTube** - Full support including signature decryption
- 🚧 **SoundCloud** - Planned
- 🚧 **PeerTube** - Planned
- 🚧 **Bandcamp** - Planned
- 🚧 **Media.ccc.de** - Planned

## Examples

### Extract All Available Streams

```typescript
const streamInfo = await extractStreamInfo(videoUrl);

console.log('Audio Streams:');
streamInfo.audioStreams.forEach((stream, index) => {
  console.log(`${index + 1}. ${stream.format} - ${stream.bitrate}bps - ${stream.quality}`);
});

console.log('Video Streams:');
streamInfo.videoStreams.forEach((stream, index) => {
  console.log(`${index + 1}. ${stream.format} - ${stream.resolution} - ${stream.bitrate}bps`);
});
```

### Handle Different URL Formats

```typescript
const urls = [
  'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  'https://youtu.be/dQw4w9WgXcQ',
  'dQw4w9WgXcQ' // Just the video ID
];

for (const url of urls) {
  if (isUrlSupported(url)) {
    const streamInfo = await extractStreamInfo(url);
    console.log(`Successfully extracted: ${streamInfo.name}`);
  }
}
```

## Error Handling

```typescript
try {
  const streamInfo = await extractStreamInfo(url);
  // Process stream info
} catch (error) {
  if (error instanceof ContentNotAvailableException) {
    console.log('Video is not available (private, deleted, or geo-blocked)');
  } else if (error instanceof AgeRestrictedException) {
    console.log('Video is age-restricted - cookies may be required');
  } else if (error instanceof ParsingException) {
    console.log('Failed to parse video data');
  } else {
    console.log('Unknown error:', error.message);
  }
}
```

## Cookie Format

The library supports YouTube cookies in JSON format:

```json
[
  {
    "name": "cookie_name",
    "value": "cookie_value",
    "domain": ".youtube.com",
    "path": "/",
    "secure": true,
    "httpOnly": false,
    "expirationDate": 1735689600
  }
]
```

You can export cookies from your browser using extensions like "Cookie Editor" or programmatically.

## Development

```bash
# Clone the repository
git clone https://github.com/location/newpipe-extractor-js.git
cd newpipe-extractor-js

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run example
npm run dev examples/basic-usage.ts
```

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## License

This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [NewPipe Team](https://github.com/TeamNewPipe) for the original NewPipeExtractor
- [yt-dlp](https://github.com/yt-dlp/yt-dlp) for YouTube extraction insights
- All contributors and the open-source community

## Disclaimer

This library is for educational and research purposes only. Please respect the terms of service of the platforms you're extracting data from.