Broadcast from a browser with the Amazon IVS web broadcast SDK

<script src="https://web-broadcast.live-video.net/1.0.0/amazon-ivs-web-broadcast.js"></script>

2. Instance the AmazonIVSBroadcast Client

The SDK exposes a global variable in the window scope named IVSBroadcastClient, and we can create an instance of the client by calling the create method with the streamConfig parameter. This parameter comprises the IVS channel class configuration, (standard channel full HD 1080p or basic channel, SD 480p) and the camera orientation mode, landscape or portrait.

Let’s assume a streaming landscape with full HD resolution for this sample integration.

IVSBroadcastClient.STANDARD_LANDSCAPE;

We also need to provide the ingest endpoint, which can be obtained in the AWS Management Console or returned by the Amazon IVS API using actions like CreateChannel or GetChannel.

In the Amazon IVS Console, find your channel and then the Stream configuration section. Under “Other ingest options,” copy the ingest endpoint, and also copy the Stream Key, which will be used in a later step as a parameter to start the live broadcast.

Now we can instance our client configuration.

const client = IVSBroadcastClient.create({
    // Enter the desired stream configuration
    streamConfig: IVSBroadcastClient.STANDARD_LANDSCAPE,
    // Enter the ingest endpoint created above
    ingestEndpoint: 'uniqueID.global-contribute.live-video.net',
});

3. Handle browser authorization and get the stream

Your application may handle browser permissions with the MediaDevices API using the getUserMedia method. That provides access to connected media input devices such as cameras, microphones, and screen sharing. The MediaStream audio and video tracks can then be added as an input device to the SDK.

4. Get MediaStream tracks

The getUserMedia method requests the user for permission to use a media input and produces a MediaStream with tracks containing audio and video tracks.

const videoParams = {video:true}
const audioParams = {audio: true}

window.cameraStream = await navigator.mediaDevices.getUserMedia(videoParams);
window.microphoneStream = await navigator.mediaDevices.getUserMedia(audioParams);

Note: The API MediaDevices also provides the enumerateDevices method that allows listing available devices, and we can filter the audio and video input array. Please refer to the sample application.

If you are using a composed canvas element to add filter or overlay in to your video element, the cameraStream needs to be captured using the method HTMLCanvasElement.captureStream().

window.cameraStream = canvas.captureStream(30);

5. Add stream to the IVS web broadcast SDK

If permission is granted, we can proceed to add the device stream to the Amazon IVS web broadcast SDK.

client.addVideoInputDevice(window.cameraStream, 'camera1', { index: 0 });
client.addAudioInputDevice(window.microphoneStream, 'mic1');

6. Start live streaming

Now that we have audio and video tracks, let’s start the broadcast by using the startBroadcast method. Provide the stream key from step 2 as a parameter.

client
    .startBroadcast(streamKey)
    .then((result) => {
        console.log('I am successfully broadcasting!');
    })
    .catch((error) => {
        console.error('Something drastically failed while broadcasting!', error);
    });

7. Stop live streaming

client.stopBroadcast();

General tips

• Browser permissions: user consent is required when capturing the video from a browser using the MediaDevices.getUserMedia. On the first page load, the browser prompts a dialog box asking users to allow or block access to the devices. If the user does not ALLOW device access in the browser, after the initial denial, the browser will not prompt anymore and the application cannot capture video. Therefore, we recommend providing a clear explanation to the end user about why and how to allow access to devices to stream audio and video from the browser. You may also want to re-prompt the permission in case it is initially denied.

• The method enumerateDevices() returns a MediaDeviceInfo array describing the devices. In your application, you may want to provide the list of cameras and microphones as an input selection in a form. When the user selects a different device, the application will need to update the deviceId passing the current value to the method getUserMedia({video:{deviceId: activeSource}}). The newly selected device will also need permission to access the MediaStream. The Amazon IVS web broadcast SDK allows you to change the camera and microphone during the transmission based on user-allowed devices (including using the method exchangeVideoDevicePositions to capture the video from a different view, like switching from rear to front camera).

client.exchangeVideoDevicePositions('camera1', 'camera2');

• WebRTC dynamically chooses the best bitrate and resolution for the resources available, and the streamer needs to consider at least 200 Kbps of upload to ensure good quality streaming.

Get started now using the Amazon IVS web broadcast SDK

The Amazon IVS web broadcast SDK allows customers to stream from their browsers with minimal setup. Follow the Getting Started guide to implement the SDK and leverage key features like high-quality streaming, automatic bitrate adjustments, secure streaming, multiple input sources, stream controls, and camera swap. Use the sample app to get started or demo the features using stream.ivs.rocks.