Introduction

This feature allows users to watch catchup television continuously.

This is a "near live" feature that allows user to start watching a catchup item and when it finishes progress to the next item that was broadcast.

Request 

In order to get next playable catchup stream URL, client should provide autoplay=catchup as an URL query parameter ref: PlayableStream related to Recording#/Stream/getChannelStreams

Example request:

curl -X GET "https://api.customer.domain/api/recordings/v1/recordings/123/relationships/streams?autoplay=catchup"

Definitions

autoplay

suggested_start_time

suggested_start_time

API response

The API will include a HATEOAS link with requests for catchup streams that indicates the next item in the series.

The client should look for the presence of a "play_next_catchup" HATEOAS item in the "links" key.  The presence if this property, or whole "links" object is not guaranteed, do not rely on it.

This response will look something like this:

{
  "links": {
    "play_next_catchup": "https://api.customer.domain/api/v1/recordings/456/relationships/streams?autoplay=catchup&suggested_start_time=450"
  },
  "data": [
    {
      "id": 123,
      "type": "Stream",
      "attributes": [
        {
          "profile_name": "string",
          "suggested_market_segments": [
            "fibre"
          ],
          "suggested_start_time": 0,
          "suggested_devices": [
            "string"
          ],
          "codec_info": "string",
          "transport_protocol": "string",
          "streaming_protocols": [
            "string"
          ],
          "bitrate": 0,
          "max_resolution": "string",
          "max_fps": "string",
          "vbr_max_bitrate": 0,
          "stream_url": "string",
          "protection_types": [
            "string"
          ],
          "protection_keys": [
            {
              "type": "string",
              "key": "string",
              "laUrl": "string"
            }
          ]
        }
      ]
    }
  ]
}

Workflow

1. Client calls recording streams for catchup with ?autoplay=catchup parameter (in case user will skip ahead immediately)
2. Client plays the (catchup) recording for a while
3. When it's close to an end, client should make exactly the same call with ?autoplay=catchup parameter, to potentially get updated "play_next_catchup" value.
4. Response might contain play_next_catchup in links
5. After finishing current playback, client shall call the provided URL as is and get new streams. Response might contain "play next" link as well.
6. Client must use suggested_start_time value from provided stream response and start playback from there
7. GOTO 2

Blacklisted items

The API will return items in the sequence that they were broadcast.  This means that if you follow the "play_next_catchup" item in the catchup response you should view the program that was broadcast live immediately after it.

Some programs are blacklisted from the catchup service.

The API will skip these programs and will give you the next valid program for catchup in the "play_next_catchup" key.

This means that the "play_next_catchup" key will consistently be the next item that is available for catchup.

Last catchup program?

If there are no catchup programs available, "play_next_catchup" value will point to live channel streams API, including "restart_at_beginning=true". It means that user will be watching live TV from now on.

In that case response will be :

{
  "links": {
    "play_next_catchup": "https://api.customer.domain/api/v1/media/channels/123/relationships/streams?restart_at_beginning=true"
  },
  "data": [
    {
      "id": 123,
      "type": "Stream",
      "attributes": [
        {
          "profile_name": "string",
          "suggested_market_segments": [
            "fibre"
          ],
          "suggested_start_time": 42,
          "suggested_devices": [
            "string"
          ],
          "codec_info": "string",
          "transport_protocol": "string",
          "streaming_protocols": [
            "string"
          ],
          "bitrate": 0,
          "max_resolution": "string",
          "max_fps": "string",
          "vbr_max_bitrate": 0,
          "stream_url": "string",
          "protection_types": [
            "string"
          ],
          "protection_keys": [
            {
              "type": "string",
              "key": "string",
              "laUrl": "string"
            }
          ]
        }
      ]
    }
  ]
}

Values in "play_next_catchup"

In call cases when "play_next_catchup" is present in the response, it contains a fully-formed stream API URL. Client code must not parse or modify this URL. URL format can change at any time to incorporate new features. While these links can point to different API endpoints (e.g. live streams, recording streams), the response is always in the same format, client code doesn't need to understand which API endpoint is actually used.