Skip to main content
NewPipe Extractor is built on a modular, service-oriented architecture that enables extraction of data from multiple streaming platforms through a unified interface.

​
Core Architecture

The library follows a layered architecture with three main components:

Services

Service implementations for each platform (YouTube, SoundCloud, etc.)

Extractors

Data extraction logic for different content types

Link Handlers

URL parsing and ID extraction utilities

​
Design Principles

​
Service Abstraction

Each streaming platform is represented by a StreamingService implementation that defines:
  • Available content types (streams, channels, playlists)
  • Link handler factories for URL processing
  • Extractor factories for data extraction
  • Supported localizations and content countries

​
Factory Pattern

The library extensively uses the Factory pattern to create:
  • Link Handlers: Parse URLs and extract IDs
  • Extractors: Fetch and parse content data
  • Kiosks: Trending/featured content sections

​
Lazy Loading

Extractors implement a two-phase loading pattern:
  1. Initialization: Create extractor with URL/ID
  2. Fetch: Call fetchPage() to download and parse data
StreamExtractor extractor = service.getStreamExtractor(url);
extractor.fetchPage();
String title = extractor.getName();

​
Entry Point

The NewPipe class serves as the main entry point: 
public static void init(Downloader d, Localization l, ContentCountry c)
public static StreamingService getService(int serviceId)
public static StreamingService getServiceByUrl(String url)
You must call NewPipe.init() before using any extractor functionality. This initializes the downloader and localization settings.

​
Initialization Example

import org.schabi.newpipe.extractor.NewPipe;
import org.schabi.newpipe.extractor.localization.Localization;
import org.schabi.newpipe.extractor.localization.ContentCountry;

// Initialize with custom downloader
NewPipe.init(new MyDownloader());

// Or with localization settings
Localization localization = new Localization("en", "GB");
ContentCountry country = new ContentCountry("US");
NewPipe.init(downloader, localization, country);

​
Service Discovery

The library automatically detects which service can handle a URL: 
// Get service by URL
StreamingService service = NewPipe.getServiceByUrl(
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
);

// Get service by ID
StreamingService youtube = NewPipe.getService(0);

// Get service by name
StreamingService soundcloud = NewPipe.getService("SoundCloud");

​
Content Types

The library supports multiple content types:
Video or audio streams (individual content items)Extractor: StreamExtractorLink Handler: LinkHandler

​
Data Flow

  1. URL Input: User provides a URL or ID
  2. Link Handler Creation: Factory parses URL and creates LinkHandler
  3. Extractor Creation: Service creates appropriate extractor
  4. Page Fetch: Extractor downloads content via Downloader
  5. Data Parsing: Extractor parses HTML/JSON response
  6. Data Access: Client calls getter methods for specific data

​
Error Handling

The library uses specific exceptions for different error cases:
  • ParsingException: Failed to parse data from response
  • ExtractionException: General extraction errors
  • ContentNotAvailableException: Content is blocked or removed
  • ContentNotSupportedException: Feature not supported by service
try {
    StreamExtractor extractor = service.getStreamExtractor(url);
    extractor.fetchPage();
    String title = extractor.getName();
} catch (ParsingException e) {
    // Handle parsing errors
} catch (ExtractionException e) {
    // Handle extraction errors
}

​
Thread Safety

Extractor instances are not thread-safe. Create separate extractor instances for concurrent operations.

​
Next Steps

Services

Learn about StreamingService implementations

Extractors

Understand the Extractor pattern

Link Handlers

Master URL parsing and validation

Localization

Configure language and region settings

Build docs developers (and LLMs) love

Get started for freeTalk to us