Skip to content

Streaming Sessions in Flussonic

Table of contents

  1. What is a streaming session
  2. Session lifecycle
  3. Example
  4. Events and session states
  5. Session parameters
  6. How to configure events
  7. Source connection events
  8. Playback started event

What is a streaming session

Streaming session in Flussonic is a temporary and interactive information interchange between Flussonic Media Server and an external system. An external system refers to:

  • a headend,
  • a player,
  • another server (either Flussonic or not) and etc.

Session is defined by the time interval, e.g. it is established at a certain point in time and then brought to an end at some later point. During a session at least one of the communicating parties needs to hold current state information and save information about the session history in order to be able to communicate.

Session is also defined through type and states. Session type defines where stream is headed. From start to finish session goes through states. Session may be initiated by the initiator, however, either an initiator or a receiver may terminate it.

Here we will discuss what session types exist in Flussonic and what there is to know about them.

Let us consider the following example. When a viewer starts watching a TV channel, he starts a new play session. When he switches to another channel, it is considered to be a start of another session. To put it simply, one viewer and one channel — one session.

Versions prior to 21.02 could track only play sessions via events system. If you have used the authorization system, this type of sessions should sound familiar to you.

In Flussonic 21.03 new types of sessions appear as an addition to the previous one:

The following table classifies these 4 types of video streaming sessions based on the initiator: ingest, publish, play, and push.

Initiated by to Flussonic from Flussonic
User publish play
Flussonic ingest push

Have a look at the following scheme as well:

Types of video transmission

For more information, see Types of video transmission with Flussonic Media Server.

Session lifecycle

Flussonic has a unified lifecycle for all kinds of sessions listed above. Each session has a state and transitions from one state to another, that raises an associated event.

The name of the event is made up of two elements (session type and event type), divided by an underscore (_).
For example: play_opened (session type: play, event type: opened).

For reasons of convenience ingest and publish sessions issue events under the same name: source.

Example

Here is an example of a play session:

  • User makes his first HLS request. The play_opened event is emitted as new play session is opened.
  • Authorization backend allows this session, so play_authorized event is emitted.
  • The player starts fetching segments, this session passes the threshold and now it is considered to be started, raising play_started event.
  • While user watches this stream, play_updated event is emitted from time to time so that the information about this session can be saved to the Middleware.
  • After some timeout since the last request the session is considered to be closed, raising the corresponding play_closed event.

It can be represented with a following diagram:

As we have just considered a specific instance (play) of session types, let's move to the general approach.

Events and session states

The diagram below represents the states that a session in Flussonic can possibly go through and events that are raised along this process.

Note

We'll name session states with a capital letter, while events and session types — with a lowercase letter.

How do states change?

When a session starts, its state changes from None to Establishing, and the event opened is raised. The Establishing state means that the session is connecting (connected event), preparing and checking authorization (authorized event), e.g. no streaming is done yet.

A session can always end raising closed event and, thus, reach a state Finished.

Sessions publish and play can emit the authorized event in Establishing state and while Running.

During the Establishing state a session either:

  • waits for the first frame or a keyframe in case it is a source session (ingest/publish)
    or
  • waits till there is enough bytes for the output for play/push.

Then the state is changed to Running, raising the started event.

To track the session event updated is emitted from time to time within the Running state. Use the updated event to update your database record for this session as it overwrites previous data about this session.

Changes in input/output bitrate or media_info in the Running state result in an altered event being emitted.

overflowed event can raise in Running state in two cases:

  1. for play or push:
    If it is not possible to send the output data as quick as asked to.

  2. for source (ingest/publish):
    If the underlying protocol informs us of that just like RTSP/RTCP or SRT do.

if the data cannot be transfered anymore, state Running changes to Stalling, raising stalled event. This state occurs if it is possible for the session to recover back to the Running state, emitting recovered event.

Externally initiated sessions like play or publish should pass the authorization with the help of the external authorization system. This external system must respond to periodic session pings. It can also terminate session, raising the denied event.

To sum up, have a look at the table below:

| States transitions | Session type | Events raised | |----------------|--------------| | None -> Establishing | source (ingest/publish), play, push | opened | | [Establishing, Running, Stalling] -> Finished | source (ingest/publish), play, push | closed | | Establishing -> Establishing | source (ingest/publish), play, push | authorized (publish and play), connected | | Establishing -> Running | source (ingest/publish), play, push | started | | Running -> Running | source (ingest/publish), play, push | selected, updated, authorized, altered, overflowed | | Running -> Stalling | source (ingest/publish), play, push | stalled | | Stalling -> Running | source (ingest/publish), play, push | recovered |

Session parameters

You can get all the information about sessions via Flussonic HTTP events sink mechanism as JSON objects.

Here is a list of parameters.

Note

This list may be a subject to change in the future. Flussonic can send additional undocumented fields. We do not recommend using them as they can be changed or removed at any moment.

Parameter Name Type Description
opened_at integer, milliseconds session creation time
id string uuid session unique ID
ip string ip peer IP (client, source, push target, etc.)
proto string protocol exact protocol that is used for the video delivery
media string stream/file name
bytes integer number of bytes transmitted within this session
duration integer, milliseconds duration of this session. Not changeable after closed event
user_id string user_id provided by an auth backend for this session
token string user provided auth token

How to configure events

Add a [notify section to the configuration file (/etc/flussonic/flussonic.conf).
Here is an example:


notify example {
  sink http://mywebserver/event.php;
  only media=example;
}
stream example {
  url tshttp://127.0.0.1/fake/mpegts;
}

With this configuration an HTTP POST requests with JSON body will be sent, including sessions described in the section above.

For more information on configuring events handlers, see Configuring event logging](events-api.md#api-events-event_handling).

Source connection events

In the example below you can see a series of events, when Flussonic connects to the source:

  • source_connected — an HTTP connection ("status":"http_connect") started.

  • source_startedsource_id=7ad153b1-68a5-4304-bbfd-b136603baebd was created.

  • stream_updatedbytes, bytes_out for the source_id=7ad153b1-68a5-4304-bbfd-b136603baebd were updated.


[{
  "event":"source_connected",
  "event_id":1023,
  "id":"4f3c7cec-5c36-4670-921b-a0dcd4a6f0c8",
  "loglevel":"info",
  "media":"example",
  "priority":1,
  "proto":"tshttp",
  "server":"mk1.e",
  "status":{"status":"http_connect"},
  "url":"tshttp://127.0.0.1/fake/mpegts",
  "utc_ms":1614524093408
 },{
  "dts":93606612.44444445,
  "event":"source_started",
  "event_id":1027,
  "id":"4f3c7cec-5c36-4670-921b-a0dcd4a6f0c8",
  "loglevel":"info",
  "media":"example",
  "priority":1,
  "proto":"tshttp",
  "server":"mk1.e",
  "source_id":"7ad153b1-68a5-4304-bbfd-b136603baebd",
  "url":"tshttp://127.0.0.1/fake/mpegts",
  "utc_ms":1614524093414
 },{
  "bytes":0,
  "bytes_out":0,
  "event":"stream_updated",
  "event_id":1028,
  "id":"82c59180-e64e-42fc-8f11-2dec111ca5f7",
  "loglevel":"debug",
  "media":"example",
  "opened_at":1614524093399,
  "server":"mk1.e",
  "source_id":"4f3c7cec-5c36-4670-921b-a0dcd4a6f0c8",
  "utc_ms":1614524093415
  }]

Playback started event

The event play_opened is raised when a client connects to an HLS stream:


  [{
    "bytes":0,
    "country":null,
    "event":"play_opened",
    "event_id":1064,
    "id":"24b79b95-7400-4da2-bf9c-a855603baed1",
    "ip":"192.168.100.7",
    "loglevel":"debug",
    "media":"example",
    "opened_at":1614524113129,
    "proto":"hls",
    "query_string":"token=test",
    "referer":null,
    "server":"mk1.e",
    "source_id":"82c59180-e64e-42fc-8f11-2dec111ca5f7",
    "token":"test","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.192 Safari/537.36",
    "user_id":null,
    "user_name":"example",
    "utc_ms":1614524113129
   }]

Note that "source_id":"82c59180-e64e-42fc-8f11-2dec111ca5f7" is the same ID as in the previous example. All events are connected with each other through the source_id parameter.

Events associated with sessions are listed on the page Events API.