Skip to content

Change playback settings

This guide shows how to let the user select the video quality, the audio track and the subtitles. The data comes from the /stream response. See Play a video.

Before you start

Make sure that:

  • Your application plays the video. See Play a video.
  • You send lang in the /stream request. The response uses this language for the names of the qualities, the audio tracks and the subtitles. It also uses lang to select the default audio track.

WARNING

The manifest (src) can contain more audio tracks and qualities than the /stream response. Your key can use only the items of the /stream response. Show only these items to the user.

The audio tracks in the response also depend on the settings of your key. Partner keys do not get 5.1 audio tracks. If your key does not allow the tracks that require subtitles, the response does not contain these tracks. If a video has only these tracks, audio_tracks is empty.

The data in the response

{
  "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://…"
      }
    ]
  }
}

The response is shortened. The values are from a test with the language en.

Select the video quality

By default, the player selects the quality automatically (adaptive streaming). To let the user select a fixed quality, use bitrates:

  1. Show the items of bitrates in the quality menu. Use name as the text.
  2. When the user selects a quality, do one of these:
    • Play the src of this item. It contains only this quality. Start the playback at the current position.
    • If your player can select a variant in the manifest, find the variant with the name {bitrate}p, for example 720p. The name is in HLS NAME or in DASH Representation id. Show only the qualities that are in bitrates and in the manifest.
  3. To go back to the automatic quality, play src of the response again.

With DRM, use the license_server of the same bitrates item.

A 4K version (is_uhd: true) has only one quality: 2160.

Select the audio track

Show the audio menu

  1. Show only the tracks of audio_tracks. Use the order of the array.
  2. Use display_name as the text. To find the language, use lang_iso_639_1 or lang_tag. Do not use lang: it is a MEGOGO code, not an ISO code.
  3. Start the playback with the track that has is_active: true. MEGOGO selects it from lang of the request.
  4. If a track has require_subtitles: true, show it with a mark, for example "with subtitles". See Subtitles.

The same language can have more than one track, for example "Ukrainian" and "Ukrainian with audio description". lang_tag is unique for each track.

Change the track

The method depends on the manifest.

The src URL contains the segment /a/{number}/, for example /a/105/ (HLS version 3, MSS). The manifest contains only one audio track:

  1. In src, replace the first /a/{number}/ with /a/{index}/ of the selected track. Do the same in the src of a bitrates item if you use a fixed quality.
  2. Start the player again with the new URL at the current position.

The manifest has audio tracks (DASH, HLS with more than one audio track):

  1. Find the manifest track with the same lang_tag: HLS LANGUAGE or DASH AdaptationSet lang.
  2. Select this track in the player.
  3. Do not show the manifest tracks that are not in audio_tracks.

Keep the selection of the user for this video. For a series, use the same track for all episodes, if the episode has it.

Select the subtitles

The subtitles array contains the subtitle files (type: srt). Each item has a url. To show the subtitles, load the file and show it in your player.

Each audio track has a subtitles_policy:

Field Use
allowed_subtitles The id values of the subtitles that the user can select with this track. Show only these subtitles in the menu
is_disableable false: the user cannot switch off the subtitles with this track. Do not show "Off" in the menu
preselect The id of the subtitles to switch on when is_disableable is false

When the user selects an audio track:

  1. If is_disableable is false, switch on the subtitles with the id from preselect. The user can change the language of the subtitles, but cannot switch them off.
  2. If is_disableable is true, do not switch on subtitles automatically. Ignore preselect. The user can switch on the subtitles in the menu.

Tracks with require_subtitles: true always have is_disableable: false and preselect. The law requires subtitles for these tracks.

CAUTION

For some subtitles, lang and lang_iso_639_1 are not correct. For example, Azerbaijani subtitles can have the code bn. Use display_name as the text in the menu.

Errors

Problem Cause Action
After you change /a/{index}/: HTTP 404 (HLS) or a manifest without audio (MSS) The index is not from audio_tracks of this response Use only the index values of audio_tracks
The player shows more audio tracks than audio_tracks The manifest has tracks that are not for your key Hide the manifest tracks that are not in audio_tracks. Match by lang_tag
A quality of bitrates is not in the manifest The manifest and bitrates are different Do not show this quality, or play the src of the bitrates item
The names are in a wrong language lang is not in the request Send lang in each /stream request

Next steps