All Products
Search
Document Center

Intelligent Media Services:Use a custom plug-in to implement the name bar feature

Last Updated:Sep 11, 2026

The ARTC SDK for Web supports custom plug-ins for the name bar feature. A name bar is a text label overlaid on a video stream during a meeting or video chat that displays the username or other identification information.

Prerequisites

  1. An application is created, and the application ID and AppKey are obtained.

  2. The SDK is integrated. For more information, see Getting started with the ARTC Web SDK.

Implementation

Define a UserNamePlugin class that inherits AliRtcPlugin and implements its constructor and abstract methods.

Sample code

import { AliRtcPlugin, AliRtcLocalStreamInfo } from 'aliyun-rtc-sdk';

export default class UserNamePlugin extends AliRtcPlugin {
  private canvas: HTMLCanvasElement;
  private requestId?: number;

  // text specifies the username that want to draw.
  constructor(text: string) {
    super('UserNamePlugin'); // The custom name of the plug-in, which must be globally unique.
    this.options = { text };
    this.canvas = document.createElement('canvas');
  }

  isSupported(): boolean {
    // The plug-in does not need to depend on the features of a specific version of aliyun-rtc-sdk. Therefore, set the value to true.
    return true;
  }

  setOptions(options: { text: string }): void {
    // Specify whether to dynamically update the username that you want to draw.
    this.options = options;
  }

  shouldUpdate(): boolean {
    // Specify whether to call the process method when the stream status changes, for example, when the camera is turned on or off. In this example, set the value to true.
    return true;
  }

  process(streamInfo: AliRtcLocalStreamInfo): Promise<void> {
    if (streamInfo.currentVideoTrack) {
      // If a video track exists, define the handling method of the video track.
      const videoTrack = streamInfo.currentVideoTrack as MediaStreamVideoTrack;
      const settings = videoTrack.getSettings();
      // Adjust the width and height of the canvas to be the same as those of the video stream.
      this.canvas.width = settings.width!;
      this.canvas.height = settings.height!;

      // Convert the MediaStreamTrack object to the source of the video element.
      const stream = new MediaStream([videoTrack]);
      const videoElement = document.createElement('video');
      videoElement.srcObject = stream;
      videoElement.play();

      const ctx = this.canvas.getContext('2d')!;

      // Draw video frames to the canvas at regular intervals and add the text.
      const drawFrame = () => {
        if (videoElement.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) {
          ctx.drawImage(videoElement, 0, 0, this.canvas.width, this.canvas.height);

          // Add the text in the lower-right corner.
          ctx.fillStyle = 'white'; // The color of the text.
          ctx.font = '40px Arial'; // The size and font of the text.
          ctx.textAlign = 'right'; // The alignment direction of the text.
          ctx.fillText(this.options.text, this.canvas.width - 20, this.canvas.height - 20); // The position of the text.
        }
        this.requestId = requestAnimationFrame(drawFrame); // Continuously draw frames.
      }
      this.requestId = requestAnimationFrame(drawFrame);

      // Create a new MediaStream object.
      const newStream = this.canvas.captureStream(settings.frameRate); // Alternatively, specify another frame rate based on your business requirements.
      const newVideoTrack = newStream.getVideoTracks()[0];

      // Call streamInfo.updateVideoTrack to replace the video track.
      streamInfo.updateVideoTrack(newVideoTrack);
    } else if (this.requestId) {
      // If requestAnimationFrame was configured and no video track exists, cancel drawing.
      cancelAnimationFrame(this.requestId);
    }

    return Promise.resolve();
  }
}

Use the plug-in

The SDK provides the enablePlugin, setPluginOption, and removePlugin methods to manage plug-ins.

Enable the name bar plug-in

The following code displays the text Name bar A in the lower-right corner of the local video preview.

// instance indicates the AliRtcEngine instance.
instance.enablePlugin(new UserNamePlugin('Name bar A'));

Update the name bar plug-in

The following code changes the displayed text to Name bar B.

// instance indicates the AliRtcEngine instance.
instance.setPluginOption('UserNamePlugin', { text: 'Name bar B' });

Delete the name bar plug-in

The following code removes the name bar from the local video preview.

// instance indicates the AliRtcEngine instance.
instance.removePlugin('UserNamePlugin');

FAQ

How do I troubleshoot low stream bitrate or playback stuttering after enabling the name bar?

If low stream bitrate or playback stuttering occur on the viewer side after enabling the name bar feature, troubleshoot the issue by performing the following steps:

  1. On the Real-time Monitoring page in the ApsaraVideo Live console, check the Stream Ingest Statistics to verify whether the current average bitrate and frame rate are normal.

  2. If the bitrate is significantly lower than the recommended value, try disabling the name bar feature and then stream again. This helps you determine whether feature stacking causes encoding resource strain.

  3. Check whether the CPU usage of the stream ingest device, such as a mobile phone, is excessively high. Feature stacking may cause insufficient encoding performance on the device.

  4. Verify that the local network bandwidth is sufficient. Local network congestion can also cause degraded stream quality and playback stuttering.