Audio и Video

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

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

Свойства

audioTracks Возвращает объект AudioTrackList, который содержит доступные для медиа элемента audio треки - audio файлы
autoplay Устанавливает или возвращает значение true|false и управляет автоматическим стартом воспроизведения медиа файла после его загрузки.
buffered Возвращает объект TimeRanges, который содержит метки частей медиа файла, уже загруженные и помещенные в буфер браузера.
controller Возвращает объект MediaController, представляющий текущий контроллер для данного аудио или видео объекта.
controls Управляет отображением панели управления в медиа плеере.
crossOrigin Устанавливает или возвращает значение атрибута crossorigin
currentSrc Возвращает URL текущего аудио, включая протокол (http:|https:) и домен.
currentTime Устанавливает или возвращает текущую позицию времени воспроизведения медиа файла
defaultMuted Управляет отключением звука при инициализации медиа элемента.
defaultPlaybackRate Устанавливает или возвращает скорость по умолчанию для воспроизведения медиа файла
duration Возвращает общую длительность медиа файла в секундах
ended Возвращает true|false и указывает, достиг ли курсор позиции воспроизведения окончания медиа файла или нет.
error Возвращает объект MediaError, содержащий статус последней возникшей ошибки.
loop Устанавливает или возвращаетзначение true|false и определяет циклическое воспроизведение медиа файла при достижении его окончания.
mediaGroup Устанавливает или возвращает имя группы, из нескольких медиа элементов, к которой данный медиа элемент принадлежит.
muted Управляет отключением звука при воспроизведении медиа файла.
networkState Возвращает текущий статус сетевой активности для медиа элемента в формате числа, которому соответствуют константы.
paused Возвращает true если медиа файл не воспроизводиться, иначе возвращает false.
playbackRate Устанавливает или возвращает текущую скорость воспроизведения для медиа файла.
played Возвращает объект TimeRanges, который содержит временные диапазоны воспроизведенных пользователем частей медиа файла.
poster Определяет URL путь к файлу изображения, которое будет показано пока видео не доступно или еще не начиналось воспроизводиться.
preload Устанавливает или возвращает наличие атрибута preload.
readyState Возвращает статус готовности медиа элемента для воспроизведения файла аудио.
seekable Возвращает объект TimeRanges, который содержит временные диапазоны медиа файла, в пределах которых пользователю доступно воспроизведение.
seeking Возвращает значение true только если в текущий момент пользователь выполняет поиск по медиа файлу, иначе false.
src Устанавливает или возвращает значение одноименного атрибута src
textTracks Возвращает объект TextTrackList, который содержит доступные для данного медиа элемента текстовые треки.
videoTracks Возвращает объект VideoTrackList, который содержит доступные для медиа элемента video треки - video файлы.
videoWidth и .videoHeight Представляют внутренние размеры видео из файла медиа ресурса в пикселях CSS.
volume Устанавливает или возвращает громкость звука в аудио
width и height Определяют размер области воспроизведения видео контента в пикселях CSS.

Методы

addTextTrack() Добавляет новую текстовую дорожку в аудио
canPlayType() Проверяет, может ли браузер проигрывать указанный тип аудио
load() Повторно загружает аудио элемент
play() Начинает воспроизведение аудио
pause() Приостановка воспроизведения текущего аудио

События

mediaEvents Представлены DOM события для медиа элемента HTML5 audio и video, возникающие при его обработке в браузере.

Пример

Example Представляет комплексную демонстрацию управления HTML5 элементами video и audio при помощи JavaScript.

addTextTrack()

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

Синтаксис

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

Параметры

kind
задает тип текстового трека и может принимать значения: "subtitles", "caption", "descriptions", "chapters", "metadata"
label
строка, которая задает название для новой текстовой дорожки в плеере.
language
строка из двух символьного кода языка, которая задает язык для новой текстовой дорожки.

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

Созданный новый TextTrack объект предоставляет возможность управления собой и получает переданные методу addTextTrack() параметры "kind", "label", "language" и состояние как "loaded", вид как "hidden", и пустой список временных меток (cues). Для добавления в новый текстовый трек временных меток (cues) и текста к ним, для вывода поверх видео, и выполнения других манипуляций, нужно уже обращаться к методам и свойствам созданного TextTrack объекта.

Свойства и методы объекта 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:

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

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

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

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

На удивление, в 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 тип медиа файла, который может опционально содержать и кодек медиа файла.

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

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

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

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

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

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 ]
Свойство controls медиа элемента audio и video устанавливает или возвращает значения true или false. Свойство controls отражает значение одноименного атрибута controls HTML элемента audio и video. Если свойство controls задано как true, то медиа плеер будет отображать панель управления медиа элементом. Если свойство controls задано как false, то панель управления у медиа плеера будет скрыта.

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

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:

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.

Объект MediaError имеет только одно свойство, доступное только для чтения - MediaError.code: 
// unsigned short, только чтение

MediaError.code;

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

load()

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

Синтаксис

media.load();

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

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

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

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

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

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

Чтобы избежать возникновения ошибок, может быть полезно узнать networkState значение медиа элемента предварительно, например, перед вызовом методов воспроизведения audio или video файла. Статусам networkState медиа элемента соответствуют константы, название которых кратко характеризует определяемый ими статус:

pause()

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

Синтаксис

media.pause ();

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

Метод не имеет входных параметров и возвращаемого значения. Для продолжения воспроизведения остановленного видео нужно использовать противоположный метод play(). Вызов метода pause() также приводит:

paused

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

Синтаксис

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

media.paused

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

Использование свойства позволяет проверить было ли аудио или видео остановлено (поставлено на паузу). Если paused = true, то это значит, что медиа файл не воспроизводиться в данный момент, если paused = false, то это значит, что медиа файл в текущий момент проигрывается. Изначально, свойство paused устанавливается браузером как true.

playbackRate

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

Синтаксис

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

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

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

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

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

play()

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

Синтаксис

media.play();

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

Метод применяется к медиа объекту и не имеет входных параметров и возвращаемого значения. При вызове метода 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 файла:

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:

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

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

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

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

На удивление, в 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>, которые они представляют.

Справочник JavaScript