Stream Count

Introduction

Vimond Stream Count is a component that helps implementing restrictions on how many concurrent streams are allowed to be active. This is useful where viewing restrictions are imposed by a third-party content owner, for example for live football matches.
In this document we refer to “streams” or “viewing sessions” as a synonym for assets being watched from the same user, potentially logged in from different devices.
For example, if user A is watching an asset from a web player while streaming another asset from the mobile app, then the service understands that user A has two active streams (or viewing sessions).

Vimond Stream Count supports four different types of restriction (rules):

• Global restriction: to be applied to every asset in the catalog
• Category restriction: to be applied to every asset in the category specified, and its sub categories
• Asset restriction: to be applied to a single asset
• Global restriction per user: to be applied to every asset in the catalog for a specific user. This rule, will overwrite any existing rule.

In case that two or more viewing sessions breach one or more rules, kick events will be generated by the service indicating the sessions that are not allowed to keep playing the stream. The streams are blocked in a FIFO mechanism by default but LIFO logic is also supported.

Stream Count Sequence Diagram

The sequence diagram below illustrates the basic stream count flow:

Configuring Stream Count Rules

One or more rules can be defined in order to restrict the number of concurrent streams allowed.
Please contact VIA support for configuring global/category/asset restrictions.

Configure user specific global restriction rule

Any rules on the catalog can be overwritten by using a user-specific global restriction rule. This is configurable via the entitlements claim using the streamcount field.

Claim	Example	Description
https://vimond/entitlements	[ { "svod": "854", "streamcount": "5" } ]	Optional

It is possible to have several stream count rules (one for each entitlements) independent from each other, meaning that if a user has the following entitlements

{
   "https://vimond/entitlements": [
      {
        "svod": "854",
        "streamcount": "1"
      },
      {
        "svod": "478",
        "streamcount": "1"
      }
   ]
}

then it is possible to have two concurrent viewing sessions, one for the svod 854 and one for the svod 478. Please contact VIA support to enable this feature.

📘 In case the entitlements claim is not used, it is possible to specify a stream rule per user by using the legacy claim https://vimond/streamcount, for example
”https://vimond/streamcount” : “4”

Client Integration

Client integration happens via the player session service by posting events at regular intervals. After making a successful play call for a given asset, the play service will include in the response a template of the event that needs to be filled and sent over the player session service

📘 API reference

See Reference: Post player event for how to post a player event from a play call response template

In order for the stream count service to work, the client needs to post a consistent viewing session identifier (field viewingSession in the player event template) throughout the whole video session. This will ensure that the service distinguishes between different viewing sessions initiated by the same user.
The response of the POST request will determine if the current viewing session is allowed to continue or whether it needs to be blocked due to breaking the stream count rules, specifically:

HTTP code	Description
200	The event was posted successfully, the player can keep playing the stream
400	The request was malformed
401	The request was incorrectly authenticated
403	The post event was successful but the stream session was kicked out. More information can be found in the response body.

In order to work properly, the stream count service requires the client device to send at least two events.
When a user session is kicked out, a kick event description for the related session will be sent to all user sessions. However, only the client with the kicked stream session will received a 403 HTTP code.
You can find an example of the kick event below:

{
  "1234-abcd-5678-efgh": {
    "eventName": "kick-event",
    "originator": "vimond-stream-count-limiter",
    "tenant": "vimond",
    "originatorId": "894c0efa-80b4-4f31-a7d9-6532b463babe",
    "versions": [
      "1.0"
    ],
    "timestamp": "2018-02-16T13:01:49.379Z",
    "guid": "84aafbda-31a7-4d57-a35a-ce36515674c9",
    "viewingSessionIdentifier": "1234-abcd-5678-efgh",
    "viewingSession": "1234-abcd-5678-efgh",
    "client": {
      "viewingSession": "1234-abcd-5678-efgh"
    },
    "kickReason": {
      "errorCode": "CATEGORY_ERROR",
      "errorMessage": "Max number (3) active streams for this category is reached"
    }
  }
}

The list of sessions being kicked is kept in memory for 60 seconds, and after that the same session, if it keeps posting events, will be treated as a new one. It is the client’s duty to actually stop the player from keeping on playing and posting events, otherwise the order between sessions might be compromised and originally allowed sessions might be kicked as well.