Web co-streaming SDK API reference

Lists the classes, methods, and events in the ApsaraVideo Live Web co-streaming SDK for stream ingest and stream pulling.

Basic classes

Class			Description
AlivcLivePusher			Stream ingest class. Note Access via window.AlivcLivePush.AlivcLivePusher.
AlivcLivePlayer			Stream pulling class. Note Access via window.AlivcLivePush.AlivcLivePlayer.

AlivcLivePusher (stream ingest)

List of methods

Method			Description
getCameras			Queries cameras. Static method.
getMicrophones			Queries microphones. Static method.
getPlayoutDevices			Queries playback devices. Static method.
checkSystemRequirements			Checks WebRTC requirements. Static method.
checkScreenShareSupported			Checks screen sharing support. Static method.
init			Initializes stream ingest parameters.
destroy			Releases the stream ingest instance.
startPreview			Starts preview.
stopPreview			Stops preview.
startPush			Starts stream ingest.
restartPush			Restarts stream ingest.
reconnectPush			Reconnects and continues stream ingest.
stopPush			Stops stream ingest.
startMicrophone			Turns on the microphone or switches to another microphone.
stopMicrophone			Turns off the microphone.
getCurrentMicDeviceId			Queries the device ID of the microphone.
startCamera			Turns on the camera or switches to another camera.
stopCamera			Turns off the camera.
getCurrentCameraDeviceId			Queries the device ID of the camera.
startScreenShare			Starts screen sharing.
stopScreenShare			Stops screen sharing.
startCustomStream			Starts ingest of the custom secondary stream.
stopCustomStream			Stops ingest of the custom secondary stream.
mute			Mutes or unmutes the stream. (Stream ingest is not stopped.)
muteVideo			Displays or stops displaying the stream. (Stream ingest is not stopped.)
getLivePushStatsInfo			Queries the last reported stream ingest statistics.
getPushUrl			Queries the ingest URL.
getChannelId			Queries the channel ID.
getUserId			Queries the user ID.
setLiveMixTranscodingConfig			Updates the layout for stream relay and mixing.
getResolution			Queries the resolution.
changeResolution			Updates the resolution.
getFps			Queries the frame rate.
changeFps			Updates the frame rate.
getPublishMediaStream			Queries the MediaStream information of the current stream.
getLiveTraceId			Queries the trace ID.
updateScreenVideoProfile			Configures the width, height, bitrate, and frame rate of the screen track.

Details

getCameras: queries cameras. Static method.

/**
 * Query cameras.
 * @return {Promise<MediaDeviceInfo[]>}
 */
const cameras = await AlivcLivePusher.getCameras();

getMicrophones: queries microphones. Static method.

/**
 * Query microphones.
 * @return {Promise<MediaDeviceInfo[]>}
 */
const microphones = await AlivcLivePusher.getMicrophones();

getPlayoutDevices: queries playback devices. Static method.

/**
 * Query playback devices.
 * @return {Promise<MediaDeviceInfo[]>}
 */
const playoutDevices = await AlivcLivePusher.getPlayoutDevices();

checkSystemRequirements: checks WebRTC requirements. Static method.

/**
 * Check whether the requirements for WebRTC are met.
 * @param {('sendonly' | 'recvonly' | 'sendrecv')} [direction]
 * @return {Promise<CheckResult>}
 */
const checkResult = await AlivcLivePusher.checkSystemRequirements();
// checkResult.support: boolean; Indicates whether the requirements are met.
// checkResult.detail.isBrowserSupported: boolean; Indicates whether the browser is supported.
// checkResult.detail.isH264DecodeSupported: boolean; Indicates whether H.264 decoding is supported.
// checkResult.detail.isH264EncodeSupported: boolean; Indicates whether H.264 encoding is supported.
// checkResult.detail.isWebRTCSupported: boolean; Indicates whether WebRTC is supported.

checkScreenShareSupported: checks screen sharing support. Static method.

/**
 * Check whether screen sharing is supported.
 * @returns {boolean}
 */
const isScreenShareSupported = AlivcLivePusher.checkScreenShareSupported();

init: initializes stream ingest parameters.

/**
 * Initialize the RTC engine.
 * @param config Configure parameters. All the parameters are optional.
 * config.resolution: AlivcResolutionEnum; The resolution.
 * config.fps: AlivcFpsEnum; The frame rate. Unit: frames per second (FPS).
 * config.logLevel: LogLevel; The log level. Default value: ERROR.
 * config.connectRetryCount: number; The maximum number of reconnection attempts.
 * config.audio: boolean; Specifies whether to enable audio.
 * config.audioId: string; The ID of the default audio device.
 * config.video: boolean; Specifies whether to turn on the camera.
 * config.cameraId: string; The device ID of the default camera.
 * config.screen: boolean; Specifies whether to enable screen sharing.
 */
const pusher = new AlivcLivePush.AlivcLivePusher();
pusher.init({
  resolution: AlivcLivePush.AlivcResolutionEnum.RESOLUTION_720P
});

destroy: releases the stream ingest instance.

// Release the stream ingest instance. You cannot use the instance after you release it.
pusher.destroy()

startPreview: starts preview.

/**
 * Start video preview.
 * @param {string ｜ HTMLVideoElement} elementOrId The node where the video resides or the ID of the video.
 * @param {boolean} secondary Specifies whether to preview the secondary stream. This parameter is optional. By default, only the primary stream is previewed.
 * @return {Promise<MediaStream>}
 */
const stream = pusher.startPreview(elementOrId);

stopPreview: stops preview.

/**
 * Stop video preview.
 * @param {string ｜ HTMLVideoElement} elementOrId The node where the video resides or the ID of the video. This parameter is optional. If you do not specify this parameter, previewing for all videos is stopped.
 */
pusher.stopPreview(elementOrId);

startPush: starts stream ingest.
```
/**
 * Start stream ingest.
 * @param {string} url The ingest URL. Example: artc://live.aliyun.com/push/....
 * @return {Promise}
 */
await pusher.startPush(url);
```
Important
You must specify an ingest URL that is used for co-streaming. For information about how to generate URLs for co-streaming, see Co-streaming URL generator.

restartPush: uses the current ingest URL to restart stream ingest.

/**
 * Use the current ingest URL to restart stream ingest.
 * @return {Promise}
 */
await pusher.restartPush();

reconnectPush: reconnects and continues stream ingest.

/**
 * Reconnect and continue stream ingest. 
 * @param {string} url The new ingest URL. Example: artc://live.aliyun.com/push/....
 * @return {Promise}
 */
await pusher.reconnectPush(url);

stopPush: stops stream ingest.

/**
 * Stop stream ingest.
 * @return {Promise}
 */
await pusher.stopPush(url);

startMicrophone: turns on the microphone or switches to another microphone.

/**
 * Turn on the microphone or switch to another microphone.
 * @param {string} deviceId The device ID of the microphone. This parameter is optional.
 * @return {Promise}
 */
await pusher.startMicrophone(deviceId);

stopMicrophone: turns off the microphone.

/**
 * Turn off the microphone.
 * @return {Promise}
 */
await pusher.stopMicrophone();

getCurrentMicDeviceId: queries the device ID of the microphone.

/**
 * Query the device ID of the microphone.
 * @return {string | undefined} The device ID of the microphone.
 */
const micId = pusher.getCurrentMicDeviceId();

startCamera: turns on the camera or switches to another camera.

/**
 * Turn on the camera or switch to another camera.
 * @param {string} deviceId The device ID of the camera. This parameter is optional.
 * @return {Promise}
 */
await pusher.startCamera(deviceId);

stopCamera: turns off the camera.

/**
 * Turn off the camera.
 * @return {Promise}
 */
await pusher.stopCamera();

getCurrentCameraDeviceId: queries the device ID of the camera.

/**
 * Query the device ID of the camera.
 * @return {string | undefined} The device ID of the camera.
 */
const cameraId = pusher.getCurrentCameraDeviceId();

startScreenShare: starts screen sharing.

/**
 * Start screen sharing.
 * @return {Promise}
 */
await pusher.startScreenShare();

stopScreenShare: stops screen sharing.

/**
 * Stop screen sharing.
 * @return {Promise}
 */
await pusher.stopScreenShare();

startCustomStream: starts ingest of the custom secondary stream.

/**
 * Start ingest of the custom secondary stream.
 * @param mediaStream The custom secondary stream.
 * @return {Promise<MediaStream>}
 */
await pusher.startCustomStream(mediaStream);

stopCustomStream: stops ingest of the custom secondary stream.

/**
 * Stop ingest of the custom secondary stream.
 * @return {Promise<void>}
 */
await pusher.stopCustomStream();

mute: mutes or unmutes the stream. (Stream ingest is not stopped.)

/**
 * Mute or unmute the stream.
 * @param {boolean} Specifies whether to mute the stream.
 * @returns {AlivcLivePusher} Returns the pusher instance for method chaining.
 */
pusher.mute(true);

muteVideo: displays or stops displaying the stream. (Stream ingest is not stopped.)

/**
 * Display or stop displaying the stream.
 * @param mute Specifies whether to stop sending video data. Valid values: true and false.
 * @returns {AlivcLivePusher} Returns the pusher instance for method chaining.
 */
pusher.muteVideo(true);

getLivePushStatsInfo: queries the last reported stream ingest statistics.

/**
 * Query the stream ingest statistics that was last reported.
 * @return {StatsInfo} The stream ingest statistics.
 */
const statsInfo = pusher.getLivePushStatsInfo();

getPushUrl: queries the ingest URL.

/**
 * Query the ingest URL.
 * @return {string | undefined} The current ingest URL.
 */
const url = pusher.getPushUrl();

getChannelId: queries the channel ID.

/**
 * Query the channel ID.
 * @return {string | undefined} The current channel ID.
 */
const channelId = pusher.getChannelId();

getUserId: queries the user ID.

/**
 * Query the user ID.
 * @return {string | undefined} The current user ID.
 */
const userId = pusher.getUserId();

setLiveMixTranscodingConfig: updates the layout for stream relay and mixing.

/**
 * Update the layout for stream relay and mixing.
 * @param {AlivcLiveTranscodingConfig} config This parameter is optional. If you do not specify this parameter, stream relay and mixing are stopped. For more information, check the details about the AlivcLiveTranscodingConfig class.
 * @return {Promise} The result of the operation.
 */
const response = await pusher.setLiveMixTranscodingConfig(config);

getResolution: queries the resolution.

/**
 * Query the resolution.
 * @return {AlivcResolutionEnum | undefined} The resolution.
 */
const resolution = pusher.getResolution();

changeResolution: updates the resolution.

/**
 * Update the resolution.
 * @param resolutionEnum The resolution that you want to use. If you set this parameter to Custom, specify a custom resolution.
 * @param width The width, which is required when you specify a custom resolution.
 * @param height The height, which is required when you specify a custom resolution.
 * @param bitrate The maximum bitrate.
 * @return {Promise}
 */
await pusher.changeResolution(AlivcResolutionEnum.RESOLUTION_720P);

getFps: queries the frame rate.

/**
 * Query the frame rate.
 * @return {AlivcFpsEnum | undefined} The current frame rate.
 */
const fps = pusher.getFps();

changeFps: updates the frame rate.

/**
 * Update the frame rate.
 * @param {AlivcFpsEnum} fps The frame rate that you want to use.
 * @return {Promise}
 */
await pusher.changeFps(AlivcFpsEnum.FPS_30);

getPublishMediaStream: queries the MediaStream information of the current stream.

/**
 * Query the MediaStream information of the current stream.
 * @return {MediaStream | undefined} The MediaStream information of the stream.
 */
const mediaStream = pusher.getPublishMediaStream();

getLiveTraceId: queries the trace ID.

/**
 * Query the trace ID.
 * @return {string} TraceId
 */
 pusher.getLiveTraceId();

updateScreenVideoProfile: configures the width, height, bitrate, and frame rate of the screen track.

/**
 * Configure the width, height, bitrate, and frame rate of the screen track. (Due to browser constraints, the specified width and height are not applied.)
 * @param width 
 * @param height 
 * @param rate 
 * @param fps 
 * @return {Promise}
 */
await pusher.updateScreenVideoProfile(width,height,rate,fps);

AlivcLiveTranscodingConfig

List of parameters

Parameter			Description
width			Width of the relayed stream.
height			Height of the relayed stream.
backgroundColor			Background color in hexadecimal. Example: 0x000000.
cropMode			AlivcLiveTranscodingCropModeEnum AlivcLiveTranscodingCropModeCrop: Cropping mode. AlivcLiveTranscodingCropModeFill: Padding mode.
mixStreams			AlivcLiveMixStream[]: Layout configuration for each stream in the mix.

AlivcLiveMixStream

List of parameters

Parameter			Description
userId			User ID of the stream mixing participant.
x			X-axis offset in pixels for the mixed stream.
y			Y-axis offset in pixels for the mixed stream.
width			Width of the mixed stream.
height			Height of the mixed stream.
zOrder			Layer order. Higher values appear on top.
sourceType			Video source type. Valid values: 0: Camera 1: Screen sharing Default value: 0.

AlivcLivePusher.info

Event			Description
bye			A viewer left the room, either displaced by other viewers or removed by the streamer.
pushstatistics			Ingest stream statistics. Fires every 2 seconds.

Sample code:

pusher.info.on('bye', (_code, reason) => {
  // console.log ('You have left the room. Reason: ${reason}');
});
pusher.info.on('pushstatistics', _stat => {
  // console.log(_stat);
});

AlivcLivePusher.error

Event			Description
system			System error.
sdk			SDK internal error.

Sample code:

pusher.error.on('system', error => {
  // console.log(error);
});
pusher.error.on('sdk', error => {
  // console.log(error);
});

AlivcLivePusher.network

Event			Description
connectionlost			Disconnected.
networkrecovery			Network recovered.
reconnectstart			Reconnection started.
reconnectfail			Reconnection failed.
reconnectsucceed			Reconnection succeeded.

Sample code:

pusher.network.on('connectionlost', () => {
  // console.log ('A network exception occurs, which results in a disconnection.');
});

AlivcLivePlayer (stream pulling)

List of methods

Method			Description
startPlay			Starts audio and video playback.
playAnotherElement			Plays audio and video on another element.
stopPlay			Stops audio and video playback.
pauseAudioPlaying			Pauses audio playback.
pauseVideoPlaying			Pauses video playback.
resumeAudioPlaying			Resumes audio playback.
resumeVideoPlaying			Resumes video playback.
destroy			Releases the player instance.

Details

startPlay: starts audio and video playback.

/**
 * Start the playback of the audio and video streams.
 * @param url The streaming URL. Example: artc://live.aliyun.com/play/...
 * @param elementOrId The label or ID of the media resource.
 * @param secondaryElementOrId The label or ID of the media resource of the secondary stream.
 * @return {Promise<AlivcLivePlayInfo>} You can use AlivcLivePlayInfo to listen to related events.
 */
const playInfo = await player.startPlay(url, elementOrId, secondaryElementOrId);

Important

You must specify a streaming URL that is used for co-streaming. For information about how to generate URLs for co-streaming, see Co-streaming URL generator.
Ordinary viewers can play the stream with ApsaraVideo Player SDK for Web. Quick access to a web player.

playAnotherElement: plays audio and video on another element.

/**
 * Play the audio and video streams on another node.
 * @param elementOrId The label or ID of the media resource.
 * @param secondary Specifies whether to play the secondary stream. This parameter is optional. By default, only the primary stream is played.
 */
player.playAnotherElement(elementOrId);

stopPlay: stops audio and video playback.

/**
 * Stop the playback of the audio and video streams.
 * @param elementOrId The label or ID of the media resource. This parameter is optional. If you do not specify this parameter, playback of all media resources is stopped.
 * @return {Promise} 
 */
await player.stopPlay(elementOrId);

pauseAudioPlaying: pauses audio playback.

/**
 * Pause the playback of the audio stream.
 */
player.pauseAudioPlaying();

pauseVideoPlaying: pauses video playback.

/**
 * Pause the playback of the video stream.
 */
player.pauseVideoPlaying();

resumeAudioPlaying: resumes audio playback.

/**
 * Resume the playback of the audio stream.
 */
player.resumeAudioPlaying();

resumeVideoPlaying: resumes video playback.

/**
 * Resume the playback of the video stream.
 */
player.resumeVideoPlaying();

destroy: releases the player instance.

/**
 * Release the stream pulling instance. You cannot use the instance after you release it.
 */
player.destroy();

AlivcLivePlayInfo

Event			Description
canplay			Stream ready for playback.
userleft			Remote user left the room.
statistics			Playback statistics.
update			Updates the remote stream.

Sample code:

playInfo.on('statistics', _stat => {
  // console.log(_stat);
});
playInfo.on('userleft', () => {
  // console.log ('The remote user leaves the room.');
});
playInfo.on('canplay', function () {
  // console.log ('The remote stream can be played.');
});
playInfo.on('update', function (previousStatus) {
  // console.log(previousStatus.mediaStream);
  // console.log(previousStatus.secondaryMediaStream);
});