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.

It's not possible for AminoTV to track the actual stream consumption because we do not always have control over the distribution network. For example when using a CDN or third party backend we have no sight of what streams are currently active.

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:

User action	API calls	Any additional logic to perform	Endpoint
Before the user is able to play media	GET an index of the current sessions	Check that the number of sessions does not equal or exceed the configured system value	Media play sessions#/Media%20Play%20Sessions/indexMediaPlaySession
When the user starts to play media	POST to create a new session	Store the id of the media playback session locally	Media play sessions#/Media%20Play%20Sessions/postMediaPlaySession
When the user stops playing media	DELETE the session	Use the id that was returned to you in the POST response to identify the resource	Media play sessions#/Media%20Play%20Sessions/deleteMediaPlaySession
Periodically	PATCH the session		Media play sessions#/Media%20Play%20Sessions/patchMediaPlaySession

The user should not be able to manipulate their playback session count themselves; You should not provide the user with a direct means to access the API but rather call it as a side-effect of other user initiated actions.

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

Description	URL	Number of MediaPlaySessions after call is made
User account is not watching anything		0
User starts watching something on their set top box	POST /users/{user_id}/media_play_sessions	1
Another person in the household starts watching something on a their mobile	POST /users/{user_id}/media_play_sessions	2
Each device periodically tells the server that the session is still active	PATCH /media_play_sessions/{media_play_session_id}	2
The second user presses stop on their mobile device		2
The first user switches off the set top box without giving the client a chance to delete their session	DELETE /media_play_sessions/{media_play_session_id}	1 (zombie session)
Some time later the periodic clean up job runs on the server and deletes the zombie session		0

Limiting concurrent media streams