[Документация Yandex Cloud](../../../index.md) > [Yandex Cloud Video](../../index.md) > Видеоплеер > [SDK](../index.md) > [JavaScript](index.md) > Состояние плеера

# Состояние плеера

Вы можете получать информацию о состоянии видеоплеера и его [параметрах](#player-params) через [объект состояния](#player-state), содержащий поля со значениями состояний.

## Параметры видеоплеера {#player-params}

#### Типы видео в плеере {#video-type-desc}

[Видеоплеер](../../concepts/player.md) поддерживает воспроизведение трех _типов видео_:

* `VOD` — обычное [видео](../../concepts/videos.md), у которого зафиксировано и начало, и конец, а длительность является постоянной величиной.

    Например: фильм.
* `EVENT` — [трансляция](../../concepts/streams.md), у которой зафиксировано только начало, длительность непрерывно увеличивается, а правая граница шкалы времени отодвигается. 

    Пользователь может перемотать видео в любую точку шкалы времени: от начала видео до текущей крайней точки правой границы шкалы. Когда пользователь смотрит видео и находится на правой границе, принято говорить, что «пользователь находится в онлайне». В какой-то момент времени правая граница может остановиться, тогда видео превратится в `VOD`.

    Например: трансляция футбольного матча.
* `LIVE` — трансляция, у которой и правая, и левая граница шкалы времени непрерывно изменяются с течением времени.

    Пользователю для перемотки доступно только «окно» между текущей левой и правой границей шкалы времени. Когда пользователь смотрит видео и находится на правой границе, как и в случае с типом `EVENT`, принято говорить, что «пользователь находится в онлайне».

    Например: трансляция телеканала.

Тип видео находится в поле [videoType](#state-videoType) объекта [состояния плеера](#player-state).

#### Текущее время {#current-time-desc}

_Текущее время_ определяет текущую позицию на шкале времени. Текущее время можно получить с помощью поля [currentTime](#state-currentTime) объекта [состояния плеера](#player-state).

В качестве единицы измерения используются секунды.

Для типа видео `LIVE` используется формат [Unix Timestamp](https://ru.wikipedia.org/wiki/Unix-время), а для `VOD` и `EVENT` — секунды относительно начала видео, принимаемого за время `0`.

> Пример 1: для типов `VOD` и `EVENT` в поле `currentTime` может находиться значение `10`. Это означает, что текущая позиция на шкале времени находится в 10 секундах от начала видео.

> Пример 2: для типа `LIVE` в поле `currentTime` может находиться значение `1600000000`. Это означает, что текущая позиция на шкале времени соответствует абсолютному времени `new Date(1600000000 * 1000)`, то есть `Sep 13 2020 14:26:40 GMT+0200`.

#### Длительность {#duration-desc}

_Длительность_ определяет разность между текущей правой и левой границами шкалы времени. Длительность видео можно получить с помощью поля [duration](#state-duration) объекта [состояния плеера](#player-state).

В качестве единицы измерения используются секунды.

Для типа видео `LIVE` длительность всегда равна `Infinity`.

#### UTC-время начала видео {#utc-start-time-desc}

_UTC-время начала видео_ определяет время начала трансляции в формате [UTC](https://ru.wikipedia.org/wiki/Всемирное_координированное_время). Значение можно получить с помощью поля [utcStartTime](#state-utcStartTime) объекта [состояния плеера](#player-state).

В качестве единицы измерения используются секунды.

Для типа видео `LIVE` — значение всегда `0`.

Для типа видео `EVENT` — это всегда ненулевое значение формата `Unix Timestamp`.

> Пример: в поле `utcStartTime` может находиться значение `1600000000`. Это означает, что видео началось в момент `new Date(1600000000 * 1000)`, то есть `Sep 13 2020 14:26:40 GMT+0200`.

Для типа видео `VOD` — это опциональное значение. Например, значение может быть задано в случае, если `VOD` был получен из `EVENT`. Незаданное значение равно `undefined`. Если значение задано, то оно задано в формате `utcStartTime` (так же, как для типа `EVENT`).

#### Область перемотки {#seekable-range-desc}

_Область перемотки_ определяет область на шкале времени, в которую пользователь может переместить текущую позицию времени. Значение можно получить с помощью поля [seekableRange](#state-seekableRange) объекта [состояния плеера](#player-state).

Формат:

```javascript
{
    /** @type {number} левая граница области в секундах */
    start,
    /** @type {number} правая граница области в секундах */
    end,
}
```

У типов видео `VOD` и `EVENT` значение поля `start` всегда равно `0`. Значение поля `end` — это правая граница шкалы времени. Причем для типа `EVENT` значение поля `end` непрерывно увеличивается.

У типа видео `LIVE` значения полей `start` и `end` задаются в формате `Unix Timestamp`. Значение поля `end` непрерывно увеличивается.

> Пример: если у трансляции типа `LIVE` в текущий момент времени в поле `seekableRange` находится объект с полями `start === 1600000000` и `end === 1600001000`, значит, область перемотки для пользователя будет иметь границы `1600000000` и `1600001000`.

#### Статус воспроизведения {#status-desc}

Значение _статуса воспроизведения_ можно получить с помощью поля [status](#state-status) объекта [состояния плеера](#player-state).

Статус воспроизведения может принимать одно из значений:

* `idle` — плеер ожидает задания контента для воспроизведения.
* `init` — инициализация плеера при задании первого контента для воспроизведения.
* `buffering` — в текущий момент плеер находится в состоянии буферизации и не может воспроизводить видео (например, из-за нехватки данных).
* `play` — в текущий момент плеер воспроизводит видео.
* `pause` — плеер находится на паузе.
* `end` — воспроизведение текущего видео завершилось на правой границе шкалы времени. 
* `fatal` — воспроизведение текущего видео невозможно, у пользователя отображается экран с ошибкой. Чтобы запустить видео, пользователь может попробовать переключиться на другой контент.
* `broken` — плеер сломан, воспроизведение видео невозможно, у пользователя отображается экран с ошибкой. Переключение на другой контент невозможно.
* `destroyed` — был вызван метод `destroy`, плеер уничтожен (destroyed) и не может больше воспроизводить видео.
* `cancelled` — трансляция видео была отменена.
* `preparing` — через некоторое время должна начаться трансляция видео.
* `finished` — трансляция видео завершена.

## Объект, содержащий параметры состояния плеера {#player-state}

Состояние плеера представляет собой объект, содержащий поля:

* [source](#state-source);
* [status](#state-status);
* [error](#state-error);
* [currentTime](#state-currentTime);
* [duration](#state-duration);
* [videoType](#state-videoType);
* [muted](#state-muted);
* [volume](#state-volume);
* [playbackSpeed](#state-playbackSpeed);
* [utcStartTime](#state-utcStartTime);
* [seekableRange](#state-seekableRange);
* [bufferedRanges](#state-bufferedRanges);
* [isFullscreen](#state-isFullscreen);
* [textTracks](#state-textTracks);
* [textTrack](#state-textTrack);
* [videoTracks](#state-videoTracks);
* [videoTrack](#state-videoTrack).

#### source {#state-source}

Ссылка на текущий контент. Если контент не задан, то значение поля `source` — `undefined`.

#### status {#state-status}

[Статус воспроизведения](#status-desc).

Может принимать значения:

* `'idle'`
* `'init'`
* `'buffering'`
* `'play'`
* `'pause'`
* `'end'`
* `'fatal'`
* `'broken'`
* `'destroyed'`
* `'cancelled'`
* `'preparing'`
* `'finished'`

Значение по умолчанию — `'idle'`.

#### error {#state-error}

Ошибка, которая возникла в плеере.

Если в текущий момент ошибки нет, принимает значение `undefined`. Если ошибка есть, значением является объект формата:

```javascript
{
    /** @type {string} код ошибки */
    code,
    /** @type {string} сообщение ошибки */
    message,
}
```

Если поле содержит объект с ошибкой, значит, плеер в текущий момент не может начать или продолжить воспроизведение видео. Значение поля [status](#state-status) при этом будет равно либо `'fatal'`, либо `'broken'`.

Значение по умолчанию — `undefined`.

#### currentTime {#state-currentTime}

[Текущее время](#current-time-desc) (позиция на шкале времени) в секундах.

Значение по умолчанию — `NaN`.

#### duration {#state-duration}

[Длительность](#duration-desc) видео в секундах.

Значение по умолчанию — `NaN`.

#### videoType {#state-videoType}

[Тип видео](#video-type-desc).

Может принимать значения:

* `undefined`
* `'VOD'`
* `'EVENT'`
* `'LIVE'`

Значение по умолчанию — `undefined`.

#### muted {#state-muted}

Статус `muted` (выключенного звука) видео. Значение `true` — звук выключен, значение `false` — включен.

Значение по умолчанию — [значение](initialization.md#muted), которое было передано в конфигурации при инициализации плеера. Если при инициализации значение не было передано, значение по умолчанию — `true`.

#### volume {#state-volume}

Уровень громкости звука видео в диапазоне от `0` (звук не слышен) до `1` (максимальная громкость).

Значение по умолчанию — [значение](initialization.md#volume), которое было передано в конфигурации при инициализации плеера. Если при инициализации значение не было передано, значение по умолчанию — `1`.

#### playbackSpeed {#state-playbackSpeed}

Скорость воспроизведения видео.

Значение скорости — число, например:
* `1` — нормальная скорость;
* `0.5` — половинная скорость;
* `2` — двойная скорость.

Значение по умолчанию — `1`.

#### utcStartTime {#state-utcStartTime}

[UTC-время начала видео](#utc-start-time-desc) в секундах, либо `undefined`.

Значение по умолчанию — `undefined`.

#### seekableRange {#state-seekableRange}

[Область перемотки](#seekable-range-desc).

Значение по умолчанию — `{ start: NaN, end: NaN }`.

#### bufferedRanges {#state-bufferedRanges}

Области буферизации. Массив объектов формата:

```javascript
{
    /** @type {number} начало буфера в секундах */
    start,
    /** @type {number} конец буфера в секундах */
    end,
}
```

Объекты массива определяют области шкалы времени, для которых в буфере имеются данные для воспроизведения.

Значение по умолчанию — пустой массив `[]`.

#### isFullscreen {#state-isFullscreen}

Статус полноразмерного режима. Значение `true` — полноразмерный режим включен, значение `false` — выключен.

Значение по умолчанию — `false`.

#### textTracks {#state-textTracks}

Массив доступных текстовых дорожек (субтитров). Каждый элемент — объект формата:

```javascript
{
    /** @type {string} название дорожки, отображается в интерфейсе */
    name,
    /** @type {string} id дорожки, используется для смены через setTextTrack */
    value,
    /** @type {string} язык дорожки в формате ISO 639-1 (например, "ru", "en") */
    lang,
}
```

Значение по умолчанию — пустой массив `[]`.

#### textTrack {#state-textTrack}

Текущая текстовая дорожка (субтитры). `null` — если субтитры отключены.

Формат объекта аналогичен элементам массива [textTracks](#state-textTracks).

Значение по умолчанию — `null`.

#### videoTracks {#state-videoTracks}

Массив доступных видеодорожек. Каждый элемент — объект формата:

```javascript
{
    /** @type {string} название дорожки, отображается в интерфейсе */
    name,
    /** @type {string} id дорожки, используется для смены через setVideoTrack */
    value,
    /** @type {number} битрейт видео в Kbps */
    bitrate,
    /** @type {number} [width] ширина видео */
    width,
    /** @type {number} [height] высота видео */
    height,
    /** @type {boolean} [auto] true — качество выбрано плеером автоматически, false — вручную или через API */
    auto,
    /** @type {number} [frameRate] количество кадров в секунду */
    frameRate,
    /** @type {string} [codecs] кодек */
    codecs,
}
```

Значение по умолчанию — пустой массив `[]`.

#### videoTrack {#state-videoTrack}

Текущая видеодорожка. `null` — если плеер еще не выбрал дорожку (например, до готовности).

В режиме автоматического выбора возвращается объект дорожки с полем `auto: true`.

Формат объекта аналогичен элементам массива [videoTracks](#state-videoTracks).

Значение по умолчанию — `null`.

#### Полезные ссылки {#see-also}

[Interface: PlayerSdkState](../../api-ref/javascript/interfaces/PlayerSdkState.md) — описание параметров состояния плеера в справочнике API