Этот документ содержит справочные сведения для API проигрывателя JavaScript YouTube.

Содержание

Обзор

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

Требования

Для корректного просмотра у конечного пользователя должен быть установлен проигрыватель Flash 8 или выше. Из-за этого требования мы советуем воспользоваться SWFObject, чтобы встроить SWF и определить версию проигрывателя Flash у пользователя.

С чего начать

Примечание. Для проверки этих вызовов необходимо, чтобы ваш файл выполнялся на веб-сервере, так как проигрыватель Flash ограничивает вызовы между Интернетом и локальными файлами.

Для включения API JavaScript, необходимо передать параметр URL на URL проигрывателя, который вы хотите контролировать. enablejsapi=1 Например, для встраивания SWF следует использовать следующий URL.

http://www.youtube.com/v/VIDEO_ID&enablejsapi=1

Это включает обработчики API JavaScript в проигрывателе, а также предписывает проигрывателю сообщить содержащей его странице HTML через обратный вызов, когда проигрыватель загружен и готов принимать вызовы JavaScript. Когда проигрыватель готов, вызовется функция JavaScript .onYouTubePlayerReady

Дополнительно можно передать параметр playerapiid, который определяет проигрыватель при привлечении обратного вызова . onYouTubePlayerReady Передаваемое как playerapiid значение будет передано как первый аргумент.onYouTubePlayerReady

http://www.youtube.com/v/VIDEO_ID&enablejsapi=1&playerapiid=ytplayer

Более подробные сведения о том, как встроить проигрыватель YouTube SWF в свою страницу, можно найти в примерах ниже.

Операции

Для вызова методов API проигрывателя, необходимо сперва получить ссылку на объект проигрывателя, который нужно контролировать. Это можно сделать, вызвав getElementById() на тег object или embed, содержащий проигрыватель SWF, если для встраивания проигрывателя SWF используется SWFObject.

Функции

player.playVideo():Void

Проигрывает вызванное/загруженное видео.

player.pauseVideo():Void

Приостанавливает проигрываемое видео.

player.stopVideo():Void

Останавливает текущее видео. Также закрывает объект NetStream и прекращает загрузку видео. После вызова stopVideo(), видео нельзя начать воспроизводить, не перезагрузив проигрыватель или не загрузив новое видео (только Chromeless Player). При вызове stopVideo(), сперва проигрыватель сперва распространит событие окончания (0), а затем событие незапуска (-1).

player.clearVideo():Void

Очищает отображаемое видео. Полезно, если нужно убрать остаток видео после вызова stopVideo().

player.getVideoBytesLoaded():Number

Возвращает количество байт, загруженных для текущего видео.

player.getVideoBytesTotal():Number

Возвращает количество байт загруженного/воспроизводимого видео.

player.getVideoStartBytes():Number

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

player.mute():Void

Отключает звук.

player.unMute():Void

Включает звук.

player.isMuted():Boolean

Возвращает "true", если звук отключен, "false", если нет.

player.setVolume(volume):Void

Устанавливает громкость. Принимает целое число от 0 до 100.

player.getVolume(volume):Void

Возвращает текущую громкость проигрывателя, целое число от 0 до 100. Заметьте, что getVolume() вернет громкость, даже если звук проигрывателя отключен.

player.seekTo(seconds, allowSeekAhead):Void

Переходит на указанное время в видео в секундах. allowSeekAhead определяет, сделает ли проигрыватель новый запрос к серверу, если seconds находится дальше, чем загруженные данные видео. Заметьте, что seekTo() попытается перейти к ближайшему к seconds ключевому кадру. Это значит, что иногда курсор может перейти сразу за или сразу после нужного времени, обычно не больше 2 секунд.

player.getPlayerState():Number

Возвращает состояние проигрывателя. Возможные значения – не запущен (-1), закончено (0), воспроизведение (1), приостановлено (2), буферизация (3), видео вызвано (5).

player.getCurrentTime():Number

Возвращает текущее время видео в секундах.

player.getDuration():Number

Возвращает продолжительность воспроизводимого видео в секундах. Заметьте, что getDuration() возвращает 0, пока не загружены метаданные видео, что происходит обычно сразу после начала воспроизведения видео.

player.addEventListener(event, listener):Void

Добавляет к указанному событию функцию приемника.

player.getVideoUrl():String

Возвращает URL YouTube.com для загруженного/воспроизводимого видео.

player.getVideoEmbedCode():String

Возвращает код встраивания для загруженного/воспроизводимого видео.

События

onStateChange

Происходит при изменении состояния проигрывателя. Возможные значения – не запущен (-1), закончено (0), воспроизведение (1), приостановлено (2), буферизация (3), видео вызвано (5). При загрузке SWF, он распространяет событие не запущен (-1). Когда все готово к воспроизведению видео с нужного момента, он начинает воспроизведение выбранного отрезка видео (5).

onError

Происходит при возникновении ошибки в проигрывателе. На настоящий момент есть только один код ошибки, 100, или "Видео не найдено". Это происходит, когда видео удаляется (по любой причине) или было обозначено как "только для избранных" или как невстраиваемое пользователем.

Специальные события

onYouTubePlayerReady(playerid)

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

Примеры

Встраивание проигрывателя YouTube с использованием SWFObject

Мы рекомендуем использовать SWFObject для встраивания любых проигрывателей, к которым будет происходить доступ через API JavaScript. Это позволит определить версию проигрывателя Flash у конечного пользователя (для API JavaScript необходим проигрыватель Flash 8 или выше), а также избавиться от окошка "Click to activate this control" при использовании для просмотра через Internet Explorer. Для включения API в SWF, необходимо передать параметр enablejsapi=1.

Ниже приведен пример использования сценария, для встраивания проигрывателя YouTube со включенным API JavaScript и с playerapiid ytplayer.

  <script type="text/javascript" src="swfobject.js"></script>    
  <div id="ytapiplayer">
    You need Flash player 8+ and JavaScript enabled to view this video.
  </div>

  <script type="text/javascript">

    var params = { allowScriptAccess: "always" };
    var atts = { id: "myytplayer" };
    swfobject.embedSWF("http://www.youtube.com/v/VIDEO_ID&enablejsapi=1&playerapiid=ytplayer", 
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

  </script>

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

Единственный атрибут, который мы передаем – id встраиваемого объекта, в данном случае, myytplayer. Этот идентификатор нужно использовать для получения ссылки на проигрыватель с помощью getElementById().

swfobject.embedSWF загрузит проигрыватель с YouTube и встроит его на вашу страницу.

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

• swfUrlStr – Это URL SWF. Заметьте, что мы присоединили параметры enablejsapi и playerapiid к нормальному URL SWF YouTube, чтобы включить вызовы API JavaScript.
• replaceElemIdStr – Это идентификатор HTML DIV, который заменяется встраиваемым содержимым. В примере выше, это ytapiplayer.
• widthStr – Ширина проигрывателя.
• heightStr – Высота проигрывателя.
• swfVersionStr – Требования к минимальной версии у пользователя для просмотра содержания. В этом случае – версия 8 или выше. Если у пользователя нет версии 8 или выше, они увидят строку текста по умолчанию в HTML DIV.
• xiSwfUrlStr – (дополнительно) Указывает URL быстрой установки SWF. Не используется в этом примере.
• flashVarsObj – (дополнительно) Указывает ваш FlashVars в парах имя:значение. Не используется в этом примере.
• parObj – (дополнительно) Параметры для встраиваемого объекта. В этом случае, мы установили allowScriptAccess.
• AttObj – (дополнительно) Атрибуты для встраиваемого объекта. В этом случае, мы установили идентификатор как myytplayer.

Для получения дополнительной информации см. документацию по SWFObject.

Получение ссылки на проигрыватель

Когда проигрыватель готов, он вызовет onYouTubePlayerReady.

Для получения ссылки на него, используйте getElementById(). Получив объект, можно начинать делать вызовы к API.

    function onYouTubePlayerReady(playerId) {
      ytplayer = document.getElementById("myytplayer");
    }

Создание вызовов

Теперь можно вызывать функции, используя ссылку на проигрыватель. Например, если вы хотите воспроизводить видео, когда пользователь нажимает ссылку, это будет выглядеть как-то так:

function play() {
  if (ytplayer) {
    ytplayer.playVideo();
  }
}

<a href="javascript:void(0);" onclick="play();">Play</a>

Или просто,

 <a href="javascript:ytplayer.playVideo()">Play</a> 

Подписка на события

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

function onYouTubePlayerReady(playerId) {
  ytplayer = document.getElementById("myytplayer");
  ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
}

function onytplayerStateChange(newState) {
   alert("Player's new state: " + newState);
}

Здесь есть простой пример, показывающий большую часть этой функции. Посмотрите исходный код и вы узнаете, что происходит под капотом.

Наверх