twilio-video

What this skill does

# twilio-video

## Purpose

Enable OpenClaw to design, implement, operate, and troubleshoot Twilio Video in production:

- Create and manage Video Rooms (Group and Peer-to-Peer), including lifecycle controls.
- Issue Access Tokens with Video grants (identity, room scoping, TTL, key rotation).
- Publish/subscribe tracks (audio/video/data), manage track priorities, and implement moderation (mute/unpublish/remove participants).
- Enable and operate recording via Compositions (server-side recording outputs), including callbacks and storage pipelines.
- Use Network Quality API and bandwidth profiles to maintain call quality under real-world network constraints.
- Integrate Video with Twilio cluster patterns: webhooks, auth, rate limits, cost controls, and operational playbooks.

This guide assumes you are building a multi-tenant, production WebRTC system with compliance, observability, and incident response requirements.

---

## Prerequisites

### Twilio account + credentials

- Twilio Account SID (format `AC...`)
- Twilio API Key SID (format `SK...`) and Secret
- (Optional) Twilio Auth Token (format `...`) for legacy/basic auth; prefer API Key + Secret for server-to-server.
- A Twilio Video-enabled project (default for most accounts).

Create API Key:

```bash
twilio api:core:keys:create --friendly-name "video-prod-key-2026-02"
```

### Supported SDKs / libraries (pin versions)

Server-side (token minting, REST API calls):

- Node.js: `node >= 20.11.1` (LTS), npm `>= 10.2.4`
  - `[email protected]` (Twilio Node helper library)
  - `[email protected]` (if you implement custom JWT handling; Twilio helper can mint tokens)
- Python: `python >= 3.11.7`
  - `twilio==9.4.1`
- Go: `go >= 1.22.1`
  - `github.com/twilio/[email protected]`

Client-side:

- Twilio Video JS SDK: `[email protected]`
  - Browser support: latest Chrome/Edge, Firefox ESR, Safari 17+ (macOS/iOS constraints apply)
- iOS: TwilioVideo iOS SDK `5.10.0` (CocoaPods/SPM)
- Android: Twilio Video Android SDK `7.6.0` (Gradle)

Twilio CLI:

- `[email protected]` (Node-based)
- Plugins:
  - `@twilio-labs/[email protected]` (Video commands; plugin availability varies—verify in your environment)

Install Twilio CLI:

```bash
npm i -g [email protected]
twilio --version
```

Install plugin:

```bash
twilio plugins:install @twilio-labs/[email protected]
twilio plugins
```

### Auth setup (local dev + CI)

Prefer environment variables:

- `TWILIO_ACCOUNT_SID`
- `TWILIO_API_KEY`
- `TWILIO_API_SECRET`
- (Optional) `TWILIO_AUTH_TOKEN` (avoid in CI if possible)

Example (bash):

```bash
export TWILIO_ACCOUNT_SID="YOUR_ACCOUNT_SID"
export TWILIO_API_KEY="YOUR_API_KEY_SID"
export TWILIO_API_SECRET="your_api_secret_from_console"
```

Twilio CLI login (stores credentials locally; not recommended for CI runners):

```bash
twilio login
```

### Network + infra prerequisites

- Public HTTPS endpoint for webhooks (Composition callbacks, Status callbacks).
- TLS: modern ciphers; certificate from a trusted CA (Let’s Encrypt OK).
- Time sync: NTP enabled on servers minting JWTs (clock skew breaks tokens).
- TURN/STUN: Twilio provides; ensure outbound UDP/TCP 3478/5349 allowed; enterprise networks may require TCP/TLS fallback.

---

## Core Concepts

### Rooms: Group vs Peer-to-Peer (P2P)

- **Group Room**: media routed via Twilio’s SFU; supports larger rooms, recording/compositions, bandwidth profiles, network quality, dominant speaker, etc. Default for most production use.
- **Peer-to-Peer Room**: direct mesh between participants; limited scalability; fewer server-side features; generally not recommended for production beyond 1:1 with strict latency constraints.

Key properties:
- `type`: `group` | `group-small` | `peer-to-peer` (availability depends on account/region)
- `status`: `in-progress` | `completed`
- `maxParticipants`: enforce caps to control cost and quality

### Participants and Tracks

- **Participant**: identity in a room (unique per room).
- **Tracks**:
  - Audio track
  - Video track
  - Data track (reliable/unreliable messaging)
- Track lifecycle: `published` → `subscribed` (remote) → `unpublished` / `stopped`
- Server-side moderation often means:
  - Disconnect participant
  - Force unpublish (where supported)
  - Enforce client behavior via signaling + policy

### Access Tokens (JWT)

Twilio Video uses JWT access tokens with a **VideoGrant**:

- `identity`: stable user identifier (tenant-scoped)
- `ttl`: seconds; keep short (e.g., 3600) and refresh
- `room`: optional; restrict token to a specific room
- Signed with API Key Secret

Clock skew is a common failure mode; keep NTP.

### Recording via Compositions

Twilio Video “recording” in production typically means **Compositions**:

- A Composition is a server-side rendered output (e.g., MP4) created from recorded tracks.
- You can configure:
  - Layout (grid, active speaker, custom)
  - Format
  - Status callback URL
- You must handle asynchronous completion and storage (S3/GCS/Azure) yourself.

### Network Quality API

- Provides per-participant network quality levels (0–5) and stats.
- Use it to:
  - Adapt bitrate/resolution
  - Trigger UI warnings
  - Decide when to switch to audio-only
- Combine with bandwidth profiles for predictable behavior.

### Bandwidth Profiles and Track Priority

- Bandwidth profiles define how Twilio allocates bandwidth among tracks.
- Track priority (`low`/`standard`/`high`) influences which tracks degrade first.
- Use for:
  - Prioritizing presenter video
  - Keeping audio stable under congestion

### Webhooks and callbacks

Common callback types:
- Composition status callbacks
- Room status callbacks (where configured)
- Participant events (often handled client-side; server can poll REST API)

Webhooks must be:
- HTTPS
- Verified (Twilio signature validation)
- Idempotent (Twilio retries)

---

## Installation & Setup

### Official Python SDK — Video

**Repository:** https://github.com/twilio/twilio-python  
**PyPI:** `pip install twilio` · **Supported:** Python 3.7–3.13

```python
from twilio.rest import Client
from twilio.jwt.access_token import AccessToken
from twilio.jwt.access_token.grants import VideoGrant

client = Client()

# Create a room
room = client.video.v1.rooms.create(
    unique_name="DailyStandup",
    type="go"  # or 'group' / 'peer-to-peer'
)
print(room.sid)

# Generate participant access token
token = AccessToken(
    os.environ["TWILIO_ACCOUNT_SID"],
    os.environ["TWILIO_API_KEY"],
    os.environ["TWILIO_API_SECRET"],
    identity="alice"
)
token.add_grant(VideoGrant(room="DailyStandup"))
print(token.to_jwt())
```

Source: [twilio/twilio-python — video](https://github.com/twilio/twilio-python/blob/main/twilio/rest/video/)

### Ubuntu 22.04 LTS (x86_64)

```bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg jq
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v
npm -v

sudo npm i -g [email protected]
twilio --version
twilio plugins:install @twilio-labs/[email protected]
```

### Fedora 39/40 (x86_64)

```bash
sudo dnf install -y nodejs npm jq
node -v
npm -v

sudo npm i -g [email protected]
twilio plugins:install @twilio-labs/[email protected]
```

### macOS (Intel + Apple Silicon)

Using Homebrew:

```bash
brew install node@20 jq
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc  # Apple Silicon
echo 'export PATH="/usr/local/opt/node@20/bin:$PATH"' >> ~/.zshrc     # Intel
source ~/.zshrc

npm i -g [email protected]
twilio plugins:install @twilio-labs/[email protected]
```

### Windows 11 (PowerShell)

Install Node.js 20 LTS from official installer or winget:

```powershell
winget install OpenJS.NodeJS.LTS
node -v
npm -v
npm i -g [email protected]
twilio --version
twilio plugins:install @twilio-labs/[email protected]
```

### Server library setup (Node.js)

```bash
mkdir -p video-service && cd video-service
npm init -y
npm i [email protected] [email protected] @fastify/[email protected] [email protected]
npm i -D typescr