List of all options

Option	Default	Description
Target		DOMelement to insert in the player.
host	false	Overwrite URL to MistServers HTTP output.
autoplay	true	Autoplay upon load.
controls	true	Spawn player controls.
loop	false	Loop upon stream end.
muted	false	Player starts muted.
poster	false	Image to display while loading video.
fillSpace	false	Enlarge player if it's smaller than player resolution.
skin	default	Skin to overwrite the player with.
reloadDelay	10	Time to reload upon error.
urlappend		Appends string to connections the player opens.
setTrack	false	Play the given track selection.
forceType	false	Forces the source to given type.
forcePlayer	false	Force the player to given player.
forcePriority	false	First try given source type or player.
monitor	false	Change quality monitor options and events.
callback	false	Use scripts to control the meta-player.
MistVideoObject	false	Object to use as reference and use for scripting the meta-player
subscribeToMetaTrack	false	Subscribe to a track for metadata updates and select output method

Basic options

These are basic options that can be used to configure the player.

They are set as a key:value pair in the options object. Simply leave out the key if you'd like to use the default value.

target

Target	Should point to a DOMelement into which the player will be inserted
Value	DOMelement
Required	Yes
example	document.getElementById("mist")

host

host	Should contain an url to MistServer's HTTP output, where the player files and stream info should be requested from. If false or not specified, the host player.js was loaded from will be used.
Value	string or boolean false
Example	"http://example.com:8080"
Default	false

autoplay

autoplay	Whether playback should start automatically. If the browser refuses autoplay, the player will attempt to autoplay with its sound muted.
Value	boolean
Default	true

controls

controls	Whether to show controls in the player. If the value "stock" is used, it will not use the Meta-Players skinned controls, but use the underlying player's default controls. Note that this means the meta-player's appearance will vary with the player that has been selected.
Value	boolean or the string "stock"
Default	true

loop

loop	Whether to loop the video. This option is not applicable to live streams.
Value	boolean
Default	false

muted

muted	Whether to start the video with its sound muted.
Value	boolean
Default	false

poster

|poster|Url to an image to display while loading the video. If false, no image is shown.| |Value | string or boolean false| |Example| "/myimage.png"| |Default| false|

fillSpace

fillspace	Whether the player should grow to fill the container when the stream resolution is smaller than the target element.
Value	boolean
Default	false

skin

skin	Change the skin the player should show.
Value	string (name of skin) or object (skin object definition)
Example	"dev" or "default"
Default	"default"

When you place the embed code on your website, you'll notice it will look slightly different from the player you can use to preview your stream in the MistServer Management Interface. This is because the Management Interface uses a skin that is aimed at developers. Should you want to use the developers' skin on your own website, you can use the value "dev".

It's also possible to use a custom skin. This is explained in detail at our skinning documentation.

reloadDelay

reloadDelay	When an error window is shown, this value will be used as the default delay in seconds after which the default action is executed.
Value	Number
Default	10

Note that there may be certain errors which have a different delay time, and that these delays are disabled on the developers' skin.

urlappend

urlappend	Appends the specified string to any connections the player opens. This can, for example, be used to pass a user id and passphrase for an access control system.
Value	String
Default
example	"?userid=1337&hash=abc123"

setTrack

setTrack	If not false, a specific track combination is selected. Use the track type as the key, and the desired track id as its value.
Value	Object or false
Default	false
Example	{video: 1, audio: -1}

A value of -1 can be used to disable the track type entirely. Leave out the track type to select it automatically.

Note that some players may not support track switching.

forceType

forceType	If not false, forces the meta-player to select a source with this mimetype.
Value	String or false
Default	false

A list of some of the more commonly used types can be found below:

• WebRTC: "webrtc"

• WebRTC (WHEP): "whep"

• HLS: "html5/application/vnd.apple.mpegurl"

• HLS(CMAF): "html5/application/vnd.apple.mpegurl;version=7"

• WS/MP4: "ws/video/mp4"

• MP4: "html5/video/mp4"

• WebM: "html5/video/webm"

• DASH: "dash/video/mp4"

• WAV: "html5/audio/wav"

• Progressive: "flash/7"

• RTMP: "flash/10"

• RTSP: "rtsp"

• MP3: "html5/audio/mp3"

Should you wish to request the current mimetypes you can do so directly on the MistServer interface through the developer console:

var list = [];
for (var i in mist.data.capabilities.connectors) {
  var connector = mist.data.capabilities.connectors[i];
  for (var j in connector.methods) {
    list.push(connector.methods[j].type);
  }
}
console.log(list);

You can also use the capabilities API call to look up the methods[type] of a specific connector (output).

forcePlayer

forcePlayer	If not false, forces the meta-player to select the player specified.
Value	string or false
Default	false
Example	"html5"

The following players are available:

Player	Description
"html5"	Native HTML5 player
"videojs"	VideoJS player
"dashjs"	Dash industry reference player
"webrtc"	MistServer WebRTC player
"mews"	MistServer websocket MP4 player
"rawws"	Player for H265
"flv"	HTML5 flash video player
"flash_strobe"	Adobe flash video player
"hlsjs"	Hlsjs player

You can ask a list from your MistServer directly. On any page where the meta-player is available try the following command in the developer console:

console.log(Object.keys(mistplayers));

That will give you a list of the possible players.

forcePriority

forcePriority	This option can be used to override the order in which sources and/or players are selected by the meta-player.
Value	Object or false
Default	false

Use the key source to override the sorting of the sources, the key player to override the sorting of the players.

By default, the meta-player loops through the sources first, and then through the players. To override this, include the key first with a value of "player".

Sorting rules

The value that can be given to source and player should be an array containing sorting rules. If sorting ties on the first rule, the second rule will be used, and so on. The default rule (MistServer's original sorting for sources, and reverse sorting by priority value for players) is always appended to the list, so it does not need to be included.

Sorting rules can take several forms:

• A string, which is the key that should be sorted by.

• An array with two values: the first the key to sort by, and the second..

  • -1 to indicate a reverse sort of this value.

  • an array of values. The array indicates which values should come first, and their order. Any values not in the array will be treated as equal to eachother.

• A function that will be called for every item to be sorted. It will receive the item as its only argument, and items will be sorted using JavaScript's sort() function on the return values.

Examples

forcePriority: {
  source: [
    [
      "type",
      [
        "html5/application/vnd.apple.mpegurl",
        "webrtc"
      ]
    ]
  ]
}

Passing this value will reorder the sources according to these rules: first try HLS sources, then WebRTC ones, then the others in their original order as determined by MistServer.

forcePriority: {
  source: [
    ["type", ["html5/video/webm","webrtc"]],
    ["simul_tracks": -1],
    function(a){ return a.priority * -1; },
    "url"
  ]
}

Passing this value will reorder the sources according to these rules: first try WebM sources, then WebRTC ones, then reverse sort by the sources' value of simul_tracks, then reverse sort by the sources' value of priority, then sort alphabetically by the sources' value of url.

monitor

monitor	Change quality monitor options and events.
Value	Object or false
Default	false

The monitor is part of the meta-player that monitors a stream as it is playing in the browser. It has functions to determine a score, that indicates how well the stream is playing. Should this score fall below a defined threshold, it will take a defined action.

The way the monitor functions can be overridden, in part or in full, by using this option. The default monitor object will be extended with the object passed through this option.

Listed below are the keys of the monitoring object, and their function. A monitoring function should contain, at the very least, these functions:

init()

The function that starts the monitor and defines the basic shape of the procedure it follows. This is called when the stream should begin playback.

destroy()

Stops the monitor. This is called when the stream has ended or has been paused by the viewer.

reset()

Clears the monitor's history. This is called when the history becomes invalid because of a seek or change in the playback rate.

To tweak the behaviour of the monitor, rather than override it in full, other keys can be used.

For example, to automatically switch to the next source / player combination when playback is subpar, pass the below as an option.

monitor: {
  action: function(){
    this.MistVideo.log("Switching to nextCombo because of poor playback in "+this.MistVideo.source.type+" ("+Math.round(this.vars.score*1000)/10+"%)");
    this.MistVideo.nextCombo();
  }
}

The default monitor is as follows:

monitor = {
  MistVideo: MistVideo,         //added here so that the other functions can use it. Do not override it.
  delay: 1,                     //the amount of seconds between measurements.
  averagingSteps: 20,           //the amount of measurements that are saved.
  threshold: function(){        //returns the score threshold below which the "action" should be taken
    if (this.MistVideo.source.type == "webrtc") {
      return 0.97;
    }
    return 0.75;
  },
  init: function(){             //starts the monitor and defines the basic shape of the procedure it follows. This is called when the stream should begin playback.
    
    if ((this.vars) && (this.vars.active)) { return; } //it's already running, don't bother
    this.MistVideo.log("Enabling monitor");
    
    this.vars = {
      values: [],
      score: false,
      active: true
    };
    
    var monitor = this;
    //the procedure to follow
    function repeat(){
      if ((monitor.vars) && (monitor.vars.active)) {
        monitor.vars.timer = this.MistVideo.timers.start(function(){
          
          var score = monitor.calcScore();
          if (score !== false) {
            if (monitor.check(score)) {
              monitor.action();
            }
          }
          repeat();
        },monitor.delay*1e3);
      }
    }
    repeat();
    
  },
  destroy: function(){          //stops the monitor. This is called when the stream has ended or has been paused by the viewer.
    
    if ((!this.vars) || (!this.vars.active)) { return; } //it's not running, don't bother]
    
    this.MistVideo.log("Disabling monitor");
    this.MistVideo.timers.stop(this.vars.timer);
    delete this.vars;
  },
  reset: function(){            //clears the monitor’s history. This is called when the history becomes invalid because of a seek or change in the playback rate.
    
    if ((!this.vars) || (!this.vars.active)) {
      //it's not running, start it up
      this.init();
      return;
    }
    
    this.MistVideo.log("Resetting monitor");
    this.vars.values = [];
  },
  calcScore: function(){        //calculate and save the current score
    
    var list = this.vars.values;
    list.push(this.getValue()); //add the current value to the history
    
    if (list.length <= 1) { return false; } //no history yet, can't calculate a score
    
    var score = this.valueToScore(list[0],list[list.length-1]); //should be 1, decreases if bad
    
    //kick the oldest value from the array
    if (list.length > this.averagingSteps) { list.shift(); }
    
    //the final score is the maximum of the averaged and the current value
    score = Math.max(score,list[list.length-1].score);
    
    this.vars.score = score;
    return score;
  },
  valueToScosubscribeToMetaTrackre: function(a,b){  //calculate the moving average
    //if this returns > 1, the video played faster than the clock
    //if this returns < 0, the video time went backwards
    var rate = 1;
    if (("player" in this.MistVideo) && ("api" in this.MistVideo.player) && ("playbackRate" in this.MistVideo.player.api)) {
      rate = this.MistVideo.player.api.playbackRate;
    }
    return (b.video - a.video) / (b.clock - a.clock) / rate;
  },
  getValue: function(){         //save the current testing value and time
    // If the video plays, this should keep a constant value. If the video is stalled, it will go up with 1sec/sec. If the video is playing faster, it will go down.
    //      current clock time         - current playback time
    var result = {
      clock: (new Date()).getTime()*1e-3,
      video: this.MistVideo.player.api.currentTime,
    };
    if (this.vars.values.length) {
      result.score =  this.valueToScore(this.vars.values[this.vars.values.length-1],result);
    }
    
    return result;
  },
  check: function(score){       //determine if the current score is good enough. It must return true if the score fails.
    
    if (this.vars.values.length < this.averagingSteps * 0.5) { return false; } //gather enough values first
    
    if (score < this.threshold()) {
      return true;
    }
  },
  action: function(){           //what to do when the check is failed
    var score = this.vars.score;
    
    //passive: only if nothing is already showing
    this.MistVideo.showError("Poor playback: "+Math.max(0,Math.round(score*100))+"%",{
      passive: true,
      reload: true,
      nextCombo: true,
      ignore: true,
      type: "poor_playback"
    });
  }
}

callback

callback	This allows other scripts to control the meta-player.
Value	function or false
Default	false

When the meta-player has initialized, and whenever it has thrown an error, the function provided will be called. It will receive the MistVideo object as its only argument.

MistVideoObject

MistVideoObject	Pass an object with this option to save a reference to the MistVideo object, which can then be used by other scripts to control the meta-player.
Value	Object or false
Default	false

For more options please refer to mistvideoobject

It can be important to always have an up to date reference to the MistVideo object. To achieve this, the MistVideo object is saved in the object passed in this option under the key reference, creating the JavaScript equivalent of a pointer.

For example:

var mv = {};
mistPlay("stream",{
  target: document.getElementById("stream"),
  MistVideoObject: mv
});
function killMistVideo() {
  if ("reference" in mv) {
    mv.reference.unload();
  }
}

The variable mv.reference will always point to the MistVideo object that is currently active, so that calling killMistVideo() will unload the meta-player, regardless of where it is in its lifetime.

subscribeToMetaTrack

subscribeToMetaTrack	Subscribes to a metadata channel to receive metadata in sync with audio/video
Value	Array or false
Default	false

When using subscribeToMetaTrack You need to pass it an array of first the track number you want to subscribe to followed by the function to use when metadata is passed.

subscribeToMetaTrack: [1,function(message){

            console.warn("Received metadata message!",message);
            /*
              the content of the message is available in message.data
              the main player class is available as `this`
              for example:
              - this.player.api.pause();
              - this.info.meta.tracks
            */

          }]

Multiple channels can be subscribed in one call

subscribeToMetaTrack: [
            [2,console.warn],
            [3,console.warn],
            [3,console.log]
          ]