/

mediaConstraints And onGetUserMedia


Using mediaConstraints and onGetUserMedia

The Red5 Pro HTML SDK will handle the getUserMedia requirements internally to set up your Camera and/or Microphone for a broadcast. As such, you can provide the Media Constraint object to be used.

WebRTC mediaConstraints

The mediaConstraints default configuration property for WebRTC Publishers.

{
  audio: true,
  video:{
    width: {
      exact: 640
    },
    height: {
      exact: 480
    }
  }
}

Internally, the Red5 Pro HTML SDK will use the provided Media Constraint to test if the resolutions requested are supported by the browser. If not, it will find the nearest supported lower neighbor based on the originally provided area dimension(s) of the resolutions.

For example, if you provide the following for mediaConstraints:

{
  audio: true,
  video:{
    width: {
      exact: 1280
    },
    height: {
      exact: 720
    }
  }
}

... and your browser does not support 720p(HD), most likely the nearest neighbor supported by the browser will be either 800x600(SVGA) or 640x480(VGA), and either of those resolutions will be used in your broadcast.

If you would like to bypass the internal determination of resolution, you can use the onGetUserMedia override of the configuration properties.

onGetUserMedia

The onGetUserMedia method - when defined on the configuration provide to a WebRTC-based Publisher - will override the internal call to getUserMedia in the Red5 Pro HTML SDK.

You can provide your own logic on how getUserMedia is invoked and a Media Stream attained by setting the onGetUserMedia attribute to a method that conforms to the following guidelines:

  • No input arguments are provided to onGetUserMedia.
  • It is expected that a Promise object is returned.
  • A MediaStream object must be provided in the resolve of the Promise.
  • The error provided in the reject of the Promise is optional, but recommended as a String.

An example of providing onGetUserMedia as a configuration:

{
  host: "localhost",
  protocol: "ws",
  port: 5080,
  streamName: "mystream",
  rtcConfiguration: {
    iceServers: [{urls: 'stun:stun2.l.google.com:19302'}],
    iceCandidatePoolSize: 2,
    bundlePolicy: 'max-bundle'
  }, // See https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection#RTCConfiguration_dictionary
  onGetUserMedia: function () {
    return navigator.mediaDevices.getUserMedia({
      audio: true,
      video: {
        width: {
          max: 1920,
          ideal: 1280,
          min: 640
        },
        width: {
          max: 1080,
          ideal: 720,
          min: 360
        }
      }
    })
  }
}

The navigator.mediaDevices.getUserMedia API returns a Promise, but you can define any other method, as long as it returns a Promise and provides a MediaStream on resolve.

Be aware that overriding onGetUserMedia you are losing the logic from the Red5 Pro HTML SDK that attempts to pick the optimal resolution supported by your browser. Use with descretion.

To read more about getUserMedia please read the following document from Mozilla Developer Network: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia