Skip to main content
warning

This page is still under construction! Some information can still be missing and expect spelling mistakes

Triggers/Hooks flowcharts

The trigger/hook system allows you to customize MistServer at nearly every event, allowing you to effectively completely rewrite how Stream data goes in or out of MistServer. Any language can be used together with trigger/hook.

All Triggers/hooks have a set of options:

  • Handler : This determines what script/page gets the trigger payload information.
  • Blocking : When blocking the trigger/hook will await a response and act on it. Otherwise the handler will be reached, but responses are ignored and normal server flow continues.
  • Default Response : When Blocking and the handler fails to answer, use what is filled in here as the answer instead.
  • Applies to: Choose the streams to which this trigger/hook applies.

Handler​

Should a local script be used, MistServer will provide the payload over standard in and expects an answer back of the standard out. If handled as an URL, a POST request is sent to the URL with an extra X-Trigger header containing the trigger name and the payload as the POST body.

Blocking​

Blocking is an important mode for triggers/hooks as it determines whether you're going to change the server flow or not. When set to Blocking MistServer will await an response to the trigger and use the response to change the default behaviour. When non-blocking is used, the handler will still get the payload and fire, however MistServer will not await a response and immediately go to the default behaviour.

Note that even if a trigger is set to non-blocking you could still have it activate a script that affects the server directly through the script itself.

Type of triggers/hooks and when do they activate​

The trigger/hook system is quite massive and there's many points that can be used. For the ease of understand we've divided the triggers in 4 categories and created flowcharts that should hopefully help in finding which trigger might be best for each use-case.

Access Control Hook/Triggers​

These exist to do any form of Access control where you allow viewers/contributors access to MistServer

  • USER_NEW - (Whenever a new session starts, True is allow access (resets after 10min of session inactivity), false is reject)
  • PLAY_REWRITE - ( Whenever playback is attempted, Response overrides the stream playback to the given stream name instead)
  • PUSH_REWRITE - (Whenever an incoming push is detected, override the MistServer Stream target or empty for reject)
  • *RTMP_PUSH_REWRITE - (Whenever an incoming RTMP push comes in, obsoleted by PUSH_REWRITE, override MistServer Stream target or empty for reject)

Lifecycle Hook/Triggers​

These exist to start/continue/stop new or existing connections.

  • CONN_OPEN - (Whenever a connection is accepted, false blocks)
  • CONN_PLAY - (Right before playback after acception, false rejects)
  • LIVE_BANDWIDTH - (Everytime keyframe is received, check bandwidth, if false shut down input)
  • STREAM_PUSH - (Right before an incoming push is accepted, false to reject the push)
  • STREAM_READY - (When a stream finished loading and is ready for playback, if false shut down the input)
  • STREAM_UNLOAD - (Before a stream input is unloaded, if false keep the stream active)
  • PUSH_OUT_START - (Whenever any push to file/target is started, override the target with response or empty for abort)
  • SYSTEM_START - (When MistServer boots, if false shut down the server)
  • SYSTEM_STOP - (When MistServer shuts down, if false abort shutdown)
  • *STREAM_LOAD - (Right before a stream input is loaded, false to abort loading of input. Obsoleted by STREAM_SOURCE which allows for more control at the same event point.)

Configuration Hook/Triggers​

These exist to adjust/change default server behaviour

  • DEFAULT_STREAM - (whenver an unavailable stream is attempted to be watched, can change stream to be used, false for error)
  • STREAM_ADD - (Before a new stream is created, false to reject)
  • STREAM_CONFIG - (Whenever a stream configuration changes, false to reject the changes)
  • STREAM_REMOVE - (Before an existing stream is removed, if false reject the change)
  • STREAM_SOURCE - (When a stream's source is loaded, response overrides the stream source, empty will continue with the current source)

Notification Hook/triggers​

These exist purely to pass on information to another application/endpoint meant to measure, list or log so decisions can be made or logged. These cannot activate a response to the trigger itself and are only there for logging purposes.

  • CONN_CLOSE - ( Whenever a connection closes)
  • INPUT_ABORT - ( Whenever an input process exists with error)
  • LIVEPEER_SEGMENT_REJECTED - ( Whenever a segmented is rejected by MistProcLivepeer with a 422 status twice in a row for different broadcasters)
  • LIVE_TRACK_LIST - ( Whenever valid tracks update/change)
  • OUTPUT_END - ( Whenever an output (push or pull out) stops)
  • OUTPUT_START - ( Whenever an output to another server starts)
  • OUTPUT_STOP - ( When a protocol connector stops listening for connections)
  • PUSH_END - ( Whenever a push (file or target) stops for any reason)
  • RECORDING_END ( Whenever a push to file finishes)
  • STREAM_BUFFER ( Whenever a live stream buffer changes)
  • STREAM_END ( Whenever a stream ends due to viewer inactivity)
  • USER_END ( Whenever a session ends, give statistics of session)

General flowchart​

Live streaming ingest​

Deprecated, DO NOT USE:

  • RTMP_PUSH_REWRITE - Replaced by PUSH_REWRITE which has the same functionality, however works for all incoming push protocols
  • STREAM_LOAD - replaced by STREAM_SOURCE which has the same trigger point, but allows changes instead of just sending a notification.

VoD ingest​

Playback/viewers​

Push output & recording​

Stream processes​

Special mention: Sessions​

While no triggers/hooks directly affect Sessions they are very important as they decide whether certain behaviour is registered as an output, viewer, or not at all and when it is recognised as a previously existing connection. A good example would be USER_NEW which can be used to force new viewers to authenticate with your account system. However should this be done when they switch protocol? When they switch playback token? When they switch IP address?

We recommend reading up on the session system for this reason.