newpipe-documentation/docs/02_Concept_of_LinkHandler.md

Concept of the LinkHandler

The LinkHandler represent links to resources like videos, search requests, channels, etc. The idea is that a video can have multiple links pointing to it, but it has one unique ID that represents it, like this example:

oHg5SJYRHA0 can be represented as:

• https://www.youtube.com/watch?v=oHg5SJYRHA0 (the default URL for YouTube)
• https://youtu.be/oHg5SJYRHA0 (the shortened link)
• https://m.youtube.com/watch?v=oHg5SJYRHA0 (the link for mobile devices)

Importand notes about LinkHandler:

• A simple LinkHandler will contain the default URL, the ID, and the original URL.
• LinkHandlers are read only.
• LinkHandlers are also used to determine which part of the extractor can handle a certain link.
• In order to get one you must either call fromUrl() or fromId() of the the corresponding LinkHandlerFactory.
• Every type of resource has its own LinkHandlerFactory. Eg. YoutubeStreamLinkHandler, YoutubeChannelLinkHandler, etc.

Usage

The typical usage for obtaining a LinkHandler would look like this:

LinkHandlerFactory myLinkHandlerFactory = new MyStreamLinkHandlerFactory();
LinkHandler myVideo = myLinkHandlerFactory.fromUrl("https://my.service.com/the_video");

Implementation

In order to use LinkHandler for your service, you must override the appropriate LinkHandlerFactory. eg:

class MyStreamLinkHandlerFactory extends LinkHandlerFactory {
    
    @Override
    public String getId(String url) throws ParsingException {
        // Return the ID based on the URL.
    }

    @Override
    public String getUrl(String id) throws ParsingException {
        // Return the URL based on the ID given.
    }

    @Override
    public boolean onAcceptUrl(String url) throws ParsingException {
        // Return true if this LinkHanlderFactory can handle this type of link
    }
}

ListLinkHandler and SearchQueryHandler

List based resources, like channels and playlists, can be sorted and filtered. Therefore these type of resources don't just use a LinkHandler, but a class called ListLinkHandler, which inherits from LinkHandler and adds the field ContentFilter, which is used to filter by resource type, like stream or playlist, and SortFilter, which is used to sort by name, date, or view count.

!!ATTENTION!! Be careful when you implement a content filter: No selected filter equals all filters selected. If your get an empty content filter list in your extractor, make sure you return everything. By all means, use "if" statements like contentFilter.contains("video") || contentFilter.isEmpty().

ListLinkHandler are also created by overriding the ListLinkHandlerFactory additionally to the abstract methods this factory inherits from the LinkHandlerFactory you can override getAvailableContentFilter() and getAvailableSortFilter(). Through these you can tell the front end which kind of filter your service supports.

SearchQueryHandler

You cannot point to a search request with an ID like you point to a playlist or a channel, simply because one and the same search request might have a different outcome depending on the country or the time you send the request. This is why the idea of an "ID" is replaced by a "SearchString" in the SearchQueryHandler These work like regular ListLinkHandler, except that you don't have to implement the methods onAcceptUrl() and getId() when overriding SearchQueryHandlerFactory.