Introduction

AminoTV supports helping clients track concurrent viewing across multiple devices by providing an API for them to interact with.

Clients can use this API to give an approximation to how many streams a user account is watching.

Implementation

The MediaPlaySession entity

Amino models a MediaPlaySession in the domain language as an entity that can be used to track playback sessions for a user.

An example of the API response representing this resource is:

{
  "data": [
    {
      "type": "MediaPlaySession",
      "id": "6b6bf3e1-555b-45cb-b5d3-63a2ff7be9e3 ",
      "attributes": {
        "service": "live",
        "ip4_address": "86.190.137.158",
        "user_agent": "Set Top Box",
        "play_started_timestamp": 1551091684,
        "last_updated_timestamp": 1551091736
      }
    }
  ]
}

Note that the IP address is not sufficient to identify a session;  A person watching on the STB at home may have the same IP address as somebody watching on their mobile phone upstairs on the same home router Wi-Fi network.

Managing sessions

The client should call the MediaPlaySession based on user activity, as below:

Creating a new session

The client should retrieve an index of the current sessions so that it is able to tell the user whether she can start a new stream or not.

If the client has reached their maximum number of sessions then the frontend should not allow the user to play media.

When the user starts playing media the client should POST to the endpoint detailed above to create a new session.

When the client calls the API to create a new session the server will check the number of sessions that already exist.

If the account is not allowed to play another stream then the API will respond with a "403 Forbidden" error, with a body as below:

{
  "id": 56071904,
  "code": "df1e80a",
  "title": "Too many sessions",
  "details": "You have tried to open a new playback session but you are already at the maximum allowable limit.  You need to stop playing content on another device in order to watch on this one."
}

Periodical PATCH calls to the session

The client is expected to periodically PATCH the session to update the "last_updated_timestamp" field to the current unix timestamp.

This is used by the server to determine if a particular session is being actively watched.

Sessions that are not updated will be removed by the server after a set interval. Note that this will not affect playback, the client will still be able to watch the stream even if the MediaPlaybackSession is removed. 

Therefore, it is essential that the client calls PATCH in order to prevent the server from incorrectly assuming the session is no longer active.

Example flow