AliRtcEngine interface

Contents

var aliWebrtc = new AliRtcEngine(option);

Basic APIs

Channel-related APIs

Publishing-related APIs

Subscription-related APIs

Video-related APIs

Audio-related APIs

Preview APIs

Remote user query APIs

Other APIs

API details

• isSupport: Checks whether the browser supports the Web SDK.

  aliWebrtc.isSupport(option).then(re =>{
      console.log(re)
  }).catch(error => {
      console.log(error)
  })

  Parameters

  Name		Type	Description
  option	isReceiveOnly	Boolean	Specifies whether to enable the subscription-only mode. Valid values: true: Yes. false (default): No.
  	isDebug	Boolean	Specifies whether to enable the local debugging mode. Valid values: true: Yes. false (default): No.
  	customPlay	Boolean	Specifies whether to enable the custom playback mode. Valid values: true: Yes. false (default): No. Note If you set customPlay to true, the onMediaStreamUpdate event is triggered when the subscription status changes. The setDisplayRemoteVideo, muteRemoteAudioPlaying, muteAllRemoteAudioPlaying, setAudioVolume, and getAudioVolume methods become invalid.

  The HTTPS protocol is required in a production environment. You can add the {isDebug: true} parameter to debug on a local host and skip the HTTPS protocol check.

  Important

  Version 1.11:

  • The {channelProfile: 2} parameter was added to check whether the browser supports the interactive stream mode with low latency. The default parameter {channelProfile: 0} checks whether the browser supports the communication mode.
  • Call this method before you instantiate the SDK.

  Version 1.12 and later:

  • You do not need to configure channel information.
  • This method is no longer static.
  • Call this method after you instantiate the SDK and before you join a channel.
  • The {channelProfile: 0} and {channelProfile: 2} parameters were removed.

  Return values

  Name	Type	Description
  audioDevice	Boolean	Indicates whether an audio device is active. Valid values: true: Yes. false: No.
  browser	String	The name of the browser.
  browser_version	String	The version of the browser.
  isSupported	Boolean	Indicates whether WebRTC is supported. Valid values: true: Yes. false: No.
  message	String	The error message.
  supportH264	Boolean	Indicates whether H.264 is supported. Valid values: true: Yes. false: No.
  supportScreenShare	Boolean	Indicates whether screen sharing is supported. Valid values: true: Yes. false: No.
  supportMixBackgroundAudio	Boolean	Indicates whether screen audio sharing is supported. Valid values: true: Yes. false: No.
  videoDevice	Boolean	Indicates whether a camera is active. Valid values: true: Yes. false: No.

• getDevices: Retrieves device information. The method returns information about cameras and audio devices. If you cannot retrieve device information after you reconnect an external device, you may need to restart your computer.

  aliWebrtc.getDevices().then((re)=>{
  }).catch((error)=>{ 
    console.log(error.message)
  });

• getAvailableResolutions: Retrieves an array of supported resolutions.

  aliWebrtc.getAvailableResolutions(deviceId).then((re)=>{
  }).catch((error)=>{ 
    console.log(error.message)
  });

  Parameters

  Name	Type	Description
  deviceId	String	The camera ID.

• isSupportScreenShare: Checks whether screen sharing is supported.

  aliWebrtc.isSupportScreenShare();

• setChannelProfile: Sets the channel mode.

  aliWebrtc.setChannelProfile(channelProfile);

  Parameters

  Name	Type	Description
  channelProfile	Number	The channel mode. Valid values: 0 (default): communication mode. 1: interactive mode. 2: interactive stream mode with low latency.

• setClientRole: Sets the user role.

  aliWebrtc.setClientRole(role);

  Parameters

  Name	Type	Description
  role	Number	The user role. This parameter is valid only when the channel mode is not communication mode. Valid values: 0: interactive role. 1 (default): viewer.

• setAudioOnlyMode: Sets the audio-only mode.

  aliWebrtc.setAudioOnlyMode(audioOnly);

  Parameters

  Name	Type	Description
  audioOnly	Boolean	Specifies whether to enable the audio-only mode. Valid values: true: Yes. false (default): No.

  Important Call this method before you call the isSupport method. After you enable the audio-only mode, the isSupport method no longer checks for a camera. After you join a channel, you cannot preview the local video. You can only publish and subscribe to audio streams.
• dispose: Releases the instance.

  aliWebrtc.dispose();

  Note When you call this function to release the instance, the leaveChannel method is called internally. You do not need to call leaveChannel again.
• joinChannel: Joins a channel.

  aliWebrtc.joinChannel({
      userid,         // The user ID.
      channel,        // The channel.
      appid,          // The application ID.
      nonce,          // The nonce.
      timestamp,      // The UNIX timestamp.
      gslb,           // The GSLB service endpoint.
      token,          // The token.
  },displayName).then(()=>{
      // Joined the channel successfully.
  } ,(error)=>{
      // Failed to join the channel. Print the error content to view the failure reason.
      console.log(error.message);
  });

  Parameters

  Name		Type	Description
  authInfo	userid	String	The user ID.
  	channel	String	The channel.
  	appid	String	The application ID.
  	nonce	String	The nonce.
  	timestamp	String	Timestamp
  	token	String	The token.
  	gslb	Array	The Global Server Load Balancing (GSLB) service endpoint.
  displayName		String	The username.

• leaveChannel: Leaves a channel.

  aliWebrtc.leaveChannel().then(()=>{
  } ,(error)=>{
      console.log(error.message);
  });

• configLocalAudioPublish: Specifies whether to publish the local audio stream.

  aliWebrtc.configLocalAudioPublish=enable;

  Parameters

  Name	Type	Description
  enable	Boolean	Specifies whether to publish the audio stream. Valid values: true (default): Yes. false: No.

  Important The setting takes effect only after you call the publish method.
• configLocalCameraPublish: Specifies whether to publish the local camera stream.

  aliWebrtc.configLocalCameraPublish=enable;

  Parameters

  Name	Type	Description
  enable	Boolean	Specifies whether to publish the camera stream. Valid values: true (default): Yes. false: No.

  Important The setting takes effect only after you call the publish method.
• configLocalScreenPublish: Specifies whether to publish the screen sharing stream.

  aliWebrtc.configLocalScreenPublish=enable;

  Parameters

  Name	Type	Description
  enable	Boolean	Specifies whether to publish the screen sharing stream. Valid values: true: Yes. false (default): No.

  Important The setting takes effect only after you call the publish method.
• publish: Publishes the local stream.

  aliWebrtc.publish().then(()=>{
  } ,(error)=>{
      console.log(error.message);
  });

  The Web SDK can publish only the main stream.

  Important Call this method after you join a channel. To allow remote users to subscribe to the local stream, you must call the publish method. Remote users will then receive the onPublisher event.
• unPublish: Stops publishing the local stream. When you stop publishing, remote users receive the onUnPublisher event.

  aliWebrtc.unPublish().then(()=>{
  } ,(error)=>{
      console.log(error.message);
  });

  Important This method has been deprecated since version 1.14. We recommend that you set the configuration and then call the publish method instead.
• configRemoteAudio: Specifies whether to subscribe to the remote audio stream.

  aliWebrtc.configRemoteAudio(userId,enable);

  Parameters

  Name	Type	Description
  userId	String	The user ID.
  enable	Boolean	Specifies whether to subscribe to the remote audio stream. Valid values: true (default): Yes. false: No.

  Important The setting takes effect only after you call the subscribe method.
• configRemoteCameraTrack: Specifies whether to subscribe to the remote camera stream.

  
  aliWebrtc.configRemoteCameraTrack(userId,preferMaster,enable);

  Parameters

  Name	Type	Description
  userId	String	The user ID.
  preferMaster	Boolean	Specifies whether to subscribe to the main stream or the substream. Valid values: true (default): Subscribe to the main stream. false: Subscribe to the substream.
  enable	Boolean	Specifies whether to subscribe to the remote camera stream. Valid values: true: Yes. false (default): No.

  The camera stream includes a main stream and a substream. The main stream has a higher resolution, and the substream has a lower resolution.

  Important The setting takes effect only after you call the subscribe method.
• configRemoteScreenTrack: Specifies whether to subscribe to the remote screen sharing stream.

  aliWebrtc.configRemoteScreenTrack(userId,enable);

  Parameters

  Name	Type	Description
  userId	String	The user ID.
  enable	Boolean	Specifies whether to subscribe to the remote screen sharing stream. Valid values: true: Yes. false (default): No.

  Important The setting takes effect only after you call the subscribe method.
• subscribe: Subscribes to a remote stream.

  aliWebrtc.subscribe(userId).then((userId)=>{
  },(error)=>{
      console.log(error.message);
  });

  Parameters

  Name	Type	Description
  userId	String	The user ID.

  Use the subscribe method to subscribe to a remote stream. By default, the camera stream and the audio stream are subscribed. You can call configRemoteAudio, configRemoteCameraTrack, and configRemoteScreenTrack to change the subscription configuration.

• unSubscribe: Unsubscribes from all streams from a specified user.

  aliWebrtc.unSubscribe(userId).then(() => {
  },(error)=>{
      console.log(error.message);
  });

  Parameters

  Name	Type	Description
  userId	String	The user ID.

  Important This method has been deprecated since version 1.14. We recommend that you set the configuration and then call the subscribe method instead.
• currentCamera: Specifies the camera device.

  // For PC
  aliWebrtc.currentCamera = {
    deviceId: deviceId
  };
  // For mobile devices, set facingMode to "user" to enable the front camera, or set it to "environment" to enable the rear camera.
  aliWebrtc.currentCamera = {
    facingMode:"user"
  };

  Parameters

  Name	Type	Description
  deviceId	String	The camera ID.

  Important Hot-swapping is not supported. Set this parameter before you preview or publish a stream.
• videoProfile: Sets the video stream parameters.

  aliWebrtc.videoProfile = { 
    frameRate:20,
    width: 640,
    height: 480
  };

  Parameters

  Name	Type	Description
  frameRate	int	The frame rate. The value ranges from 5 to 30. The default value is 15.
  width	int	The video width. The default value is 640.
  height	int	The device height. The default value is 480.

  The specified resolution must be one of the resolutions returned by getAvailableResolutions. The setting takes effect only after you call the publish method. If you specify an unsupported resolution, the system automatically adjusts it.

  Important This method was deprecated in SDK version 1.14. Use setVideoProfile instead.
• muteLocalCamera: Stops local video capture.

  aliWebrtc.muteLocalCamera(true);

  Parameters

  Name	Type	Description
  mute	Boolean	Specifies whether to stop local video capture. Valid values: true (default): Stop local video capture. false: Do not stop local video capture.

  Return value

  Returns true if the call is successful, or false if the call fails.

  Important This method has a return value since version 1.10. This method is only valid when a stream is being published.
• setDisplayRemoteVideo: Sets the rendering window and drawing parameters for a remote video stream.

  aliWebrtc.setDisplayRemoteVideo(
      userId,       // The user ID.
      video,        // The video element in the HTML used to display the stream object.
      1             // 1 indicates the camera stream (main and substreams), and 2 indicates the screen sharing stream.
  )

  Important

  • In versions 1.10.0 to 1.13.x, you do not need to set a view for an audio stream. The audio stream plays automatically after you subscribe to it.
  • In version 1.14.0 and later, an audio stream can be played only if a video element is available for playback. The policies are as follows.
    • If you subscribe to an audio stream and set only the view for the camera, the audio can be played. The audio stream plays in sync with the camera view.
    • If you subscribe to an audio stream and set only the view for the screen sharing stream, the audio can be played. The audio stream plays in sync with the screen sharing view.
    • If you subscribe to an audio stream and set views for both the camera and the screen sharing stream, the audio can be played. The audio stream plays in sync with the camera view.
    • If you subscribe to an audio stream but do not set a view, the audio cannot be played.
  • On Safari, an audio stream plays in the background by default after you subscribe to it.
• setVideoProfile: Sets the parameters for the camera or screen sharing stream.

  aliWebrtc.setVideoProfile({ 
        width,
        height,
        frameRate,
      },type);

  Parameters

  Name		Type	Description
  config	width	Number	The width. Valid values: Camera: 640 (default). Screen sharing: 960 (default).
  	height	Number	The height. Valid values: Camera: 480 (default). Screen sharing: 540 (default).
  	frameRate	Number	The frame rate. The value ranges from 5 to 30. Valid values: Camera: 15 (default). Screen sharing: 10 (default).
  	maxBitrate	Number	The maximum bitrate. Valid values: Camera: 500000 (default). Screen sharing: 1500000 (default). Important This parameter is removed in version 1.13.2. The SDK automatically sets the maximum bitrate based on the specified resolution and frame rate. For versions earlier than 1.13.2, you must configure this parameter when you call setVideoProfile.
  type		Number	The stream type. Valid values: 1. Camera. 2: screen sharing stream.

  Important The definition of the screen sharing stream depends on network quality and device performance. A higher resolution does not guarantee better definition. You must republish the stream for the changes to take effect.
• enableCamera: Specifies whether to use the camera.

  aliWebrtc.enableCamera = enable;

  Parameters

  Name	Type	Description
  enable	Boolean	Specifies whether to use the camera. Valid values: true (default): Yes. false: No.

  Important Call this method before you call isSupport. After you set this parameter, the isSupport method no longer checks for a camera.
• currentAudioCapture: Specifies the microphone device.

  aliWebrtc.currentAudioCapture = {
    deviceId: deviceId
  };

  Parameters

  Name	Type	Description
  deviceId	String	The microphone ID.

• muteLocalMic: Stops local audio capture.

  aliWebrtc.muteLocalMic(true, true);

  Parameters

  Name	Type	Description
  mute	Boolean	Specifies whether to stop local audio capture. Valid values: true (default): Stop local audio capture. false: Do not stop local audio capture.
  isRemember	Boolean	Specifies whether to remember the status. If you set this to true, the previous audio collection configuration is used when you republish the stream after stopping it. Valid values: true: Remember the status. false (default): Does not retain information.

  Return value

  Returns true if the call is successful, or false if the call fails.

  Note This method has a return value since version 1.10. This method is only valid when a stream is being published.
• muteRemoteAudioPlaying: Stops playing a remote audio stream.

  aliWebrtc.muteRemoteAudioPlaying(userId, muted);

  Parameters

  Name	Type	Description
  userId	String	The user ID.
  muted	Boolean	Specifies whether to mute the stream. Valid values: true: It is enabled. false (default): The feature is disabled.

• muteAllRemoteAudioPlaying: Stops playing all remote audio streams.

  aliWebrtc.muteAllRemoteAudioPlaying(muted);

  Parameters

  Name	Type	Description
  muted	Boolean	Specifies whether to mute all remote audio streams. Valid values: true: Enabled. false (default): Disabled

• setAudioVolume: Sets the playback volume for a subscribed user.

  aliWebrtc.setAudioVolume (userId, volume);

  Parameters

  Name	Type	Description
  userId	String	The user ID.
  volume	Number	The volume. The value ranges from 0 to 1.

  Return value

  Returns true if the call is successful, or false if the call fails.

  Important

  • This method does not conflict with the mute methods.
  • This method is not supported on iOS devices.
• getAudioVolume: Retrieves the playback volume of a subscribed user.

  aliWebrtc.getAudioVolume(userId);

  Parameters

  Name	Type	Description
  userId	String	The user ID.

  Return values

  Name	Type	Description
  volume	Number	The volume. The value ranges from 0 to 1.

• enableAudioVolumeIndicator: Enables the callback that reports audio volume levels.

  aliWebrtc.enableAudioVolumeIndicator = enable;

  Parameters

  Name	Type	Description
  enable	Boolean	Specifies whether to receive audio volume callbacks. Valid values: true: Accepted. false (default): Do not receive callbacks.

• startPreview: Starts the local camera preview.

  aliWebrtc.startPreview(
      video    // The video element in the HTML.
  ).then(()=>{
  }).catch((error) => {
      // Failed to preview.
  });

  Playback is handled by the video element.

• stopPreview: Stops the local camera preview.

  aliWebrtc.stopPreview().then(()=>{
  }).catch((error) => {
      // Failed to stop the preview.
  });

• enableHighDefinitionPreview: Enables high-definition preview.

  aliWebrtc.enableHighDefinitionPreview(enable);

  Parameters

  Name	Type	Description
  enable	Boolean	Specifies whether to enable high-definition preview. Valid values: true (default): Enabled. false: Disabled.

• getUserList: Retrieves the list of online users in the current channel.

  aliWebrtc.getUserList();

  Parameters

  Name		Type	Description
  displayName		String	The username.
  userId		String	The user ID.
  muteAudioPlaying		Boolean	Indicates whether the audio is muted. Valid values: true: Yes. false: No.
  streamConfigs	-	Array	An array of audio and video streams.
  	label	String	The stream label.
  	state	String	The stream state. Valid values: active: The stream is active. inactive: The stream is inactive.
  	subscribed	Boolean	Indicates whether you have subscribed to the remote user. Valid values: true: Yes. false: No.
  	type	String	The stream type. Valid values: audio: Audio data. video: Video content.

  Return value

  Returns a list of all online users who are publishing streams in the current channel.

• getUserInfo: Retrieves user information.

  aliWebrtc.getUserInfo(userId);

  Parameters

  Name		Type	Description
  displayName		String	The username.
  userId		String	The user ID.
  muteAudioPlaying		Boolean	Indicates whether the audio is muted. Valid values: true: Yes. false: No.
  streamConfigs	-	Array	An array of audio and video streams.
  	label	String	The stream label.
  	state	String	The stream state. Valid values: active: The stream is active. inactive: The stream is not active.
  	subscribed	Boolean	Indicates whether you have subscribed to the remote user. Valid values: true: Yes. false: No.
  	type	String	The stream type. Valid values: audio: audio stream. video: The video.

• on: Subscribes to an event.

  on(name, handler)

  Parameters

  Name	Type	Description
  name	String	The event name.
  handler	String	The method to handle the event.

• off: Unsubscribes from an event.

  off(name, handler)

  Parameters

  Name	Type	Description
  name	String	The event name.
  handler	String	The method to handle the event.

• setExternalMediaTrack: Sets an external input source.

  aliWebrtc.setExternalMediaTrack(track, type);

  Parameters

  Name	Type	Description
  track	MediaStreamTrack	The media stream type. Valid values: audiotrack: Pass an audio stream. videotrack: Pass a video stream.
  type	Number	The type of stream to replace. Valid values: 0: audio stream. 1: video stream. 2: screen sharing stream.

  Note

  • The resolution of the external video input is the same as the resolution of the input media stream. This resolution is not affected by the setVideoProfile method.
  • You can use an audiotrack to replace the microphone. You can use a videotrack to replace the camera or screen sharing stream.
  • You can call the setExternalMediaTrack method to set an external audio or video stream only when no stream is being published.
  • To cancel the external audio or video stream, call the setExternalMediaTrack method and pass null for the track parameter. You must do this when no stream is being published.
  • This setting is cleared when you stop publishing. You must call this method again before you publish again.
• startAudioMixing: Starts playing a music file for audio mixing.

  aliWebrtc.startAudioMixing({filePath: filePath}, (err)=> {
      if(err) {
        // Failed to start playing the music file.
    }else {
        // Started playing the music file successfully.
    }
  })

  Parameters

  Parameter		Type	Description
  options	-	Object	The options.
  	filePath	String	The file path. This parameter is required.
  	cacheResource	Boolean	Specifies whether to cache the resource. Default value: true.
  	playTime	Number	The playback start position in milliseconds. Default value: 0.
  callback		Function	The callback function.

• stopAudioMixing: Stops playing the music file.

  aliWebrtc.stopAudioMixing((err)=> {
      if(err) {
        // Failed to stop playing the music file.
    }else {
        // Stopped playing the music file successfully.
    }
  })

  Parameters

  Parameter	Type	Description
  callback	Function	The callback function.

• pauseAudioMixing: Pauses playing the music file.

  aliWebrtc.pauseAudioMixing((err)=> {
      if(err) {
        // Failed to pause playing the music file.
    }else {
        // Paused playing the music file successfully.
    }
  })

  Parameters

  Parameter	Type	Description
  callback	Function	callback function

• resumeAudioMixing: Resumes playing the music file.

  aliWebrtc.resumeAudioMixing((err)=> {
      if(err) {
        // Failed to resume playing the music file.
    }else {
        // Resumed playing the music file successfully.
    }
  })

  Parameters

  Parameter	Type	Description
  callback	Function	The callback function.

• adjustAudioMixingVolume: Adjusts the audio mixing volume.

  aliWebrtc.adjustAudioMixingVolume(volume)

  Parameters

  Parameter	Type	Description
  volume	Number	The accompaniment volume. The value ranges from 0 to 100.

• setAudioMixingPosition: Sets the playback position of the music file.

  aliWebrtc.setAudioMixingPosition(position, (err)=> {
      if(err) {
        // Failed to set the playback position of the music file.
    }else {
        // Set the playback position of the music file successfully.
    }
  })

  Parameters

  Parameter	Type	Description
  position	Number	The position of the accompaniment in milliseconds.
  callback	Function	The callback function.

• getAudioMixingDuration: Retrieves the duration of the music file.

  aliWebrtc.getAudioMixingDuration()

  Parameters

  Return value	Type	Description
  duration	Number	The total duration in milliseconds.

• getAudioMixingCurrentPosition: Retrieves the current playback position of the music file.

  aliWebrtc.getAudioMixingCurrentPosition()

  Parameters

  Return value	Type	Description
  position	Number	The current playback progress in milliseconds.

• setAudioOutput: Sets the audio playback device.

  aliWebrtc.setAudioOutput(deviceId).then(()=>{
      // Set successfully.
  }).catch(()=> {
      // Failed to set.
  })

  Parameters

  Parameter	Type	Description
  deviceId	String	The speaker device ID. You can obtain the ID by calling getDevices.