video-sdk-web

name	video-sdk/web
description	Guidance for building browser-based sessions with Zoom Video SDK for Web (@zoom/videosdk v2.4.5) in React, Vue, Angular, Svelte, or vanilla TypeScript. Use for session lifecycle, audio/video rendering, screen sharing, chat/file transfer, recording, subsessions, live and broadcast streaming, incoming RTMP, RTMS controls, whiteboard, voice translation, custom processors, video masks, PTZ, stats, WebAssembly/SharedArrayBuffer, CSP/COOP/COEP, JWT session tokens, and SDK error debugging. Prefer over generic WebRTC advice whenever @zoom/videosdk is involved.
triggers	["video sdk web","custom video web","attachvideo","web videosdk","zoom videosdk web","@zoom/videosdk","video web session","peer-video-state-change","video rendering"]

Zoom Video SDK Web (v2.4.5)

Current npm/changelog release verified on 2026-07-10. Version 2.4.5 adds incoming RTMP ingestion and customAudioConstraints, improves share rendering, AMD environments, and virtual backgrounds on lower-performance devices, and restores the missing userKey field.

Expert guidance for building video sessions with Zoom Video SDK for Web.

This skill is for custom video sessions, not embedded Zoom meetings. If the user wants a custom UI for a real Zoom meeting, route to ../../meeting-sdk/web/component-view/SKILL.md. Use ../../probe-sdk/SKILL.md as an optional browser/device/network readiness gate before client.join(...).

SDK Sample Package

The reviewed zoom-video-sdk-web-2.4.5.zip archive is the react-video-sdk-demo sample application, not the @zoom/videosdk library distribution. It contains no bundled SKILL.md or paired API-reference files.

• Use this skill as the primary workflow and API-routing guide.
• Use references/sample-app-2.4.5.md for source-backed implementation patterns from the sample.
• Treat installed @zoom/videosdk TypeScript declarations and official API documentation as authoritative when the sample and types disagree.
• Never ship the sample's client-side SDK Secret/JWT generator. Generate Video SDK JWTs on a backend.

Quick Start

Installation

bun install @zoom/videosdk --save
# or 
npm install @zoom/videosdk --save

Basic Session Setup

import ZoomVideo from "@zoom/videosdk";

// 1. Create client
const client = ZoomVideo.createClient();

// 2. Initialize SDK
await client.init("en-US", "Global", { patchJsMedia: true });

// 3. Join session (requires JWT token from your server)
await client.join(sessionName, jwtToken, userName, sessionPassword);

// 4. Get media stream for audio/video control
const stream = client.getMediaStream();

Core API Reference

ZoomVideo (Static Methods)

Method	Description
createClient()	Create VideoClient instance (singleton)
checkSystemRequirements()	Check browser compatibility → { audio, video, screen }
checkFeatureRequirements()	Get supported/unsupported features list
getDevices(skipPermissionCheck?)	Enumerate media devices
createLocalAudioTrack(deviceId?)	Create local audio track for preview
createLocalVideoTrack(deviceId?)	Create local video track for preview
destroyClient()	Destroy client instance
preloadDependentAssets(path?)	Preload WebAssembly/Worker assets

VideoClient Methods

Session Management

// Initialize before joining
await client.init(language, dependentAssets, options?);

// Join session
await client.join(topic, token, userName, password?, idleTimeoutMins?);

// Leave or end session
await client.leave(end?); // end=true ends for all (host only)

User Management

client.getCurrentUserInfo(): Participant;
client.getAllUser(): Participant[];
client.getUser(userId): Participant | undefined;
client.getSessionHost(): Participant | undefined;

// Host/Manager actions
client.makeHost(userId);      // Transfer host
client.makeManager(userId);   // Promote to manager
client.revokeManager(userId); // Revoke manager
client.removeUser(userId);    // Remove participant
client.changeName(name, userId?);

Feature Clients

client.getMediaStream(); // Audio/Video/Screen share
client.getChatClient(); // In-session chat
client.getCommandClient(); // Custom signaling
client.getRecordingClient(); // Cloud recording
client.getSubsessionClient(); // Breakout rooms
client.getLiveTranscriptionClient(); // Captions
client.getLiveStreamClient(); // RTMP streaming
client.getWhiteboardClient(); // Whiteboard
client.getBroadcastStreamingClient(); // Host-side broadcast control
client.getRealTimeMediaStreamsClient(); // RTMS lifecycle control
client.getVoiceTranslatorClient(); // Voice translation
client.getIncomingLiveStreamClient(); // Incoming RTMP; verify against installed types

MediaStream (Audio/Video Control)

Audio

const stream = client.getMediaStream();

// Start audio (requires user gesture)
await stream.startAudio({
  mute?: boolean,
  speakerOnly?: boolean,
  backgroundNoiseSuppression?: boolean,
  microphoneId?: string,
  speakerId?: string,
});

// Control
await stream.muteAudio();
await stream.unmuteAudio();
stream.stopAudio();

// Device management
stream.getMicList(): MediaDevice[];
stream.getSpeakerList(): MediaDevice[];
await stream.switchMicrophone(deviceId);
await stream.switchSpeaker(deviceId);

Video

// Start video (simple call, no options needed)
await stream.startVideo();

// Or with options
await stream.startVideo({
  cameraId?: string,
  hd?: boolean,           // 720p
  fullHd?: boolean,       // 1080p
  mirrored?: boolean,
  virtualBackground?: { imageUrl: string | 'blur' | undefined, cropped?: boolean },
});

// CRITICAL: Attach video to DOM
// 1. Container MUST be a <video-player-container> custom element
// 2. attachVideo returns an element - append it to the container
// 3. Do NOT pass container as third parameter
const videoElement = await stream.attachVideo(userId, VideoQuality.Video_720P);
container.appendChild(videoElement);

// Stop video
await stream.stopVideo();

// Detach video (cleanup)
stream.detachVideo(userId);

// Device management
stream.getCameraList(): MediaDevice[];
await stream.switchCamera(deviceId);

Screen Share

// Start sharing
await stream.startShareScreen({
  broadcastToSubsession: boolean,
  optimizedForSharedVideo: boolean,
  secondaryCameraId: string, // Share secondary camera
});

// Stop sharing
await stream.stopShareScreen();

// View others' share
await stream.startShareView(canvas, userId);
stream.stopShareView();

Events

// Connection
client.on("connection-change", (payload) => {
  // payload.state: 'Connected' | 'Reconnecting' | 'Closed' | 'Fail'
});

// Users
client.on("user-added", (participants: Participant[]) => {});
client.on("user-updated", (participants: Participant[]) => {});
client.on("user-removed", (participants: Participant[]) => {});

// Audio
client.on("current-audio-change", (payload) => {
  // payload.action: 'join' | 'leave' | 'muted' | 'unmuted'
});
client.on("active-speaker", (payload) => {
  // payload.activeSpeaker: { oderId: number, oderId?: number }[]
});

// Video
client.on("video-active-change", (payload) => {
  // payload.userId, payload.state: 'Active' | 'Inactive'
});
client.on("peer-video-state-change", (payload) => {
  // payload.userId, payload.action: 'Start' | 'Stop'
});

// Screen Share
client.on("active-share-change", (payload) => {
  // payload.userId, payload.state: 'Active' | 'Inactive'
});
client.on("peer-share-state-change", (payload) => {
  // payload.userId, payload.action: 'Start' | 'Stop'
});

// Chat
client.on("chat-on-message", (payload) => {
  // payload.message, payload.sender, payload.timestamp
});

// Device
client.on("device-change", () => {
  // Re-enumerate devices
});

Framework-Specific Implementation Guides

For complete implementation examples with full project setup, hooks/composables/services, and components:

• references/react.md - React 19 + Vite 7 + TypeScript + shadcn/ui implementation
• references/vue.md - Vue 3 + Vite 7 + TypeScript + shadcn-vue implementation
• references/angular.md - Angular 21 + Standalone Components + Signals implementation
• references/svelte.md - Svelte 5 + Runes + Vite 7 + TypeScript implementation

Quick Setup Requirements

All frameworks MUST configure:

1. COOP/COEP Headers (for SharedArrayBuffer support):

// vite.config.ts
server: {
  headers: {
    'Cross-Origin-Opener-Policy': 'same-origin',
    'Cross-Origin-Embedder-Policy': 'require-corp',
  },
}

2. TypeScript Custom Elements (for video rendering):

// src/types/zoom-elements.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    "video-player-container": React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement>,
      HTMLElement
    >;
  }
}

Core Implementation Pattern

All implementations should follow this pattern:

1. Client Management - Singleton client with init/join/leave lifecycle
2. Media Stream - Audio/video/screen share controls with state sync
3. Participants - User list with video state change listeners
4. Video Rendering - Use video-player-container + attachVideo()
5. Event Handling - Connection, audio, video, chat events
6. Error Handling - Map SDK error codes to user messages

Custom UI Responsibility

The Video SDK Web package provides media/session APIs, not a complete meeting toolbar. In custom or PureJS samples, implement these controls explicitly:

• Device selectors: populate stream.getMicList(), stream.getSpeakerList(), and stream.getCameraList() after permissions are available; refresh on device-change and device-permission-change; switch with switchMicrophone, switchSpeaker, and switchCamera.
• Camera effects: check stream.isSupportVirtualBackground() before offering blur; apply blur with startVideo({ virtualBackground: { imageUrl: 'blur' } }) or stream.updateVirtualBackgroundImage('blur').
• Statistics: subscribe with subscribeAudioStatisticData, subscribeVideoStatisticData, and subscribeShareStatisticData; render audio-statistic-data-change, video-statistic-data-change, and share-statistic-data-change payloads or poll get*StatisticData().
• Participant media reconciliation: after join and after user-added, user-updated, user-removed, and peer-video-state-change, call client.getAllUser() and render/detach users based on bVideoOn. Do not rely on events alone for users who were already in the session.
• Screen share reconciliation: after join and on active-share-change, peer-share-state-change, share-content-change, and passively-stop-share, check stream.getActiveShareUserId() / stream.getShareUserList() and attach or detach share views yourself.
• Recording/captions: wire toolbar buttons to client.getRecordingClient() and client.getLiveTranscriptionClient(); handle host/account privilege failures and update UI from recording-change, caption-message, caption-enable, and caption-host-disable.

JWT Token Requirements

Generate JWT on your server using HMAC SHA256. Never expose SDK secret in client code.

Required Claims

{
  app_key: 'YOUR_SDK_KEY',    // Video SDK key
  tpc: 'session-name',        // Session name (max 200 chars), must match join() topic
  role_type: 1,               // 1 = host/co-host, 0 = participant
  version: 1,                 // Always set to 1
  iat: Math.floor(Date.now() / 1000) - 30,  // Issued at (subtract 30s for clock skew)
  exp: iat + 7200,            // Expiration: min 1800s, max 48 hours after iat
}

Optional Claims

Claim	Description
user_key	Unique user identifier (max 36 chars)
session_key	Session identifier for cloud recording (max 36 chars)
geo_regions	Data center regions: AU,BR,CA,DE,HK,IN,JP,CN,MX,NL,SG,US
cloud_recording_option	0 = combined video, 1 = separate files per user
cloud_recording_election	1 to record user's self-view
cloud_recording_transcript_option	0 = none, 1 = transcript, 2 = transcript + summary
video_webrtc_mode	0 = disable, 1 = enable WebRTC video
audio_webrtc_mode	1 = enable WebRTC audio (Web only)
telemetry_tracking_id	For Web SDK telemetry tracking

Node.js(jsrsasign) Quick Start JWT Generator Service:

git clone https://github.com/zoom/videosdk-auth-endpoint-sample.git

cd videosdk-auth-endpoint-sample

bun install
# or 
npm install
# Rename .env.example to .env, edit the file contents to include your Zoom Video SDK key and secret, save the file contents, and close the file
mv .env.example .env
# Start the server
# server code https://raw.githubusercontent.com/zoom/videosdk-auth-endpoint-sample/refs/heads/master/src/index.js
bun run start
# or
npm run start

jsrsasign Example Code:

import { KJUR } from "jsrsasign";

const iat = Math.floor(Date.now() / 1000) - 30;
const exp = iat + 60 * 60 * 2; // 2 hours

const payload = {
  app_key: process.env.ZOOM_SDK_KEY,
  tpc: "session-name",
  role_type: 1,
  version: 1,
  video_webrtc_mode: 1,
  audio_webrtc_mode: 1,
  iat,
  exp,
};

const token = KJUR.jws.JWS.sign(
  "HS256",
  JSON.stringify({ alg: "HS256", typ: "JWT" }),
  JSON.stringify(payload),
  process.env.ZOOM_SDK_SECRET
);

Init Options

interface InitOptions {
  webEndpoint?: string; // Custom endpoint
  enforceMultipleVideos?: boolean | { disableRenderLimits?: boolean };
  enforceVirtualBackground?: boolean;
  stayAwake?: boolean; // Prevent screen dimming
  leaveOnPageUnload?: boolean; // Quick leave on page close
  patchJsMedia?: boolean; // Apply latest media fixes (recommended: true)
  alternativeNameForVideoPlayer?: string;
}

Video Quality Enum

enum VideoQuality {
  Video_90P = 0,
  Video_180P = 1,
  Video_360P = 2,
  Video_720P = 3,
  Video_1080P = 4,
}

Best Practices

1. Always check browser support before initializing
2. Generate JWT on server - never expose SDK secret in client
3. Handle connection events for robust session management
4. Request user gesture before starting audio (browser requirement)
5. Use patchJsMedia: true for latest WebAssembly fixes
6. Set leaveOnPageUnload: true for clean disconnection
7. Implement error handling for all async operations
8. Clean up event listeners on session end

Common Issues

Issue	Solution
Audio doesn't start	Requires user gesture (click/tap)
Video not rendering	Use video-player-container custom element and append attachVideo() result
Video briefly appears then goes black/hidden	Remove old canvas/avatar/name overlays; the returned video-player must be the visible tile
Late join misses remote video/share	Reconcile getAllUser(), getShareUserList(), and active share state after join and media events
Device/blur/stats controls missing	Build toolbar controls manually with MediaStream device, virtual background, and statistic APIs
JWT invalid	Verify tpc matches session name
SharedArrayBuffer error	MUST add COOP/COEP headers in vite.config.ts
OPERATION_TIMEOUT on startVideo	Check camera permissions and ensure COOP/COEP headers are set
INVALID_PARAMETERS on attachVideo	Don't pass container as 3rd param - append the returned element instead
Self-video not showing	Pass currentUserVideoOn prop to VideoGrid (participant.bVideoOn may lag)
Participants not updating	Listen for video-active-change and peer-video-state-change events
"Waiting for participants" stuck	Pass isJoined to useParticipants hook and listen for connection-change

Detailed Guides

Core Concepts (read these first — they apply to every feature)

• concepts/sdk-architecture-pattern.md - The universal 5-step pattern (createClient → init → join → getMediaStream → use) that every feature follows
• concepts/singleton-hierarchy.md - Service-locator navigation tree from ZoomVideo root to every sub-client (media, chat, recording, subsession, command, etc.)

Feature References

• references/sessions.md - Session lifecycle, user roles, JWT token, connection events
• references/audio.md - Audio controls, devices, muting, dial-out, noise suppression
• references/video.md - Video capture, rendering, virtual background, PTZ cameras
• references/screen-share.md - Screen sharing, annotation, tab audio, share privileges
• references/features.md - Preview, recording, subsessions, live stream, command channel, transcription, PSTN, SIP, quality stats
• references/advanced.md - Chat, custom processors, whiteboard
• references/sample-app-2.4.5.md - Reviewed React/Vite sample map: RTMS, incoming RTMP, broadcast viewing, whiteboard, voice translation, processors, and video masks
• references/browser-support.md - Browser compatibility, SharedArrayBuffer, CSP headers
• references/error-codes.md - Complete error code reference
• troubleshooting/common-issues.md - Troubleshooting guide: symptoms → causes → fixes for the most common Video SDK bugs

Type Definitions Location

All TypeScript definitions are in @zoom/videosdk/dist/types:

• index.d.ts - Main exports
• zoomvideo.d.ts - ZoomVideo namespace
• videoclient.d.ts - VideoClient methods and events
• media.d.ts - MediaStream, audio/video options
• common.d.ts - Shared types (Participant, enums)
• chat.d.ts - Chat client
• recording.d.ts - Recording client
• subsession.d.ts - Breakout rooms
• broadcast-streaming.d.ts - Broadcast host/viewer APIs
• real-time-media-streams.d.ts - RTMS lifecycle client
• event-callback.d.ts - Event names and payloads

Resources Homepage

• Official Docs: https://developers.zoom.us/docs/video-sdk/web/
• API Reference: https://marketplacefront.zoom.us/sdk/videosdk/web/
• Sample App: https://github.com/zoom/videosdk-web-sample
• Angular: https://developers.zoom.us/docs/video-sdk/web/frameworks/#using-angular
• Requirejs: https://developers.zoom.us/docs/video-sdk/web/frameworks/#using-amd-mode-requirejs-or-named-modules

Official Docs URLs

# Main Documentation
https://developers.zoom.us/docs/video-sdk/web/get-started/
https://developers.zoom.us/docs/video-sdk/web/sessions/
https://developers.zoom.us/docs/video-sdk/web/event-handling/

# Audio & Video
https://developers.zoom.us/docs/video-sdk/web/video/
https://developers.zoom.us/docs/video-sdk/web/audio/
https://developers.zoom.us/docs/video-sdk/web/preview/

# Screen Sharing
https://developers.zoom.us/docs/video-sdk/web/share/
https://developers.zoom.us/docs/video-sdk/web/share-annotation/
https://developers.zoom.us/docs/video-sdk/web/share-browser-options/

# Advanced Features
https://developers.zoom.us/docs/video-sdk/web/recording/
https://developers.zoom.us/docs/video-sdk/web/subsessions/
https://developers.zoom.us/docs/video-sdk/web/live-stream/
https://developers.zoom.us/docs/video-sdk/web/command-channel/
https://developers.zoom.us/docs/video-sdk/web/transcription-translation/
https://developers.zoom.us/docs/video-sdk/web/chat/

# Phone Integration
https://developers.zoom.us/docs/video-sdk/web/pstn/
https://developers.zoom.us/docs/video-sdk/web/sip/

# Quality & Compatibility
https://developers.zoom.us/docs/video-sdk/web/quality/
https://developers.zoom.us/docs/video-sdk/web/browser-support/
https://developers.zoom.us/docs/video-sdk/web/sharedarraybuffer/
https://developers.zoom.us/docs/video-sdk/web/error-codes/

# Other
https://developers.zoom.us/docs/video-sdk/web/virtual-background/
https://developers.zoom.us/docs/video-sdk/web/frameworks/

Repo-Local Appendices

The documents above are primarily based on the incoming zoom-videosdk-web skill. The files below remain in this repo as complementary material for deeper examples, compatibility shims, and operational debugging.

Operational Docs

• RUNBOOK.md - 5-minute preflight checks before deep debugging
• MAINTENANCE.md - upstream/source-maintenance notes for this imported skill

Compatibility References

• references/web.md - compatibility index for repo links that previously pointed to the monolithic web reference
• references/web-reference.md - repo-local extended API reference
• references/events-reference.md - repo-local event catalog and payload notes
• troubleshooting/common-issues.md - canonical troubleshooting guide from the imported skill
• references/common-issues.md - compatibility pointer for upstream-style reference links

Complementary Examples

• examples/session-join-pattern.md - complete join flow example
• examples/video-rendering.md - repo-local rendering patterns
• examples/event-handling.md - detailed event handling examples
• examples/screen-share.md - screen sharing send/view patterns
• examples/chat.md - in-session messaging examples
• examples/command-channel.md - custom signaling examples
• examples/recording.md - recording control examples
• examples/transcription.md - live transcription examples
• examples/react-hooks.md - @zoom/videosdk-react patterns
• examples/framework-integrations.md - repo-local SSR and framework notes