Как встраивать видео RUTUBE и управлять плеером: полная справка

Коротко: о чём справка

Официальный FAQ RUTUBE описывает, как встроить плеер с видео, Shorts или трансляцией на сторонний сайт, как задать размер и цвет плеера, моменты начала и конца воспроизведения, а также как встроить контент с доступом «Только по ссылке». Для разработчиков в справке есть расширенные параметры iframe, команды управления плеером через postMessage() и события для отслеживания проигрывания.

Что такое встраивание видео

Эмбед (встраивание) — функция, которая позволяет разместить плеер RUTUBE с конкретным видео на сторонней вебстранице.

Какие видео и трансляции можно встроить

На данный момент доступно встраивание следующих типов контента:

горизонтальные видео с доступом «Для всех»;

горизонтальные видео с доступом «Только по ссылке»;

короткие вертикальные ролики Shorts в формате горизонтального плеера с доступом «Для всех»;

короткие вертикальные ролики Shorts в формате горизонтального плеера с доступом «Только по ссылке»;

трансляции с доступом «Для всех»;

трансляции с доступом «Только по ссылке».

Как встроить видео или трансляцию

На сайте RUTUBE

1. Найдите видео или трансляцию на сайте RUTUBE и нажмите «Поделиться» → «Код вставки плеера».

2. Скопируйте код: кликните по коду или по кнопке «Скопировать». Можно также нажать на видео в плеере правой кнопкой мыши → «Скопировать код для вставки плеера».

3. Вставьте код вставки плеера в код страницы, на которую хотите встроить плеер.

В мобильной вебверсии

1. Откройте видео или трансляцию и в правом верхнем углу плеера нажмите «Настройки» → «Ещё» → «Скопировать код для вставки плеера».

2. Вставьте код вставки плеера в код страницы.

Минимальный размер плеера

Минимальный поддерживаемый размер встраиваемого плеера RUTUBE — 320 × 180 px. Можно задать и другие значения, но корректное отображение элементов плеера не гарантируется: возможны наложения контролов друг на друга и потеря части функциональности.

Через Студию RUTUBE

Видео находятся в разделе «Видео» (https://studio.rutube.ru/videos), трансляции — в разделе «Трансляции» (https://studio.rutube.ru/streams).

1. Нажмите на «три точки» и выберите «Поделиться».

2. Выберите «Код вставки плеера» и скопируйте код кнопкой «Скопировать».

3. Вставьте код вставки плеера в код страницы.

Как встроить Shorts

Ролики Shorts можно встраивать только в формате горизонтального плеера:

1. Откройте нужный ролик.

2. В адресной строке замените слово «shorts» на «video». Например (ссылки приведены как в справке):

до: https://rutube.ru/shorts/a930fc3d073038eaf4fdc962e0e6b5cb/

после: https://rutube.ru/video/ a930fc3d073038eaf4fdc962e0e6b5cb/

3. Нажмите Enter или перезагрузите страницу — ролик откроется в горизонтальном плеере.

4. Скопируйте код вставки плеера: «Поделиться» → «Код вставки плеера».

5. Вставьте код вставки плеера в код страницы.

Дополнительные возможности: настройки до копирования кода

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

1. Размер окна плеера. Замените размер в одном из полей блока «Размеры, px» на нужный; второе поле подстроится автоматически, чтобы сохранить пропорции оригинального плеера.

2. Цвет элементов плеера. Нажмите «Изменить» в блоке «Основной цвет» и выберите цвет из палитры.

3. Начало и конец воспроизведения. Поставьте галочку в чекбоксе «Начало» и/или «Конец» и добавьте таймкод. Выбор часов доступен, только если видео длится больше 59 минут 59 секунд; значение 99 минут автоматически пересчитывается в часы и остаток в минутах, секунды аналогично пересчитываются в минуты.

Дополнительные параметры прямо в коде вставки

Стандартный код вставки без дополнительных настроек для видео по ссылке https://rutube.ru/play/embed/7716bd3e665725c3c008ae7ab4ff02e2:

```html

```

Код того же видео с параметрами — окно 864 × 486 пикселей, красный цвет интерфейса, начало воспроизведения с 5й минуты и окончание на 8й минуте, с отображением названия видео и имени автора канала (пример приведён в справке без изменений):

«Тотальный футбол»: топовый дебют Миранчука, как поменять наш футбол – реформы Гогниева от Тотальный футбол на RUTUBE

Разбор параметров и фрагментов кода:

width="864" height="486" — ширина и высота окна плеера;

autostartmute=true/false — параметр, определяющий старт видео в эмбеде без звука или со звуком;

skinColor=e53935 — основной цвет интерфейса (в примере красный);

t=300 — время в секундах, с которого начнётся воспроизведение (300 секунд = 5 минут);

stopTime=480 — время в секундах, на котором воспроизведение завершится (480 секунд = 8 минут);

frameborder — рамка по периметру окна плеера: 1 — включена, 0 — выключена (по умолчанию);

allow="clipboardwrite; autoplay" — управление буфером копирования и автоматическим запуском видео, если выполнены все условия автозапуска;

webkitAllowFullScreen mozallowfullscreen — запуск плеера в полноэкранном режиме на устаревших версиях браузеров;

allowFullScreen — полноэкранный просмотр из эмбеда; если удалить фрагмент, функция будет недоступна;

… — фрагмент, отвечающий за отображение названия видео; содержит ссылку на встраиваемое видео;

Тотальный футбол — фрагмент, отвечающий за отображение автора канала, с которого взято видео;

RUTUBE — фрагмент, отображающий ссылку на видеохостинг и название RUTUBE; добавляется при проставленной галочке «Показывать название видео»;

q (quality) — начальное качество видео. Доступные значения: 144, 240, 360, 480, 720, 1080, 1440, 2160, auto. Если у пользователя сохранено качество от предыдущих просмотров, при инициализации будет выбрано именно оно;

autoplay={true|false} — переопределяет значение параметра autostart, настроенного на сервере.

Как встроить приватное видео или трансляцию «Только по ссылке»

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

Шаг 1. Откройте видео с ограниченным доступом в Студии RUTUBE и скопируйте его ссылку. Пример прямой ссылки с ID и ключом доступа:

```text

Шаг 2. Откройте видео по скопированной ссылке и нажмите «Поделиться» → «Код для вставки». Пример кода вставки с ID видео, но без ключа доступа:

Шаг 3. Скопируйте из ссылки в браузере ключ доступа — всё после последнего «/» (все ключи видео начинаются с «/ ?p=») — и добавьте его в код вставки через слэш «/» сразу после ID видео. Пример кода вставки с ID и ключом доступа:

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

Если возникли сложности, напишите на help@rutube.ru или в бот поддержки https://max.ru/rutubesupportbot.

Расширенные параметры: встраивание и управление плеером

Настройка воспроизведения

Чтобы встроить плеер RUTUBE на HTMLстраницу, добавьте тег iframe вида:

<iframe width="{width}" height="{height}" src="https://rutube.ru/play/embed/{idvideoparаms}"

frameBorder="0" allow="clipboardwrite; autoplay" webkitAllowFullScreen mozallowfullscreen allowFullScreen

{width}, {height} — ширина и высота встраиваемого плеера; можно задать самостоятельно, но для правильного отображения лучше сохранять стандартные пропорции;

{idvideoparams} — внутренний ID видео на RUTUBE, к которому добавляются дополнительные параметры в формате:

{idvideoparams} : {idvideo} [? {параметр} [& {параметр} [& {параметр} ]]]

Возможны три параметра:

t — момент начала воспроизведения видео в секундах, например t=9876;

skinColor — цвет элементов управления плеера; задаётся 16ричным кодом с информацией об интенсивности красного, зелёного и синего цветов, например skinColor=7cb342;

getPlayOptions — параметр, вызывающий событие player:playOptionsLoaded. После него перечисляются атрибуты: например, getPlayOptions=pgrating,isadult,islicensed,duration,title — тогда data события содержит полную информацию об атрибутах верхнего уровня pgrating, isadult, islicensed, duration, title.

В параметре можно указать только атрибуты верхнего уровня; если странице нужен вложенный атрибут, укажите его «родителя» верхнего уровня. Полный перечень доступных атрибутов — https://rutube.ru/api/play/options/{idvideo} (подставьте ID конкретного видео).

Пример встраивания плеера с параметрами:

<iframe width ="1066" height ="600" frameBorder="0" allow="clipboardwrite; autoplay"

src="https://rutube.ru/play/embed/7716bd3e665725c3c008ae7ab4ff02e2 ?getPlayOptions=pgrating,isadult&skinColor=7cb342&t=6040 "

webkitAllowFullScreen mozallowfullscreen allowFullScreen

Автоподстройка размера для нестандартных окон и мобильных устройств

Чтобы размер окна плеера подстраивался под размер страницы, оберните тег iframe в тег div:

<iframe width="100%" height="100%" src="https://rutube.ru/play/embed/{idvideoparams}"

frameBorder="0" allow="clipboardwrite" allowFullScreen

В изменённом коде параметры {width} и {height} «переезжают» из тега iframe в тег div. Пример встраивания с параметрами и автоподстройкой:

<iframe width="100%" height="100%" src="https://rutube.ru/play/embed/7716bd3e665725c3c008ae7ab4ff02e2?t=6040"

frameBorder="0" allow="clipboardwrite" webkitAllowFullScreen mozallowfullscreen allowFullScreen

HTMLфайл с примером поведения окна плеера с автоподстройкой и без неё — Example01Playerdiv.html. Чтобы проверить работу, меняйте размер окна браузера во время воспроизведения видео.

Управление плеером

Плеер принимает и исполняет команды, которые передаются ему из JavaScript через механизм postMessage():

function doCommand() {

var player = document.getElementById('myplayer');

player.contentWindow.postMessage(JSON.stringify( {CommandJSON} ), '');

}

...

'myplayer' — имя тега , содержащего плеер;

{idvideoparams} — внутренний ID видео на RUTUBE с дополнительными параметрами;

{CommandJSON} — команда и её параметры в формате JSON.

Стандартный формат команды CommandJSON:

```javascript

doCommand(

{type:typeValue, data:dataValue}

);

где {type} — тип команды, {data} — параметры команды в формате JSON. Примеры функций управления приведены в справке без изменений:

function dopause() { doCommand( {type:'player:pause', data:{} } ); }

function dochangeVideo() { doCommand( {type:'player:changeVideo', data:{id:'aaf9fbe99fd8400d6096ef5cc1af404c'}} ); }

function dosetSkinColor() { doCommand( {type:'player:setSkinColor', data: color: Color value is invalid } ); }

function doVolumeDown() { doCommand( {type:'player:setVolume', data: {change: 0.1} } ); }

Для корректного воспроизведения команды player:play, player:pause и player:stop стоит отправлять после готовности плеера — события player:ready.

Основные команды:

// player:play — начать воспроизведение видео

{

type: 'player:play',

data: {}

// player:pause — поставить видео на паузу

type: 'player:pause',

// player:stop — закончить цикл воспроизведения (сброс буфера видео и рекламы)

type: 'player:stop',

Остановка видео с прекращением загрузки и её отмена описаны в справке как пара команд: player:suspend (небезопасный метод) используется вместе с player:wakeup, который возобновляет воспроизведение и восстановление загрузки. В примерах кода справки имена этих команд приведены как player:susupend — сохраняем написание первоисточника.

// player:setCurrentTime — установить текущее время воспроизведения

type: 'player:setCurrentTime',

data: {

time: 20 // время в секундах

// player:relativelySeek — перемотать видео на N секунд вперёд (без знака) или назад (с минусом)

type: 'player:relativelySeek',

time: 20 // time:20 — вперёд, time:20 — назад

// player:changeVideo — загрузить в плеер другое видео

// для quality доступны значения 144, 240, 360, 480, 720, 1080, 1440, 2160, auto

type: 'player:changeVideo',

id: 'xyz123',

params: {

quality:'1080'

// player:changeQuality — изменить текущее качество видео;

// отправлять после загрузки списка качеств (событие player:qualityList)

type:'player:changeQuality',

data:

// player:setSkinColor — изменить цветовую схему

// цвет в RGB, HEX (без решётки «»)

type: 'player:setSkinColor',

color: '39a939'

Управление звуком:

// player:mute — отключить звук

type: 'player:mute'

// player:unMute — включить звук

type: 'player:unMute'

// player:setVolume — установить уровень громкости (значение от 0 до 1)

type: 'player:setVolume',

volume: 0.20

// player:setVolume — изменить громкость: минус — тише, плюс — громче

change: 0.20

HTMLфайл с примером управления плеером — Example02PlayerpostMessage.html.

События плеера и отслеживание статуса проигрывания

Пример подписки на сообщения от плеера:

window.addEventListener('message', function (event) {

var message = JSON.parse(event.data);

console.log(message.type); // some type

switch (message.type) {

case 'player:changeState':

console.log(message.data.state); // Текущее состояние плеера

break;

};

});

Шаблон приходящих сообщений:

```json

"type": 'player:type',

"data": 'some data'

Перечень типов сообщений type и структура значений data:

player:ready — плеер загружен и готов к воспроизведению; отправляется один раз, при вставке плеера на страницу.

"clientId": ,

"videoId": ,

"playerId":

player:init — отправляется после загрузки данных для воспроизведения и выбора типа провайдера; идентификатор плеера playerId здесь всегда один и тот же.

"playerId":"videoframe"

player:playOptionLoaded — отправляется при наличии в query параметра getPlayOptions с перечислением ключей из запроса /api/play/options/57e1cb24939d657284dc2900deb5949a/. Например: ?getPlayOptions=id,thumbnailurl.

"id": 19749029,

"thumbnailurl": " ",

"playerId": "videoframe"

player:changeState — изменилось состояние проигрывания: playing — началось воспроизведение видео, paused — видео на паузе, stopped — конец воспроизведения. isLicensed — у автора видео статус лицензионного автора.

"state": ,

"isLicensed": ,

player:rollState — факт и статус проигрывания рекламы в плеере: type — preroll, midroll, postroll; state — старт или окончание рекламы play / complete.

"type":"preroll5",

"state":"complete",

player:durationChange — обновление или уточнение длительности видео в секундах; событие также отправляется при изменении длительности, например при стриминге.

"duration": ,

player:adRequest — отправляется после загрузки данных по рекламе (did — fingerprint id, axurl — URL для получения рекламы, e — название события для логирования).

"aformat":"preroll4",

"did":"5c6182bc6da219ea5c71003b7055cd3b",

"videoId": "57e1cb24939d657284dc2900deb5949a",

"e":"arequest",

"axurl":" ",

player:adStart — отправляется после старта рекламы; структура данных та же, значение e — astart.

player:adEnd — отправляется после успешного завершения рекламы; структура та же, значение e — aend.

player:currentTime — текущий момент воспроизведения видео в секундах.

"time": ,

player:buffering — диапазоны буферизации.

"range": [

{"start":0,"end":0},

{"start": ,"end": }

],

player:volumeChange — смена уровня громкости: volume — от 0 до 1, muted — выключен ли звук.

"volume": ,

"muted": ,

player:changeFullscreen — переход в полноэкранный режим и выход из него.

"isFullscreen": ,

player:error — ошибка во время проигрывания.

"code": ,

"text": ,

player:playComplete — окончание воспроизведения видео и рекламы, переход плеера на финальный экран.

player:playStart — первый старт проигрывания. В data передаются: идентификатор видео (videoid), автокачество (qa), отображение плеера default/cinema (sm), yclid, viewid (REQUESTID из метаданных запроса либо новый UUID4, если его нет в запросе), идентификатор пользователя user (если он залогинен), cid, pid, страница проигрывания (referer), уровень звука (v), ширина и высота активного уровня качества (qw, qh), тип провайдера (tr) и playerId.

"videoid":"e30edf24ea097b45d0d469fac449478c",

"qa":true,

"sm":"default",

"yclid":"1715854197193969726",

"viewid":"339f02f2c72f0d0f2676c1ec6c069d3b",

"user":null,

"cid":"d65fba3c75a7450db2734e86b0569791",

"pid":"c97972a08269402a82e30192366dc98b",

"referer":"http%3A%2F%2Flocalhost%3A8080",

"v":100,

"qw":1920,

"qh":1080,

"tr":"hls",

player:currentQuality — отправляется при изменении текущего уровня качества: height — высота для текущего качества, quality — текущее качество, isAutoQuality — выбрано ли качество автоматически.

"quality":

{"height":1080,

"quality":"1080",

"isAutoQuality":false

},

В справке также приведён сокращённый вариант структуры этого события:

"quality":{

"height":

player:qualityList — отправляется после загрузки уровней качества видео; в list — перечень доступных значений, например [232,360,480,720,1080].

"list":[ ,..., ],

player:showControls — позволяет отображать все контролы в плеере.

type:'player:showControls'

player:hideControls — позволяет скрывать все контролы в плеере.

type:'player:hideControls'

player:playOptionsLoaded — передаёт атрибуты видео, перечисленные в параметре getPlayOptions, и ID плеера.

Обозначения в структурах данных:

— текстовая строка в кавычках;

— последовательность цифр / число в кавычках;

— число;

— логическое значение true или false;

— атрибуты видео, доступные также по адресу https://rutube.ru/api/play/options/{idvideo}, но только те, которые перечислены в параметре getPlayOptions; частично описаны в разделе «Получение атрибутов видео» справки.

Пример кода, управляющего плеером с учётом его статуса, — файл Example03Playerevents.html. В примере:

видео начинает воспроизводиться со 100й секунды;

по достижении 4х минут воспроизведение продолжается с начала 2й минуты и далее по циклу;

если принудительно перемотать проигрывание дальше 4:10, видео продолжает воспроизводиться до конца;

по достижении конца видео проигрывание переходит к началу 2й минуты и приостанавливается;

под видео отображается информация, полученная из события playOptionsLoaded.

Источник

Официальный FAQ RUTUBE о встраивании видео: https://rutube.ru/info/embed/

Полезно: документация или схема помогают быстрее заметить новые возможности и уточнения API.

Риск: изменение контракта может потребовать правок в интеграции, генерации типов или пользовательских сценариях.