On this page

Using the refresh_playlist Parameter in the Qencode API

Introduction

The refresh_playlist parameter enables incremental updates to HLS and DASH playlists during the encoding process, allowing each resolution to be available for playback as soon as its processing is completed. This often means that lower resolution versions are available to watch more quickly, allowing viewers to start streaming the content while higher resolutions are still being encoded.

1
Understanding the refresh_playlist Parameter

The refresh_playlist parameter allows the master playlist (either HLS or DASH) to be updated as resolutions become available. When enabled, the playlist is updated on your specified storage destination each time a new resolution stream becomes available during the encoding process.

Default Value: 0 (disabled)
Enabled Value: 1 (enabled)

2
Setting Up Your JSON API Request

Here's a sample JSON request using the refresh_playlist parameter with multiple resolutions:


{
  "query": {
    "source": "https://example.com/source_video.mp4",
    "encoder_version": 2,
    "callback_url": "https://yourcallback.url/callback",
    "format": [
      {
        "output": "advanced_hls",
        "refresh_playlist": 1,
        "stream": [
          {"audio_bitrate": "128", "size": "640x360"},
          {"audio_bitrate": "128", "size": "852x480"},
          {"audio_bitrate": "320", "size": "1280x720"},
          {"audio_bitrate": "320", "size": "1920x1080"}
        ]
      }
    ]
  }
}

Source: URL of the input video.
Callback_url: (Optional) Your endpoint to receive notifications each time the playlist is updated. If not specified, you can poll the job status using the /v1/status API method.

3
Monitoring Encoding Progress

Using Callbacks:

With refresh_playlist enabled and callback_url specified, you will receive HTTP callbacks as each new resolution becomes available to play. Each callback will include:

Task Token: Unique identifier for the task.
Event: Type of event (e.g., 'queued', 'saved').
Callback_type: "stream" indicates the callback event sent when the master playlist is updated.
Status: Contains the status of the encoding, any errors, and URLs for the updated playlists.

For instance, after the 480p resolution is processed, you'll receive a callback with a payload indicating that the resolution has been added to the playlist, along with other pertinent information like video URL and bitrate.

Polling Status:

If callback_url is not used, you can periodically poll the /v1/status API method with your task token to check the job status. This method will return the same JSON structure containing information about the job status.

Need More Help?

For additional information, tutorials, or support, visit the Qencode Documentation home page Link or contact Qencode Support at support@qencode.com.