Налаштування відтворення¶

Нижче описано, як дати користувачеві змогу вибирати якість відео, аудіодоріжку й субтитри. Усі потрібні дані містить відповідь /stream (див. Відтворення відео).

Перед початком роботи¶

Переконайтеся, що:

ваш застосунок уже відтворює відео (див. Відтворення відео);
ви передаєте lang у запиті /stream. Цією мовою у відповіді повертаються назви якостей, аудіодоріжок і субтитрів; за lang також вибирається аудіодоріжка за замовчуванням.

УВАГА

Маніфест (src) може містити більше аудіодоріжок і якостей, ніж відповідь /stream. Вашому ключу дозволено лише ті елементи, що є у відповіді /stream, тому показуйте користувачеві тільки їх.

Набір аудіодоріжок у відповіді залежить і від налаштувань вашого ключа. Доріжки 5.1 партнерським ключам не надаються. Якщо ваш ключ не дозволяє доріжок, для яких обов'язкові субтитри, таких доріжок у відповіді не буде. Якщо у відео є лише такі доріжки, audio_tracks буде порожнім.

Дані у відповіді¶

{
  "data": {
    "src": "https://…/a/105/…/playlist.m3u8?…",
    "stream_type": "hls",
    "bitrates": [
      { "index": 5, "bitrate": 720, "name": "High (720)", "src": "https://…" }
    ],
    "audio_tracks": [
      {
        "index": 105,
        "id": 14,
        "lang_iso_639_1": "uk",
        "lang_tag": "uk-x-14",
        "display_name": "Ukrainian",
        "is_active": true,
        "require_subtitles": false,
        "subtitles_policy": {
          "allowed_subtitles": [2922105, 3785765],
          "is_disableable": true
        }
      }
    ],
    "subtitles": [
      {
        "id": 2922105,
        "type": "srt",
        "lang_iso_639_1": "ru",
        "lang_tag": "ru-x-11",
        "display_name": "Russian",
        "url": "https://…"
      }
    ]
  }
}

Відповідь скорочено. Значення отримано під час тесту з мовою en.

Вибір якості відео¶

За замовчуванням плеєр вибирає якість автоматично (адаптивний стримінг). Щоб користувач міг зафіксувати якість, використовуйте bitrates:

Виведіть елементи bitrates у меню якості, підписавши їх значенням name.
Коли користувач вибирає якість, зробіть одне з такого:
- відтворіть src цього елемента — він містить лише цю якість. Відтворення почніть із поточної позиції;
- якщо ваш плеєр уміє вибирати варіант у маніфесті, знайдіть варіант із назвою {bitrate}p, наприклад 720p. Назву містить атрибут HLS NAME або атрибут id елемента DASH Representation. Показуйте лише ті якості, які є і в bitrates, і в маніфесті.
Щоб повернутися до автоматичного вибору якості, знову відтворіть src із відповіді.

Для відео з DRM беріть license_server з того самого елемента bitrates.

4K-версія (is_uhd: true) має лише одну якість — 2160.

Вибір аудіодоріжки¶

Показуйте лише доріжки з audio_tracks у тому порядку, у якому вони йдуть у масиві.
Підписуйте доріжки значенням display_name. Щоб визначити мову, використовуйте lang_iso_639_1 або lang_tag, але не lang: це код MEGOGO, а не код ISO.
Запускайте відтворення з доріжкою, що має is_active: true. MEGOGO вибирає її за параметром lang запиту.
Доріжку з require_subtitles: true позначайте в меню, наприклад «із субтитрами». Див. Субтитри.

Для однієї мови може бути кілька доріжок, наприклад «Українська» та «Українська з аудіоописом». Значення lang_tag унікальне для кожної доріжки.

Зміна доріжки¶

Спосіб залежить від маніфесту.

URL src містить сегмент /a/{number}/, наприклад /a/105/ (HLS версії 3, MSS). У такому маніфесті лише одна аудіодоріжка:

Замініть у src перший сегмент /a/{number}/ на /a/{index}/ вибраної доріжки. Якщо використовується фіксована якість, зробіть те саме в src елемента bitrates.
Перезапустіть плеєр із новим URL з поточної позиції.

Маніфест містить аудіодоріжки (DASH, HLS із кількома аудіодоріжками):

Знайдіть у маніфесті доріжку з тим самим lang_tag: атрибут HLS LANGUAGE або атрибут lang елемента DASH AdaptationSet.
Увімкніть цю доріжку в плеєрі.
Доріжки маніфесту, яких немає в audio_tracks, не показуйте.

Запам'ятовуйте вибір користувача для цього відео. У серіалі вмикайте ту саму доріжку для всіх серій, у яких вона є.

Вибір субтитрів¶

Масив subtitles містить файли субтитрів (type: srt), і кожен елемент має url. Щоб показати субтитри, завантажте файл і виведіть його у своєму плеєрі.

Кожна аудіодоріжка має subtitles_policy:

Поле	Використання
`allowed_subtitles`	Значення `id` субтитрів, які користувач може вибрати з цією доріжкою. Показуйте в меню лише ці субтитри
`is_disableable`	`false`: з цією доріжкою користувач не може вимкнути субтитри. Не показуйте в меню пункт «Вимкнено»
`preselect`	`id` субтитрів, які треба ввімкнути, коли `is_disableable` має значення `false`

Коли користувач вибирає аудіодоріжку:

Якщо is_disableable має значення false, увімкніть субтитри з id, указаним у preselect. Користувач може змінити мову субтитрів, але не може їх вимкнути.
Якщо is_disableable має значення true, не вмикайте субтитри автоматично й ігноруйте preselect. Користувач сам може ввімкнути субтитри в меню.

Доріжки з require_subtitles: true завжди мають is_disableable: false і preselect: для цих доріжок субтитри обов'язкові за законом.

ОБЕРЕЖНО

Для деяких субтитрів значення lang і lang_iso_639_1 неправильні. Наприклад, азербайджанські субтитри можуть мати код bn. Тому для підписів у меню використовуйте display_name.

Помилки¶

Проблема	Причина	Дія
Після заміни `/a/{index}/`: HTTP 404 (HLS) або маніфест без аудіо (MSS)	`index` узято не з `audio_tracks` цієї відповіді	Використовуйте лише значення `index` з `audio_tracks`
Плеєр показує більше аудіодоріжок, ніж є в `audio_tracks`	Маніфест містить доріжки, не призначені для вашого ключа	Приховайте доріжки маніфесту, яких немає в `audio_tracks`, зіставляючи їх за `lang_tag`
Якості з `bitrates` немає в маніфесті	Маніфест і `bitrates` не збігаються	Не показуйте цю якість або відтворіть `src` відповідного елемента `bitrates`
Назви не тією мовою	У запиті немає `lang`	Передавайте `lang` у кожному запиті `/stream`

Що далі¶

Версія посібника 1.4.1, 2026-10-31 · Повідомити про проблему на цій сторінці