Як вбудувати HLS-відео на свій сайт (iframe та hls.js)

HLS (HTTP Live Streaming) — формат, який сьогодні використовує більшість сайтів для відео за запитом. Замість одного величезного MP4-файлу відео описується невеликим текстовим плейлистом, що вказує на кілька версій того самого відео, кожна з яких нарізана на короткі сегменти. Плеєр завантажує кілька сегментів наперед, вимірює, як швидко вони надходять, і перемикається між версіями на льоту. Глядачі з мобільним інтернетом отримують легку версію, глядачі з оптикою — чітку, і ніхто не чекає, поки завантажиться весь файл, перш ніж з'явиться перший кадр.

У цьому посібнику показано два способи розмістити HLS-відео з UFOLOAD на власній вебсторінці: готовий плеєр в iframe, на що піде приблизно хвилина, і власний елемент <video> під керуванням hls.js, що дає повний контроль над сторінкою. Обидва використовують той самий потік, тож можна почати з iframe і згодом перейти на hls.js без повторного завантаження.

Як виглядає HLS-потік з UFOLOAD

Після завантаження файлу конвертер кодує його у відео H.264 і стереозвук AAC в одну–чотири версії: 360p, 720p, 1080p і 2160p (4K). Версія ніколи не буває більшою за джерело, тож із завантаження в 720p вийдуть 720p і 360p, а не збільшене до 1080p відео. Найвища версія, яку ви отримаєте, залежить також від тарифу; актуальні ліміти наведено на сторінці тарифів. Якщо хочете повністю розібратися, як обираються щаблі, прочитайте статтю адаптивні драбини бітрейту.

Кожна версія зберігається як звичайний MP4 з індексом на початку файлу. Коли глядач запускає відтворення, рівень сховища на льоту пакує ці MP4-файли в HLS: майстер-плейлист (master.m3u8) перелічує всі версії з їхньою піковою смугою, роздільністю та кодеками, а кожна версія має власний плейлист чотирисекундних сегментів. Ключові кадри розставлено так, щоб вони збігалися з межами сегментів, — саме це дозволяє плеєру чисто перемикати якість посеред відео.

Плейлист і сегменти віддаються з кеш-нод із заголовком Access-Control-Allow-Origin: *, тож плеєр на вашому домені може запитувати їх напряму. Кожен URL підписаний і має час закінчення дії — це стане важливим далі, коли йтиметься про підхід із hls.js.

Крок 1: завантажте відео й дочекайтеся, поки воно буде готове

Завантажте відео в кабінеті, перетягнувши файл або вставивши пряме посилання, або скористайтеся FTP, WebDAV чи API (приклади на curl, Python і Node.js — у статті завантаження відео через API). Файл проходить статуси uploading, queued, processing і ready; статус failed повідомляється з причиною, і завантаження можна повторити з кабінету. Короткі кліпи готові за кілька хвилин, довгі фільми — довше, а на платних тарифах є пріоритетна черга кодування.

Чекати на завершення не обов'язково. Якщо хтось відкриє плеєр, поки файл ще обробляється, плеєр покаже повідомлення про обробку з прогресом і сам перемкнеться на відео, коли обробку буде завершено. Проте перевірте, що статус — ready, перш ніж публікувати сторінку, щоб її перші відвідувачі не побачили смугу прогресу.

Вам знадобиться ідентифікатор відео. Кабінет показує його в панелі «Поділитися», а API повертає його як public_id — короткий код з 11 символів. Саме цей код підставляється в адресу вбудовування.

Крок 2: вбудуйте плеєр через iframe

Кабінет видає фрагмент коду з iframe одразу після завантаження та в панелі «Поділитися» кожного відео. Він виглядає як перший блок нижче. Замініть VIDEO_ID на ідентифікатор свого відео. Сама сторінка плеєра не індексується пошуковими системами, і для вбудовування це саме те, що треба: у видачі ранжується ваша сторінка, а не фрейм плеєра.

<iframe width="640" height="360"
  src="https://iframe.andromedans.live/e/VIDEO_ID"
  title="My video"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture"
  allowfullscreen></iframe>

Фіксовані розміри в пікселях ламаються на телефонах. Для адаптивної сторінки обгорніть iframe контейнером, що зберігає співвідношення 16:9, і дайте фрейму заповнити його. Плеєр заповнює весь фрейм, тож відео масштабується чисто.

<div style="position:relative;aspect-ratio:16/9;max-width:960px">
  <iframe src="https://iframe.andromedans.live/e/VIDEO_ID"
    title="My video"
    style="position:absolute;inset:0;width:100%;height:100%;border:0"
    loading="lazy"
    allow="autoplay; fullscreen; picture-in-picture"
    allowfullscreen></iframe>
</div>

Параметри, які можна додати до адреси

• autoplay=1 запускає відтворення, щойно плеєр завантажиться. Браузери здебільшого блокують автозапуск зі звуком, тож поєднуйте його з mute=1.
• mute=1 запускає відео без звуку; глядач може ввімкнути звук будь-коли.
• loop=1 запускає відео спочатку, коли воно закінчується.
• t=30 починає відтворення з 30-ї секунди — зручно для посилань на конкретний момент у довшому відео.

Параметр в адресі завжди має пріоритет над тим самим налаштуванням у студії плеєра. Використовуйте студію плеєра для налаштувань за замовчуванням, що діють усюди, — скіна, акцентного кольору, логотипа й розташування кнопок, — а параметри — тоді, коли одна сторінка має поводитися інакше. Можна навіть тримати окремий профіль плеєра для кожного домену вбудовування.

Крок 3 (необов'язковий): відтворюйте потік через hls.js

Iframe — найкоротший шлях, але іноді потрібна власна розмітка: своя панель керування, відео всередині каруселі, події аналітики з вашого коду. Тоді вам знадобиться адреса плейлиста й бібліотека плеєра. Браузери, крім Safari, не вміють відтворювати HLS нативно, тож зазвичай обирають hls.js — JavaScript-бібліотеку, яка подає HLS-сегменти в стандартний елемент <video>. Safari та iOS відтворюють HLS нативно, і вона їм не потрібна.

Адреса плейлиста — це поле links.playback об'єкта відео. Запитуйте її зі свого сервера з API-ключем, бо ключ ніколи не повинен потрапляти в код браузера. Той самий виклик повертає links.expires_at, а посилання підписані й обмежені в часі, тож запитуйте свіже посилання щоразу, коли рендерите сторінку, а не зберігайте його в базі даних.

const BASE = 'https://ufoload.com/api/v1'

export async function playbackUrl(fileId) {
  const res = await fetch(`${BASE}/files/${fileId}`, {
    headers: { Authorization: `Bearer ${process.env.UFOLOAD_API_KEY}` },
  })
  if (!res.ok) throw new Error(`UFOLOAD API: ${res.status}`)
  const { file, links } = await res.json()
  if (file.status !== 'ready') return null // still processing
  return links.playback // signed master.m3u8 URL
}

Якщо потрібен інший термін дії, ніж за замовчуванням, POST /files/{id}/links приймає ttl від 60 секунд до 30 днів і може прив'язати посилання до IP-адреси або cookie. Повний опис — у документації API. Є також публічний ендпоінт GET /api/v1/public/files/{id}, якому не потрібен ключ; його використовують сторінки перегляду та вбудовування, а його посилання дійсні шість годин.

На сторінці створіть плеєр. Блок нижче використовує hls.js там, де він підтримується, у Safari переходить на нативне відтворення, а в інших випадках показує просте повідомлення. Розміщуйте файл бібліотеки у себе або фіксуйте версію, а не завантажуйте щоразу найсвіжішу.

<video id="player" controls playsinline preload="metadata"
       poster="POSTER_URL" style="width:100%;aspect-ratio:16/9;background:#000"></video>
<script src="/vendor/hls.min.js"></script>
<script>
  const video = document.getElementById('player')
  const src = 'PLAYLIST_URL_FROM_YOUR_SERVER'

  if (window.Hls && Hls.isSupported()) {
    const hls = new Hls()
    hls.loadSource(src)
    hls.attachMedia(video)
    hls.on(Hls.Events.ERROR, (_, data) => {
      if (!data.fatal) return
      if (data.type === Hls.ErrorTypes.NETWORK_ERROR) hls.startLoad()
      else if (data.type === Hls.ErrorTypes.MEDIA_ERROR) hls.recoverMediaError()
      else hls.destroy()
    })
  } else if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src // Safari, iOS
  } else {
    video.outerHTML = '<p>This browser cannot play HLS video.</p>'
  }
</script>

Об'єкт відео також містить links.poster для обкладинки й links.sprite для мініатюр попереднього перегляду при наведенні — вони знадобляться, якщо ви робите власну шкалу перемотування. З hls.js ви відмовляєтеся від того, що плеєр UFOLOAD робить за вас: меню якості, розділів, вибору субтитрів, логотипа поверх відео і, коли реклама доступна, реклами. Це і є справжній компроміс, і таблиця нижче його підсумовує.

iframe чи hls.js: що вибрати

Чек-лист для пошуку проблем

• Чорний кадр або нескінченний індикатор завантаження. Відкрийте в браузері панель мережі й знайдіть master.m3u8. Код 403 означає, що посилання прострочене або глядача заблоковано правилом для країни чи IP; запитайте свіже посилання.
• Браузер блокує на HTTPS-сторінці. Усе має працювати через HTTPS. Ніколи не вставляйте адресу http:// в iframe чи hls.js.
• Автозапуск нічого не робить. Браузери блокують автозапуск зі звуком. Додайте mute=1 або в hls.js встановіть video.muted = true перед викликом play().
• Повідомлення про обробку замість відео. Файл ще не готовий. Опитуйте GET /files/{id}, доки status не стане ready.
• Відтворюється лише низька якість. Плеєр стартує обережно й піднімається, щойно виміряє пропускну здатність. Верхню версію також обмежують ваш тариф і ваше джерело; порівняйте зі сторінками тарифів і можливостей.

Коли ваша сторінка запрацює, можливо, ви захочете захистити її від хотлінкінгу або, коли реклама доступна, заробляти на ній. Про це — у наступних посібниках: обмежте, де можна вбудовувати ваше відео і монетизуйте відеосайт за допомогою реклами в плеєрі. Якщо ви ще вирішуєте, де розміщувати відео, чек-лист вибору відеохостингу підкаже, що порівнювати.