本站点除 Legacy 产品与方案外，已迁移至声网新文档中心，当前页面不再维护

Documentation





All

Console 官网 Community Technical support





Agora Web SDK API Reference

Overview AgoraRTC AgoraRTCClient LocalTrack RemoteTrack Error codes

LocalVideoTrack is the basic interface for local video tracks, providing the main methods for local video tracks.

You can get create a local video track by calling AgoraRTC.createCustomVideoTrack or AgoraRTC.createScreenVideoTrack method.

Inherited from LocalVideoTrack, CameraVideoTrack is an interface for the video captured by a local camera and adds several camera-related functions.

Hierarchy

ILocalTrack
- ILocalVideoTrack
  - ICameraVideoTrack

Index

Events

Properties

Events

beauty-effect-overload

beauty-effect-overload(): void

Occurs when the device is overloaded after you call setBeautyEffect to enable image enhancement.

You can listen for this event to notify users of the device overload and disable image enhancement.
```
localVideoTrack.on("beauty-effect-overload", () => {
  console.log("beauty effect overload, disable beauty effect");
  localVideoTrack.setBeautyEffect(false);
});
```
Returns void

video-element-visible-status-2

video-element-visible-status-2(data?: CheckVideoVisibleResult): void

Since
4.8.0

Indicates the visibility of the <video> HTML tag.

The SDK triggers this event every 30 seconds.

After you call localVideoTrack.play, the SDK creates an <video> tag for playing video tracks. When localVideoTrack.isPlaying is true but you cannot see any video, this event helps you check whether the <video> tag is visible or not and learn the reason when the <video> tag is invisible.

Parameters
- Optional data: CheckVideoVisibleResult
  
  The visibility of the <video> tag.
Returns void

Properties

enabled

enabled: boolean

isPlaying

isPlaying: boolean

Whether a media track is playing on the webpage:

true: The media track is playing on the webpage.
false: The media track is not playing on the webpage.

muted

muted: boolean

processorDestination

processorDestination: IBaseProcessor

Since
4.10.0

The destination of the current processing pipeline on the local video track.

trackMediaType

trackMediaType: "audio" | "video"

The type of a media track:

"audio": Audio track.
"video": Video track.

Methods

close

close(): void

Inherited from IBufferSourceAudioTrack.close

Closes a local track and releases the audio and video resources that it occupies.

Once you close a local track, you can no longer reuse it.

Returns void

getCurrentFrameData

getCurrentFrameData(): ImageData

Since
4.1.0

Gets the data of the video frame being rendered.

You should call this method after calling play. Otherwise, the method call returns null.

Returns ImageData

An ImageData object that stores RGBA data. ImageData is a web API supported by the browser. For details, see ImageData.

getListeners

getListeners(event: string): Function[]

Inherited from EventEmitter.getListeners

Gets all the listeners for a specified event.

Parameters
- event: string
  
  The event name.
Returns Function[]

getMediaStreamTrack

getMediaStreamTrack(): MediaStreamTrack

Inherited from IBufferSourceAudioTrack.getMediaStreamTrack

Gets an MediaStreamTrack object.

Returns MediaStreamTrack

An MediaStreamTrack object.

getStats

getStats(): LocalVideoTrackStats

Overrides ILocalTrack.getStats

Gets the statistics of a local video track.

DEPRECATED from v4.1.0. Use AgoraRTCClient.getLocalVideoStats and AgoraRTCClient.getLocalAudioStats instead.

Returns LocalVideoTrackStats

getTrackId

getTrackId(): string

Inherited from IBufferSourceAudioTrack.getTrackId

Gets the ID of a media track, a unique identifier generated by the SDK.

Returns string

The media track ID.

getTrackLabel

getTrackLabel(): string

Inherited from IBufferSourceAudioTrack.getTrackLabel

Gets the label of a local track.

Returns string

The label that the SDK returns may include:
- The MediaDeviceInfo.label property, if the track is created by calling createMicrophoneAudioTrack or createCameraVideoTrack.
- The sourceId property, if the track is created by calling createScreenVideoTrack.
- The MediaStreamTrack.label property, if the track is created by calling createCustomAudioTrack or createCustomVideoTrack.

getVideoElementVisibleStatus

getVideoElementVisibleStatus(): CheckVideoVisibleResult | undefined

Since
4.8.0

Gets the visibility of the <video> HTML tag.

After you call localVideoTrack.play, the SDK creates an <video> tag for playing video tracks. When localVideoTrack.isPlaying is true but you cannot see any video, call this method to check whether the <video> tag is visible or not and learn the reason when the <video> tag is invisible.

Returns CheckVideoVisibleResult | undefined

The CheckVideoVisibleResult object. If this method returns undefined, it may be due to the following reasons:
- localVideoTrack.isPlaying is false.
- The <video> tag does not exist.
- The <video> tag is not created by calling the play method.

off

off(event: string, listener: Function): void

Inherited from EventEmitter.off

Removes the listener for a specified event.

Parameters
- event: string
  
  The event name.
- listener: Function
  
  The callback that corresponds to the event listener.
Returns void

on

on(event: "beauty-effect-overload", listener: typeof event_beauty_effect_overload): void
on(event: "track-ended", listener: typeof event_track_ended): void
on(event: "video-element-visible-status", listener: typeof event_video_element_visible_status_2): void

Overrides ILocalAudioTrack.on

Parameters
- event: "beauty-effect-overload"
- listener: typeof event_beauty_effect_overload
Returns void
Overrides ILocalAudioTrack.on

Parameters
- event: "track-ended"
- listener: typeof event_track_ended
Returns void
Overrides ILocalAudioTrack.on

Parameters
- event: "video-element-visible-status"
- listener: typeof event_video_element_visible_status_2
Returns void

once

once(event: string, listener: Function): void

Inherited from EventEmitter.once

Listens for a specified event once.

When the specified event happens, the SDK triggers the callback that you pass and then removes the listener.

Parameters
- event: string
  
  The event name.
- listener: Function
  
  The callback to trigger.
Returns void

pipe

pipe(processor: IBaseProcessor): IBaseProcessor

Inserts a Processor to the local video track.

Parameters
- processor: IBaseProcessor
  
  The Processor instance. Each extension has a corresponding type of Processor.
Returns IBaseProcessor

The Processor instance.

play

play(element: string | HTMLElement, config?: VideoPlayerConfig): void

Overrides ILocalTrack.play

Plays a local video track on the web page.

Parameters
- element: string | HTMLElement
  Specifies a DOM element. The SDK will create a <video> element under the specified DOM element to play the video track. You can specify a DOM element in either of the following ways:
  - string: Specify the ID of the DOM element.
  - HTMLElement: Pass a DOM object.
- Optional config: VideoPlayerConfig
  
  Sets the playback configurations, such as display mode and mirror mode. See VideoPlayerConfig. By default, the SDK enables mirror mode for a local video track.
Returns void

removeAllListeners

removeAllListeners(event?: undefined | string): void

Inherited from EventEmitter.removeAllListeners

Removes all listeners for a specified event.

Parameters
- Optional event: undefined | string
  
  The event name. If left empty, all listeners for all events are removed.
Returns void

setBeautyEffect

setBeautyEffect(enabled: boolean, options?: BeautyEffectOptions): Promise<void>

Enables/Disables image enhancement and sets the options.
Notes:
- Agora is planning to sunset this built-in image enhancement feature. You can use the upgraded Image Enhancement Extension instead. For details, see Use the Image Enhancement Extension.
- This method supports the following browsers:
- Safari 12 or later.
- Chrome 65 or later.
- Firefox 70.0.1 or later.
- This function is not supported on mobile devices.
- If you enable dual-stream mode, the image enhancement options only apply to the high-quality video stream.
Parameters
- enabled: boolean
  Whether to enable image enhancement:
  - true: Enable image enhancement.
  - false: Disable image enhancement.
- Optional options: BeautyEffectOptions
  
  Sets image enhancement options. See BeautyEffectOptions.
Returns Promise<void>

setEnabled

setEnabled(enabled: boolean): Promise<void>

Inherited from IBufferSourceAudioTrack.setEnabled
Since
4.0.0

Enables/Disables the track.

After a track is disabled, the SDK stops playing and publishing the track.
- Disabling a track does not trigger the LocalTrack.on("track-ended") event.
- If a track is published, disabling this track triggers the user-unpublished event on the remote client, and re-enabling this track triggers the user-published event.
- Do not call setEnabled and setMuted together.
Parameters
- enabled: boolean
  Whether to enable the track:
  - true: Enable the track.
  - false: Disable the track.
Returns Promise<void>

setMuted

setMuted(muted: boolean): Promise<void>

Inherited from IBufferSourceAudioTrack.setMuted
Sends or stops sending the media data of the track.

Since
4.6.0

If the track is published, a successful call of setMuted(true) triggers the user-unpublished event on the remote client, and a successful call of setMuted(false) triggers the user-published event.
- Calling setMuted(true) does not stop capturing audio or video and takes shorter time to take effect than setEnabled. For details, see What are the differences between setEnabled and setMuted?.
- Do not call setEnabled and setMuted together.
Parameters
- muted: boolean
  Whether to stop sending the media data of the track:
  - true: Stop sending the media data of the track.
  - false: Resume sending the media data of the track.
Returns Promise<void>

setOptimizationMode

setOptimizationMode(mode: "balanced" | "motion" | "detail"): Promise<void>

Since
4.2.0

Sets the video transmission optimization mode.

You can call this method during a video call, a live streaming or screen sharing to dynamically change the optimization mode. For example, during the screen sharing, before you change the shared content from text to video, you can change the optimization mode from "detail" to "motion" to ensure smoothness in poor network conditions.

Note: This method supports Chrome only.

Parameters
- mode: "balanced" | "motion" | "detail"
  The video transmission optimization mode:
  - "balanced": Uses the default optimization mode.
    - For a screen-sharing video track, the default transmission optimization strategy is to prioritizes clarity.
    - For the other types of video tracks, the SDK may reduce the frame rate or the sending resolution in poor network conditions.
  - "detail": Prioritizes video quality.
    - The SDK ensures high-quality images by automatically calculating a minimum bitrate based on the capturing resolution and frame rate. No matter how poor the network condition is, the sending bitrate will never be lower than the minimum value.
    - In most cases, the SDK does not reduce the sending resolution, but may reduce the frame rate.
  - "motion": Prioritizes video smoothness.
    - In poor network conditions, the SDK reduces the sending bitrate to minimize video freezes.
    - In most cases, the SDK does not reduce the frame rate, but may reduce the sending resolution.
Returns Promise<void>

stop

stop(): void

Inherited from IBufferSourceAudioTrack.stop

Stops playing the media track.

Returns void

unpipe

unpipe(): void

Since
4.10.0

Removes the Processor inserted to the local video track.

Returns void

Agora Web SDK API Reference

Hierarchy

Index

Events

Properties

Methods

Events

beauty-effect-overload

Returns void

video-element-visible-status-2

Parameters

Optional data: CheckVideoVisibleResult

Returns void

Properties

enabled

isPlaying

muted

processorDestination

trackMediaType

Methods

close

Returns void

getCurrentFrameData

Returns ImageData

getListeners

Parameters

event: string

Returns Function[]

getMediaStreamTrack

Returns MediaStreamTrack

getStats

Returns LocalVideoTrackStats

getTrackId

Returns string

getTrackLabel

Returns string

getVideoElementVisibleStatus

Returns CheckVideoVisibleResult | undefined

off

Parameters

event: string

listener: Function

Returns void

on

Parameters

event: "beauty-effect-overload"

listener: typeof event_beauty_effect_overload

Returns void

Parameters

event: "track-ended"

listener: typeof event_track_ended

Returns void

Parameters

event: "video-element-visible-status"

listener: typeof event_video_element_visible_status_2

Returns void

once

Parameters

event: string

listener: Function

Returns void

pipe

Parameters

processor: IBaseProcessor

Returns IBaseProcessor

play

Parameters

element: string | HTMLElement

Optional config: VideoPlayerConfig

Returns void

removeAllListeners

Parameters

Optional event: undefined | string

Returns void

setBeautyEffect

Parameters

enabled: boolean

Optional options: BeautyEffectOptions

Returns Promise<void>

setEnabled