Flussonic Media Server documentation

Events API

What are the events? Anchor Anchor x2

Flussonic has a convenient and flexible system of internal event system with routing and handling.

In version 4.6.14 we have added powerful configuration of event routing and handling.

Events are initiated in different parts of system and can be used for different scenarios.

Configuring event handlers Anchor Anchor x2

Each event handler can be declared in config:

notify handler_name {
    sink http://backend.local/notify.php;
}

Such configuration will create event handler with name handler_name and it will send ALL events to HTTP URL http://backend.local/notify.php.

In this configuration all flussonic events will be send in JSON format as a list of objects.

On a high loaded system it can generate enormous amount of events most of which are not required.

We can reduce event traffic by better configuration:

notify handler_name {
    sink http://backend.local/notify.php;
    only event=stream_started,stream_stopped,source_ready,source_lost;
}

This configuration will send only four specific events to this handler.

Event handler calls are synchronous: event will not be sent to handler if the handler hasn't handled previous event batch.

Event configuration block knows about following configuration options:

sink
Specification of handler. It may be http://URL, https://URL, path_to_lua_script.lua
only
White list of guards. You can specify several key=value or key=value1,value2 options on each only line. You can filter events by their event field, by media field or any other like country or ip. Usually it is event and media. You should read more explicit explanation of this only behaviour.
except
Blacklist of guards. Events matched by any of except fields will not be passed to handler.
buffer
You can use value false to immitate old behaviour of pre-4.6.14 version. Better don't use it.

All other configuration options in this block will be passed to underlying sink handler. In a LUA script they can be accessed via the args table. When using http backend they passed along with other parameters.

Here goes some extra configuration options:

sign_key
You can specify signature key for HTTP event sink. When Flussonic will prepare HTTP POST with JSON body, it will add this secret key to then end of body, make SHA1 hash from it and add it in hex form as a header X-Signature. This can be used for verifying that it is a Flussonic posting events.

Event filtering Anchor Anchor x2

You can pre-filter events before passing them to handlers. It is very important mechanism, try to use it, because it reduce load on your event handler. Each event is prefiltered in the emitter thread before being passed to handler.

Here goes rules for filtering:

  • if ANY except directive fully matches event, it is dropped and not sent to handler;
  • if there are no only directives, events are sent to handler;
  • if there are only directive then event is passed to handler if ANY directive fully matches the event.

Full match of event and directive means that ALL key=value pairs in directive are equal to values in event. If directive has key=value1,value2,value3 pair, then it means that event MUST have ANY of these values to match this directive.

Examples:

  • only event=stream_started; matches {event: "stream_started", media: "cbc"}
  • only event=stream_started,stream_stopped; matches {event: "stream_started", media: "cbc"}
  • only event=stream_started,stream_stopped media=tnt; NOT matches {event: "stream_started", media: "cbc"}
  • only event=stream_started media=cbc group=news; NOT matches {event: "stream_started", media: "cbc"}

List of available events Anchor Anchor x2

Here is a list of known events:

server_started
sent when server has started
listener_start
flussonic is listening on some port for protocol
listener_failure
flussonic has failed to listen on port
config_reloaded
config has reloaded
session_opened
session was opened
session_closed
session was closed
file_opened
file was opened
file_closed
file was closed
stream_started
stream has started
stream_stop
stream is told to stop via API
stream_stopped
stream has stopped
stream_reconfigured
stream has reloaded configuration
stream_motion_started
motion event has appeared on stream (for IP cameras)
stream_motion_stopped
motion event has been closed on stream
source_ready
stream source has received first frames
stream_media_info
stream media info has changed
source_lost
stream source considered to be lost and needs restarting
source_switch
stream source has been switched to another
stream_backup
backup file started playing while source is lost
publish_started
publishing to stream has started
publish_stopped
publishing to stream has finished and you can get lot of valuable information from this event
push_started
stream has started pusher to another source
stream_jpeg
new jpeg thumbnail has been generated
dvr_new_fragment
new DVR fragment has been recorded on disk
dvr_deleted_fragments
old fragments has been deleted from DVR
dvr_new_blob
new hour blob has been opened for recording video to DVR
stream_force_close_gop
error in stream: invalid timestamps are coming or too low FPS
stream_rt_sync
stream had to resync timestamps. May be indication of stream errors if happens too often.
stream_broken_source
stream is refusing to read from current source and decided to completely restart

Examples with sending mail Anchor Anchor x2

Let's learn what can you do with events system. For example you want to receive emails if stream is down.

Simplest configuration will be:

notify no_video {
    only event=stream_stopped,source_lost;
    sink /etc/flussonic/no_video.lua;
    from flussonic@streamer1.my.cdn;
    to admin@my.cdn;
    via smtp://127.0.0.1:5625;
}

This configuration is enough unless you want to filter streams here.

What will be in no_video.lua:

body = "Source lost on following streams: \n"

for _, event in pairs(events) do
    body = body.."  "..event.media.."\n"
end

mail.send({from = args.from, to = args.to, subject = "Source lost", body = body})