Tutorial: Interactive Whiteboard

Feature Description

This article describes how to use the interactive whiteboard during a call. The initiator (the host) opens a whiteboard and publishes it to remote users without screen sharing. Viewers (the guests) open the host's whiteboard and write and draw together. The whiteboard supports inserting PDF, PPT, images, videos and more.

• Omitting userId means the local user is the host. Passing userId means the local user is a guest opening that user's whiteboard.
• The interactive whiteboard and Screen Share Annotation are mutually exclusive. Only one of them can run at a time.
• Demo RoomKit

Core Advantages

Conventional interactive whiteboard solutions usually require a separate whiteboard SDK and service: whiteboard content is synchronized over an independent signaling channel and rendered separately on each endpoint, separate from the audio/video path, so viewing endpoints, recording and playback all need extra adaptation. TRTC Interactive Whiteboard renders the whiteboard directly into a video picture on the host side, and what is published to remote users is an ordinary video stream (the sub stream). As a result:

Prerequisites

• TRTC Web SDK version >= 5.21.0

• Compatibility:

  OS	Browser	Host (initiator)	Guest (participant)
  Windows / macOS	Chrome 86+, Edge 86+ and other Chromium 86+ based browsers	✅	✅
  macOS	Safari 15.4+	✅	✅
  Windows / macOS	Firefox 117+	✅	✅
  Android	Chrome 86+, WeChat built-in browser and other Chromium 86+ based browsers	❌ Mixing is not supported on mobile yet	✅
  iOS 15.4+	Safari, WeChat built-in browser, etc.	❌ Mixing is not supported on mobile yet	✅

  Users who only pull streams and do not take part in the whiteboard are not limited by the table above: the whiteboard is rendered into the sub stream picture, so it is visible in any environment that supports TRTC stream pulling. See Browsers Supported.

• The role must be anchor (the audience role cannot call whiteboard APIs).

Implementation

Deploy Static Assets

Inserting PDF / PPT depends on some static asset files. To make sure the browser can load them, complete the following steps:

1. Publish the node_modules/trtc-sdk-v5/assets directory to your CDN or static asset server (the whiteboard assets are in its whiteboard subdirectory).
2. Pass your CDN address to the assetsPath parameter when creating the trtc instance, e.g. TRTC.create({ assetsPath: 'https://xxxx/assets' }). The SDK loads the assets on demand.

• Without assetsPath, the PDF button and PPT entry do not appear in the whiteboard. Other features are not affected.
• If the host URL of the assets differs from that of your web app, enable CORS on the asset domain.
• Do not serve the assets over HTTP, because loading HTTP resources from an HTTPS page is blocked by the browser.

Import and Register Plugins

The whiteboard depends on VideoMixer (renders the whiteboard picture) and Whiteboard (the whiteboard plugin), and requires enableSEI.

import TRTC from 'trtc-sdk-v5';
import { VideoMixer } from 'trtc-sdk-v5/plugins/video-effect/video-mixer';
import { Whiteboard } from 'trtc-sdk-v5/plugins/whiteboard';
import AudioPlayer from 'trtc-sdk-v5/plugins/audio-player'; // optional, see below
const trtc = TRTC.create({
  plugins: [VideoMixer, Whiteboard, AudioPlayer],
  enableSEI: true,
  assetsPath: 'https://xxxx/assets'
});

• Calling whiteboard APIs without VideoMixer / Whiteboard registered throws an error. Guests only need Whiteboard.
• AudioPlayer is optional. It plays the audio of videos inserted into the whiteboard. Without it, those videos are silent.

Host: Start the Whiteboard

await trtc.startWhiteboard({
  view: 'local-board',            // whiteboard container: element id or HTMLElement
  option: {
    profile: '1080p',             // default: 1920×1080 / 15fps / 2000kbps
    backgroundColor: '#fcfcfc',   // optional; the theme background is used if omitted
    theme: 'light'                // optional
  }
});

• The whiteboard occupies the sub stream, so screen sharing cannot be started while the whiteboard is running, and vice versa.
• profile determines both the whiteboard canvas size and its frame rate.

Guest: Open the Whiteboard

A guest must subscribe to the host's whiteboard (sub stream) first, then open the whiteboard. Whether it succeeds depends on the remote side, so wrap it in try/catch.

await trtc.startRemoteVideo({
  userId: 'host_user_id',
  streamType: TRTC.TYPE.STREAM_TYPE_SUB,
  view: 'remote-board'
});
try {
  await trtc.startWhiteboard({ userId: 'host_user_id' });
} catch (error) {
  // The remote user hasn't started the whiteboard / the sub stream isn't subscribed / timed out, etc.
  console.warn(error.message);
}

• You must subscribe to the sub stream with startRemoteVideo before calling startWhiteboard({ userId }). The reverse order throws an error.
• Either the host or the guest can start first. The SDK waits for the remote side to be ready (up to 10s).
• A guest can open the whiteboard for only one host at a time. Passing a new userId switches the target host.

Update Parameters as Needed

// Host: change the background color and theme
await trtc.updateWhiteboard({ option: { backgroundColor: '#ffffff', theme: 'dark' } });
// Host: read-only locally; guests can still write
await trtc.updateWhiteboard({ option: { interactive: false } });
// Host: switch the whiteboard container
await trtc.updateWhiteboard({ view: 'small-board' });
// Guest: open in read-only mode (watch without writing, keep the whiteboard open)
await trtc.updateWhiteboard({ userId: 'host_user_id', option: { interactive: false } });
// Guest: switch the playback container; the whiteboard moves with the video
await trtc.updateRemoteVideo({ userId: 'host_user_id', streamType: TRTC.TYPE.STREAM_TYPE_SUB, view: 'another-view' });

Stop the Whiteboard

// Guest: close the whiteboard
await trtc.stopWhiteboard({ userId: 'host_user_id' });
// Host: stop the whiteboard (stops publishing and releases the whiteboard)
await trtc.stopWhiteboard();

API Description

trtc.startWhiteboard(options)

• Host: starts the whiteboard and publishes it via the sub stream.
• Guest: opens the specified user's whiteboard.

options

Example:

// host
await trtc.startWhiteboard({ view: 'local-board', option: { profile: '720p' } });
// guest
await trtc.startWhiteboard({ userId: 'host_user_id' });

trtc.updateWhiteboard(options)

Updates whiteboard parameters incrementally. Only the fields passed in are changed.

options

trtc.stopWhiteboard(options)

• Host: stops the whiteboard, stops publishing and releases it.
• Guest: closes the whiteboard.

options

Events

Whiteboard state changes are notified via TRTC.EVENT.WHITEBOARD_STATE_CHANGED. The callback receives { userId, type, payload }:

Handle only the three type values above and ignore any others.

available: Whiteboard Is Available

Show / enable your whiteboard entry when you receive it. Values of payload.reason:

trtc.on(TRTC.EVENT.WHITEBOARD_STATE_CHANGED, ({ userId, type, payload }) => {
  if (type !== 'available') return;
  // Show / enable the whiteboard entry
  showWhiteboardEntry(userId);
  if (payload.reason === 'resume') {
    hideBanner(); // dismiss notices such as "Connection lost"
  }
});

unavailable: Whiteboard Is Unavailable

Hide / disable your whiteboard entry when you receive it. Whether to notify the user or call an API again depends on payload.reason:

• The host only receives 'end'.
• A session may receive unavailable several times (e.g. 'host-lost' and then 'end'). Use the most recent one.

trtc.on(TRTC.EVENT.WHITEBOARD_STATE_CHANGED, ({ userId, type, payload }) => {
  if (type !== 'unavailable') return;
  disableWhiteboardEntry(userId);
  switch (payload.reason) {
    case 'end':
      showToast('The presenter closed the whiteboard');
      break;
    case 'local-stop':
      // The local user closed the whiteboard / switched hosts; no notice needed
      break;
    case 'silence':
      showBanner('Waiting for the presenter to open the whiteboard');
      break;
    case 'host-lost':
      showBanner('Connection lost, reconnecting');
      break;
    case 'queue-full':
    case 'ack-timeout':
      showBanner('Syncing, please wait');
      break;
  }
});

error: Whiteboard Runtime Error

An asynchronous error during runtime. payload takes one of two forms:

Fields of payload when content fails to load:

Failed API calls (e.g. startWhiteboard rejected) are handled with try/catch; see "Error Handling" below.

const CONTENT_ERROR_TEXT = {
  'invalid-url': 'Invalid file link',
  'file-too-large': 'The file is too large',
  corrupt: 'The file is corrupted',
  unsupported: 'Unsupported file format',
  network: 'Network error, please retry',
  unknown: 'Failed to load the file'
};
trtc.on(TRTC.EVENT.WHITEBOARD_STATE_CHANGED, ({ userId, type, payload }) => {
  if (type !== 'error') return;
  if (payload instanceof Error) {
    console.error('[whiteboard] error', payload.message);
    reportError(payload);
    return;
  }
  // A PDF / PPT / image / video failed to load
  showToast(CONTENT_ERROR_TEXT[payload.reason] || CONTENT_ERROR_TEXT.unknown);
  console.warn('[whiteboard] content load failed', payload.contentType, payload.message);
});

Error Handling

The error code for the whiteboard is TRTC.ERROR_CODE.INVALID_OPERATION (5100), distinguished by extraCode:

try {
  await trtc.startWhiteboard({ userId: 'host_user_id' });
} catch (error) {
  if (error.code === TRTC.ERROR_CODE.INVALID_OPERATION && error.extraCode === 5110) {
    console.warn(error.message);
  }
}

FAQ

1. There is no PDF / PPT entry in the whiteboard toolbar?

Check that you have deployed the static assets as described in "Deploy Static Assets" above and passed assetsPath to TRTC.create.

2. Starting the whiteboard fails because screen sharing is running?

The whiteboard and screen sharing are mutually exclusive. Call stopScreenShare() before starting the whiteboard.

The whiteboard and screen sharing share the same sub stream. If you call one while the previous startScreenShare() / startWhiteboard() has not returned yet (for example, the screen picker is still open), the call fails with OPERATION_ABORT (already start) instead of INVALID_OPERATION (5110). Wait for the previous call to return (whether it succeeds or fails) before switching, or disable the switch entry while it is in progress.

3. PDF / images are misaligned in the local preview but correct for remote users?

Do not size canvas / video inside the container with descendant selectors (especially with !important), because they also match the plugin's internal canvases. Constrain only the container's own layer:

#local-board > .trtc-wb-video-layer video {
  width: 100%;
  height: 100%;
}

4. Do I need to call an API after the container size changes?

No. When the container itself is resized, or a parent's size change propagates to the container (percentage / flex layout), the whiteboard and the PDF / PPT in it re-lay out automatically. To switch containers, use updateWhiteboard({ view }) (host) or updateRemoteVideo({ view }) (guest).

Applying transform: scale() to the container or its ancestors is not recommended, as windows, PDF, text and other content will be misaligned with the whiteboard. To change the display size, change the container's width / height directly.