Playback API documentation version v1

https://client-api.{environment}/api/playback/{version}

  • environment: required(one of magine.com, tvoli.com - default: magine.com)
  • version: required(v1)

Introduction

The Playback service acts as the aggregation layer for all playback related services, including DRM, the preflight check and the playlist service. Error messages will be returned localised and ready for user consumption in clients (see example error responses below).

Playback Preflight

Required request to obtain approval to play content. A play session will be generated that can later be used in license and heartbeat requests.

post

post

Valid DRM and Streaming Protocol combinations:

  • fairplay and hls
  • fairplay and hls-audio
  • widevine and dash
  • widevine and dashs
  • playready and sstr
  • playready and sstrs
  • playready and dash
  • playready and dashs

Valid DRM and Streaming Protocol combinations:

  • fairplay and hls
  • fairplay and hls-audio
  • widevine and dash
  • widevine and dashs
  • playready and sstr
  • playready and sstrs
  • playready and dash
  • playready and dashs

URI Parameters

  • assetId: required(string)

    Example:

    4f93bb80-c01b-11e5-8a26-0002a5d5c51b

Headers

  • Authorization: required(string)

    Global header for authorisation on a normal JWT format.

  • Magine-AccessToken: required(string)

    Global header for all API requests to a specific partner.

  • Magine-Play-DRM: required(one of fairplay, widevine, playready)
  • Magine-Play-Protocol: required(one of hls, hls-audio, dash, sstr, dashs, sstrs)
  • Magine-Play-EntitlementId: required(object)

    A JWT where the Claims permit playback of the requested Asset

    • userId: required(string)
    • assetId: required(string)

      The globally unique id of the video Asset to be played.

    • exp: required(integer)

      When this Entitlement JWT expires (unix timestamp). After that, these Claims are no longer valid.

    • allowedCountries: (array of CountryIsoCode)

      A list of countries (ISO 3166-1 alpha-2) where the User is allowed to play the Asset.

    • offlineExpiration: (integer)

      A time (unix timestamp) in the future when the Offline License must expire. If offlineExpiration is set, offlineAvailable and offlineLicenseDurationSecs should not be used.

    • offlineAvailable: (boolean)

      Decides if Offline License should be available for the User or not. Used together with offlineLicenseDurationSecs.

    • offlineLicenseDurationSecs: (integer)

      The duration in seconds for which the Offline License should be valid, measured from the time the license request is issued. Only used together with offlineAvailable.

  • Magine-Play-DevicePlatform: required(string)

    Can be values such as: web, android, apple, windows, chromecast, amazon-fire, tizen.

  • Magine-Play-DeviceType: required(string)

    Can be values such as: tv, mobile, tablet, desktop, console, internet-of-things.

  • Magine-Play-DeviceModel: required(string)

    Can be set to any value that make sense, such as the manufacturer and model version.

  • Magine-Play-DeviceId: required(string)

    A unique device ID. Should not change.

HTTP status code 200

Body

Media type: application/json

Type: object

Properties
  • playlist: required(string)
  • license: required(string)
  • offlineLicense: (string)
  • certificate: (string)
  • heartbeat: required(string)
  • headers: required(object)
  • playlistDuration: (integer)
  • reloadManifest: (integer)
  • rightsDenied: (array of any)

Examples:

vod:

{
  "playlist": "http://cdn-host.local/assetid/Manifest.mpd",
  "license": "https://magine-host.local/api/playback/v1/widevine/license",
  "heartbeat": "https://magine-host.local/api/playback/v1/heartbeat",
  "headers": {
    "Magine-Play-Session": "uuid"
  },
  "rightsDenied": [
    "offline"
  ]
}

live:

{
  "playlist": "http://cdn-host.local/assetid/Manifest.mpd",
  "license": "https://magine-host.local/api/playback/v1/widevine/license",
  "heartbeat": "https://magine-host.local/api/playback/v1/heartbeat",
  "headers": {
    "Magine-Play-Session": "uuid"
  },
  "playlistDuration": 7200,
  "rightsDenied": [
    "offline"
  ]
}

HTTP status code 400

Body

Media type: application/json

Type: any

Example:

{
  "error": {
    "message": "Unknown Error",
    "user_message": "Okänt fel",
    "code": 1000
  }
}

Playback Heartbeat

Required request every 10 seconds during playback of an asset.

post

post

Headers

  • Authorization: required(string)

    Global header for authorisation on a normal JWT format.

  • Magine-AccessToken: required(string)

    Global header for all API requests to a specific partner.

  • Magine-Play-DRM: required(one of fairplay, widevine, playready)
  • Magine-Play-Protocol: required(one of hls, hls-audio, dash, sstr, dashs, sstrs)
  • Magine-Play-EntitlementId: required(object)

    A JWT where the Claims permit playback of the requested Asset

    • userId: required(string)
    • assetId: required(string)

      The globally unique id of the video Asset to be played.

    • exp: required(integer)

      When this Entitlement JWT expires (unix timestamp). After that, these Claims are no longer valid.

    • allowedCountries: (array of CountryIsoCode)

      A list of countries (ISO 3166-1 alpha-2) where the User is allowed to play the Asset.

    • offlineExpiration: (integer)

      A time (unix timestamp) in the future when the Offline License must expire. If offlineExpiration is set, offlineAvailable and offlineLicenseDurationSecs should not be used.

    • offlineAvailable: (boolean)

      Decides if Offline License should be available for the User or not. Used together with offlineLicenseDurationSecs.

    • offlineLicenseDurationSecs: (integer)

      The duration in seconds for which the Offline License should be valid, measured from the time the license request is issued. Only used together with offlineAvailable.

  • Magine-Play-DevicePlatform: required(string)

    Can be values such as: web, android, apple, windows, chromecast, amazon-fire, tizen.

  • Magine-Play-DeviceType: required(string)

    Can be values such as: tv, mobile, tablet, desktop, console, internet-of-things.

  • Magine-Play-DeviceModel: required(string)

    Can be set to any value that make sense, such as the manufacturer and model version.

  • Magine-Play-DeviceId: required(string)

    A unique device ID. Should not change.

  • Magine-Play-Session: required(string)

    Example:

    c649f119-a2ba-49de-b5c6-4a33841b9297
  • Magine-Play-Timestamp: required(number)

    For live assets this should be set to the current live offset in seconds. For example, if playing ten seconds behind the live point, set it to -10.00 (decimal part is optional but if present it requires use of decimal point, not decimal comma).

    For VOD and catch-up assets this should be set to the number of seconds played into the asset.

    Examples:

    live:

    -10.73

    vod:

    2718.28
  • Magine-Play-Bitrate: required(number)

    The video bitrate the player is currently playing, in bits per second.

  • Magine-Play-ResolutionWidth: required(number)

    The video resolution width of the player

  • Magine-Play-ResolutionHeight: required(number)

    The video resolution height of the player

HTTP status code 200

Body

Media type: application/json

Type: any

HTTP status code 400

Body

Media type: application/json

Type: any

Remove registered devices

Clear the user's registered device list.

delete

delete

DRM - FairPlay

get

get

post

post

HTTP status code 200

Body

Media type: application/json

Type: any

HTTP status code 400

Body

Media type: application/json

Type: any

HTTP status code 401

Body

Media type: application/json

Type: any

HTTP status code 403

Body

Media type: application/json

Type: any

HTTP status code 404

Body

Media type: application/json

Type: any

DRM - Widevine

post

post

HTTP status code 200

Body

Media type: application/json

Type: any

HTTP status code 400

Body

Media type: application/json

Type: any

HTTP status code 401

Body

Media type: application/json

Type: any

HTTP status code 403

Body

Media type: application/json

Type: any

HTTP status code 404

Body

Media type: application/json

Type: any

DRM - PlayReady

post

post

HTTP status code 200

Body

Media type: application/json

Type: any

HTTP status code 400

Body

Media type: application/json

Type: any

HTTP status code 401

Body

Media type: application/json

Type: any

HTTP status code 403

Body

Media type: application/json

Type: any

HTTP status code 404

Body

Media type: application/json

Type: any