### Start API Service Locally (Bun)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

Starts the API service locally by navigating to its directory and executing the built Javascript file. This is an example for the API; other services can be started similarly.

```sh
cd apps/api
$ bun run dist/index.js
```

--------------------------------

### Player Initialization and Usage

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/player-overview.md

Demonstrates how to install the Superstreamer player and initialize it with a media source.

```APIDOC
## Installation

Install the Superstreamer player using your preferred package manager:

### npm
```sh
npm i @superstreamer/player
```

### pnpm
```sh
pnpm add @superstreamer/player
```

### yarn
```sh
yarn add @superstreamer/player
```

### bun
```sh
bun add @superstreamer/player
```

## Usage

Create an `HlsPlayer` instance and load a media source.

### Method
```ts
import { HlsPlayer } from "@superstreamer/player";

const container = document.getElementById("playerContainer");
const player = new HlsPlayer(container);

// Load a source.
player.load("https://stitcher.superstreamer.xyz/sessions/b435b2e3-870c-48ce-bc29-fa397e360098/master.m3u8");
```

Refer to the [Player reference](/reference/player) for more details on available methods and properties.
```

--------------------------------

### Install Superstreamer Player

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Install the HLS.js wrapper package using common Node.js package managers.

```bash
npm install @superstreamer/player
pnpm add @superstreamer/player
yarn add @superstreamer/player
bun add @superstreamer/player
```

--------------------------------

### Installing Superstreamer Dependencies with Bun

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

These commands install the project's JavaScript dependencies using Bun and then install binary dependencies, such as ffmpeg, which are required for video processing. Run these commands at the root of the Superstreamer project.

```sh
# Install dependencies
$ bun install
# Install binary dependencies, such as ffmpeg
$ bun run install-bin

```

--------------------------------

### HlsPlayer Initialization and Loading

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/reference/player.md

Demonstrates how to create an HlsPlayer instance and load a video stream from a given URL. This is a fundamental step for starting playback.

```typescript
const player = new HlsPlayer(document.getElementById('player-container'));
player.load('https://example.com/stream.m3u8');
```

--------------------------------

### Install Superstreamer Player using Package Managers

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/player-overview.md

Instructions for installing the Superstreamer Player package using various package managers like npm, pnpm, yarn, and bun. This package is essential for integrating the player into your project.

```sh
npm i @superstreamer/player
```

```sh
pnpm add @superstreamer/player
```

```sh
yarn add @superstreamer/player
```

```sh
bun add @superstreamer/player
```

--------------------------------

### Start Development Mode (Bun)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

Launches all Superstreamer services and the dashboard app in development mode. Ensure environment variables are correctly configured before running. Access the app at http://localhost:52000.

```sh
$ bun run dev
```

--------------------------------

### Configure In-Stream Signaling with HLS Cues

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-ad-insertion.md

This example shows an HLS playlist containing SCTE-35 style cue tags and the corresponding JSON configuration to trigger ad insertion based on those cues.

```m3u8
#EXTM3U
#EXT-X-VERSION:8
#EXT-X-TARGETDURATION:2
#EXTINF:2
video_1080_h264/40.m4s
#EXTINF:2
video_1080_h264/41.m4s
#EXTINF:1.4
video_1080_h264/42.m4s
#EXT-X-CUE-OUT:DURATION=5
#EXTINF:2
video_1080_h264/43.m4s
#EXTINF:2
video_1080_h264/44.m4s
#EXTINF:1
video_1080_h264/45.m4s
#EXT-X-CUE-IN
#EXTINF:2
video_1080_h264/46.m4s
```

```json
{
  "uri": "https://example.com/live-stream/ca66c6d4-65fc-46e3-8a9c-60901f5b485e/master.m3u8",
  "vast": {
    "url": "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=&duration={duration}"
  }
}
```

--------------------------------

### Complete HLS Player UI Implementation in TypeScript

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

This example demonstrates a full implementation of a video player UI using the HLSPlayer from @superstreamer/player. It covers initializing the player, setting up event listeners for various player states (ready, time change, playhead change, quality change, audio track change, timeline change), and implementing methods for loading media, controlling playback, seeking, setting volume, and selecting quality/audio/subtitle tracks. It also includes basic UI update functions and a destroy method.

```typescript
import { HlsPlayer, Events } from "@superstreamer/player";

class VideoPlayerUI {
  private player: HlsPlayer;

  constructor(containerId: string) {
    const container = document.getElementById(containerId) as HTMLDivElement;
    this.player = new HlsPlayer(container);
    this.setupEventListeners();
  }

  private setupEventListeners() {
    this.player.on(Events.READY, () => {
      this.updateUI();
    });

    this.player.on(Events.TIME_CHANGE, () => {
      this.updateProgress();
    });

    this.player.on(Events.PLAYHEAD_CHANGE, () => {
      this.updatePlayButton();
    });

    this.player.on(Events.QUALITIES_CHANGE, () => {
      this.populateQualityMenu();
    });

    this.player.on(Events.AUDIO_TRACKS_CHANGE, () => {
      this.populateAudioMenu();
    });

    this.player.on(Events.TIMELINE_CHANGE, () => {
      this.renderAdMarkers();
    });
  }

  load(sessionUrl: string) {
    this.player.load(sessionUrl);
  }

  togglePlayPause() {
    this.player.playOrPause();
  }

  seek(time: number) {
    this.player.seekTo(time);
  }

  setVolume(level: number) {
    this.player.setVolume(level);
  }

  selectQuality(height: number | null) {
    this.player.setQuality(height);
  }

  selectAudioTrack(id: number) {
    this.player.setAudioTrack(id);
  }

  selectSubtitle(id: number | null) {
    this.player.setSubtitleTrack(id);
  }

  private updateUI() {
    console.log(`Duration: ${this.player.duration}s, Live: ${this.player.live}`);
  }

  private updateProgress() {
    const progress = (this.player.currentTime / this.player.duration) * 100;
    console.log(`Progress: ${progress.toFixed(1)}%`);
  }

  private updatePlayButton() {
    const isPlaying = this.player.playhead === "playing";
    console.log(`Playing: ${isPlaying}`);
  }

  private populateQualityMenu() {
    this.player.qualities.forEach(q => {
      console.log(`Quality: ${q.height}p ${q.active ? "(active)" : ""}`);
    });
  }

  private populateAudioMenu() {
    this.player.audioTracks.forEach(t => {
      console.log(`Audio: ${t.label} ${t.active ? "(active)" : ""}`);
    });
  }

  private renderAdMarkers() {
    this.player.timeline.forEach(item => {
      console.log(`Ad at ${item.start}s, duration: ${item.duration}s`);
    });
  }

  destroy() {
    this.player.destroy();
  }
}

// Usage
const playerUI = new VideoPlayerUI("video-container");
playerUI.load("https://stitcher.superstreamer.xyz/sessions/session-id/master.m3u8");

```

--------------------------------

### Initialize and Load HLS Source with Superstreamer Player

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/player-overview.md

Demonstrates how to create an instance of the HLSPlayer and load an HLS stream. This involves getting a container element and passing its ID to the HlsPlayer constructor, followed by calling the load method with the stream URL.

```ts
import { HlsPlayer } from "@superstreamer/player";

const container = document.getElementById("playerContainer");
const player = new HlsPlayer(container);

// Load a source.
player.load("https://stitcher.superstreamer.xyz/sessions/b435b2e3-870c-48ce-bc29-fa397e360098/master.m3u8");
```

--------------------------------

### Starting Superstreamer Services with Docker Compose

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

This command initiates all the services defined in the docker-compose.yml file in detached mode. It ensures that the Superstreamer application and its dependencies are running in the background.

```sh
docker compose up -d

```

--------------------------------

### Superstreamer Player Integration

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Guidelines for installing and using the @superstreamer/player for HLS playback, including event handling, playback controls, and quality management.

```APIDOC
## Player Installation

### Description
Install the Superstreamer player wrapper via your preferred package manager.

### Commands
- npm: `npm install @superstreamer/player`
- pnpm: `pnpm add @superstreamer/player`
- yarn: `yarn add @superstreamer/player`
- bun: `bun add @superstreamer/player`

## Basic Usage

### Description
Initialize the player and listen to playback events.

### Example
```typescript
import { HlsPlayer, Events } from "@superstreamer/player";
const player = new HlsPlayer(container);
player.on(Events.READY, () => console.log("Ready"));
player.load("https://stitcher.superstreamer.xyz/sessions/session-id/master.m3u8");
```
```

--------------------------------

### Transcode Job with Multiple Subtitles (cURL)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/media-subtitles.md

This example demonstrates how to initiate a transcode job using cURL, specifying multiple subtitle files as input and defining corresponding text streams for the output HLS playlist. Ensure the input paths are correctly formatted S3 URIs and languages are specified accurately.

```sh
curl -X POST \
  "https://api.superstreamer.xyz/jobs/transcode"
```

```json
{
  "inputs": [
    {
      "type": "text",
      "path": "s3://english_subtitles.vtt",
      "language": "eng"
    },
    {
      "type": "text",
      "path": "s3://dutch_subtitles.vtt",
      "language": "nld"
    }
    // ... audio and video input
  ],
  "streams": [
    {
      "type": "text",
      "language": "eng"
    },
    {
      "type": "text",
      "language": "nld"
    }
  ]
}
```

--------------------------------

### Create Session Request (Shell)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-create-a-session.md

Example using curl to send a POST request to the Superstreamer sessions endpoint. This initiates the creation of a playback session.

```sh
curl -X POST
  "https://stitcher.superstreamer.xyz/sessions"
```

--------------------------------

### Cloning Superstreamer Repository

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

This command clones the Superstreamer project from GitHub to your local machine. After cloning, navigate into the project directory to proceed with the setup.

```sh
git clone git@github.com:superstreamerapp/superstreamer.git
cd superstreamer

```

--------------------------------

### GET /user

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Retrieves the current authenticated user profile.

```APIDOC
## GET /user

### Description
Retrieves information about the currently authenticated user based on the provided JWT token.

### Method
GET

### Endpoint
/user

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer <token>

### Request Example
curl -X GET "https://api.superstreamer.xyz/user" \
  -H "Authorization: Bearer <token>"

### Response
#### Success Response (200)
- **id** (string) - User ID
- **username** (string) - Username

#### Response Example
{
  "id": "1",
  "username": "admin"
}
```

--------------------------------

### Create Stitcher Playback Sessions

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Initialize HLS playback sessions using internal asset URIs or external HLS playlist URLs.

```bash
curl -X POST "https://stitcher.superstreamer.xyz/sessions" -H "Content-Type: application/json" -d '{"uri": "asset://46169885-f274-43ad-ba59-a746d33304fd"}'

curl -X POST "https://stitcher.superstreamer.xyz/sessions" -H "Content-Type: application/json" -d '{"uri": "https://stream.mux.video/1b0cd077-965e/master.m3u8"}'
```

--------------------------------

### Package API

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/media-transcode-package.md

Creates an HLS playlist from previously transcoded video and audio assets.

```APIDOC
## POST /jobs/package

### Description
Packages transcoded video and audio assets into an HLS playlist format.

### Method
POST

### Endpoint
/jobs/package

### Parameters
#### Request Body
- **assetId** (string) - Required - The ID of the asset to package, typically obtained from a transcode job.

### Request Example
```json
{
  "assetId": "46169885-f274-43ad-ba59-a746d33304fd"
}
```

### Response
#### Success Response (200)
- **playlistUrl** (string) - The URL to the generated HLS master playlist.

#### Response Example
```
https://cdn.superstreamer.xyz/package/46169885-f274-43ad-ba59-a746d33304fd/hls/master.m3u8
```
```

--------------------------------

### Manage Player Lifecycle and Cleanup

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Shows how to properly unload media content and destroy the player instance to free up resources.

```typescript
import { HlsPlayer, Events } from "@superstreamer/player";

const player = new HlsPlayer(container);

player.on(Events.RESET, () => {
  console.log("Player was reset/unloaded");
});

player.load("https://stitcher.superstreamer.xyz/sessions/session-id/master.m3u8");
player.unload();
player.load("https://stitcher.superstreamer.xyz/sessions/another-session/master.m3u8");
player.destroy();
```

--------------------------------

### Build Superstreamer Project (Bun)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

Builds all the services and applications within the Superstreamer project into single Javascript files, typically located in the 'dist' folder. This command utilizes Bun for service bundling and Vite for client packages.

```sh
$ bun run build
```

--------------------------------

### Configure API Environment Variables (.env)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

Sets up the environment variables for the API service, including port, database connections, S3 credentials, and a super secret key for encryption. Ensure the SUPER_SECRET is kept confidential.

```sh
PORT=52001
REDIS_URI=redis://localhost:6379
S3_ENDPOINT=
S3_REGION=
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_BUCKET=
DATABASE_URI=
SUPER_SECRET=secret
```

--------------------------------

### POST /sessions

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-create-a-session.md

Creates a new playback session for an individual viewer by providing a source URI.

```APIDOC
## POST /sessions

### Description
Creates a new playback session. This endpoint processes the provided URI to generate a customized HLS playlist URL for the viewer.

### Method
POST

### Endpoint
/sessions

### Parameters
#### Request Body
- **uri** (string) - Required - The source of the content. Can be an 'asset://' scheme, a raw asset UUID, or an external 'https://' HLS master playlist URL.

### Request Example
{
  "uri": "asset://2d6e6c0e-07d9-48b1-8192-318f32a3b909"
}

### Response
#### Success Response (200)
- **url** (string) - The generated HLS playlist URL for the session.

#### Response Example
{
  "url": "https://stitcher.superstreamer.xyz/sessions/625f68c2-6c09-44d4-a50f-81873cb7839b/master.m3u8"
}
```

--------------------------------

### Importing Video from S3 Bucket

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/media-import-video.md

Demonstrates how to reference a video file stored in an S3 bucket. The path must use the s3:// scheme followed by the bucket object key.

```json
{
  "inputs": [
    {
      "type": "video",
      "path": "s3://sources/BigBuckBunny.mp4"
    }
  ]
}
```

--------------------------------

### Create Package Job

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Packages previously transcoded streams into an HLS playlist. This enables adaptive bitrate streaming for the specified asset.

```bash
curl -X POST "https://api.superstreamer.xyz/jobs/package" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "assetId": "46169885-f274-43ad-ba59-a746d33304fd",
    "segmentSize": 4,
    "name": "hls",
    "language": "eng",
    "concurrency": 2,
    "public": true
  }'
```

--------------------------------

### Serve Dashboard App Locally (npx serve)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

Hosts the built single-page dashboard application statically using 'npx serve'. The application reads public environment variables from the root config file and includes them in the Javascript bundles. The build files are located in 'apps/app/dist'.

```sh
cd apps/app
$ npx serve dist
```

--------------------------------

### Initialize and Control HLS Player

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Configure the player instance, handle playback events, and manage transport controls like seeking and volume.

```typescript
import { HlsPlayer, Events } from "@superstreamer/player";
const container = document.getElementById("playerContainer") as HTMLDivElement;
const player = new HlsPlayer(container);
player.on(Events.READY, () => console.log("Ready"));
player.load("https://stitcher.superstreamer.xyz/sessions/session-id/master.m3u8");
player.playOrPause();
player.seekTo(30);
player.setVolume(0.5);
```

--------------------------------

### POST /jobs (Video Import)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/media-import-video.md

Initiate a processing job by providing the path to a video source via S3 or HTTP(S).

```APIDOC
## POST /jobs

### Description
Initiates a new video processing job by referencing a source file located in S3 or at a public URL.

### Method
POST

### Endpoint
/jobs

### Request Body
- **inputs** (array) - Required - A list of input objects containing the video source.
- **inputs.type** (string) - Required - The type of media, e.g., "video".
- **inputs.path** (string) - Required - The URI of the file (e.g., "s3://bucket/path/to/video.mp4" or "https://example.com/video.mp4").

### Request Example
{
  "inputs": [
    {
      "type": "video",
      "path": "s3://sources/BigBuckBunny.mp4"
    }
  ]
}

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier for the created processing job.

#### Response Example
{
  "job_id": "job_123456789"
}
```

--------------------------------

### Configure VAST Preroll Ad

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-ad-insertion.md

This request demonstrates how to insert a single VAST ad as a preroll at the beginning of a video asset.

```json
{
  "uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689",
  "interstitials": [
    {
      "time": 0,
      "vast": {
        "url": "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator="
      }
    }
  ]
}
```

--------------------------------

### Apply Playlist Filtering

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Customize HLS output by applying resolution constraints and audio language preferences during session creation.

```bash
curl -X POST "https://stitcher.superstreamer.xyz/sessions" -H "Content-Type: application/json" -d '{"uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689", "filter": {"resolution": "<= 480"}}'

curl -X POST "https://stitcher.superstreamer.xyz/sessions" -H "Content-Type: application/json" -d '{"uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689", "filter": {"audioLanguage": "eng, nld"}}'
```

--------------------------------

### Create Transcode Job

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Initiates a job to transcode video files into multiple quality streams. Requires specifying input sources and desired output stream configurations.

```bash
curl -X POST "https://api.superstreamer.xyz/jobs/transcode" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "inputs": [
      {"type": "video", "path": "s3://sources/BigBuckBunny.mp4"},
      {"type": "audio", "path": "s3://sources/BigBuckBunny.mp4", "language": "eng"},
      {"type": "audio", "path": "s3://sources/dutch_audio.mp3", "language": "nld"},
      {"type": "text", "path": "s3://sources/english_subtitles.vtt", "language": "eng"}
    ],
    "streams": [
      {"type": "video", "codec": "h264", "height": 1080, "bitrate": 5000000},
      {"type": "video", "codec": "h264", "height": 720, "bitrate": 2500000},
      {"type": "video", "codec": "h264", "height": 480, "bitrate": 1000000},
      {"type": "audio", "codec": "aac", "language": "eng", "bitrate": 128000},
      {"type": "audio", "codec": "aac", "language": "nld", "bitrate": 128000},
      {"type": "text", "language": "eng"}
    ],
    "segmentSize": 4
  }'
```

--------------------------------

### Manage Jobs and Assets

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Provides endpoints to list, filter, and retrieve details for jobs and assets. Includes functionality to fetch logs for troubleshooting.

```bash
curl -X GET "https://api.superstreamer.xyz/jobs?page=1&perPage=20&sortKey=createdAt&sortDir=desc" -H "Authorization: Bearer YOUR_TOKEN"
curl -X GET "https://api.superstreamer.xyz/jobs/pipeline_a1b2c3d4-e5f6-7890-abcd-ef1234567890" -H "Authorization: Bearer YOUR_TOKEN"
curl -X GET "https://api.superstreamer.xyz/jobs/pipeline_a1b2c3d4-e5f6-7890-abcd-ef1234567890/logs" -H "Authorization: Bearer YOUR_TOKEN"
curl -X GET "https://api.superstreamer.xyz/assets?page=1&perPage=20&sortKey=createdAt&sortDir=desc" -H "Authorization: Bearer YOUR_TOKEN"
```

--------------------------------

### Importing Video from HTTP(S) URL

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/media-import-video.md

Demonstrates how to reference a publicly accessible video file using an HTTP or HTTPS URL. This is useful for content hosted on external CDNs or web servers.

```json
{
  "inputs": [
    {
      "type": "video",
      "path": "https://cdn.superstreamer.xyz/source/Sintel.mp4"
    }
  ]
}
```

--------------------------------

### POST /sessions

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Create a new streaming session with ad insertion. This endpoint supports manual interstitial scheduling, VMAP ad scheduling, and live stream ad replacement.

```APIDOC
## POST /sessions

### Description
Creates a new streaming session. You can provide interstitial ad definitions, a VMAP URL, or VAST configuration for live streams.

### Method
POST

### Endpoint
https://stitcher.superstreamer.xyz/sessions

### Parameters
#### Request Body
- **uri** (string) - Required - The source video URI or HLS master playlist URL.
- **interstitials** (array) - Optional - List of ad breaks defined by time and duration.
- **vmap** (object) - Optional - VMAP configuration object containing a URL.
- **vast** (object) - Optional - VAST configuration for live stream signaling.

### Request Example
{
  "uri": "asset://4588d0f0-5054-41e6-ac05-010087eb60d8",
  "interstitials": [
    {
      "time": 10,
      "duration": 10,
      "vast": {
        "url": "https://pubads.g.doubleclick.net/gampad/ads?output=vast"
      }
    }
  ]
}

### Response
#### Success Response (200)
- **session_id** (string) - The unique identifier for the created session.
```

--------------------------------

### Manage Audio and Subtitle Tracks

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Demonstrates how to listen for track changes, retrieve available track lists, and switch between audio or subtitle tracks using the HlsPlayer API.

```typescript
import { HlsPlayer, Events } from "@superstreamer/player";

const player = new HlsPlayer(container);

player.on(Events.AUDIO_TRACKS_CHANGE, () => {
  const audioTracks = player.audioTracks;
  console.log("Audio tracks:", audioTracks.map(t => t.label));
});

player.on(Events.SUBTITLE_TRACKS_CHANGE, () => {
  const subtitleTracks = player.subtitleTracks;
  console.log("Subtitle tracks:", subtitleTracks.map(t => t.label));
});

player.setAudioTrack(1);
player.setSubtitleTrack(0);
player.setSubtitleTrack(null);

player.load("https://stitcher.superstreamer.xyz/sessions/session-id/master.m3u8");
```

--------------------------------

### Create Session Request Body (JSON)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-create-a-session.md

Demonstrates the JSON payload for creating a session. It shows how to specify the content source using 'asset://' for internal assets or 'https://' for external HLS playlists.

```json
{
  "uri": "asset://2d6e6c0e-07d9-48b1-8192-318f32a3b909"
}
```

```json
{
  "uri": "2d6e6c0e-07d9-48b1-8192-318f32a3b909"
}
```

```json
{
  "uri": "https://stream.mux.video/1b0cd077-965e-4693-b102-37cd6bc32c17/master.m3u8"
}
```

--------------------------------

### Configure Ad Stitching Sessions

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Create ad-stitched video sessions using REST API calls. Supports manual interstitial insertion, VMAP scheduling, and live stream ad replacement via in-stream signaling.

```bash
curl -X POST "https://stitcher.superstreamer.xyz/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "asset://4588d0f0-5054-41e6-ac05-010087eb60d8",
    "interstitials": [
      {
        "time": 10,
        "duration": 10,
        "vast": {
          "url": "https://pubads.g.doubleclick.net/gampad/ads?output=vast"
        }
      }
    ]
  }'
```

```bash
curl -X POST "https://stitcher.superstreamer.xyz/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689",
    "vmap": {
      "url": "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpremidpost&ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&impl=s&cmsid=496&vid=short_onecue&correlator="
    }
  }'
```

```bash
curl -X POST "https://stitcher.superstreamer.xyz/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "https://example.com/live-stream/master.m3u8",
    "vast": {
      "url": "https://pubads.g.doubleclick.net/gampad/ads?output=vast&duration={duration}"
    }
  }'
```

--------------------------------

### Configure Artisan Environment Variables (.env)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/getting-started.md

Sets up environment variables for the artisan service, mirroring the configuration required by the API service, particularly for Redis and S3 connections.

```sh
REDIS_URI=redis://localhost:6379
S3_ENDPOINT=
S3_REGION=
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_BUCKET=
```

--------------------------------

### Insert HLS Interstitials

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Inject bumpers or custom content into HLS streams at specific playback timestamps.

```bash
curl -X POST "https://stitcher.superstreamer.xyz/sessions" -H "Content-Type: application/json" -d '{"uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689", "interstitials": [{"time": 0, "assets": [{"uri": "asset://abbda878-8e08-40f6-ac8b-3507f263450a"}]}]}'
```

--------------------------------

### Configure Linear Ad Replacement

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-ad-insertion.md

This request demonstrates how to replace a specific segment of a video stream with personalized ads by specifying a time and duration.

```json
{
  "uri": "asset://4588d0f0-5054-41e6-ac05-010087eb60d8",
  "interstitials": [
    {
      "time": 10,
      "duration": 10,
      "vast": {
        "url": "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator="
      }
    }
  ]
}
```

--------------------------------

### Configure Environment Variables

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Essential environment variables for S3 storage integration and application security secrets.

```bash
S3_ENDPOINT=
S3_REGION=us-east-1
S3_ACCESS_KEY=
S3_SECRET_KEY=
S3_BUCKET=superstreamer
PUBLIC_S3_ENDPOINT=https://s3.us-east-1.amazonaws.com/superstreamer
SUPER_SECRET=somethingsupersecret
```

--------------------------------

### Insert VAST Ads

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Integrate VAST-compliant ad servers to insert preroll or mid-roll advertisements into playback sessions.

```bash
curl -X POST "https://stitcher.superstreamer.xyz/sessions" -H "Content-Type: application/json" -d '{"uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689", "interstitials": [{"time": 0, "vast": {"url": "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&output=vast"}}]}'
```

--------------------------------

### POST /stitcher/signaling

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-ad-insertion.md

Configures automated ad insertion based on HLS in-stream signaling tags (EXT-X-CUE-OUT/IN).

```APIDOC
## POST /stitcher/signaling

### Description
Automatically detects cue tags in a live stream and replaces them with ads from a VAST server, supporting dynamic duration parameters.

### Method
POST

### Request Body
- **uri** (string) - Required - The URL of the live HLS stream.
- **vast** (object) - Required - Configuration for the VAST ad server, supporting {duration} placeholder.

### Request Example
{
  "uri": "https://example.com/live-stream/ca66c6d4-65fc-46e3-8a9c-60901f5b485e/master.m3u8",
  "vast": {
    "url": "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&duration={duration}"
  }
}
```

--------------------------------

### Configure VMAP Ad Insertion

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-ad-insertion.md

This JSON request demonstrates how to instruct the stitcher to process a VMAP URL to insert multiple ad breaks into a video asset.

```json
{
  "uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689",
  "vmap": {
    "url": "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpremidpost&ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&impl=s&cmsid=496&vid=short_onecue&correlator="
  }
}
```

--------------------------------

### HlsPlayer Event Handling

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/reference/player.md

Illustrates how to attach event listeners to the HlsPlayer for various playback events, such as when the player is ready, seeking, or when media tracks change.

```typescript
player.on('ready', () => console.log('Player is ready'));
player.on('timeChange', (time) => console.log('Current time:', time));
```

--------------------------------

### HlsPlayer Constructor

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/reference/player.md

Initializes a new HlsPlayer instance. It requires an HTMLDivElement as a container to render the player.

```typescript
new HlsPlayer(container: HTMLDivElement): HlsPlayer
```

--------------------------------

### Submit Transcoding Job with Audio Inputs

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/media-audio.md

Demonstrates how to submit a POST request to the Superstreamer API to define multiple audio tracks, including language codes and explicit channel counts for 5.1 surround sound.

```shell
curl -X POST "https://api.superstreamer.xyz/jobs/transcode"
```

```json
{
  "inputs": [
    {
      "type": "audio",
      "path": "s3://source/video.mp4",
      "language": "eng"
    },
    {
      "type": "audio",
      "path": "s3://source/video/dutch.mp3",
      "language": "nld"
    },
    {
      "type": "audio",
      "path": "s3://source/video/dutch_5.1.mp3",
      "language": "nld",
      "channels": 6
    }
  ],
  "streams": [
    {
      "type": "audio",
      "language": "eng"
    },
    {
      "type": "audio",
      "language": "nld"
    }
  ]
}
```

--------------------------------

### Deploy Superstreamer with Docker Compose

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

This configuration defines the core services including API, Artisan, Stitcher, and the required Redis and PostgreSQL infrastructure. It enables a full-stack deployment using Docker Compose.

```yaml
version: "3"

volumes:
  superstreamer_redis_data:
  superstreamer_postgres_data:

services:
  superstreamer-api:
    image: "superstreamerapp/api:latest"
    restart: always
    ports:
      - 52001:3000
    depends_on:
      - superstreamer-postgres
      - superstreamer-redis
    env_file: .env
    environment:
      - REDIS_URI=redis://superstreamer-redis:6379
      - DATABASE_URI=postgresql://postgres:sprs@superstreamer-postgres/sprs

  superstreamer-app:
    image: "superstreamerapp/app:latest"
    ports:
      - 52000:3000
    environment:
      - PUBLIC_API_ENDPOINT=http://localhost:52001
      - PUBLIC_STITCHER_ENDPOINT=http://localhost:52002

  superstreamer-artisan:
    image: "superstreamerapp/artisan:latest"
    restart: always
    depends_on:
      - superstreamer-redis
    env_file: .env
    environment:
      - REDIS_URI=redis://superstreamer-redis:6379

  superstreamer-stitcher:
    image: "superstreamerapp/stitcher:latest"
    restart: always
    ports:
      - 52002:3000
    depends_on:
      - superstreamer-redis
    env_file: .env
    environment:
      - REDIS_URI=redis://superstreamer-redis:6379
      - PUBLIC_API_ENDPOINT=http://localhost:52001
      - PUBLIC_STITCHER_ENDPOINT=http://localhost:52002

  superstreamer-redis:
    image: redis/redis-stack-server:7.2.0-v6
    ports:
      - 127.0.0.1:6379:6379
    volumes:
      - superstreamer_redis_data:/data

  superstreamer-postgres:
    image: "postgres:latest"
    restart: always
    ports:
      - "5432:5432"
    volumes:
      - superstreamer_postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_INITDB_ARGS=--data-checksums
      - POSTGRES_DB=sprs
      - POSTGRES_PASSWORD=sprs
```

--------------------------------

### Manage Video Quality

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Monitor available quality levels and toggle between manual selection or automatic adaptive switching.

```typescript
import { HlsPlayer, Events } from "@superstreamer/player";
const player = new HlsPlayer(container);
player.on(Events.QUALITIES_CHANGE, () => {
  console.log("Available qualities:", player.qualities);
});
player.setQuality(720);
player.setQuality(null);
```

--------------------------------

### POST /token

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Authenticates a user and returns a JWT token for subsequent API requests.

```APIDOC
## POST /token

### Description
Authenticates the user using credentials and returns a JSON Web Token (JWT) required for protected endpoints.

### Method
POST

### Endpoint
/token

### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
{
  "username": "admin",
  "password": "admin"
}

### Response
#### Success Response (200)
- **token** (string) - The JWT access token.

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

--------------------------------

### Define Import Map Dependencies

Source: https://github.com/superstreamerapp/superstreamer/blob/main/fixtures/media-chrome/index.html

Configures the browser import map to resolve module specifiers for the SuperStreamer player and its underlying media dependencies.

```json
{
  "imports": {
    "super-media-element": "https://cdn.jsdelivr.net/npm/super-media-element@1.3/+esm",
    "media-tracks": "https://cdn.jsdelivr.net/npm/media-tracks@0.2/+esm",
    "@superstreamer/player": "/packages/player/dist/index.js",
    "hls.js": "https://cdn.jsdelivr.net/npm/hls.js@1.6.0-beta.1/dist/hls.mjs"
  }
}
```

--------------------------------

### Configure HLS Interstitial Request (JSON)

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/stitcher-hls-interstitials.md

This JSON object defines the configuration for HLS interstitials. It specifies the primary content URI and an array of interstitial objects, each with a time offset and an array of asset URIs to be played at that time. This allows for dynamic insertion of ads or bumpers into the video stream.

```json
{
  "uri": "asset://f7e89553-0d3b-4982-ba7b-3ce5499ac689",
  "interstitials": [
    {
      "time": 10,
      "assets": [
        {
          "uri": "asset://abbda878-8e08-40f6-ac8b-3507f263450a"
        }
      ]
    }
  ]
}
```

--------------------------------

### Execute Automated Transcode and Package Pipeline

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/media-transcode-package.md

Runs a combined pipeline job that automates both transcoding and packaging in a single request. This is ideal for standard workflows that do not require custom profile configurations.

```sh
curl -X POST "https://api.superstreamer.xyz/jobs/pipeline"
```

```json
{
  "inputs": [
    {
      "type": "video",
      "path": "s3://input.mp4"
    },
    {
      "type": "audio",
      "path": "s3://input.mp4",
      "language": "eng"
    }
  ],
  "streams": [
    {
      "type": "video",
      "codec": "h264",
      "height": 1080
    },
    {
      "type": "video",
      "codec": "h264",
      "height": 720
    },
    {
      "type": "audio",
      "codec": "aac",
      "language": "eng"
    }
  ]
}
```

--------------------------------

### Package Job API

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Package transcoded streams into an HLS playlist for adaptive bitrate streaming.

```APIDOC
## POST /jobs/package

### Description
Packages transcoded streams into an HLS playlist for adaptive bitrate streaming.

### Method
POST

### Endpoint
/jobs/package

### Parameters
#### Request Body
- **assetId** (string) - Required - The ID of the asset to package.
- **segmentSize** (integer) - Required - The size of segments for the HLS playlist.
- **name** (string) - Required - The name for the HLS playlist (e.g., "hls").
- **language** (string) - Required - The primary language for the HLS playlist.
- **concurrency** (integer) - Optional - The number of concurrent encoding tasks.
- **public** (boolean) - Optional - Whether the HLS playlist should be publicly accessible.

### Request Example
```json
{
  "assetId": "46169885-f274-43ad-ba59-a746d33304fd",
  "segmentSize": 4,
  "name": "hls",
  "language": "eng",
  "concurrency": 2,
  "public": true
}
```

### Response
#### Success Response (200)
- **jobId** (string) - The unique identifier for the created package job.

#### Response Example
```json
{
  "jobId": "package_46169885-f274-43ad-ba59-a746d33304fd"
}
```

### Resulting HLS playlist URL
`https://cdn.superstreamer.xyz/package/{assetId}/{name}/master.m3u8`
```

--------------------------------

### Handle Interstitial Timelines

Source: https://context7.com/superstreamerapp/superstreamer/llms.txt

Explains how to monitor the player timeline for interstitial markers such as ads or bumpers and check the current interstitial state.

```typescript
import { HlsPlayer, Events } from "@superstreamer/player";

const player = new HlsPlayer(container);

player.on(Events.TIMELINE_CHANGE, () => {
  const timeline = player.timeline;
  console.log("Interstitials:", timeline);
});

const currentInterstitial = player.interstitial;
if (currentInterstitial) {
  console.log("Currently playing interstitial");
}

player.load("https://stitcher.superstreamer.xyz/sessions/session-id/master.m3u8");
```

--------------------------------

### Transcode Video Assets via API

Source: https://github.com/superstreamerapp/superstreamer/blob/main/docs/guide/media-transcode-package.md

Initiates a transcoding job by sending a POST request with input source paths and desired output stream configurations. The API returns a unique jobId used to track the status of the processing task.

```sh
curl -X POST "https://api.superstreamer.xyz/jobs/transcode"
```

```json
{
  "inputs": [
    {
      "type": "video",
      "path": "https://cdn.superstreamer.xyz/source/video.mp4"
    },
    {
      "type": "audio",
      "path": "https://cdn.superstreamer.xyz/source/video.mp4",
      "language": "eng"
    }
  ],
  "streams": [
    {
      "type": "video",
      "codec": "h264",
      "height": 1080
    },
    {
      "type": "video",
      "codec": "h264",
      "height": 720
    },
    {
      "type": "audio",
      "codec": "aac",
      "language": "eng"
    }
  ]
}
```

```json
{
  "jobId": "transcode_46169885-f274-43ad-ba59-a746d33304fd"
}
```