| name | build-zoom-video-sdk-app |
| description | Reference skill for Zoom Video SDK. Use after routing to a custom-session workflow when the user needs full control over the video experience rather than an actual Zoom meeting. |
| triggers | ["custom video","video sdk","build video app","video session","video chat","video call","video conferencing","custom video ui","twitter spaces","clubhouse alternative","audio-only room","screen sharing","virtual background","native video sdk"] |
/build-zoom-video-sdk-app
Background reference for fully custom video-session products. Prefer plan-zoom-product first when the boundary between Meeting SDK and Video SDK is still unclear.
Build custom video experiences powered by Zoom's infrastructure.
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).
Meeting SDK vs Video SDK
| Feature | Meeting SDK | Video SDK |
|---|
| UI | Default Zoom UI or Custom UI | Fully custom UI (you build it) |
| Experience | Zoom meetings | Video sessions |
| Branding | Limited customization | Full branding control |
| Features | Full Zoom features | Core video features |
UI Options (Web)
Video SDK gives you full control over the UI:
| Option | Description |
|---|
| UI Toolkit | Pre-built React components (low-code) |
| Custom UI | Build your own UI using the SDK APIs |
Prerequisites
- Zoom Video SDK credentials from Marketplace
- SDK Key and Secret
- Web development environment
Need help with OAuth or signatures? See the zoom-oauth skill for authentication flows.
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.
Quick Start (Web)
NPM Usage (Bundler like Vite/Webpack)
import ZoomVideo from '@zoom/videosdk';
const client = ZoomVideo.createClient();
await client.init('en-US', 'Global', { patchJsMedia: true });
await client.join(topic, signature, userName, password);
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.
curl "https://source.zoom.us/videosdk/zoom-video-1.12.0.min.js" -o js/zoom-video-sdk.min.js
<script src="js/zoom-video-sdk.min.js"></script>
const ZoomVideo = WebVideoSDK.default;
const client = ZoomVideo.createClient();
await client.init('en-US', 'Global', { patchJsMedia: true });
await client.join(topic, signature, userName, password);
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:
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);
});
}
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.
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):
const client = ZoomVideo.createClient();
await client.init('en-US', 'Global');
const stream = client.getMediaStream();
await client.join(...);
const client = ZoomVideo.createClient();
await client.init('en-US', 'Global');
await client.join(...);
const stream = client.getMediaStream();
Video Rendering (Event-Driven)
The SDK is event-driven. You must listen for events and render videos accordingly.
Use attachVideo() NOT renderVideo()
import { VideoQuality } from '@zoom/videosdk';
await stream.startVideo();
const element = await stream.attachVideo(userId, VideoQuality.Video_360P);
container.appendChild(element);
await stream.detachVideo(userId);
Required Events
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);
}
});
client.on('user-added', (payload) => { });
client.on('user-removed', (payload) => { stream.detachVideo(payload.userId); });
See web/references/web.md for complete event handling patterns.
Key Concepts
| Concept | Description |
|---|
| Session | Video session (not a meeting) |
| Topic | Session identifier (any string you choose) |
| Signature | JWT for authorization |
| MediaStream | Audio/video stream control |
Session Creation Model
Important: Video SDK sessions are created just-in-time, not in advance.
| Aspect | Video SDK | Meeting SDK |
|---|
| Pre-creation | NOT required | Create meeting via API first |
| Session start | First participant joins with topic | Join existing meeting ID |
| Topic | Any string (you define it) | Meeting ID from API |
| Scheduling | N/A - sessions are ad-hoc | Meetings can be scheduled |
How Sessions Work
- No pre-creation needed: Sessions don't exist until someone joins
- Topic = Session ID: Any participants joining with the same
topic string join the same session
- First join creates it: The session is created when the first participant joins
- No meeting ID: There's no numeric meeting ID like in Zoom Meetings
await client.join('my-custom-session-123', signature, 'User Name');
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)
# Nginx config
location /api/ {
proxy_pass http://YOUR_BACKEND_HOST:3005/api/;
proxy_http_version 1.1;
proxy_set_header Host $host;
}
const response = await fetch('/api/signature', { ... });
Option 2: CORS Configuration
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:
- AWS Access Key - simpler setup
- Cross Account Access - more secure (IAM role assumption)
S3 path structure:
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
Platform Guides
Sample Repositories
Official (by Zoom)
Full list: See general/references/community-repos.md
Resources
Environment Variables
Linux Operations
