# 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

```html
<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:

```html
<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:
```ts
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
};
```