Как да вградите 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 (вижте качване на видеа през API за примери на curl, Python и Node.js). Файлът минава през статусите 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 адрес или бисквитка. Документацията на 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.
• Възпроизвежда се само ниско качество. Плейърът започва предпазливо и се качва нагоре, щом измери пропускателната способност. Планът ви и оригиналът също ограничават най-високата версия; сравнете с цените и страницата с възможностите.

Когато страницата ви заработи, може да искате да я защитите от hotlinking или, когато рекламата е налична, да печелите от нея. И двете са описани в следващите ръководства: ограничете къде може да се вгражда видеото ви и монетизирайте видеосайта си с реклама в плейъра. Ако още решавате къде да хоствате, чеклистът за избор на видеохостинг изброява какво да сравните.