Streaming sessions in Flussonic¶

Table of contents¶

1. What is a streaming session
2. Session lifecycle
3. Example
4. Events and session states
5. How to configure events
6. Source connection events
7. 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.

A session is also defined through type and states. Session type defines where a stream is headed. From start to finish, a session goes through states. A 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, they start a new play session. When the viewer 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.

Flussonic has the following types of sessions as an addition to the previous one:

• publish session - when a user publishes video from webcam or OBS.
• ingest session - when Flussonic captures your source, e.g. IPTV (udp://, tshttp://, etc), IP-camera (rtsp://) or any other one (rtmp://, shout://, etc.)
• push session - when Flussonic pushes the stream to other server or service, like Youtube and Facebook, or performs multicast streaming.

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

Have a look at the following scheme as well:

Streaming sessions in Flussonic can be described by OpenAPI 3.0 (learn more here). You can find our public API reference with the description of all methods here.

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:

• A user makes their first HLS request. The play_opened event is emitted as the new play session is opened.
• Authorization backend allows this session, so the 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 the user watches this stream, the 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 the 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.

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)
• 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.

1. 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:

How to configure events¶

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

event_sink example {
  url http://examplehost:5000/events;
  only media=example_stream;
}
stream example_stream {
  input fake://fake;
}

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.

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_started — source_id=7ad153b1-68a5-4304-bbfd-b136603baebd was created.
• stream_updated — bytes, 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 in the API schema.