Twilio Video API — Complete Guide to Real-Time Video

In this tutorial, you will learn about Twilio Video API. We cover key concepts, practical examples, and best practices to help you master this topic.

Twilio Video API enables real-time video and audio communication with WebRTC, supporting group rooms, screen sharing, recording, and custom video layouts for building immersive communication applications.

What You'll Learn

• Setting up Twilio Video for web and mobile
• Creating and joining video rooms
• Screen sharing, recording, and track management

Why It Matters

WebRTC is powerful but complex. Twilio Video abstracts the complexity of STUN/TURN servers, codec negotiation, and connection management into a simple API.

Real-World Use

Durga Antivirus Pro technical support uses Twilio Video for screen-sharing troubleshooting sessions. Customers share their screen while a support engineer guides them through configuration, with session recording for Compliance.

flowchart LR
    U["User"] --> R["Twilio Video Room"]
    A["Agent"] --> R
    U -->|"Share Screen"| R
    A -->|"Share Screen"| R
    R --> V["Recording"]
    style R fill:#dbeafe,stroke:#2563eb

Code Examples

// Generate access token (server-side)
const twilio = require('twilio');

function getVideoToken(identity, roomName) {
  const AccessToken = twilio.jwt.AccessToken;
  const VideoGrant = AccessToken.VideoGrant;

  const token = new AccessToken(accountSid, apiKey, apiSecret, { identity });
  const grant = new VideoGrant({ room: roomName });
  token.addGrant(grant);

  return token.toJwt();
}

// Client joins a room
const { connect } = require('twilio-video');

async function joinRoom(token, roomName) {
  const room = await connect(token, {
    name: roomName,
    audio: true,
    video: true,
  });

  console.log('Joined room:', room.name);

  room.participants.forEach(participant => {
    console.log('Participant:', participant.identity);
    participant.tracks.forEach(track => {
      if (track.isSubscribed) {
        attachTrack(track);
      }
    });
  });

  room.on('participantConnected', participant => {
    console.log('Participant joined:', participant.identity);
  });
}

Expected output: User joins a video room with audio/video enabled and sees other participants.

// Screen sharing
async function shareScreen(room) {
  try {
    const stream = await navigator.mediaDevices.getDisplayMedia();
    const track = stream.getTracks()[0];
    const publication = await room.localParticipant.publishTrack(track);

    track.onended = () => {
      publication.unpublish();
    };
  } catch (err) {
    console.error('Screen share failed:', err);
  }
}

// Room recording
async function startRecording(roomSid) {
  const client = new twilio(accountSid, authToken);
  const recording = await client.video.v1.recordings.create({
    groupSid: roomSid,
  });
  console.log('Recording SID:', recording.sid);
}

Expected output: Screen sharing track published to the room; recording started for the video session.

# Server-side room management
from twilio.rest import Client

client = Client(account_sid, auth_token)

# Create a group room
room = client.video.v1.rooms.create(
    unique_name="support-session-1234",
    type="group",
    max_participants=4
)
print(f"Room SID: {room.sid}")

# List active rooms
active_rooms = client.video.v1.rooms.list(status="in-progress")
for r in active_rooms:
    print(f"Active: {r.sid} - {r.unique_name} ({r.participant_count} participants)")

# Complete a room
client.video.v1.rooms(room.sid).update(status="completed")

Expected output: Group room created, active rooms listed, and room completed after session ends.

Common Mistakes

1. Generating Tokens Client-Side

Access tokens contain API credentials. Always generate tokens on the server and pass them to the client.

2. Not Handling Track Unsubscription

When a participant leaves, their tracks become unsubscribed. Remove detached video elements to avoid ghost tracks.

3. Ignoring Network Quality Events

Poor network degrades video quality. Listen for networkQualityLevel events and show connection status to users.

4. Using Peer-to-Peer Rooms for Groups

Peer-to-peer rooms are limited to 2 participants. Use group rooms for 3+ participants.

5. Not Cleaning Up Rooms

Completed rooms accumulate. Use room status callbacks or scheduled cleanup to manage room lifecycle.

Practice Questions

1. Why must access tokens be generated server-side for Twilio Video?
2. What is the difference between peer-to-peer and group rooms?
3. How do you implement screen sharing with Twilio Video?
4. What happens when a participant's network degrades?
5. How do you record a Twilio Video room session?

Answers:

1. Tokens contain API credentials; generating client-side exposes your secret keys.
2. Peer-to-peer rooms support 2 participants directly; group rooms support up to 50 via TURN server.
3. Use getDisplayMedia to capture the screen, then publish the track to the room.
4. Video quality adjusts via the networkQualityLevel event; you can show connection status to users.
5. Create a Recording resource with the room SID when the session starts.

Challenge: Build a one-on-one video support chat with Twilio Video including: room creation, token generation, audio/video toggles, screen sharing, and session recording with a stop button.

FAQ

Mini Project

Build a telemedicine consultation app using Twilio Video: doctor and patient join a private room, both share cameras, doctor can share diagnostic images via screen share, and the session is recorded for medical records.

What's Next

Learn about Twilio Chat API for in-app messaging companion to video, or explore Twilio Conversations API for multi-channel follow-up communication.