Zoom Video Sdk

Zoom Video SDK

Build custom video experiences powered by Zoom's infrastructure.

Current Release Snapshot

Verified from the public changelog and package registries on 2026-07-10:

Native 2.6.0 contains breaking changes. Read the native 2.6.0 upgrade reference before using the older 2.5.10 package inventories bundled into several child skills.

Hard Routing Guardrail (Read First)

• If the user asks for custom real-time video app behavior (topic/session join, custom rendering, attach/detach), route to Video SDK.
• Do not switch to REST meeting endpoints for Video SDK join flows.
• Video SDK does not use Meeting IDs, join_url, or Meeting SDK join payload fields (meetingNumber, passWord).
• After confirming Video SDK, select one platform child skill before generating implementation code.

Platform Router

Do not answer from this root's Web quick start when the user selected another platform.

Chaining Order

Use this order so workflow guidance and version-specific APIs remain distinct:

1. Read this root skill to confirm Video SDK rather than Meeting SDK.
2. Read the selected platform SKILL.md for architecture, lifecycle, implementation patterns, and troubleshooting.
3. If the downloaded SDK package contains a bundled API skill, read that skill and its relevant Markdown/JSON pair to verify exact signatures, enums, callbacks, threading, and role requirements.
4. Cross-check generated API documentation against package headers, TypeScript source, or exported wrapper APIs.
5. Load only the cross-product skill required by the feature using the table below.
6. Return to the platform runbook for validation and troubleshooting.

For React Native, Flutter, and Unity, never invent wrapper APIs from native Android/iOS/Windows documentation. Use native documentation only to understand behavior after confirming the wrapper exports the feature.

Meeting SDK vs Video SDK

UI Options (Web)

Video SDK gives you full control over the UI:

Prerequisites

• Zoom Video SDK credentials from Marketplace
• SDK Key and Secret
• A development environment for the selected platform

Need to create the Video SDK app first? Use Marketplace app management for app creation, manifest validation, app-type quirks, and credential response shapes before generating Video SDK session JWTs.

Need a Video SDK session JWT? Start with authorization. Use zoom-oauth only for OAuth or REST API flows outside the session join contract.

Need pre-join diagnostics on web? Use probe-sdk before Video SDK join() to reduce first-minute failures.

Start troubleshooting fast: Use the 5-Minute Runbook before deep debugging.

SDK-Bundled API Skills

The reviewed Video SDK 2.5.10 packages include version-matched API skills and paired Markdown/JSON documentation for several native platforms. These are historical package snapshots now that native 2.6.0 is public. Keep the platform skill in this repository as the workflow entry point, then use the bundled skill from the exact package you deploy to verify signatures, enums, callbacks, threading, role requirements, and object lifetime.

Flutter and Unity packages in this review do not include an equivalent bundled SKILL.md. Web now includes an official build skill and AI-readable JSON type definitions; route Web work through web/SKILL.md and use web/references/type-definitions-json.md for exact 2.5.0 API verification. The older React/Vite sample remains mapped in web/references/sample-app-2.4.5.md. Do not infer platform parity from another package; verify against that platform's exported API.

Quick Start (Web)

NPM Usage (Bundler like Vite/Webpack)

javascriptCopy code
import ZoomVideo from '@zoom/videosdk';

const client = ZoomVideo.createClient();
await client.init('en-US', 'Global', { patchJsMedia: true });
await client.join(topic, signature, userName, password);

// IMPORTANT: getMediaStream() ONLY works AFTER join()
const stream = client.getMediaStream();
await stream.startVideo();
await stream.startAudio();

CDN Usage (No Bundler)

WARNING: Ad blockers block source.zoom.us. Self-host the SDK to avoid issues.

bashCopy code
# Download SDK locally example VERSION=2.5.0
curl "https://source.zoom.us/videosdk/zoom-video-{VERSION}.min.js" -o js/zoom-video-sdk.min.js

htmlCopy code
<script src="js/zoom-video-sdk.min.js"></script>

javascriptCopy code
// CDN exports as WebVideoSDK, NOT ZoomVideo
// Must use .default property
const ZoomVideo = WebVideoSDK.default;
const client = ZoomVideo.createClient();

await client.init('en-US', 'Global', { patchJsMedia: true });
await client.join(topic, signature, userName, password);

// IMPORTANT: getMediaStream() ONLY works AFTER join()
const stream = client.getMediaStream();
await stream.startVideo();
await stream.startAudio();

ES Module with CDN (Race Condition Fix)

When using <script type="module"> with CDN, SDK may not be loaded yet:

javascriptCopy code
// Wait for SDK to load before using
function waitForSDK(timeout = 10000) {
  return new Promise((resolve, reject) => {
    if (typeof WebVideoSDK !== 'undefined') {
      resolve();
      return;
    }
    const start = Date.now();
    const check = setInterval(() => {
      if (typeof WebVideoSDK !== 'undefined') {
        clearInterval(check);
        resolve();
      } else if (Date.now() - start > timeout) {
        clearInterval(check);
        reject(new Error('SDK failed to load'));
      }
    }, 100);
  });
}

// Usage
await waitForSDK();
const ZoomVideo = WebVideoSDK.default;
const client = ZoomVideo.createClient();

SDK Lifecycle (CRITICAL ORDER)

The SDK has a strict lifecycle. Violating it causes silent failures.

Copy code
1. Create client:     client = ZoomVideo.createClient()
2. Initialize:        await client.init('en-US', 'Global', options)
3. Join session:      await client.join(topic, signature, userName, password)
4. Get stream:        stream = client.getMediaStream()  ← ONLY AFTER JOIN
5. Start media:       await stream.startVideo() / await stream.startAudio()

Common Mistake (Silent Failure):

javascriptCopy code
// ❌ WRONG: Getting stream before joining
const client = ZoomVideo.createClient();
await client.init('en-US', 'Global');
const stream = client.getMediaStream();  // Returns undefined!
await client.join(...);

// ✅ CORRECT: Get stream after joining
const client = ZoomVideo.createClient();
await client.init('en-US', 'Global');
await client.join(...);
const stream = client.getMediaStream();  // Works!

Video Rendering (Event-Driven)

The SDK is event-driven. You must listen for events and render videos accordingly.

Use attachVideo() NOT renderVideo()

javascriptCopy code
import { VideoQuality } from '@zoom/videosdk';

// Start your camera
await stream.startVideo();

// Attach video - returns element to append to DOM
const element = await stream.attachVideo(userId, VideoQuality.Video_360P);
container.appendChild(element);

// Detach when done
await stream.detachVideo(userId);

Required Events

javascriptCopy code
// When other participant's video turns on/off
client.on('peer-video-state-change', async (payload) => {
  const { action, userId } = payload;
  if (action === 'Start') {
    const el = await stream.attachVideo(userId, VideoQuality.Video_360P);
    container.appendChild(el);
  } else {
    await stream.detachVideo(userId);
  }
});

// When participants join/leave
client.on('user-added', (payload) => { /* check bVideoOn */ });
client.on('user-removed', (payload) => { stream.detachVideo(payload.userId); });

See web/references/web.md for complete event handling patterns.

Key Concepts

Session Creation Model

Important: Video SDK sessions are created just-in-time, not in advance.

How Sessions Work

1. No pre-creation needed: Sessions don't exist until someone joins
2. Topic = Session ID: Any participants joining with the same topic string join the same session
3. First join creates it: The session is created when the first participant joins
4. No meeting ID: There's no numeric meeting ID like in Zoom Meetings

javascriptCopy code
// Session is created on-the-fly when first user joins
// Any string can be the topic - it becomes the session identifier
await client.join('my-custom-session-123', signature, 'User Name');

// Other participants join the SAME session by using the SAME topic
await client.join('my-custom-session-123', signature, 'Another User');

Signature Endpoint Setup

The signature endpoint must be accessible from your frontend without CORS issues.

Option 1: Same-Origin Proxy (Recommended)

nginxCopy code
# Nginx config
location /api/ {
    proxy_pass http://YOUR_BACKEND_HOST:3005/api/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
}

javascriptCopy code
// Frontend uses relative URL (same origin)
const response = await fetch('/api/signature', { ... });

Option 2: CORS Configuration

javascriptCopy code
// Express.js backend
const cors = require('cors');
app.use(cors({
  origin: ['https://your-domain.com'],
  credentials: true
}));

WARNING: Mixed content (HTTPS page → HTTP API) will be blocked by browsers.

Use Cases

BYOS (Bring Your Own Storage)

Video SDK feature - Zoom saves cloud recordings directly to your Amazon S3 bucket. No downloading required.

Official docs: https://developers.zoom.us/docs/build/storage/

Prerequisites:

• Video SDK account with Cloud Recording add-on (Universal Credit includes this)
• AWS S3 bucket

Authentication options:

1. AWS Access Key - simpler setup
2. Cross Account Access - more secure (IAM role assumption)

S3 path structure:

Copy code
Buckets/{bucketName}/cmr/byos/{YYYY}/{MM}/{DD}/{GUID}/cmr_byos/

Key benefits:

• Zero download bandwidth costs
• Direct storage during recording
• Config-only setup (no webhook/download code needed)

Setup location: Developer Portal → Account Settings → General → Communications Content Storage Location

See ../general/use-cases/video-sdk-bring-your-own-storage.md for complete setup guide.

Detailed References

UI & Components

• references/ui-toolkit.md - Pre-built UI components (Web)
• references/triage-intake.md - What to ask first (turn vague reports into answers)
• references/session-lifecycle.md - Correct API ordering + event-driven rendering
• references/licensing-and-entitlements.md - License/admin prerequisites
• references/token-contract-test-spec.md - Shared backend token contract and cross-platform smoke test

Platform Guides

• references/authorization.md - Video SDK JWT generation
• web/SKILL.md - Web Video SDK (JavaScript/TypeScript)
  • web/SKILL.md - Complete documentation navigation
  • web/examples/react-hooks.md - Official React hooks library
  • web/examples/framework-integrations.md - Next.js, Vue/Nuxt patterns
• react-native/SKILL.md - React Native Video SDK (mobile wrapper, helper/event architecture)
  • react-native/SKILL.md - React Native documentation navigation
  • react-native/examples/session-join-pattern.md - Tokenized session join flow
• flutter/SKILL.md - Flutter Video SDK (mobile wrapper, event-driven architecture)
  • flutter/SKILL.md - Flutter documentation navigation
  • flutter/examples/session-join-pattern.md - Tokenized session join flow
• android/SKILL.md - Android Video SDK (native mobile custom UI, tokenized sessions)
• ios/SKILL.md - iOS Video SDK (native mobile custom UI, delegate-driven lifecycle)
• macos/SKILL.md - macOS Video SDK (desktop native apps, custom session windows)
• unity/SKILL.md - Unity Video SDK wrapper (game-engine integration, scene-driven UX)
• linux/SKILL.md - Linux Video SDK overview (C++ headless bots)
• linux/linux.md - Linux C++ SDK (headless bots, raw media capture/injection)
• linux/references/linux-reference.md - Linux API Reference
• windows/SKILL.md - Windows C++ SDK (desktop applications, raw media capture/injection)
• windows/references/windows-reference.md - Windows API Reference
• references/troubleshooting.md - Common issues and solutions
• references/forum-top-questions.md - Common forum question patterns (what to cover)

Sample Repositories

Official (by Zoom)

Full list: See general/references/community-repos.md

Resources

• Official docs: https://developers.zoom.us/docs/video-sdk/
• Developer forum: https://devforum.zoom.us/

Environment Variables

• See references/environment-variables.md for standardized .env keys and where to find each value.

Linux Operations

• linux/RUNBOOK.md - Linux platform preflight and debugging checklist.