---
sidebar_position: 0
---

# stream

The `sos.stream` API groups together methods for streaming videos from different sources. There are various methods for preparing, playing, stopping, pausing, and resuming streams.

Streams are identified by their URI and their position on the screen (x, y, width, height).

This API allows you to play video stream from:
- URL (e.g., HTTP, RTSP, RTP, UDP, RTMP)
- HDMI (e.g., Picture-in-Picture, Internal ports) streams

:::warning
Are you using **Samsung Tizen** to play streams? Read more about limitation and
[Tizen-specific details](https://docs.signageos.io/hc/en-us/articles/4405387373458).
:::

:::danger
Be aware version of JS API (v6.0.0+) changed how stream functions `play()` and `prepare()` work. For using an options object you need to
our latest core app versions. If you are using older core app versions, you need to use deprecated format.
:::

## Methods

### getTracks()

The `getTracks()` method returns a list of subtitles, video, and audio tracks of a stream.

```ts expandable
getTracks(videoId: IVideoProperties): Promise<ITrackInfo[]>;
// show-more
type ITrackInfo = ITrackVideoInfo | ITrackAudioInfo | ITrackTextInfo;

interface ITrackVideoInfo extends ITrack<'VIDEO'> {
    videoSize: {
        width: number;
        height: number;
    };
}

interface ITrack<T extends TrackType> {
    trackType: T;
    mimeType: string;
    groupId: string;
    trackIndex: number;
    selected: boolean;
    language: string | null;
    supported: boolean;
}

type TrackType = 'TEXT' | 'AUDIO' | 'VIDEO';

interface ITrackAudioInfo extends ITrack<'AUDIO'> {
    channelCount: number;
}

interface ITrackTextInfo extends ITrack<'TEXT'> {
    selection: string[];
}

interface IVideoProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
}

```

#### Params

| Name      | Type               | Required         | Description                                           |
|-----------|--------------------|------------------|-------------------------------------------------------|
| `videoId` | `IVideoProperties` |  <div>Yes</div>  | The video properties of the stream to get tracks for. |

#### Return value

Returns array of object with information about subtitles, video, and audio tracks.

#### Example

```ts
// Example of getting tracks for a stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
const tracks = await sos.stream.getTracks(streamId);
console.log(tracks); // Outputs an array of track information
```

<Separator />

### onConnected()

The `onConnected()` method sets up a listener, which is called whenever a stream is connected.

```ts expandable
onConnected(listener: (event: IStreamEvent<'connected'>) => void): void;
// show-more
interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                         | Required         | Description                                               |
|------------|----------------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamEvent<"connected">) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener for the connected event
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onConnected((event) => {
  console.log('Stream connected:', event.srcArguments.uri);
});
```

<Separator />

### onDisconnected()

The `onDisconnected()` method sets up a listener, which is called whenever a stream gets disconnected.
Usually when source URI is not available anymore or when the stream is stopped.

```ts expandable
onDisconnected(listener: (event: IStreamEvent<'disconnected'>) => void): void;
// show-more
interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                            | Required         | Description                                               |
|------------|-------------------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamEvent<"disconnected">) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener for the disconnected event
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onDisconnected((event) => {
    console.log('Stream disconnected:', event.srcArguments.uri);
});
```

<Separator />

### onError()

The `onError()` method sets up a listener, which is called whenever an unexpected error occurs during a stream.

```ts expandable
onError(listener: (event: IStreamErrorEvent) => void): void;
// show-more
interface IStreamErrorEvent extends IStreamEvent<'error'> {
    errorMessage?: string | undefined;
}

interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                 | Required         | Description                                               |
|------------|--------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamErrorEvent) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener for the error event
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onError((event) => {
    console.error('Stream error:', event.errorMessage);
});
```

<Separator />

### onPause()

The `onPause()` method sets up a listener, which is called whenever a stream is paused.

```ts expandable
onPause(listener: (event: IStreamEvent<'pause'>) => void): void;
// show-more
interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                     | Required         | Description                                               |
|------------|------------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamEvent<"pause">) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener for the pause event
await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onPause((event) => {
    console.log('Stream paused:', event.srcArguments.uri);
});
```

<Separator />

### onPlay()

The `onPlay()` method sets up a listener, which is called whenever a stream starts playing.

```ts expandable
onPlay(listener: (event: IStreamEvent<'play'>) => void): void;
// show-more
interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                    | Required         | Description                                               |
|------------|-----------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamEvent<"play">) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener for the play event
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onPlay((event) => {
    console.log('Stream started playing:', event.srcArguments.uri);
});
```

<Separator />

### onPrepare()

The `onPrepare()` method sets up a listener, which is called whenever a stream gets prepared.

```ts expandable
onPrepare(listener: (event: IStreamEvent<'prepare'>) => void): void;
// show-more
interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                       | Required         | Description                                               |
|------------|--------------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamEvent<"prepare">) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener for the prepare event
await sos.stream.prepare('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onPrepare((event) => {
    console.log('Stream prepared:', event.srcArguments.uri);
});
```

<Separator />

### onResume()

The `onResume()` method sets up a listener, which is called whenever a stream is resumed.

```ts expandable
onResume(listener: (event: IStreamEvent<'resume'>) => void): void;
// show-more
interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                      | Required         | Description                                               |
|------------|-------------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamEvent<"resume">) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener for the resume event
await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause the stream
// ... after some time
await sos.stream.resume('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onResume((event) => {
    console.log('Stream resumed:', event.srcArguments.uri);
});
```

<Separator />

### onStop()

The `onStop()` method sets up a listener, which is called whenever a stream stops.

```ts expandable
onStop(listener: (event: IStreamEvent<'stop'>) => void): void;
// show-more
interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                    | Required         | Description                                               |
|------------|-----------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamEvent<"stop">) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener for the stop event
await sos.stream.stop('http://example.com/stream', 0, 0, 1920, 1080);
sos.stream.onStop((event) => {
    console.log('Stream stopped:', event.srcArguments.uri);
});
```

<Separator />

### onTracksChanged()

The `onTracksChanged()` method sets up a listener, which is called whenever a track is changed
from functions `selectTrack()` or `resetTrack()`.

```ts expandable
onTracksChanged(listener: (event: IStreamTracksChangedEvent) => void): void;
// show-more
interface IStreamTracksChangedEvent extends IStreamEvent<'tracks_changed'> {
    tracks: ITrackInfo[] | undefined;
}

type ITrackInfo = ITrackVideoInfo | ITrackAudioInfo | ITrackTextInfo;

interface ITrackVideoInfo extends ITrack<'VIDEO'> {
    videoSize: {
        width: number;
        height: number;
    };
}

interface ITrack<T extends TrackType> {
    trackType: T;
    mimeType: string;
    groupId: string;
    trackIndex: number;
    selected: boolean;
    language: string | null;
    supported: boolean;
}

type TrackType = 'TEXT' | 'AUDIO' | 'VIDEO';

interface ITrackAudioInfo extends ITrack<'AUDIO'> {
    channelCount: number;
}

interface ITrackTextInfo extends ITrack<'TEXT'> {
    selection: string[];
}

interface IStreamEvent<T extends StreamEventType> {
    type: T;
    srcArguments: IStreamEventProperties;
}

type StreamEventType = 'connected' | 'disconnected' | 'error' | 'stop' | 'play' | 'prepare' | 'pause' | 'resume' | 'tracks_changed';

interface IStreamEventProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
    protocol?: keyof typeof StreamProtocol | string;
    options?: IStreamOptions | IStreamPrepareOptions;
}

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

```

#### Params

| Name       | Type                                         | Required         | Description                                               |
|------------|----------------------------------------------|------------------|-----------------------------------------------------------|
| `listener` | `(event: IStreamTracksChangedEvent) => void` |  <div>Yes</div>  | The listener function to be called when the event occurs. |

#### Return value

Resolves when the listener is successfully set up.

#### Example

```ts
// Example of setting up a listener with starting a stream and selecting a track
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
await sos.stream.selectTrack(videoId, 'AUDIO', 'audioGroup1', 0);

// Create the listener for tracks changed event
sos.stream.onTracksChanged((event) => {
    console.log('Track type:', event.tracks[0].trackType); // AUDIO
    console.log('Track group ID:', event.tracks[0].groupId); // audioGroup1
    console.log('Track index:', event.tracks[0].trackIndex); // 0
});
```

<Separator />

### pause()

The `pause()` method pauses the active stream, it can be resumed with `resume()`.

```ts expandable
pause(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
```

#### Params

| Name     | Type     | Required         | Description                                    |
|----------|----------|------------------|------------------------------------------------|
| `uri`    | `string` |  <div>Yes</div>  | Network address where the stream is available. |
| `x`      | `number` |  <div>Yes</div>  | Stream x-position on the screen                |
| `y`      | `number` |  <div>Yes</div>  | Stream y-position on the screen                |
| `width`  | `number` |  <div>Yes</div>  | Stream width on the screen                     |
| `height` | `number` |  <div>Yes</div>  | Stream height on the screen                    |

#### Return value

Returns a promise that resolves when the stream is paused.

#### Possible errors

Error If parameters are invalid.

#### Example

```ts
// Example of pausing an active stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
// ... after some time
await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause
```

<Separator />

### play()

The `play()` method starts the video stream based by uri or stream which was prepared by `prepare()` method.

:::note Internal ports
This method use same functionality, instead of URL (for stream), specify a URI of the port to display.

| Port URI value | Description |
|-----------------|-------------|
| `internal://hdmi<number>` | HDMI |
| `internal://dp` | DisplayPort |
| `internal://dvi` | DVI |
| `internal://pc` | PC or VGA |

`<number>` has to be a value between 1 - 4, depending on which of the available HDMI ports you want to use.
:::

```ts expandable
play(uri: string, x: number, y: number, width: number, height: number, options?: IStreamOptions | keyof typeof StreamProtocol): Promise<void>;
// show-more
interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

```

#### Params

| Name      | Type                                                                      | Required         | Description                                    |
|-----------|---------------------------------------------------------------------------|------------------|------------------------------------------------|
| `uri`     | `string`                                                                  |  <div>Yes</div>  | Network address where the stream is available. |
| `x`       | `number`                                                                  |  <div>Yes</div>  | Stream x-position on the screen                |
| `y`       | `number`                                                                  |  <div>Yes</div>  | Stream y-position on the screen                |
| `width`   | `number`                                                                  |  <div>Yes</div>  | Stream width on the screen                     |
| `height`  | `number`                                                                  |  <div>Yes</div>  | Stream height on the screen                    |
| `options` | `IStreamOptions \| "HLS" \| "RTP" \| "HTTP" \| "UDP" \| "RTMP" \| "RTSP"` |  <div>No</div>   | Additional options for the stream              |

#### Return value

Returns a promise that resolves when the stream is successfully started.

#### Possible errors


- AppletStreamError If the protocol is not a string or if the parameters are invalid.
- Error If parameters are invalid.
- Error If the device fails to prepare the stream.

#### Example

```ts
// Example with specific protocol type
await sos.stream.play(uri, x, y, width, height, { protocol: 'HTTP' });

// Example with options - reconnect stream when it disconnects after 60 seconds
await sos.stream.play(uri, x, y, width, height, { protocol: 'HTTP', autoReconnect: true, autoReconnectInterval: 60000 });

// Example for playing HDMI port
await sos.stream.play('internal://hdmi1', 0, 0, 1920, 1080, { protocol: 'RTP' });
```

:::note[GitHub Example]

- [ How to create video Applet with for URL streams](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream)
- [ How to create video Applet with HDMI port](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream-hdmi-port)

:::

<Separator />

### prepare()

Calls the internal player and prepares a video stream in memory, so it can later start playing instantaneously.

:::info
If you want to play a video stream in full screen mode, use x = y = 0 and width = document.documentElement.clientWidth and height = document.documentElement.clientHeight as setup parameters.
:::

```ts expandable
prepare(uri: string, x: number, y: number, width: number, height: number, options?: IStreamPrepareOptions | keyof typeof StreamProtocol): Promise<void>;
// show-more
interface IStreamPrepareOptions extends IStreamOptions {
    trackSelection?: {
        maxAudioChannelCount?: number;
        minVideoSize?: {
            width: number;
            height: number;
        };
        maxVideoSize?: {
            width: number;
            height: number;
        };
        preferredAudioLanguages?: string[];
        preferredTextLanguages?: string[];
    };
    drm?: {
        scheme: DrmScheme;
        licenseUri: string;
        licenseRequestHeaders: {
            [key: string]: string;
        };
    };
}

type DrmScheme = 'CommonPSSH' | 'ClearKey' | 'Widevine' | 'PlayReady' | AnyString;

type AnyString = string & {};

interface IStreamOptions extends IOptions {
    protocol?: keyof typeof StreamProtocol | string;
    autoReconnect?: boolean;
    autoReconnectInterval?: number;
    lowLatency?: boolean;
}

interface IOptions {
    '4k'?: boolean;
    background?: boolean;
    volume?: number;
}

```

#### Params

| Name      | Type                                                                             | Required         | Description                                    |
|-----------|----------------------------------------------------------------------------------|------------------|------------------------------------------------|
| `uri`     | `string`                                                                         |  <div>Yes</div>  | Network address where the stream is available. |
| `x`       | `number`                                                                         |  <div>Yes</div>  | Stream x-position on the screen                |
| `y`       | `number`                                                                         |  <div>Yes</div>  | Stream y-position on the screen                |
| `width`   | `number`                                                                         |  <div>Yes</div>  | Stream width on the screen                     |
| `height`  | `number`                                                                         |  <div>Yes</div>  | Stream height on the screen                    |
| `options` | `IStreamPrepareOptions \| "HLS" \| "RTP" \| "HTTP" \| "UDP" \| "RTMP" \| "RTSP"` |  <div>No</div>   | Additional options for the stream              |

#### Return value

Returns a promise that resolves when the stream is prepared.

#### Possible errors


- AppletStreamError If the protocol is not a string or if the parameters are invalid.
- Error If parameters are invalid.
- Error If device fail to prepare the stream.

#### Example

```ts
// Example with specific protocol type
await sos.stream.prepare(uri, x, y, width, height, { protocol: 'HTTP' });

// Example with options - prepare stream in the background
await sos.stream.prepare(uri, x, y, width, height, { protocol: 'HTTP', background: true });

// Deprecated format
await sos.stream.prepare(uri, x, y, width, height, 'HTTP');
```

:::note[GitHub Example]

- [ How to create video Applet with for streams](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream)

:::

<Separator />

### removeEventListeners()

The `removeEventListeners()` removes all listeners set up on `sos.stream`.

```ts expandable
removeEventListeners(): void;
```

<Separator />

### resetTrack()

The `resetTrack()` method resets a selected track of a stream.

```ts expandable
resetTrack(videoId: IVideoProperties, trackType: TrackType, groupId?: string): Promise<void>;
// show-more
interface IVideoProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
}

type TrackType = 'TEXT' | 'AUDIO' | 'VIDEO';

```

#### Params

| Name        | Type               | Required         | Description                                                                                      |
|-------------|--------------------|------------------|--------------------------------------------------------------------------------------------------|
| `videoId`   | `IVideoProperties` |  <div>Yes</div>  | The video properties of the stream to reset track for.                                           |
| `trackType` | `TrackType`        |  <div>Yes</div>  | The type of the track to reset (e.g., 'TEXT', 'AUDIO', 'VIDEO').                                 |
| `groupId`   | `string`           |  <div>No</div>   | The group ID of the track to reset. If not provided, the first track in the group will be reset. |

#### Return value

Resolves when the track is successfully reset.

#### Possible errors

Error If parameters are invalid or if the track type is not supported.

#### Example

```ts
// Example of resetting a track for a stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);
// Reset the audio track in the group with ID 'audioGroup1'
await sos.stream.resetTrack(videoId, 'AUDIO', 'audioGroup1');
```

<Separator />

### resume()

The `resume()` method resumes the paused stream by `pause()` function.

```ts expandable
resume(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
```

#### Params

| Name     | Type     | Required         | Description                                    |
|----------|----------|------------------|------------------------------------------------|
| `uri`    | `string` |  <div>Yes</div>  | Network address where the stream is available. |
| `x`      | `number` |  <div>Yes</div>  | Stream x-position on the screen                |
| `y`      | `number` |  <div>Yes</div>  | Stream y-position on the screen                |
| `width`  | `number` |  <div>Yes</div>  | Stream width on the screen                     |
| `height` | `number` |  <div>Yes</div>  | Stream height on the screen                    |

#### Return value

Returns a promise that resolves when the stream is successfully resumed.

#### Possible errors

Error If parameters are invalid.

#### Example

```ts
// Example of resuming a paused stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
await sos.stream.pause('http://example.com/stream', 0, 0, 1920, 1080); // Pause
// ... after some time
await sos.stream.resume('http://example.com/stream', 0, 0, 1920, 1080); // Resume
```

<Separator />

### selectTrack()

The `selectTrack()` method selects a text (subtitles), video or audio track of a stream.

```ts expandable
selectTrack(videoId: IVideoProperties, trackType: TrackType, groupId: string, trackIndex: number): Promise<void>;
// show-more
interface IVideoProperties {
    uri: string;
    x: number;
    y: number;
    width: number;
    height: number;
}

type TrackType = 'TEXT' | 'AUDIO' | 'VIDEO';

```

#### Params

| Name         | Type               | Required         | Description                                                       |
|--------------|--------------------|------------------|-------------------------------------------------------------------|
| `videoId`    | `IVideoProperties` |  <div>Yes</div>  | The video properties of the stream to select track for.           |
| `trackType`  | `TrackType`        |  <div>Yes</div>  | The type of the track to select (e.g., 'TEXT', 'AUDIO', 'VIDEO'). |
| `groupId`    | `string`           |  <div>Yes</div>  | The group ID of the track to select.                              |
| `trackIndex` | `number`           |  <div>Yes</div>  | The index of the track to select within the group.                |

#### Return value

Resolves when the track is successfully selected.

#### Possible errors

Error If parameters are invalid or if the track type is not supported.

#### Example

```ts
// Example of selecting a track for a stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080);

// Select the first audio track in the group with ID 'audioGroup1'
await sos.stream.selectTrack(videoId, 'AUDIO', 'audioGroup1', 0);
// Select the first text track in the group with ID 'subtitlesGroup1'
await sos.stream.selectTrack(videoId, 'TEXT', 'subtitlesGroup1', 0);
// Select the first video track in the group with ID 'videoGroup1'
await sos.stream.selectTrack(videoId, 'VIDEO', 'videoGroup1', 0);
```

:::note[GitHub Example]

- [ How to set subtitles for a stream](https://github.com/signageos/applet-examples/tree/master/examples/content-js-api/stream-subtitles)

:::

<Separator />

### stop()

The `stop()` method stops the active stream, it can't be later resumed with `resume()`.

```ts expandable
stop(uri: string, x: number, y: number, width: number, height: number): Promise<void>;
```

#### Params

| Name     | Type     | Required         | Description                                    |
|----------|----------|------------------|------------------------------------------------|
| `uri`    | `string` |  <div>Yes</div>  | Network address where the stream is available. |
| `x`      | `number` |  <div>Yes</div>  | Stream x-position on the screen                |
| `y`      | `number` |  <div>Yes</div>  | Stream y-position on the screen                |
| `width`  | `number` |  <div>Yes</div>  | Stream width on the screen                     |
| `height` | `number` |  <div>Yes</div>  | Stream height on the screen                    |

#### Return value

Returns a promise that resolves when the stream is stopped.

#### Possible errors

Error If parameters are invalid.

#### Example

```ts
// Example of stopping an active stream
await sos.stream.play('http://example.com/stream', 0, 0, 1920, 1080); // Start
// ... after some time
await sos.stream.stop('http://example.com/stream', 0, 0, 1920, 1080); // Stop
```