Streaming Sessions

Here you will learn what session types exist in Flussonic and what you should know about them.

When a user starts watching a TV channel, he starts a play session in Flussonic terminology. He switches to another channel, it will be another session. Before version 21.02 play sessions were the only kind of sessions that were accounted and reported via events system. You know these sessions from authorization system.

In Flussonic 21.03 new types of sessions appear:

• The publish session, when user publish video from webcam or OBS.

• The ingest session, when Flussonic captures your source, e.g. IPTV (udp://, tshttp://, etc), IP-camera (rtsp://), or pulling any other one (rtmp://, shout://, etc.)

• The push session, when Flussonic pushing stream to other server or service, like Youtube and Facebook, or stream to a multicast group.

The following table classifies the 4 kinds of video streaming sessions based on how each type of session is initiated: ingest, publish, play, and push.

Session lifecycle

Flussonic has a unified lifecycle for all kinds of sessions listed above. Each session is in some state and transitioning from one state to another will issue some event.

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

Example

Here is an example:

• User makes the 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 started with play_started event
• While user watches this stream, periodically the play_updated event is emitted that can be used to save this session info to the middleware.
• After some timeout since the last request, the session is considered closed with the corresponding play_closed event.

Events and session states

When a session opens, its state changes from None to Establishing, and the event opened is generated at this moment. The Establishing state means that the session is not doing any valuable things yet, but it is trying to do them: connecting, preparing, and checking authorization.

A session can always exit with the event closed and go into the state Finished.

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

A session in the Establishing state waits for a first frame or keyframe if it is a source session (ingest/publish), or waits till enough bytes of output for play/push. Then it becomes Running with the started event.

A Running session is updated periodically and you can use this event to track this session. Use the updated event to update your database record for this session as it will overwrite previous data about this session.

A Running session can be altered if the input/output bitrate has changed or media_info has changed.

A Running play or push session can be overflowed if it cannot send output data as fast as it is required. A source (ingest/publish) session can be overflowed only if the underlying protocol can inform us about that just like RTSP/RTCP or SRT can do.

A Running session can even change with stalled to Stalling if it cannot transfer data anymore. This state occurs if it is possible for the session to become recovered back to Running.

Externally initiated sessions like play or publish should be authorized on an external authorization system. This external system must respond to periodic pings on each session and sometimes it can terminate a session with the denied event.

Session fields

You can get all these sessions via the Flussonic's HTTP events sink mechanism as JSON objects.

Here is the list of fields.

How to configure events

Add a notify section, here is an example from our lab:

notify example {
  sink http://mywebserver/event.php;
  only media=example;
}

stream example {
  url tshttp://127.0.0.1/fake/mpegts;
}

This configuration will send HTTP POST requests with JSON body containing sessions described in the section above. Raw messages are too long to show them here but I'll show just some of them.

Source connection events

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

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

• source_started — source_id=7ad153b1-68a5-4304-bbfd-b136603baebd was created.

• stream_updated — bytes, bytes_out for 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

You'll receive the event play_opened when a client connects to a stream via HLS:

  [{
    "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 that we got in the previous example. All events are linked to each other via the source_id parameter.