Audio и Video

Объекты Audio и Video (Media объекты) представляет собой HTML элементы <audio> и <video>.

Информация об этих медиа объектах позаимствована с web-страницы https://andew.ru/

addTextTrack()

Метод addTextTrack() выполняет добавление в лист текстовых треков медиа элемента новой текстовой дорожки и возвращает созданный новый TextTrack объект

Синтаксис

myVideo.addTextTrack ( kind [, label [, language ] ] );

Параметры

kind

задает тип текстового трека и может принимать значения: "subtitles", "caption", "descriptions", "chapters", "metadata"

label

строка, которая задает название для новой текстовой дорожки в плеере.

language

строка из двух символьного кода языка, которая задает язык для новой текстовой дорожки.

Описание, комментарии

Свойства и методы объекта TextTrack:

//  метод getTrackById(), получить textTrack из медиа элемента через его свойство textTracks
textTrack = media.textTracks.getTrackById( id )

// свойство kind, только чтение, вернет строку: тип трека
textTrack.kind

// свойство label, только чтение, вернет строку: этикетка трека или пустую строку
textTrack.label

// свойство language, только чтение, вернет строку: код символа языка
textTrack.language

// свойство id, только чтение, вернет строку: ID трека
textTrack.id

// свойство inBandMetadataTrackDispatchType, только чтение, вернет строку: тип метаданных
textTrack.inBandMetadataTrackDispatchType

// свойство mode, получить или установить вид режима для трека, доступны:
//   "disabled", "hidden", "showing"
textTrack.mode [ = value ]

// свойство cues, только чтение, вернет TextTrackCueList объект
textTrack.cues

// свойство activeCues, только чтение, вернет TextTrackCueList объект
// с активными в данный момент cues
textTrack.activeCues

// метод addCue(), добавление временной метки в textTrack
textTrack.addCue( cue )

// метод removeCue(), удаление временной метки из textTrack
textTrack.removeCue( cue )

audioTracks

Свойство audioTracks возвращает объект AudioTrackList, который содержит доступные для медиа элемента audio треки - audio файлы.

Синтаксис

// объект AudioTrackList, только чтение

media.audioTracks

Возвращаемое значение

Объект AudioTrackList, который представляет доступные звуковые дорожки для аудио.

Свойства объекта AudioTrackList:

• length - получить количество доступных аудиодорожек
• getTrackById(id) - получить объект AudioTrack по идентификатору
• [index] - получить AudioTrack объекта по индексу. Первый доступный объект AudioTrack имеет индекс 0

Объект AudioTrack представляет собой звуковую дорожку.

Свойства объекта AudioTrack:

• id - получить идентификатор звуковой дорожки
• kind - получить тип звуковой дорожки (может быть: "alternative" , "description" , "main" , "translation" , "commentary" , или "" (пустая строка))
• label - получить ярлык звуковой дорожки
• language - получить код языка звуковой дорожки
• enabled - получить или установить активность трека (true|false)

Совместимость с браузерами

Этот функционал пока не реализован в большинстве браузеров, и поэтому на практике не используется.

На удивление, в IE11 свойства audioTracks и videoTracks работают

autoplay

Свойство autoplay медиа элементов video и audio устанавливает или возвращает значение true|false и управляет автоматическим стартом воспроизведения медиа файла после его загрузки.

Синтаксис

// boolean, чтение и изменение, default = false

media.autoplay [ = true|false ]

Описание, комментарии

Если свойство autoplay содержит значение true, то медиа файл аудио или video начнет воспроизводиться сразу после его загрузки. Если autoplay = false, то автоматический старт проигрывания медиа файла после его загрузки не будет выполняться. По умолчанию значение свойства autoplay для медиа элемента установлено как false. Свойство autoplay отражает значение одноименного атрибута autoplay HTML элементов <video> и <audio>. Свойство autoplay медиа элемента, если установлено в true, то переопределяет свойство preload, которое в этом случае игнорируется, так как медиа файл должен быть загружен и воспроизведен.

buffered

Свойство buffered медиа элемента audio и video возвращает объект TimeRanges, который представляет и содержит временные диапазоны (buffered time-range) медиа файла, которые уже были загружены браузером и помещены в буфер (кеш) браузера.

Синтаксис

// объект TimeRanges, только чтение

media.buffered

Комментарии

Пользователь, в пределах временных диапазонов, может свободно перемещать курсор воспроизведения и устанавливать его любое место, в пределах диапазонов, и воспроизводить медиа файл с выбранной позиции. Время начала и окончания для временных диапазонов задается как число секунд от начала audio или video файла.

Свойства и методы объекта TimeRanges применительно к свойству media.buffered:

// readonly, unsigned long

media.buffered.length;

Свойство length объекта TimeRanges, полученное из свойства media.buffered, вернет количество временных диапазонов (частей) audio или video файла, которые загружены браузером и помещены в его буфер (кеш);

Синтаксис

// double in seconds от начала файла
startTime = media.buffered.start(index);

// double in seconds от начала файла
endTime = media.buffered.end(index);

Методы start() и end() объекта TimeRanges вернут стартовую и конечную позицию в секундах для временного диапазона соответствующего индекса, как время от начала медиа файла на временной шкале плеера, или IndexSizeError в случае отсутствия такого индекса в объекте TimeRanges.

Замечание: Значения Index начинается с 0. Если указанный индекс будет отсутствовать в объекте TimeRanges, то возникнет ошибка IndexSizeError.

canPlayType()

Метод canPlayType() проверяет поддерживает ли браузер клиента переданный тип медиа файла (MIME type) или нет.

Синтаксис

Video.canPlayType ( mediaType );

Комментарии

Метод ожидает в качестве параметра строку как MIME тип медиа файла, который может опционально содержать и кодек медиа файла.

Возвращаемое значение

• "probably" - когда браузер, скорее всего, воспроизведет данный тип медиа файла. Такой ответ браузер сможет вернуть только если переданный ему тип медиа файла будет полный т.е. будет содержать опциональный параметр кодека.
        Пример: media.canPlayType('video/mp4; codecs="avc1.4D401E, mp4a.40.2"');
• "maybe" - когда браузер вероятно может воспроизводить данный тип медиа файла, но точно ответить не может т.к. переданный методу параметр MIME type не полный, например не содержит кодек;
• "" - пустая строка, когда браузер не поддерживает данный тип медиа файла.

Примеры параметров для метода canPlayType():

Для демонстрации работы метода с примерами параметров - «кликай» ссылки.

Параметр, как общий MIME тип файла, примеры:

• video/ogg
• video/mp4
• video/webm
• audio/mpeg
• audio/ogg
• audio/mp4

• video/ogg; codecs="theora, vorbis"
• video/mp4; codecs="avc1.4D401E, mp4a.40.2"
• video/webm; codecs="vp8.0, vorbis"
• audio/ogg; codecs="vorbis"
• audio/mp4; codecs="mp4a.40.5"

controller

Свойство controller определяет объект MediaController, представляющий текущий контроллер для данного аудио или video объекта.

Синтаксис

// MediaController object, чтение и изменение
media.controller [ = MediaController object ]

Описание, комментарии

Медиа контроллер (media controller) - это такой объект, который предоставляет необходимые методы, свойства и обработчики событий для управления на web странице медиа элементом audio и video, который он представляет. Иными словами, MediaController - это удобное, объектное представление медиа элемента audio и video в соответствии с концепцией объектно ориентированного программирования. Это значит, что единожды получив в JS переменную объект MediaController, все дальнейшие манипуляции с медиа элементом можно выполнять уже с полученным MediaController объектом, а не с JS объектом медиа элемента.

На практике, свойство media.controller медиа элемента audio и video не реализовано в браузерах.

MediaController object:

// создание нового медиа контроллера
controller = new MediaController();

// получение текущего медиа контроллера
media.controller [ = controller ];

// свойства объекта медиа контроллера
controller.readyState;
controller.buffered;
controller.seekable;
controller.duration;
controller.currentTime [ = value ];
controller.paused;
controller.playbackState;
controller.played;
controller.defaultPlaybackRate [ = value ];
controller.playbackRate [ = value ];
controller.volume [ = value ];
controller.muted [ = value ];

// методы объекта медиа контроллера
controller.pause();
controller.unpause();
controller.play();

// Проверка поддержки браузером свойства media.controller:
var myVideo = document.getElementById("video-example-1");

if (myVideo.controller == undefined || myVideo.controller == null) {
   alert("Свойство media.controller НЕ поддерживается браузером."); }

controls

Свойство controls медиа элемента audio и video управляет отображением панели управления в медиа плеере.

Синтаксис

// boolean, чтение и изменение, default = false
media.controls [ = true|false ]

Стандартная панель управления медиа плеера браузера, обычно, содержит такие элементы управления как:

• Play - воспроизведение;
• Pause - пауза;
• Seeking - ползунок прокрутки виде на шкале;
• Volume - громкость;
• Fullscreen - развернуть на полный экран;
• Captions/Subtitles - выбор файла заголовков/субтитров, если доступны;
• Track - выбор медиа файла, если доступно.

crossOrigin

Свойство crossOrigin возвращает или устанавливает строковое значение, которое указывает браузеру на необходимость выполнения CORS (Cross-origin resource sharing) запроса для данного элемента. Свойство crossOrigin отражает значение одноименного атрибута crossorigin HTML тега <audio> и <video>.

Синтаксис

// string, чтение и изменение, default = NULL

media.crossOrigin [ = "anonymous|use-credentials" ]

Описание, комментарии

По умолчанию атрибут crossorigin у HTML тегов аудио и video отсутствует и, соответственно, свойство crossOrigin возвращает значение NULL. Для свойства crossOrigin, также как и для его одноименного HTML атрибута crossorigin, возможны следующие значения: "anonymous" и "use-credentials". Установка свойства в одно из этих значений дает команду браузеру выполнять CORS запрос для данного медиа элемента.

currentSrc

Свойство currentSrc возвращает строку, содержащую текущий абсолютный URL пути к медиа файлу для медиа объекта, включая протокол (http:|https:) и домен.

Синтаксис

// string, только чтение

media.currentSrc

Описание, комментарии

Если медиа файл не задан для медиа элемента audio и video, то свойство возвращает пустую строку. Значение свойства currentSrc устанавливается в процессе работы алгоритма выбора ресурса для медиа-элемента, который запускается как часть алгоритма загрузки медиа элемента, что может происходить при смене значения свойства src или при вызове метода load() для объекта медиа элемента. Значение свойства currentSrc определяется из атрибута src HTML тегов <audio> и <video>, или из дочерних для них тегов <source>, находящихся внутри данного контейнера аудио или video. Нужно обратить внимание, что свойство currentSrc будет устанавливаться сначала из значения атрибута src HTML тега audio или video, иначе, если же этот атрибут отсутствует у этих тегов, то тогда значение будет устанавливаться из атрибута src HTML тегов <source>, вложенных в HTML тег audio и video. Иными словами, атрибут src HTML тега audio и video имеет приоритет перед атрибутами src вложенных HTML тегов source.

currentTime

Свойство currentTime устанавливает или возвращает текущую позицию времени воспроизведения медиа файла.

Синтаксис

// double, чтение и изменение, default = 0

media.currentTime [ = time in seconds ]

Описание, комментарии

Значение свойства имеет формат double и является числом с плавающей запятой, и представляет время в секундах, например: 60.125. Если выполнено изменение или установка свойства currentTime в заданное новое значение, то воспроизведение медиа фала будет перенесено к этой новой временной позиции. Если медиа файл в момент изменения свойства currentTime еще не загружен и не готов (readyState является HAVE_NOTHING = 0), то значение default playback start position (по умолчанию = 0) будет установлено в заданное значение, и когда файл загрузиться, его воспроизведение начнется уже не с начала, а уже с заданной временной позиции.

Можно создать временные закладки для медиа файла видео или аудио в виде ссылок и навесить на них JS изменение свойства currentTime, получив, таким образом, навигацию по медиа файлу.

defaultMuted

Свойство defaultMuted устанавливает или возвращает значения true или false и определяет состояние звука по умолчанию при загрузке web страницы и инициализации медиа элемента.

Синтаксис

// boolean, чтение, изменение, default = false

media.defaultMuted [ = true|false ]

Описание, комментарии

Значение true свойства defaultMuted определяет выключенное состояние звука по умолчанию для медиа элемента при его загрузке, а значение false - задает включенное состояние для звука. Свойство defaultMuted доступно как для чтения, так и для изменения, однако нужно помнить, что это свойство определяет только состояние звука по умолчанию для загружаемого медиа элемента и динамическое изменение значения этого свойства не имеет эффекта. Для изменения текущего состояния звука уже загруженного медиа элемента нужно использовать свойство muted медиа элемента, которое управляет именно текущим состоянием звука. Свойство defaultMuted отражает значение атрибута muted HTML элемента audio и video.

Значение по умолчанию для свойства defaultMuted задано как false, что означает включенное состояние звука для медиа элемента.

defaultPlaybackRate

Свойство defaultPlaybackRate устанавливает или возвращает скорость по умолчанию для воспроизведения медиа файла, которая будет использована браузером. Не путать со свойством playbackRate медиа элемента, которое определяет текущую скорость воспроизведения медиа файла.

Синтаксис

// double, чтение и изменение, default = 1.0

media.defaultPlaybackRate [ = скорость воспроизведения ]

Описание, комментарии

Свойства defaultPlaybackRate и playbackRate могут иметь отличные друг от друга значения, что позволяет понять прокручивает ли пользователь медиа файл, в какую сторону и с какой скоростью. Формат значения свойств defaultPlaybackRate и playbackRate - число с плавающей точкой, которое, по своей сути, является множителем для скорости воспроизведения медиа файла.

Значение по умолчанию для свойств defaultPlaybackRate и playbackRate установлено как 1.0, что соответствует нормальной скорости воспроизведения.

Примеры значений для свойств defaultPlaybackRate и playbackRate:

• 1.0 - нормальная скорость;
• 0.5 - замедленная, половина от нормальной;
• 2.0 - в два раза быстрее от нормальной;
• -1.0 - воспроизведение назад с нормальной скоростью;
• -0.5 - замедленное воспроизведение назад, половина от нормальной скорости.

duration

Свойство duration возвращает общую длительность медиа файла в секундах.

Синтаксис

// double, только чтение

media.duration

Описание, комментарии

Если медиа файл не доступен, то свойство duration возвращает NaN (Not-a-Number) значение. Если медиа файл не может быть ограничен по длительности (например, потоковое audio или video с не объявленным конечным временем), то свойство duration возвращает положительное значение бесконечности. Браузер устанавливает свойство duration прежде чем начать воспроизведение медиа файла или его части и прежде чем установить свойство readyState = 1 (HAVE_METADATA) или в большее значение, даже если это требует извлечения данных из нескольких частей медиа файла.

ended

Свойство ended возвращает true если в процессе проигрывания медиа файла в прямом направлении (воспроизведение вперед) курсор позиции воспроизведения достиг окончания медиа файла на временной шкале плеера, в противном случае свойство ended возвращает false.

Синтаксис

// boolean, только чтение

media.ended

Описание, комментарии

Свойство ended позволяет определить, достиг ли курсор позиции воспроизведения, в процессе проигрывании медиа файла вперед, конца временной шкалы плеера или нет. При этом медиа файл не обязательно мог быть воспроизведен полностью. Например, пользователь мог перемешать курсор воспроизведения по временной шкале и проиграть только конечную часть медиа файла. В любом случае, когда курсор позиции воспроизведения достигает, именно в процессе прямого проигрывания, конца audio или video файла на временной шкале плеера, браузер устанавливает свойство ended как true. Если, после этого, сдвинуть курсор воспроизведения в сторону начала файла на любое значение, то свойство ended будет переустановлено браузером в значение false. Если курсор позиции воспроизведения будет поставлен в конец временной шкалы плеера пользователем, но при этом не будет выполнено прямое воспроизведение файла, то свойство ended не измениться и будет как false.

error

Свойство error возвращает объект MediaError, содержащий статус последней возникшей ошибки для данного медиа элемента в процессе исполнения алгоритма выбора ресурса.

Синтаксис

// MediaError object, только чтение

media.error

Описание, комментарии

Если для медиа элемента не было ошибок, то свойство error вернет NULL.

// unsigned short, только чтение

MediaError.code;

Кодам ошибок соответствую именные константы, названия которых кратко описывают тип ошибки, который возник для медиа элемента:

• 1 = MEDIA_ERR_ABORTED - получение и загрузка медиа файла были прерваны пользователем, например, по нажатию СТОП кнопки в медиа плеере, что связано с событием abort для медиа элемента. Свойство networkState будет в этих случаях как NETWORK_EMPTY или как NETWORK_IDLE;
• 2 = MEDIA_ERR_NETWORK - ошибка при загрузке медиа файла, например, при обрыве сетевого соединения. Свойство networkState будет в этих случаях как NETWORK_EMPTY или как NETWORK_IDLE;
• 3 = MEDIA_ERR_DECODE - ошибка при декодировании медиа файла. В этом случае, если свойство readyState равно HAVE_NOTHING, то оно будет установлено networkState как NETWORK_EMPTY, и show poster flag будет установлено как true, и будет вызвано событие emptied для медиа элемента, networkState будет установлено в NETWORK_IDLE;
• 4 = MEDIA_ERR_SRC_NOT_SUPPORTED - данное audio/video не поддерживается, свойство networkState будет установлено как NETWORK_NO_SOURCE и show poster flag как true.

load()

Метод load() вызывает перезагрузку (обновление) медийного элемента audio или video на WEB странице.

Синтаксис

media.load();

Описание, комментарии

Метод используют, когда над медиа элементом выполнялись JS манипуляции по его HTML изменению, т.е. изменился HTML код элемента и вложенных в него элементов. Например, смена источника (URL) подключаемого медиа файла, что самое частое, или изменение и добавление других атрибутов медиа элемента или тегов внутри контейнера видео/аудио.

Метод не имеет входных параметров и возвращаемого значения, а просто выполняет обновление HTML медиа элемента на web странице. Вызов метода load() запускает алгоритм загрузки медиа элемента в ходе которого выполняются:

• для текущего медиа элемента прекращается загрузка и воспроизведение, если они выполнялись;
• удаляются все задачи, имеющиеся в очереди, для текущего медиа элемента;
• к медиа элементу video или audio применяются, сделанные после его последней загрузки, изменения;
• некоторые свойства JS объекта медиа элемента сбрасываются в начальные значения:
  • свойство readyState в HAVE_NOTHING;
  • свойство paused в true;
  • свойство seeking в false;
  • current playback position в значение 0;
  • official playback position в значение 0;
  • initial playback position в значение 0;
  • свойство playbackRate устанавливается в значение равное свойству defaultPlaybackRate;
  • свойство error в значение null и autoplaying flag в true;
• поле выполнения всех описанных выше преобразований запускается алгоритм выбора ресурса, который выполняет обновление медиа файла источника для медиа элемента аудио или видео;
• медиа элемент заново перезагружается и перерисовывается на web странице, все его JS свойства устанавливаются в начальные значения;
• в случае возникновения ошибок, выводятся соответствующие сообщения и устанавливаются статусы.

loop

Свойство loop устанавливает или возвращает флаг true|false, который определяет повторное воспроизведение медиа файла при достижении его конца. Если свойство loop задано как true, то медиа файл будет воспроизводится снова и снова (по кругу) при наступлении его окончания. Значение свойства loop по умолчанию установлено как false.

Синтаксис

// boolean, чтение и изменение, default = false

media.loop [ = true|false ]

mediaGroup

Свойство mediaGroup возвращает или устанавливает строку, определяющую имя группы, из нескольких медиа элементов, к которой данный медиа элемент принадлежит.

Синтаксис

// string, чтение и изменение

media.mediaGroup [ = "myMediaGroupName" ]

Описание, комментарии

Видео и аудио элементы можно объединить между собой в группу через задание для них одинакового значения свойства mediaGroup. Соответственно, медиа элементы, имеющее одно и тоже значение свойства mediaGroup, будут принадлежать одной группе, имя которой и есть значение этого свойства. Целью объединения нескольких медиа элементов в одну группу является одновременное управление ими как одним целым, т.е. переданная команда будет применена для всех аудио или видео элементов, входящих в одноименную группу. Свойство mediaGroup отражает значение одноименного атрибута mediagroup HTML тега audio и video. Это значит, что значение атрибута mediagroup тега audio и video может динамически изменяться и задаваться через свойство mediaGroup медиа объекта. По умолчанию, если в теге audio и video не задан HTML атрибут mediagroup, свойство mediaGroup не определено, иначе, значение свойства устанавливается из одноименного HTML атрибута.

muted

Свойство muted устанавливает или возвращает значения true или false и определяет текущее состояние звука, т.е. должен ли быть включен звук или нет при воспроизведении медиа файла в плеере в текущий момент.

Синтаксис

/ boolean, чтение, изменение, default = false

media.muted [ = true|false ]

Описание, комментарии

Свойство muted предназначено для пользовательских манипуляций текущим состоянием звука при воспроизведении медиа файла. Не путать со свойством defaultMuted, которое задает состояние звука по умолчанию при загрузке web страницы и инициализации медиа элемента. Если свойство muted для аудио или видео задано пользователем как true, то звук будет выключен в плеере, и медиа файл будет воспроизводиться без звука, и наоборот, если свойство muted заданно как false, то звук будет включен. Если свойство muted будет задано как true, то свойство volume медиа элемента, задающее уровень громкости звука, будет игнорироваться, и звук при воспроизведении медиа файла будет выключен. Если HTML элемент audio или video имеет атрибут muted (или muted="true"), то браузер, при загрузке web страницы и инициализации медиа элемента, установит свойство muted как true, вне зависимости от последнего сохраненного в его сессии пользовательского значения.

networkState

Свойство networkState возвращает целое, положительное число, которое означает текущий статус сетевой активности для медиа элемента.

Синтаксис

// unsigned short, только чтение

media.networkState

Описание, комментарии

В процессе различных манипуляций, которые выполняются с медиа элементом видео и аудио на странице, может происходить активное его взаимодействие с сетью, например, при загрузке медиа файла, получения метаданных и т.п. Эти изменения, также, связаны с наступлением тех или иных событий для медиа элемента.

• 0 = NETWORK_EMPTY - медиа элемент не инициализирован еще, это начальное состояние, также, если src не указан вообще для медиа элемента, то выполняется установка свойства networkState в значение NETWORK_EMPTY и выполнение resource selection алгоритма заканчивается;
• 1 = NETWORK_IDLE - запущен алгоритм выбора ресурса для медиа элемента в ходе которого выбран ресурс (медиа файл), но загрузка файла еще не начата. Это значит, что медиа файл выбран и медиа элемент ожидает наступления события, запускающего загрузку файла, которое может наступить автоматически, если установлен атрибут preload или autoplay тегов video или audio, или быть вызвано пользователем по нажатию кнопки воспроизведения/прокрутки файла в медиа плеере;
• 2 = NETWORK_LOADING - браузер выполняет загрузку медиа файла и по окончании загрузки браузером медиа файла будет выполнена установка значения свойства networkState медиа элемента в NETWORK_LOADING, что говорит о том, что медиа файл может быть доступен и воспроизведен в плеере. Однако, если браузер закэшировал медиа файл ранее, то загрузка может и не выполняться и, соответственно, этот статус не будет задан, а вместо него будет NETWORK_IDLE, но файл, все равно сможет быть воспроизведен в этой ситуации;
• 3 = NETWORK_NO_SOURCE - запущен алгоритм выбора ресурса для медиа элемента, но медиа файл еще не найден. Если загрузка файла не удалась, то будут заданы: error как MEDIA_ERR_SRC_NOT_SUPPORTED, networkState как NETWORK_NO_SOURCE и закончиться работа алгоритма выбора ресурса.

pause()

Метод pause() вызывает остановку проигрывания медиа файла.

Синтаксис

media.pause ();

Описание, комментарии

• media.paused = TRUE;
• к установке флага авто воспроизведения = FALSE;
• к установке позиции для последующего воспроизведения видео в текущее состояние, что бы при старте медиа файл начал проигрываться с позиции остановки, а не сначала;
• к завершению очереди задач для медиа объекта.

paused

Свойство paused возвращает true если воспроизведение медиа файла было остановлено, в противном случае возвращает false.

Синтаксис

// boolean, только чтение

media.paused

Описание, комментарии

playbackRate

Свойство playbackRate устанавливает или возвращает текущую скорость воспроизведения для медиа файла видео или аудио. Не путать со свойством defaultPlaybackRate медиа элемента, которое определяет скорость по умолчанию для воспроизведения медиа файла.

Синтаксис

// double, чтение и изменение, default = 1.0

media.playbackRate [ = скорость воспроизведения ]

Описание, комментарии

Свойства defaultPlaybackRate и playbackRate могут иметь отличные друг от друга значения, что позволяет понять прокручивает ли пользователь медиа файл, в какую сторону и с какой скоростью. Формат значения свойств defaultPlaybackRate и playbackRate - число с плавающей точкой, которое, по своей сути, является множителем для скорости воспроизведения медиа файла. Значение по умолчанию для свойств defaultPlaybackRate и playbackRate установлено как 1.0, что соответствует нормальной скорости воспроизведения.

Примеры значений для свойств defaultPlaybackRate и playbackRate:

• 1.0 - нормальная скорость;
• 0.5 - замедленная, половина от нормальной;
• 2.0 - в два раза быстрее от нормальной;
• -1.0 - воспроизведение назад с нормальной скоростью;
• -0.5 - замедленное воспроизведение назад, половина от нормальной скорости.

play()

Метод play() запускает проигрывание медиа фала для выбранного HTML5 элемента video или audio.

Синтаксис

media.play();

Описание, комментарии

Метод применяется к медиа объекту и не имеет входных параметров и возвращаемого значения. При вызове метода play() происходит:

• установка свойства paused медиа элемента в FALSE;
• выполняется загрузка медиа файла и начинается его воспроизведение. Если медиа файл к этому моменту был полностью проигран (свойство ended = TRUE), то вызов метода play() начнет воспроизведение файла сначала.

Для остановки воспроизведения нужно применять противоположный метод pause() к проигрываемому медиа объекту.

played

Свойство played возвращает объект TimeRanges, который представляет и содержит временные диапазоны воспроизведенных пользователем частей медиа audio или video файла.

Синтаксис

// TimeRanges object, только чтение

media.played

Описание, комментарии

Метки start и end в временных диапазонах являются временем от начала медиа файла на временной шкале, которая покрывает объект. Если пользователь воспроизводил медиа файл несколько раз и каждое воспроизведение выполнялось с новой стартовой позиции, то объект TimeRanges будет содержать несколько временных диапазонов, каждый из которых будет соответствовать своему случаю воспроизведения. При этом, если при воспроизведении видео или аудио будет поставлено на паузу, а потом проигрывание продолжиться с этого же места, то случай воспроизведения будет один, т.е. такая ситуация соответствует одному временному интервалу. Однако если пользователь будет воспроизводить файл каждый раз меняя стартовую позицию начала воспроизведения, то каждый такой случай будет считаться самостоятельным временным интервалом. Таким образом, свойство played позволяет узнать воспроизведенные пользователем временные отрезки медиа файла audio или video, которые он выбрал на временной шкале плеера и проиграл.

Свойства и методы TimeRanges объекта применительно к свойству played:

// unsigned long, readonly
media.played.length;

Свойство length объекта TimeRanges вернет количество воспроизведенных пользователем временных диапазонов для audio/video файла, которые содержаться в объекте TimeRanges;

// double в секундах 
time = media.played.start(index);

Метод start() вернет стартовую позицию в секундах для временного диапазона, как время от начала медиа файла на временной шкале плеера, соответствующее заданному индексу временного диапазона в объекте TimeRanges или IndexSizeError в случае ошибки, когда в объекте TimeRanges нет временных диапазонов;

// double в секундах 
time = media.played.end(index);

Метод end() вернет конечную позицию в секундах для временного диапазона, как время от начала медиа файла на временной шкале плеера, соответствующее заданному индексу временного диапазона в объекте TimeRanges или IndexSizeError в случае ошибки, когда в объекте TimeRanges нет временных диапазонов;

Замечание: Index начинается с 0 для временных диапазонов в объекте TimeRanges. Учитывая то, что если в TimeRanges не будет содержится временных диапазонов, то для его методов start() и end() будет возвращена ошибка IndexSizeError.

poster

Свойство poster возвращает или устанавливает строку, определяющую URL путь к файлу изображения, которое будет показано пока видео не доступно или еще не начиналось воспроизводиться.

Синтаксис

// string, чтение, изменение

video.poster [ = "URL String" ]

Описание, комментарии

Свойство poster объекта Video представляет и отражает значение одноименного HTML атрибута poster тега <video>. Значение по умолчанию для свойства poster, при его инициализации, будет соответствовать первичному значению HTML атрибута poster тега video, или пустой строке, если HTML атрибут poster отсутствует в теге video. Если свойство poster не задано (равно пустой строке), то плеер браузера будет пытаться показать первый кадр видео. При задании свойства poster, URL путь к файлу изображения можно указать как полный URL вида: http://www.example.com/..., так и как относительный к текущему домену web страницы. При получении же значения свойства poster, всегда будет возвращаться полный URL, как путь к файлу изображения, включая протокол (http:|https:) и домен.

preload

Свойство preload устанавливает или возвращает наличие атрибута preload.

Синтаксис

// string, чтение, изменение

media.preload [ = "auto|metadata|none" ]

auto

браузер должен загрузить все media при загрузке страницы.

metadata

браузер должен загружать только метаданные при загрузке страницы.

none

браузер не следует загружать видео при загрузке страницы.

Возвращаемое значение

Строка, представляющая какие данные должны быть предварительно загружены. Возможные возвращаемые значения "auto" , "metadata" , или "none".

Описание, комментарии

Свойство preload media объекта представляет и отражает значение одноименного HTML атрибута preload тега <audio>/<video>.

readyState

Свойство readyState возвращает целое, положительное число, которое означает текущий статус готовности медиа элемента для воспроизведения медиа файла.

Синтаксис

// unsigned short, только чтение

media.readyState

Описание, комментарии

Значение свойства readyState позволяет понять, готово ли видео или аудио для воспроизведения или нет и какой статус этой готовности.

Статусы готовности readyState определяются для медиа элемента положительными целыми числами, которым соответствуют константы, название которых кратко характеризует определяемый ими статус готовности медиа элемента к воспроизведению медиа audio или video файла:

• 0 = HAVE_NOTHING - Нет какой либо информации о готовности или неготовности audio/video к воспроизведению. Обычно, когда никакие данные о медиа файле еще не загружены и статус сети соответствует NETWORK_EMPTY;
• 1 = HAVE_METADATA - Для audio/video доступны только метаданные;
• 2 = HAVE_CURRENT_DATA - Данные для текущей позиции воспроизведения полностью доступны, но недостаточно данных для продолжения воспроизведения, т.к. не доступен следующий кадр/последовательность медиа файла;
• 3 = HAVE_FUTURE_DATA - Данные для текущей позиции воспроизведения и, как минимум, для следующего кадра/последовательности воспроизведения полностью доступны;
• 4 = HAVE_ENOUGH_DATA - Для воспроизведение медиа файла полностью доступны все необходимые данные.

seekable

Свойство seekable возвращает объект TimeRanges, который представляет и содержит временные диапазоны медиа audio или video файла, в пределах которых пользователю доступно воспроизведение файла и изменение позиции воспроизведения.

Синтаксис

// TimeRanges object, только чтение

media.seekable

Описание, комментарии

Каждый временной диапазон (seekable time-range) указывает время начала и окончания части медиа аудио или видео файла, которая доступна пользователю для проигрывания и перемещения позиции воспроизведения по ней. Иными словами, пользователь, в пределах этого диапазона, может свободно перемещать курсор воспроизведения и устанавливать его любое место в пределах этого диапазона и воспроизводить медиа файл с выбранной позиции. Время начала и окончания для временных диапазонов задается как число секунд от начала audio или video файла.

Свойства и методы TimeRanges объекта применительно к свойству seekable:

// readonly, unsigned long
media.seekable.length;

Свойство length вернет количество временных диапазонов audio или video файла в пределах которых пользователю доступно воспроизведение и перемещение по файлу;

//  double in seconds от начала файла
startTime = media.seekable.start(index);

Метод start() вернет стартовую позицию в секундах для временного диапазона соответствующего индекса, как время от начала медиа файла на временной шкале плеера, или IndexSizeError в случае отсутствия такого индекса в объекте TimeRanges;

//  double in seconds от начала файла
endTime = media.seekable.end(index);

Метод end() вернет конечную позицию в секундах для временного диапазона соответствующего индекса, как время от начала медиа файла на временной шкале плеера, или IndexSizeError в случае отсутствия такого индекса в объекте TimeRanges.

Замечание: Для временных диапазонов в объекте TimeRanges значения Index начинается с 0. Если указанный индекс будет отсутствовать в объекте TimeRanges, то возникнет ошибка IndexSizeError.

seeking

Свойство seeking возвращает значение true только если в текущий момент пользователь выполняет поиск по медиа файлу, т.е. выполняет перемещение курсора воспроизведения на шкале медиа плеера, при этом позиция воспроизведения постоянно изменяется. Как только перемещение курсора воспроизведения будет прекращено, свойство seeking медиа элемента будет установлено как false.

Синтаксис

// boolean, только чтение

media.seeking

Описание, комментарии

Свойство seeking медиа элемента audio и video позволяет определить выполняется ли пользователем в текущий момент перемещение курсора воспроизведения по шале плеера или нет. Для того, чтобы свойство seeking возвращало true обязательно должно выполняться движение курсора пользователем по шкале воспроизведения.

При инициализации, значение для свойства seeking медиа элемента audio и video по умолчанию устанавливается как false.

src

Свойство src возвращает или устанавливает строку, определяющую URL путь к медиа файлу.

Синтаксис

// string, чтение и изменение

media.src [ = "URL String" ]

Описание, комментарии

Свойство src отражает значение одноименного атрибута src HTML тега audio и video. Это значит, что значение атрибута src тега audio и video может динамически изменяться и задаваться через свойство src медиа объекта. Значение по умолчанию для свойства src медиа объекта, при его инициализации, будет соответствовать первичному значению атрибута src тега audio или video, или пустой строке, если HTML атрибут src не задан для этих тегов. Любые изменения значения свойства src объекта медиа элемента audio и video будут приводить и к изменению значения одноименного атрибута src HTML тегов audio и video. Также, установка или изменение значения свойства src объекта медиа элемента audio и video будет вызывать перезагрузку медиа элемента на web странице, точно также, как это происходит при вызове метода load(). Также, в ходе перезагрузки медиа элемента на web странице будет исполнен алгоритм выбора ресурса, в ходе которого будет переопределено значение свойства currentSrc, которое будет обновлено на новый абсолютный URL, заданный для свойства src.

При задании свойства src, URL путь к файлу источнику видео или аудио можно указать как абсолютный (полный URL вида: http://www.example.com/...), так и как относительный к текущему домену web страницы. При получении же значения свойства src, всегда будет возвращаться полный абсолютный URL, как путь к медиа файлу, включая протокол (http:|https:) и домен.

textTracks

Свойство textTracks возвращает объект TextTrackList, который представляет набор доступных для данного медиа элемента объектов TextTrack (текстовых треков).

Синтаксис

//TextTrackList object, только для чтения

media.textTracks 

Описание, комментарии

Cвойство доступно в большинстве браузеров и позволяет манипулировать подключенными к медиа элементу текстовыми треками. Из возвращаемого TextTrackList можно получить нужный TextTrack по его индексу и извлечь из него текстовые фразы, которые привязаны к временной шкале медиа файла.

videoTracks

Свойство videoTracks возвращает объект VideoTrackList, который содержит доступные для медиа элемента video треки - video файлы.

Синтаксис

// VideoTrackList object, только для чтения

media.videoTracks

Возвращаемое значение

Объект VideoTrackList, который представляет доступные видео дорожки.

Свойства объекта VideoTrackList:

• length - получить количество доступных видео дорожек
• getTrackById(id) - получить объект VideoTrack по идентификатору
• [index] - получить VideoTrack объекта по индексу. Первый доступный объект VideoTrack имеет индекс 0

Объект VideoTrack представляет собой видео дорожку.

Свойства объекта VideoTrack:

• id - получить идентификатор видео дорожки
• kind - получить тип видео дорожки (может быть: "alternative" , "description" , "main" , "translation" , "commentary" , или "" (пустая строка))
• label - получить ярлык видео дорожки
• language - получить код языка видео дорожки
• enabled - получить или установить активность трека (true|false)

Совместимость с браузерами

Этот функционал пока не реализован в большинстве браузеров, и поэтому на практике не используется.

На удивление, в IE11 свойства audioTracks и videoTracks работают

videoWidth и videoHeight

Свойства videoWidth и videoHeight устанавливаются при инициализации или перезагрузке видео элемента на WEB странице и представляют действительные внутренние размеры видео из файла медиа ресурса, выраженные в пикселях CSS.

Синтаксис

// unsigned long, только чтение, default = 0

video.videoWidth
video.videoHeight

Комментарии

Если видео файл отсутствует (video.readyState равно HAVE_NOTHING), то значения свойств устанавливаются как 0 ноль. При обновлении и установке этих свойств возникает событие resize для видео элемента.

volume

Свойство volume устанавливает или возвращает текущее значение громкости звука при воспроизведении медиа файла.

Синтаксис

// double, чтение, изменение, default = 1.0

media.volume [ = число от 0.0 до 1.0 ]

Описание, комментарии

Значение является числом (double) в диапазоне от 0.0 до 1.0, где 0.0 соответствует самому тихому состоянию звука, что равносильно выключенному звуку, а 1.0 самому громкому состоянию звука. Свойство volume аудио и видео доступно как для чтения так и для изменения, что позволяет динамически изменять громкость воспроизведения медиа файла при помощи JS кода. Если при задании нового значения для свойства volume медиа элемента audio и video будет попытка установить значение, находящееся вне диапазона 0.0-1.0, то будет выдана ошибка и исключение IndexSizeError, поэтому целесообразно сделать проверку значения свойства volume перед его изменением. Значение по умолчанию для свойства volume медиа элемента audio и video задается как 1.0.

Также, нужно помнить, что если свойство muted медиа элемента будет задано как true, то значение свойства volume будет игнорироваться и звук будет полностью выключен в медиа плеере.

width и height

Свойства width и height задают размер области воспроизведения видео контента в пикселях CSS.

Синтаксис

// unsigned long, чтение, изменение, default = 0

video.width [ = число unsigned long в px CSS]
video.height [ = число unsigned long в px CSS]

Описание, комментарии

Значения этих свойств доступны для изменения и не влияют на истинные внутренние размеры самого видео, т.к. определяют лишь размер области показа. Если установленные значения свойств width и height будут иметь не совпадающее соотношение сторон с оригинальным соотношением сторон видео, то, при воспроизведении, видео подстроится под размер заданной области воспроизведения, но с сохранением своих начальных пропорций. Поэтому, в таких случаях могут появиться полосы по бокам или сверху и снизу от видео. Свойства width и height объекта video соответствуют одноименным HTML атрибутам width и height тега <video>, которые они представляют.