API и инструменты YouTube

Начало работы
API данных YouTube
- Руководства и код клиентской библиотеки ^{(вер. 2.0)}
- Руководство разработчика ^{(вер. 2.0)}
- Справочное руководство ^{(вер. 2.0)}
- Руководство по переходу на новую версию ^{(вер. 2.0)}
- Интерактивная демонстрация
- Предыдущие версии API
  - Версия 1.0
Инструменты проигрывателя YouTube
- Параметры проигрывателя
- API проигрывателя
  - JavaAPI JavaScript
  - API Flash (AS3)
    - API Flash (AS2)
- Демонстрация API проигрывателя
- Пример площадки для экспериментов
Дополнительные ресурсы

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

В настоящем документе представлена справочная информация по API YouTube для проигрывателя JavaScript.

Содержание

Общая информация
Требования
Начало работы
Операции
1. Функции
2. События
Обработчики событий
Пример

Общая информация

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

Требования

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

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

Начало работы

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

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

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

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

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

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

Можно также загрузить на страницу проигрыватель Chromeless Player, если элементы управления создаются с помощью JavaScript.

http://www.youtube.com/apiplayer?enablejsapi=1

Чтобы отправить запрос на получение проигрывателя AS3 без элементов управления, добавьте параметр &version=3 к приведенному выше URL.

http://www.youtube.com/apiplayer?enablejsapi=1&version=3

После того как загружен проигрыватель Chromeless Player SWF, можно воспользоваться функциями cueVideoById(), loadVideoById(), cueVideoByUrl() или loadVideoByUrl(), чтобы загрузить конкретное видео с YouTube.

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

Операции

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

Функции

player.cueVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void: Загрузка значка указанного видео и подготовка проигрывателя к воспроизведению видео. Проигрыватель не запрашивает FLV до тех пор, пока не будет вызвана функция playVideo() или seekTo().

Обязательный параметр videoId определяет идентификатор воспроизводимого видео YouTube. В фидах видео API данных YouTube тег <yt:videoId> определяет идентификатор.

Дополнительный параметр startSeconds может принимать целочисленные значения или значения с плавающей точкой и задает время, с которого начнется воспроизведение видео при вызове playVideo(). Если задать значение startSeconds и затем вызвать seekTo(), проигрыватель начнет воспроизведение с момента, указанного в вызове seekTo(). Когда видео размечено и готово к воспроизведению, проигрыватель передает событие "видео размечено" (5).

Дополнительный параметр suggestedQuality определяет предлагаемое качество воспроизведения видео. Дополнительная информация о качестве воспроизведения видео приведена в определении функции setPlaybackQuality.
player.loadVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void: Загрузка и воспроизведение указанного видео.

Обязательный параметр videoId определяет идентификатор воспроизводимого видео YouTube. В фидах видео API данных YouTube тег <yt:videoId> определяет идентификатор.

Дополнительный параметр startSeconds принимает целочисленные значения и значения с плавающей точкой. Если этот параметр установлен, воспроизведение видео начнется с ключевого кадра, ближайшего к указанному времени.

Дополнительный параметр suggestedQuality определяет предлагаемое качество воспроизведения видео. Дополнительная информация о качестве воспроизведения видео приведена в определении функции setPlaybackQuality.
player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void: Загрузка значка указанного видео и подготовка проигрывателя к воспроизведению видео. Проигрыватель не запрашивает FLV до тех пор, пока не будет вызвана функция playVideo() или seekTo().

В качестве mediaContentUrl нужно использовать полный URL проигрывателя YouTube в формате http://www.youtube.com/v/VIDEO_ID. Если атрибут format тега <media:content> имеет значение 5, в фидах видео API данных YouTube атрибут url этого тега будет содержать полный URL проигрывателя.

Параметр startSeconds может принимать целочисленные значения или значения с плавающей точкой и задает время, с которого начнется воспроизведение видео при вызове playVideo(). Если задать значение startSeconds и затем вызвать seekTo(), проигрыватель начнет воспроизведение с момента, указанного в вызове seekTo(). Когда видео размечено и готово к воспроизведению, проигрыватель передает событие "видео размечено" (5).
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):Void: Эта функция, которая загружает и воспроизводит указанное видео, еще не реализована для API проигрывателя ActionScript 3.0.

В качестве mediaContentUrl нужно использовать полный URL проигрывателя YouTube в формате http://www.youtube.com/v/VIDEO_ID. Если атрибут format тега <media:content> имеет значение 5, в фидах видео API данных YouTube атрибут url этого тега будет содержать полный URL проигрывателя.

Параметр startSeconds может принимать целочисленные значения или значения с плавающей точкой и задает время, с которого начнется воспроизведение видео. Если задать параметр startSeconds (можно в формате с плавающей точкой), воспроизведение видео начнется с ключевого кадра, ближайшего к указанному моменту времени.; Загрузка и воспроизведение указанного видео.

В качестве mediaContentUrl нужно использовать полный URL проигрывателя YouTube в формате http://www.youtube.com/v/VIDEO_ID. Если атрибут format тега <media:content> имеет значение 5, в фидах видео API данных YouTube атрибут url этого тега будет содержать полный URL проигрывателя.

Параметр startSeconds может принимать целочисленные значения или значения с плавающей точкой и задает время, с которого начнется воспроизведение видео. Если задать параметр startSeconds (можно в формате с плавающей точкой), воспроизведение видео начнется с ключевого кадра, ближайшего к указанному моменту времени.
player.playVideo():Void: Воспроизведение размеченного/загруженного видео.
player.pauseVideo():Void: Приостановка воспроизведения видео.
player.stopVideo():Void: Остановка воспроизведения видео. Эта функция также отменяет загрузку видео.
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void: Переход к указанному времени в видео (в секундах). Функция seekTo() будет искать ближайший ключевой кадр до времени, определенного параметром seconds. Это означает, что иногда воспроизведение будет начинаться в момент, предшествующий заданному времени (обычно не более чем на 2 секунды).

Параметр allowSeekAhead определяет, будет ли проигрыватель делать новый запрос серверу, если значение seconds превышает продолжительность загруженных видеоданных.
player.clearVideo():Void: Удаление видео с экрана. Эта функция используется, если нужно удалить с экрана видео, оставшееся после вызова функции stopVideo(). Обратите внимание, что в API проигрывателя ActionScript 3.0 эта функция считается устаревшей.
player.mute():Void: Выключает звук в проигрывателе.
player.unMute():Void: Включает звук в проигрывателе.
player.isMuted():Boolean: Возвращает значение true, если звук в проигрывателе выключен, и false, если включен.
player.setVolume(volume:Number):Void: Устанавливает громкость. Принимает целочисленное значение от 0 до 100.
player.getVolume():Number: Возвращает уровень громкости, установленный в проигрывателе (целое число от 0 до 100). Обратите внимание, что getVolume() возвращает установленный уровень громкости, даже если звук в проигрывателе отключен.
player.setSize(width:Number, height:Number):Void: Устанавливает размер проигрывателя в пикселях. Этот метод не следует использовать в JavaScript, поскольку размер проигрывателя будет автоматически изменен, если изменятся свойства высоты и ширины элементов в коде встраивания, содержащих проигрыватель.
player.getVideoBytesLoaded():Number: Возвращает число байтов, загруженных для текущего видео.
player.getVideoBytesTotal():Number: Возвращает размер в байтах текущего загруженного/воспроизводимого видео.
player.getVideoStartBytes():Number: Возвращает число байтов, с которого началась загрузка видеофайла. Пример применения. Пользователь переходит вперед в место, которое еще не было загружено, и проигрыватель делает новый запрос для воспроизведения фрагмента видео, который еще не был загружен.
player.getPlayerState():Number: Возвращает состояние проигрывателя. Возможные значения: не запущен (-1), воспроизведение закончено (0), идет воспроизведение (1), пауза (2), буферизация (3), видео размечено (5).
player.getCurrentTime():Number: Возвращает время в секундах, прошедшее с начала воспроизведения видео.
player.getPlaybackQuality():String: Эта функция получает фактическое значение качества текущего видео. Если текущее видео отсутствует, возвращается undefined. Могут возвращаться следующие значения: hd720, large, medium и small.
player.setPlaybackQuality(suggestedQuality:String):Void: Эта функция устанавливает предлагаемое значение качества текущего видео. При вызове этой функции видео перезагружается с текущей позиции с новым качеством. Качество воспроизведения изменится только для видео, воспроизводимого в данный момент.

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

Параметр suggestedQuality может принимать значения small, medium, large, hd720 и default. Присвоение параметру значения default предписывает YouTube выбрать наиболее подходящее качество воспроизведения в зависимости от пользователя, видео, применяемых систем и других условий воспроизведения.

Если для видео принято предложение в отношении качества воспроизведения, это предлагаемое значение будет действительно только для данного видео. Следует выбирать такое качество воспроизведения, которое соответствует размеру проигрывателя видео. Например, если на странице отображается проигрыватель, имеющий размеры 640 х 360 пикселей, видео в качестве medium будет выглядеть лучше, чем в качестве large. В следующем списке приводятся рекомендованные уровни качества воспроизведения для различных размеров проигрывателя.

Уровень качества small: разрешение проигрывателя – менее 640 х 360 пикселей.

Уровень качества medium: минимальное разрешение проигрывателя – 640 х 360 пикселей.

Уровень качества large: минимальное разрешение проигрывателя – 854 х 480 пикселей.

Уровень качества hd720: минимальное разрешение проигрывателя – 1280 х 720 пикселей.

Уровень качества default: YouTube выбирает подходящее качество воспроизведения. Данная настройка возвращает уровень качества в значение по умолчанию и отменяет все предыдущие действия по настройке качества воспроизведения с использованием функций cueVideoById, loadVideoById или setPlaybackQuality.

Если функция setPlaybackQuality вызывается с уровнем качества suggestedQuality, который недоступен для данного видео, то будет установлен следующий доступный более низкий уровень качества. Например, если запрашивается уровень качества large и он недоступен, будет установлено качество воспроизведения medium (если данный уровень качества доступен).

Также присвоение параметру suggestedQuality значения, которое не является распознаваемым уровнем качества, равносильно установке для suggestedQuality значения default.
player.getAvailableQualityLevels():Array: Эта функция возвращает набор форматов качества, которые доступны для текущего видео. Эта функция может использоваться для определения того, доступно ли для просматриваемого видео более высокое качество, и проигрыватель может отобразить кнопку или другой элемент, позволяющий пользователю изменить качество.

Эта функция возвращает массив строк, упорядоченных от самого высокого до самого низкого качества. Элементы массива могут принимать значения hd720, large, medium и small. Функция возвращает пустой массив, если текущее видео отсутствует.

Ваш клиент не должен автоматически переключаться на использование самого высокого (или низкого) качества или формата с неизвестным названием. YouTube может расширить список уровней качества, чтобы включить форматы, которые могут подходить для контекста вашего проигрывателя. Аналогично YouTube может удалить параметры качества, которые могут отрицательно повлиять на восприятие пользователя. Добившись того, чтобы ваш клиент переключался только на известные, доступные форматы, вы сможете гарантировать, что на работу клиента не повлияет введение новых уровней качества или удаление уровней качества, неподходящих для контекста вашего проигрывателя.
player.getDuration():Number: Возвращает длительность в секундах видео, воспроизводимого в текущий момент. Обратите внимание на то, что getDuration() возвратит 0, если метаданные видео еще не загружены, что обычно случается в самом начале воспроизведения видео.
player.getVideoUrl():String: Возвращает URL на YouTube.com для видео, загружаемого или воспроизводимого в текущий момент.
player.getVideoEmbedCode():String: Возвращает код встраивания для видео, загружаемого или воспроизводимого в текущий момент.

player.addEventListener(event:String, listener:String):Void: К указанному event добавляется функция прослушивателя. В следующем разделе, События, указаны различные события, вызываемые проигрывателем. Прослушиватель – это строка, задающая функцию, которая будет выполняться при возникновении указанного события.

События

onStateChange: Это событие возникает при изменении состояния проигрывателя. Возможные значения: не запущен (-1), воспроизведение закончено (0), идет воспроизведение (1), пауза (2), буферизация (3), видео размечено (5). Сначала при загрузке SWF сообщается о событии "не запущен" (-1). Когда видео размечено и готово к воспроизведению, сообщается о событии "видео размечено" (5).
onPlaybackQualityChange: Это событие возникает при изменении качества воспроизведения видео. Например, при вызове функции setPlaybackQuality(suggestedQuality) это событие возникнет, если качество воспроизведения изменится. Код должен отвечать на событие, а не предполагать, что качество автоматически изменится при вызове функции setPlaybackQuality(suggestedQuality). Точно так же код не должен предполагать, что качество воспроизведения будет меняться только в результате явного вызова setPlaybackQuality или другой функции, позволяющей установить предлагаемое качество воспроизведения.

Значение, сообщаемое событием, указывает новое качество воспроизведения. Возможны следующие значения: small, medium, large и hd720.
onError: Это событие вызывается, если в проигрывателе произошла ошибка. Возможны следующие коды ошибок: 100, 101 и 150. Код ошибки 100 выдается, когда запрошенное видео не найдено. Это происходит, если видео было удалено (по любой причине) или было помечено как личное. Код ошибки 101 выдается, если запрошенное видео не может быть воспроизведено встроенными проигрывателями. Код ошибки 150 означает то же самое, что и 101. Это просто замаскированный 101.

Обработчики событий

На HTML-странице с Chromeless Player должна быть реализована функция обратного вызова onYouTubePlayerReady. API вызовет эту функцию, когда проигрыватель будет полностью загружен и API будет готов к приему вызовов.

onYouTubePlayerReady(playerid): Вызывается после полной загрузки проигрывателя и приведения API в состояние готовности к приему вызовов. Если через аргументы URL проигрывателю передано значение playerapiid, то оно передается этой функции.

Пример

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

Для встраивания любых проигрывателей, доступ к которым будет осуществляться через API JavaScript, рекомендуется использовать SWFObject. Это позволяет определить версию проигрывателя 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. Обратите внимание, что к обычному URL SWF YouTube добавлены параметры enablejsapi и playerapiid, чтобы включить вызовы API JavaScript.
replaceElemIdStr – это идентификатор тега DIV в HTML-коде, который будет заменен встроенным контентом. В приведенном выше примере – ytapiplayer.
widthStr – ширина проигрывателя.
heightStr – высота проигрывателя.
swfVersionStr – минимальная версия, необходимая для отображения контента. В данном случае необходима версия 8 или выше. Если у пользователя не установлена версия 8 или выше, то он увидит строку текста, заданную по умолчанию в теге DIV HTML-кода.
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);
}

Онлайновая демонстрация

Для проверки функций API JavaScript со встроенным проигрывателем или Chromeless Player можно воспользоваться Демонстрацией проигрывателя YouTube. Помимо этого, имеется площадка для экспериментов с кодом Google, предназначенная для отладки вызова кода API проигрывателя JavaScript, где можно увидеть, каким образом код будет выглядеть для пользователя веб-интерфейса.

К началу

API и инструменты YouTube

Начало работы

API данных YouTube

Инструменты проигрывателя YouTube

Дополнительные ресурсы

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

Содержание

Общая информация

Требования

Начало работы

Операции

Функции

События

Обработчики событий

Пример

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

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

Выполнение вызовов

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

Онлайновая демонстрация