When to use triggers

Triggers provide infinite flexibility and customization to MistServer. Since the realm of possibilities is so broad it is hard to wrap your head around what is possible. After all nearly every event within MistServer can be used as a trigger for your own customization. To make it easier to understand what triggers can be used for we provide some of the more common usages here.

List of examples

Example usage	Description
Access Control	Blocking certain viewers from playback
Stream Push tokens	Using stream tokens for pushing into MistServer
Viewing tokens	Using view tokens with MistServer.
Redirect offline streams	Redirect viewers to other streams.
Only list watchable live streams	Only show live streams that you can view.
Limit viewers on bandwidth	Block viewers once a bandwidth limit has been reached.

Access control: Limiting content to certain viewers

When do you want to use Access control?

You use Access control if you need some method to determine whether viewers can watch content and need to block others for any reason.

How it works

The session system determines what makes a new viewer based on various metrics. The USER_NEW trigger will activate for any new viewer and will pass on whatever cookies or parameters you wish to use to identify them in your own systems. Using this information allows you to identify who is trying to watch content and grant them access based on your own information.

Components to use	Reason
USER_NEW trigger	Allows you to run checks on new connecting users
Session system	Determine when a viewer is "new"
invalidate_sessions API call	Reset all sessions

• The USER_NEW trigger allows you to run your own logic on newly connecting users. A very simple usage of this would be checking for a cookie or url parameter that you use to identify them in a database of users and if they have an account or paid for the content they are allowed to watch. All this trigger needs is a true response and the viewer can watch.
• The session system is important to decide exactly when you consider someone a new viewer. Do want to identify them only based on IP? Should there be a Token that can be re-used over different playback protocols? Sessions will stay active for as long as the viewer is connected and 10 minutes afterwards. Once expired a viewer will have to renegotiate through the USER_NEW trigger to determine whether access is allowed.
• invalidate_sessions is there to reset the sessions for streams and have everyone renegotiate through the USER_NEW trigger. This can be used to update restrictions on content, say a stream goes from free to paid content.

A more detailed insight on how this would work can be found here

Using stream tokens to push to MistServer

When do you want to use tokens to push to MistServer?

Using tokens grants you security for pushing into MistServer while keeping playback of streams as easy as possible for your viewers.

How it works

Any push towards MistServer requires a stream name, however since the same stream name is used for playback viewers can potentially "steal" a stream push if there's no password or address whitelisting. Tokens serve to solve this by allowing users to push into Mistserver using a (preferably long & randomized) stream name which MistServer can match & redirect towards the correct easier to use stream name for playback.

Components to use	Reason
PUSH_REWRITE	This trigger can redirect incoming pushes to other stream names

The PUSH_REWRITE trigger is especially powerful as it unifies every push method to MistServer and will work regardless of which method your user has chosen to connect to your server. The only thing you need to do is redirect a stream name that corresponds with a token towards the right stream name by answering the stream name it should go to. If there's no match simply return an empty response and the push is denied.

Make sure to only allow tokens and block the actual stream name being used, otherwise you haven't solved anything.

Note: An RTMP only version exists in RTMP_PUSH_REWRITE, this is considered deprecated and inferior to the PUSH_REWRITE trigger.

A more detailed example on why and how to use tokens can be found here. A very simple to understand token example can be found here.

Using tokens to view from MistServer

When do you want to use tokens for viewing?

Using tokens to view from MistServer is like access control. It allows you to block or limit playback depending on your choices, however using tokens also keeps the stream name private.

How it works

The trigger DEFAULT_STREAM redirects any offline (or invalid) stream. This allows you to redirect any stream name attempted to another stream name. This means you can have users attempt to view a unique token, match this with your own database/list and redirect them towards another stream if the token matches. Now whether a token can only be used once or multiple times is up to you.

Components to use	Reason
DEFAULT_STREAM	Allows redirecting of requested streams to another
USER_NEW (optional)	Allows blocking & allowing of new viewers

• DEFAULT_STREAM allows you to check whether a token matches with your own database/list and if it does you can redirect them towards the stream to view. You could keep track of how many times this token has been used and invalidate it after "x" attempts. The only thing the trigger needs to reply is the stream name to send the viewer to, or empty for denial.
• USER_NEW could be needed as well. As DEFAULT_STREAM only blocks view attempts that do not match an existing stream name. Meaning any direct view attempt on the correct stream name has nothing to block unwanted viewers. By adding the USER_NEW trigger you can ensure that only viewers redirected by DEFAULT_STREAM can view. We recommend setting a cookie or parameter for USER_NEW to check against for this.

Redirect offline streams to a fallback

When do you want to redirect to a fallback?

If you want to make sure viewers always have something to view, or if you want to show the latest recording of a live stream when the stream itself goes offline.

How it works

DEFAULT_STREAM redirects any offline (or invalid) stream. In this case if a stream is unavailable (offline) you just have to point them to the latest recording instead by redirecting the playback attempt to whatever the recording has as stream name within MistServer. STREAM_BUFFER will notify you if a stream is available again, which you can then in turn use to tell current viewers to reload to the now live stream.

Components to use	Reason
DEFAULT_STREAM	Allows the redirection of requested streams to another.
STREAM_BUFFER	Get notified if the stream goes back live.
stop_sessid (optional)	Disonnect sessions to move them to live.

• DEFAULT_STREAM will trigger if a stream has gone offline or is unavailable. By using the stream name attempted you can match this to the recordings and give them the latest recording instead. You will obviously need to keep track of this, but if you do the only thing you need to return is the stream name of the latest recording and you're done.
• STREAM_BUFFER will run with a stream state of FULL once a live stream is considered playable. At this point you will need to have any viewer currently playing a recording while they wanted to play the live stream to reload the player with the now live stream.
• Once you know the stream is available, the "best" solution would be to provide the option to go to the live stream on the front end. After all surprising viewers with a stream suddenly switching might be considered bad. However should you wish to just force viewers to the live stream you can use the stop_sessid call. Once you know the stream is back live you can force viewers with sessions that attempted to view the live stream first be stopped, when the player reconnects they are connected to the live stream instead. Just make sure to track whether they have moved on from the live stream as well!

Only list active live streams

When do you want to list only available live streams?

Nothing is more annoying than having a list of streams and some of them being offline or unwatchable. There's two good methods to ensure your listings only contain live streams.

How it works

STREAM_BUFFER will notify you of every live stream that is currently playable. Once a stream hits the state FULL it means every playback protocol can start on immediate playback. This is the moment when you want to show the stream as available.

active_streams is an alternative to the STREAM_BUFFER trigger, but requires polling/monitoring of the state. Where STREAM_BUFFER activates when the state changes active_streams can be used to monitor all current live streams. Any stream that shows up in this call can be considered live.

Components to use	Reason
STREAM_BUFFER	Get notified when a live stream is viewable
active_streams (alternative)	Pull in information about which streams are viewable

Both methods are valid and would work well, it's a matter of preference. Important is that you use either method to build a list of stream names that you can show on your website as available.

Block viewers on bandwidth limits

When do you want to block viewers on bandwidth limits

Whenever you want to impose a maximum amount of bandwidth a stream can pull from your server limiting the amount of viewers is a good idea.

How it works

totals API call can be used to generate the amount of bandwidth in use at any point in time. Requesting this 5 seconds ago guarantees that MistServer has all the information available. This can then be used to block viewers through USER_NEW. USER_NEW will be checked every time a new viewer tries to connect. This will have to check if the current bandwidth is above a limit and if so deny the viewer. invalidate_sessions API call can be used on any viewer no longer actively watching to clear up any blocks imposed on previous viewers.

Components to use	Reason
Totals API call	Get the current bandwidth usage
USER_NEW	Run this when viewers want to watch a stream
invalidate_sessions API call	Clear up previous blocks

The totals API call can be used with:

'"totals":{"streams":["STREAMNAME"],"fields":["upbps"],"start":-5}'

This will give you the current total bytes served at the requested point. Requesting 5 seconds ago guarantees you of an reliable measure as some statistics backfill in about 1-3 seconds.

The USER_NEW trigger should use the totals call to determine whether a new viewer can be allowed at this time.

invalidate_sessions API call should be used when the totals call goes under a "safe" number. That way you will re-allow any previous blocked sessions. Otherwise blocked sessions will stay blocked for 10 minutes (by default) after their last attempt to view. Previously allowed session will time-out after 15 seconds so these should be less of an issue