Extractable Enhancers

Overview

ClapperExtractable is an interface to implement enhancers that need to resolve given URI into data that GStreamer will be able to play. While not limited to, main use-case is for media information extraction.

While implementer is free to write whole extraction by hand, he can alternatively integrate some 3rd party library that does most of this work. In such case, extractable enhancer is more of a wrapper for integrating said library. This is especially useful if library that you want to use is written in different programming language than Clapper is.

For the basics about writing enhancers see Clapper Enhancers.

Requirements

Additional fields for .plugin info file: X-Schemes and X-Hosts. The former one should hold the ; separated list of supported URI schemes, while the latter is for hostnames.

Example:

X-Schemes=https;expl
X-Hosts=example.com;other.example.com

With this in place, enhancer will be loaded and used for URIs that match combinations of one of the schemes and hosts. The special rule is that when using some custom URI scheme other than http(s), X-Hosts can be skipped since such URI explicitly says to use this module.

Considering all of the above, this enhancer would try to extract URIs like:

  • https://example.com/video_id=ABCD
  • expl://video.it?id=ABCD

It would not act however for:

  • https://video.it?id=ABCD
  • qwerty://other.example.com/video_id=ABCD

An enhancer of this type must implement Clapper.ExtractableInterface.extract virtual method.

Harvesting data

When Clapper.ExtractableInterface.extract is called, newly made ClapperHarvest is passed as this function argument. Implementation is responsible for filling it with data (see clapper_harvest_fill()) that can be played. Such content can be either a resolved URI to actual media file or some streaming manifest (like HLS or DASH).

Supported media types for single item include:

  • application/dash+xml - DASH manifest
  • application/x-hls - HLS manifest
  • text/x-uri - direct media URI

During extract function, implementation might optionally add media tags such as title (which will be merged with tags of ClapperMediaItem) and extra HTTP request headers if any are required to access this content.

Multiple items extraction

It is possible to handle URIs which would normally return more than one media item to play. Examples being playlists, search queries, related videos, etc.

This can be handled in two ways, depending on set media type:

  • text/uri-list - playlist of URIs
  • application/clapper-playlist - custom playlist format

If you use the first option, harvest should be filled with idividual URIs one per line. Clapper will use its built-in URI list parser to create a media item for each URI and place them in its playback queue. This is equivalent of creating ClapperMediaItem for each of these URIs without setting any tags in it initially.

The second option requires for this enhancer to also implement ClapperPlaylistable interface. In this case, you can fill harvest with ANY kind of data considering that Clapper.PlaylistableInterface.parse of your own enhancer will be used with the data you passed. With this, you can add more info to media items such as extra tags, timeline markers or subtitle URI. Useful if your extractor extracts both URIs and tags in one go.