Using streams

Streams can sometimes be quite picky on how they can be used. So here is a guide on how to use them.

Essentials

All streams have the same common parameters:

  • Stream.type: The type of stream. Either hls or file
  • Stream.id: The id of this stream, unique per scraper output.
  • Stream.flags: A list of flags that apply to this stream. Most people won't need to use it.
  • Stream.captions: A list of captions/subtitles for this stream.
  • Stream.headers: Either undefined or a key value object of headers you must set to use the stream.
  • Stream.preferredHeaders: Either undefined or a key value object of headers you may want to set if you want optimal playback - but not required.

Now let's delve deeper into how to watch these streams!

Streams with type hls

HLS streams can be tough to watch. They're not normal files you can just use. These streams have an extra property Stream.playlist which contains the m3u8 playlist.

Here is a code sample of how to use HLS streams in web context using hls.js

<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>

<video id="video"></video>
<script>
  const stream = null; // add your stream here

  if (Hls.isSupported()) {
    var video = document.getElementById('video');
    var hls = new Hls();
    hls.loadSource(stream.playlist);
    hls.attachMedia(video);
  }
</script>

Streams with type file

File streams are quite easy to use, they just return a new property: Stream.qualities. This property is a map of quality and a stream file. So if you want to get 1080p quality you do stream["1080"] to get your stream file. It will return undefined if that quality is absent.

The possibly qualities are: unknown, 360, 480, 720, 1080, 4k. File based streams are always guaranteed to have one quality.

Once you get a streamfile, you have the following parameters:

  • StreamFile.type: Right now it can only be mp4.
  • StreamFile.url: The URL linking to the video file.

Here is a code sample of how to watch a file based stream in a browser:

<video id="video"></video>
<script>
  const stream = null; // add your stream here
  const video = document.getElementById('video');

  const qualityEntries = Object.keys(stream.qualities);
  const firstQuality = qualityEntries[0];
  video.src = firstQuality.url;
</script>

Streams with headers

Streams have both a Stream.headers and a Stream.preferredHeaders. The difference between the two is that Stream.headers must be set in order for the stream to work. While the other is optional, and enhances the quality or performance.

If your target is set to BROWSER, headers will never be required, as it's not possible to do.

Using captions/subtitles

All streams have a list of captions at Stream.captions. The structure looks like this:

type Caption = {
  type: CaptionType; // Language type, either "srt" or "vtt"
  id: string; // Unique per stream
  url: string; // The URL pointing to the subtitle file
  hasCorsRestrictions: boolean; // If true, you will need to proxy it if you're running in a browser
  language: string; // Language code of the caption
};
Table of Contents