Playback API

watch.stream.session.playback

The Playback API enables you to start the playback of a video.

Endpoint

POST v4/watch/stream/{screener_key}/playback

Headers

Depending on the type of screener and the configuration settings, either a JWT token or an API key must be provided in the Authorization header. This allows you to ensure secure controlled access to Indee screeners, tailored to the specific requirements of your screener configurations.

JWT Token

If the product does not permit link-type screeners and the force-login option is enabled for the screener, a JWT token must be included in the Authorization header. This applies only to Publicity screeners and ensures that playback requests are securely authenticated.

Header	Value
Authorization	JWT token

API Key

If the product allows link-type screeners and force-login is not enabled, the API key can be used in the authorization header for authentication. This provides flexibility and ease of access for users while maintaining security.

Header	Value
Authorization	Bearer api_key

ClientID

A ClientID header is required on every request. It must consist of four hyphen-separated components, the first of which identifies the platform.

Header	Value
ClientID	platform-\<id>-app_version-\<id>

Accepted platform values are web, roku, firestick, fireos, appletv, ipad and tizen.

Request Body

    {
        "stream_protocol": "dash",
        "enable_5_1": true,
        "offline": true,
        "hdr": {
            "hdr10": true
        },
        "credentials": <credentials>
    }

Parameter	Type	Requirement	Description
stream_protocol	String	Required	The protocol used for streaming. Values accepted are: hls, dash.
enable_5_1	Boolean	Required	Enables 5.1 surround audio for the playback session.
offline	Boolean	Optional	Allows viewing in offline mode. This is currently supported only for iPad and valid only if stream protocol is hls.
hdr	JSON	Optional	Map of HDR standard code to a boolean indicating the standards the player supports. HDR is enabled only when a requested standard matches the one the title was mastered in and HDR is permitted for the screener.
credentials		Optional	If the screener is password-protected, the password needs to be passed in the request to get the playback info. See below for more.

Credentials

If the screener is password-protected, the password needs to be passed in the request to get playback information as below:

    {
        "password": "abcd12345@"
    }

If the screener has 2FA protection where the viewer needs to verify with a phone number, the one-time passcode received as a text message needs to be passed in the request to get playback information. The schema would be as below:

    {
        "passcode": 123456
    }

Response

    {
        "session_key": "ssn-01j1f9m09mfy2a98jy5d8rftxx",
        "session_expiry_in_secs": "<int>",
        "engagement": {
            "push_interval": 30
        },
        "drm": {
            "provider": "ezdrm",
            "license_url": "https://widevine-dash.ezdrm.com/proxy?pX=3B1xxD&sk=W4UHcGauhsZ610qdnFxxIhm-fezUvXWbOy9t041UxxE%3D&server_url=https://api.indee.tv/api/v1/videos/drm/widevine/",
            "custom_headers": {
                "headername1": "headervalue1",
                "headername2": "headervalue2"
            },
            # Sample only. The certificate_url won't be a part of this response as the request is for DASH playback.
            # It is returned only when the request is for HLS playback.
            "certificate_url": "https://mediahost.indee.tv/fairplay.cer"
        },
        "manifest": {
            "url": "example.com"
        },
        "status_code": "W0000",
        "status_message": "Success"
    }

Field	Type	Description
session_key	String	Unique identifier for the playback session being initiated.
session_expiry_in_secs	Integer	Lifetime of the playback session, in seconds.
engagement	JSON	Captures the engagement data for the video streaming.
push_interval	Integer	Seconds interval at which engagement data is pushed.
drm	JSON object	The encryption data associated with your DRM.
provider	String	Third party provider for DRM service. Values returned are ezdrm, vudrm or DRMTODAY.
license_url	String	URL of the DRM license.
custom_headers	JSON	Custom headers to be passed along with all DRM license requests for playback. This varies depending on the provider.
ceritificate_url	String	This is returned only for hls playback.
manifest	JSON	The streaming manifest to load in the player.
url	String	URL of the streaming manifest.
status_code	String	The Indee status code for the response.
status_message	String	Human readable message describing the response.

The response also carries a signature header containing a signature of the response body.

Status Codes

Indee status code	HTTP Response Code	Description
W0000	HTTP 200	Success
W2000	HTTP 401	Authorization header was either not passed or there was some issue parsing it
W2001	HTTP 401	API key is invalid or expired, or is not fully configured
W2003	HTTP 401	Invalid or expired auth token
W2007	HTTP 401	Viewer sign-in is required to play this screener
W2009	HTTP 401	ClientID header was either not passed or is malformed
W2008	HTTP 403	The screener password or passcode supplied is invalid
W2010	HTTP 403	Concurrent stream limit reached
W2011	HTTP 403	Video is not ready. Please try again after some time
W2012	HTTP 403	The title is being re-processed and will be ready soon
W2100	HTTP 403	Not authorized to play this screener, or the origin domain is not whitelisted
W2108	HTTP 403	Watch product is inactive
W2102	HTTP 451	Request blocked by geofencing for the resolved region
W4200	HTTP 400	The screener is either expired or invalid
W4900	HTTP 400	Malformed request body, or a required credential was not supplied
W5001	HTTP 429	Rate limited
W5000	HTTP 500	Unknown server error occurred

DRM License Response Formatting

When the DRM provider is DRMTODAY, FairPlay responses are returned as Base64 encoded data and will need to be decoded for usage by the CDM for both the Browser and iOS.

Browser Example:

// Assume the raw license response is taken named rawLicenseBase64
let rawLicenseString = atob(rawLicenseBase64);
// Convert that string into a Uint8Array
let data = new Uint8Array(rawLicenseString.length);
for (let i = 0; i < rawLicenseString.length; ++i) {
    data[i] = rawLicenseString.charCodeAt(i);
}
let licenseData = data.buffer;
// Load licenseData into CDM however player framework utilizes this (usually in license interceptors)

iOS Example:

NSData *licenseData = [[NSData alloc] initWithBase64EncodedData:rawLicenseBase64 options:0];
// Load licenseData into CDM using this as a response to the
// getContentKeyAndLeaseExpiryfromKeyServerModuleWithRequest method for AVPlayer.