Interface ICameraVideoTrack

Inherited from [LocalVideoTrack]ILocalVideoTrack, CameraVideoTrack is an interface for the video captured by a local camera and adds functions such as switching devices and adjusting video encoder configurations.

You can create a local camera video track by calling [AgoraRTC.createCameraVideoTrack]IAgoraRTC.createCameraVideoTrack.

interface ICameraVideoTrack {
    enabled: boolean;
    isPlaying: boolean;
    muted: boolean;
    processorDestination: IBaseProcessor;
    trackMediaType: "audio" | "video";
    clone(config?, cloneTrack?): ICameraVideoTrack;
    close(): void;
    getCurrentFrameData(): ImageData;
    getListeners(event): Function[];
    getMediaStreamTrack(): MediaStreamTrack;
    getRTCRtpTransceiver(type?): undefined | RTCRtpTransceiver;
    getStats(): LocalVideoTrackStats;
    getTrackId(): string;
    getTrackLabel(): string;
    getVideoElementVisibleStatus(): undefined | CheckVisibleResult;
    off(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    on(event, listener): void;
    once(event, listener): void;
    pipe(processor): IBaseProcessor;
    play(element, config?): void;
    removeAllListeners(event?): void;
    replaceTrack(track, stopOldTrack): Promise<void>;
    sendSeiData(sei): void;
    setDevice(deviceId): Promise<void>;
    setEnabled(enabled): Promise<void>;
    setEncoderConfiguration(config): Promise<void>;
    setMuted(muted): Promise<void>;
    setOptimizationMode(mode): Promise<void>;
    stop(): void;
    unpipe(): void;
}

Hierarchy (view full)

Properties

enabled isPlaying muted processorDestination trackMediaType

Methods

clone close getCurrentFrameData getListeners getMediaStreamTrack getRTCRtpTransceiver getStats getTrackId getTrackLabel getVideoElementVisibleStatus off on once pipe play removeAllListeners replaceTrack sendSeiData setDevice setEnabled setEncoderConfiguration setMuted setOptimizationMode stop unpipe

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

clone

  • clone(config?, cloneTrack?): ICameraVideoTrack

  • Parameters

    • Optional config: string | VideoEncoderConfiguration

      The encoding configuration for the new video track. You can pass in the SDK's built-in encoding configuration through [[VideoEncoderConfiguration]], or customize the video encoding configuration by passing in a [[VideoEncoderConfigurationPreset]].

    • Optional cloneTrack: boolean

      Whether to clone the current track. Default is true.

    Returns ICameraVideoTrack

    The newly generated video track.

    Since


       4.19.0

    Clones the current video track to create a new video track.

    In scenarios such as video conferencing and online education, you can use this method to display the same video stream with two sets of display parameters, including resolution, frame rate, and bitrate. For example, you can have one display set to high-definition and the other to low-definition.

close

  • close(): void

  • 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

  • Returns ImageData

    An ImageData object that stores RGBA data. ImageData is a web API supported by the browser. For details, see 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.

getListeners

  • getListeners(event): Function[]

  • Gets all the listeners for a specified event.

    Parameters

    • event: string

      The event name.

    Returns Function[]

getMediaStreamTrack

getRTCRtpTransceiver

  • getRTCRtpTransceiver(type?): undefined | RTCRtpTransceiver

  • Gets the RTCRtpTransceiver instance of the current track.

    This method is currently mainly used for end-to-end encryption of video streams (Beta).

    If the SDK experiences a reconnection, the RTCRtpTransceiver instance corresponding to the current track might change. You can obtain the new RTCRtpTransceiver instance through the following callbacks:

    • For a local track: [ILocalTrack.transceiver-updated]event_transceiver_updated
    • For a remote track: [IRemoteTrack.transceiver-updated]event_transceiver_updated_2

    Parameters

    • Optional type: StreamType

      The type of the video stream. See StreamType.

    Returns undefined | RTCRtpTransceiver

    The RTCRtpTransceiver instance of the current track.

getStats

getTrackId

  • getTrackId(): string

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

    Returns string

    The media track ID.

getTrackLabel

  • getTrackLabel(): string

  • 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(): undefined | CheckVisibleResult

  • Returns undefined | CheckVisibleResult

    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.

    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.

off

  • off(event, listener): void

  • 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, listener): void

  • Parameters

    • event: "track-updated"

      The event name.

    • listener: ((track) => void)

      See [track-updated]event_track_updated.

        • (track): void

        • Triggers when a media track is updated.

          Parameters

          Returns void

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "track-ended"

      The event name.

    • listener: (() => void)

      See [track-ended]event_track_ended.

        • (): void

        • Occurs when a audio or video track ends.

          Reasons may include:

          • Camera is unplugged.
          • Microphone is unplugged.
          • The local user stops screen sharing.
          • The local user closes the underlying MediaStreamTrack.
          • A local media device malfunctions.
          • The device permission is revoked.

          Returns void

          As Member Of

          ILocalTrack

          Group

          Events

    Returns void

  • on(event, listener): void

  • Parameters

    • event: "video-element-visible-status"

      The event name.

    • listener: ((data?) => void)

      See [video-element-visible-status]event_video_element_visible_status.

        • (data?): void

        • Parameters

          • Optional data: CheckVisibleResult

            The visibility of the <video> tag.

          Returns void

    Returns void

  • on(event, listener): void

  • Adds an event listener.

    Parameters

    • event: "transceiver-updated"

      The event name.

    • listener: ((transceiver, type?) => void)

      See [ILocalTrack.transceiver-updated]event_transceiver_updated.

        • (transceiver, type?): void

        • Occurs when the RTCRtpTransceiver instance of the current track is updated.

          Parameters

          • transceiver: RTCRtpTransceiver

            The new RTCRtpTransceiver instance.

          • Optional type: StreamType

            The type of the video stream to which the current track belongs. See StreamType.

          Returns void

          As Member Of

          ILocalTrack

          Group

          Events

    Returns void

once

  • once(event, listener): void

  • 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

  • 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, config?): void

  • Plays a remote 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?): void

  • Removes all listeners for a specified event.

    Parameters

    • Optional event: string

      The event name. If left empty, all listeners for all events are removed.

    Returns void

replaceTrack

  • replaceTrack(track, stopOldTrack): Promise<void>

  • Parameters

    • track: MediaStreamTrack

      The new video track, which is a MediaStreamTrack object.

    • stopOldTrack: boolean

      Whether to stop the old video track:

      • true: Stops the old video track.
      • false: Retains the old video track.

    Returns Promise<void>

    Since


       4.17.0

    Replaces the local video track.

    You can call this method before or after publishing the local video stream:

    • If you call this method before publishing, the new video track is played locally.
    • If you call this method after publishing, the new video track is received by the remote user.

    The new video track can be retrieved by the ILocalVideoTrack.getMediaStreamTrack or mediaStream.getVideoTracks method. You can choose to either stop or retain the replaced track.

    Notes:

    • This method supports Chrome 65+, Safari, and the latest Firefox.
    • This method might not take effect on some mobile devices.
    • Agora recommends switching between video tracks that are of the same type and have the same encoder configurations for the following reasons:
      • If the video track types are different, such as replacing a CameraVideoTrack object with a ScreenVideoTrack object, the video is flipped horizontally due to the mirror effect enabled by default on CameraVideoTrack (see VideoPlayerConfig.mirror for details).
      • If the encoder configurations (encoderConfig) are different, the actual sending resolution or frame rate might be different from what you set.
    • The subscriber will not be notified if the track gets replaced.
    • To switch the media input devices, Agora recommends using ICameraVideoTrack.setDevice.

    Example

    // Current video track
    const localVideoTrack = await AgoraRTC.createCameraVideoTrack();
    // Gets the new video track (option one)
    const newTrack = localVideoTrack.getMediaStreamTrack();
    // Gets the new video track (option two)
    const newTrack = await navigator.mediaDevices.getUserMedia({audio: true, video: true}).then(mediaStream => mediaStream.getVideoTracks()[0]);
    // Replaces and stops the current video track
    await localVideoTrack.replaceTrack(newTrack, true);

sendSeiData

  • sendSeiData(sei): void

  • Add the SEI data to the H.264 video stream.

    Parameters

    • sei: Uint8Array

    Returns void

setDevice

  • setDevice(deviceId): Promise<void>

  • Sets the device for capturing video.

    You can call this method either before or after publishing the video track.

    Parameters

    • deviceId: string | {
          deviceId: string;
          facingMode?: undefined;
      } | {
          deviceId?: undefined;
          facingMode: VideoFacingModeEnum;
      }

      Device ID, which can be passed in using the following ways:

      • Pass a string: Pass the deviceId obtained using [AgoraRTC.getCameras]IAgoraRTC.getCameras.
      • Pass an object: Starting from version 4.19.0, you can pass an object containing facingMode or deviceId, but only one of these properties can be specified. deviceId can be obtained through [AgoraRTC.getCameras]IAgoraRTC.getCameras, and facingMode supports the following values:
        • "environment": Use the rear camera.
        • "user": Use the front camera.

    Returns Promise<void>

setEnabled

  • setEnabled(enabled): Promise<void>

  • Parameters

    • enabled: boolean

      Whether to enable the track:

      • true: Enable the track.
      • false: Disable the track.

    Returns Promise<void>

    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_track_ended event.
    • If a track is published, disabling this track triggers the [user-unpublished]IAgoraRTCClient.event_user_unpublished event on the remote client, and re-enabling this track triggers the [user-published]IAgoraRTCClient.event_user_published event.
    • Do not call setEnabled and setMuted together.

setEncoderConfiguration

  • setEncoderConfiguration(config): Promise<void>

  • Sets the video encoder configurations, such as resolution, frame rate, and bitrate.

    Parameters

    • config: string | VideoEncoderConfiguration

      The video encoder configurations. You can pass either [[VideoEncoderConfigurationPreset]] or a customized [[VideoEncoderConfiguration]] object.

    Returns Promise<void>

setMuted

  • setMuted(muted): Promise<void>

  • Sends or stops sending the media data of the track.

    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>

    Since


       4.6.0

    If the track is published, a successful call of setMuted(true) triggers the [user-unpublished]IAgoraRTCClient.event_user_unpublished event on the remote client, and a successful call of setMuted(false) triggers the [user-published]IAgoraRTCClient.event_user_published event.

setOptimizationMode

  • setOptimizationMode(mode): Promise<void>

  • Parameters

    • mode: "motion" | "detail" | "balanced"

      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": Since 4.21.0, the SDK 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>

    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.

stop

  • stop(): void

  • Stops playing the media track.

    Returns void

unpipe

  • unpipe(): void

  • Returns void

    Since


       4.10.0

    Removes the Processor inserted to the local video track.

Settings

Member Visibility

Theme

On This Page

enabledisPlayingmutedprocessorDestinationtrackMediaTypecloneclosegetCurrentFrameDatagetListenersgetMediaStreamTrackgetRTCRtpTransceivergetStatsgetTrackIdgetTrackLabelgetVideoElementVisibleStatusoffononcepipeplayremoveAllListenersreplaceTracksendSeiDatasetDevicesetEnabledsetEncoderConfigurationsetMutedsetOptimizationModestopunpipe