# Metered — Complete API & SDK Reference
(last updated: 2026-05-05)

> Metered provides real-time communication infrastructure: a Video/Voice SDK, TURN Server Service, and Global Cloud SFU. This file combines all product references into one document.

For individual product files, see: https://www.metered.ca/docs/llms.txt

---

## Part 1: Video SDK

# Metered Video SDK — llms.txt reference

Metered Video is a real-time video and audio calling SDK. It lets you build group video/audio
calling apps, live streaming, recording, composition, and RTMP-out to third-party services.

## Getting Started

1. **Sign up** at https://dashboard.metered.ca/signup to create a free Metered account.
2. After signup your app is created automatically. Your **app name** (e.g. `yourappname`) forms your domain: `yourappname.metered.live`. Find it on the Dashboard home page.
3. Go to **Dashboard → Developers** to find your **Secret Key**. This is used for all server-side REST API calls. Never expose it in front-end code.
4. Rooms are created via the Dashboard or the REST API. Each room has a URL: `yourappname.metered.live/roomName`.

CDN import (JavaScript):
```
<script src="//cdn.metered.ca/sdk/video/1.4.6/sdk.min.js"></script>
```

REST API base URL:
```
https://<appname>.metered.live/api/v1
```
Authentication: pass `secretKey` as a query parameter on every REST call (e.g. `?secretKey=YOUR_SECRET_KEY`).

Key concepts:
- Room: a meeting space with a unique URL (`<appname>.metered.live/<roomName>`).
- Session (meetingSession): one call that happened inside a room.
- Participant Session: one user's participation in a session.

---

## Setup

```javascript
// 1. Include SDK
// <script src="//cdn.metered.ca/sdk/video/1.4.6/sdk.min.js"></script>

// 2. Create meeting object
const meeting = new Metered.Meeting();

// 3. Join a room
const meetingInfo = await meeting.join({
  roomURL: "yourapp.metered.live/your-room-name",
  name: "John Doe"
});

// 4. Share camera / mic
await meeting.startVideo();
await meeting.startAudio();

// 5. Handle remote streams
meeting.on("remoteTrackStarted", function(trackItem) {
  var stream = new MediaStream([trackItem.track]);
  var video = document.createElement("video");
  video.id = trackItem.streamId;
  video.autoplay = true;
  video.srcObject = stream;
  document.getElementById("container").append(video);
});

meeting.on("remoteTrackStopped", function(trackItem) {
  document.getElementById(trackItem.streamId).remove();
});

// 6. Leave
await meeting.leaveMeeting();
```

---

## SDK Methods

All methods are called on the `meeting` object (`new Metered.Meeting()`).

### join(options)

Join a meeting room. Must be called before any media methods.

```javascript
const meetingInfo = await meeting.join(options);
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| roomURL | string | yes | `<appname>.metered.live/<roomName>` |
| name | string | yes | Display name for the participant |
| accessToken | string | no | Token from `/api/v1/token`. Required for private rooms |
| receiveVideoStreamType | string | no | `only_individual` (default), `none`, `only_composed`, `all` |
| receiveAudioStreamType | string | no | `only_individual` (default), `none`, `only_composed`, `all` |

Returns `meetingInfo`:

```
{
  roomId: string,
  meetingSessionId: string,
  participantSessionId: string,
  onlineParticipants: [{ _id, name, isAdmin, meetingSessionId, roomId }]
}
```

### leaveMeeting()

Leave the meeting. Emits `stateChanged`, `meetingLeft` to self and `participantLeft` to others.

```javascript
await meeting.leaveMeeting();
```

Returns: void

### startVideo()

Share the participant's camera. Browser will prompt for camera permission. **Must call `join()` first.**

```javascript
await meeting.startVideo();
```

Returns: void. Emits `localTrackStarted` (type "video").

### stopVideo()

Stop sharing camera or screen. Emits `localTrackStopped` to self, `remoteTrackStopped` to others.

```javascript
await meeting.stopVideo();
```

Returns: void

### startAudio()

Share the participant's microphone. Browser will prompt for mic permission. **Must call `join()` first.**

```javascript
await meeting.startAudio();
```

Returns: void. Emits `localTrackStarted` (type "audio").

### stopAudio()

Stop sharing microphone. Emits `localTrackStopped` to self, `remoteTrackStopped` to others.

```javascript
await meeting.stopAudio();
```

Returns: void

### startScreenShare()

Share the participant's screen. Shows browser popup to select screen/window/tab. Replaces camera feed if one is active. **Must call `join()` first.**

```javascript
await meeting.startScreenShare();
```

Returns: void. Emits `localTrackStarted` (type "video") if no camera was active, or `localTrackUpdated` if replacing an existing camera feed.

### muteLocalAudio()

Mute microphone without stopping the audio stream. `remoteTrackStopped` is NOT emitted. Browser still shows mic as in use.

```javascript
await meeting.muteLocalAudio();
```

Returns: void

### unmuteLocalAudio()

Unmute previously muted microphone. `remoteTrackStarted` is NOT emitted.

```javascript
meeting.unmuteLocalAudio();
```

Returns: void

### pauseLocalVideo()

Mute video (black frame sent) without stopping the video stream. `remoteTrackStopped` is NOT emitted.

```javascript
await meeting.pauseLocalVideo();
```

Returns: void

### resumeLocalVideo()

Resume previously paused video. `remoteTrackStarted` is NOT emitted.

```javascript
await meeting.resumeLocalVideo();
```

Returns: void

### listVideoInputDevices()

List all cameras connected to the device. Browser will prompt for camera permission.

```javascript
const devices = await meeting.listVideoInputDevices();
// => [{ deviceId: string, groupId: string, label: string }]
```

Returns: Array of `{ deviceId, groupId, label }`

### listAudioInputDevices()

List all microphones connected to the device. Browser will prompt for mic permission.

```javascript
const devices = await meeting.listAudioInputDevices();
// => [{ deviceId: string, groupId: string, label: string }]
```

Returns: Array of `{ deviceId, groupId, label }`

### listAudioOutputDevices()

List all speakers/audio-output devices. Not supported in Firefox.

```javascript
const devices = await meeting.listAudioOutputDevices();
// => [{ deviceId: string, groupId: string, label: string }]
```

Returns: Array of `{ deviceId, groupId, label }`

### chooseVideoInputDevice(deviceId)

Select or switch camera. Can be called before or after join().

```javascript
await meeting.chooseVideoInputDevice(deviceId);
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| deviceId | string | yes | From `listVideoInputDevices()` |

Returns: void

### chooseAudioInputDevice(deviceId)

Select or switch microphone. Can be called before or after join().

```javascript
await meeting.chooseAudioInputDevice(deviceId);
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| deviceId | string | yes | From `listAudioInputDevices()` |

Returns: void

### chooseAudioOutputDevice(deviceId)

Select or switch speaker. Not supported in Firefox.

```javascript
await meeting.chooseAudioOutputDevice(deviceId);
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| deviceId | string | yes | From `listAudioOutputDevices()` |

Returns: void

### getOnlineParticipants()

Return the list of participants currently in the meeting. Synchronous call.

```javascript
const participants = meeting.getOnlineParticipants();
```

Returns: Array of `{ _id, name, isAdmin: boolean, meetingSessionId, roomId }`

### getLocalVideoStream()

Get the MediaStream of the selected (or default) video input device.

```javascript
var stream = await meeting.getLocalVideoStream();
```

Returns: MediaStream. Throws if no video device available.

### shareCustomVideoTrack(videoTrack)

Share a custom video MediaStreamTrack (e.g., from a canvas or processed stream) instead of the camera. join() must be called first.

```javascript
await meeting.shareCustomVideoTrack(videoTrack);
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| videoTrack | MediaStreamTrack | yes | Video track to share |

Returns: MediaStreamTrack. Emits `localTrackStarted` (first time) or `localTrackUpdated` (replacing existing).

### shareCustomAudio(audioStream)

Share a custom audio MediaStream (e.g., from Web Audio API) instead of the microphone. join() must be called first.

```javascript
await meeting.shareCustomAudio(audioStream);
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| audioStream | MediaStream | yes | Stream containing an audio track |

Returns: void. Emits `localTrackStarted` when no prior audio producer exists. Unlike video, replacing an existing audio track does NOT emit `localTrackUpdated`.

---

## SDK Events

All events are listened to via `meeting.on(eventName, callback)`.

### localTrackStarted

Fired when `startAudio()`, `startVideo()`, `startScreenShare()`, `shareCustomVideoTrack()`, or `shareCustomAudio()` is called.

```javascript
meeting.on("localTrackStarted", function(localTrackItem) { });
```

Callback data (`localTrackItem`):

| Field | Type | Description |
|---|---|---|
| type | string | `"audio"` or `"video"` |
| streamId | string | Unique stream identifier |
| track | MediaStreamTrack | The media track |

### localTrackStopped

Fired when `stopAudio()`, `stopVideo()` is called, or when custom tracks end.

```javascript
meeting.on("localTrackStopped", function(localTrackItem) { });
```

Callback data: same shape as `localTrackStarted`.

### localTrackUpdated

Fired when an existing local track is replaced (e.g., `shareCustomVideoTrack()` while already sharing, switching devices, switching between camera and screen share).

```javascript
meeting.on("localTrackUpdated", function(localTrackItem) { });
```

Callback data: same shape as `localTrackStarted`.

### remoteTrackStarted

Fired when any remote participant shares their mic, camera, or screen.

```javascript
meeting.on("remoteTrackStarted", function(remoteTrackItem) { });
```

Callback data (`remoteTrackItem`):

| Field | Type | Description |
|---|---|---|
| streamId | string | Unique stream identifier |
| type | string | `"audio"` or `"video"` |
| participantSessionId | string | Source participant's session ID |
| track | MediaStreamTrack | The media track (wrap in `new MediaStream([track])` for HTML video) |
| name | string | Source participant's display name |
| isComposedStream | boolean | `true` if this is a composed stream |

### remoteTrackStopped

Fired when a remote participant stops sharing mic, camera, or screen.

```javascript
meeting.on("remoteTrackStopped", function(remoteTrackItem) { });
```

Callback data: same shape as `remoteTrackStarted`.

### participantJoined

Fired to all existing participants when a new participant joins.

```javascript
meeting.on("participantJoined", function(participantInfo) { });
```

Callback data (`participantInfo`):

| Field | Type | Description |
|---|---|---|
| _id | string | participantSessionId |
| name | string | Display name |
| isAdmin | boolean | Whether participant is admin |
| meetingSessionId | string | Current meeting session ID |
| roomId | string | Room ID |
| email | string | Email if specified |
| externalUserId | string | External user ID if specified |
| meta | string | Custom metadata if specified |

### participantLeft

Fired to all other participants when someone leaves the meeting.

```javascript
meeting.on("participantLeft", function(participantInfo) { });
```

Callback data: same shape as `participantJoined`.

### onlineParticipants

Fired periodically during the meeting with the current list of online participants.

```javascript
meeting.on("onlineParticipants", function(onlineParticipants) { });
```

Callback data: Array of `{ _id, name, isAdmin, meetingSessionId, roomId }`

### stateChanged

Fired when the meeting connection state changes.

```javascript
meeting.on("stateChanged", function(meetingState) { });
```

`meetingState` values:
- `"not_joined"` - initial or error during join
- `"joining"` - join() called
- `"connecting_streams"` - connected to server, receiving streams
- `"joined"` - fully connected
- `"reconnect_success"` - reconnected after interruption
- `"network_connection_lost"` - connection interrupted
- `"network_connection_restored"` - connection restored
- `"terminated"` - meeting ended

### meetingEnded

Fired when the meeting is terminated (duration limit reached, admin ejected participant, room expired with ejectOnExpiry).

```javascript
meeting.on("meetingEnded", function() { });
```

Callback data: none.

### meetingLeft

Fired to the local participant after calling `leaveMeeting()`. Not emitted to other participants.

```javascript
meeting.on("meetingLeft", function() { });
```

Callback data: none.

### activeSpeaker

Fired when a participant is speaking.

```javascript
meeting.on("activeSpeaker", function(speakerInfo) { });
```

Callback data (`speakerInfo`):

| Field | Type | Description |
|---|---|---|
| streamId | string | Stream ID |
| meetingSessionId | string | Meeting session ID |
| name | string | Speaker's display name |
| roomId | string | Room ID |
| participantSessionId | string | Speaker's participant session ID |
| volumeLevel | number | -128 (silent) to 0 (loudest) |

### composedTrackStarted

Fired when a composed media stream is received (requires composition enabled on the room).

```javascript
meeting.on("composedTrackStarted", function(remoteTrackItem) { });
```

Callback data: same shape as `remoteTrackStarted` with `isComposedStream: true`.

---

## REST API

Base URL: `https://<appname>.metered.live/api/v1`
Auth: `?secretKey=<your_secret_key>` on every request.
Content-Type for POST/PUT bodies: `application/json`

---

### Room Endpoints

#### POST /room -- Create Room

Create a new meeting room.

```
POST https://<appname>.metered.live/api/v1/room?secretKey=<key>
Content-Type: application/json
```

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| roomName | string | no | URL-friendly name; auto-generated if omitted |
| privacy | string | yes | `"public"` or `"private"` |
| expireUnixSec | integer | no | Room expiry (unix seconds) |
| ejectAtRoomExp | boolean | no | Eject participants at expiry |
| notBeforeUnixSec | integer | no | Earliest join time (unix seconds) |
| maxParticipants | integer | no | Max participants allowed |
| autoJoin | boolean | no | Auto join |
| enableRequestToJoin | boolean | no | Allow request-to-join for private rooms |
| enableChat | boolean | no | Enable chat (iframe only) |
| enableScreenSharing | boolean | no | Enable screen sharing (iframe only) |
| joinVideoOn | boolean | no | Camera on by default (iframe only) |
| joinAudioOn | boolean | no | Mic on by default (iframe only) |
| ownerOnlyBroadcast | boolean | no | Only admin can share media |
| enableRecording | boolean | no | Allow recording |
| recordRoom | boolean | no | Auto-record the meeting |
| ejectAfterElapsedTimeInSec | integer | no | Max participant duration (seconds) |
| meetingJoinWebhook | string | no | Webhook URL for join events |
| meetingLeftWebhook | string | no | Webhook URL for leave events |
| meetingStartedWebhook | string | no | Webhook URL for session start |
| meetingEndedWebhook | string | no | Webhook URL for session end |
| endMeetingAfterNoActivityInSec | integer | no | Auto-end after inactivity (seconds) |
| audioOnlyRoom | boolean | no | Audio-only room (audio pricing) |
| enableComposition | boolean | no | Enable composition (required for live streaming, recording composed, RTMP out) |
| compositionLayout | string | no | `"grid"` or `"active_speaker"` |
| recordComposition | boolean | no | Record the composed stream |
| enableRTMPOut | boolean | no | Stream to third-party RTMP services |
| rtmpOutURL | string | conditional | RTMP ingest URL (required when enableRTMPOut is true) |
| enableLiveStreaming | boolean | no | Enable HLS live streaming |
| showInviteBox | boolean | no | Show invite box (iframe only) |
| newChatForMeetingSession | boolean | no | New chat history per meeting session (iframe only) |
| deleteOnExp | boolean | no | Delete room when it expires |

Response 200:

```json
{
  "_id": "string",
  "roomName": "string",
  "privacy": "public",
  "app": "string",
  "created": "ISO date",
  "deleteOnExp": false,
  "autoJoin": false,
  "enableRequestToJoin": false,
  "enableChat": false,
  "enableScreenSharing": true,
  "joinVideoOn": true,
  "joinAudioOn": true,
  "ownerOnlyBroadcast": false,
  "recordRoom": false,
  "ejectAtRoomExp": false,
  "archived": false,
  "lang": "en"
}
```

#### GET /room/{roomName} -- Get Room

```
GET https://<appname>.metered.live/api/v1/room/{roomName}?secretKey=<key>
```

Response 200: Room object (same shape as create response).

#### GET /rooms -- Get All Rooms

```
GET https://<appname>.metered.live/api/v1/rooms?secretKey=<key>
```

Response 200: Paginated list.

```json
{
  "pages": 4,
  "limit": 10,
  "skip": 0,
  "data": [ { ...room with participantSessions... } ]
}
```

#### PUT /room/{roomName} -- Update Room

```
PUT https://<appname>.metered.live/api/v1/room/{roomName}?secretKey=<key>
Content-Type: application/json
```

Request body: same fields as Create Room. All are optional except `privacy`.

Response 200: Updated room object.

#### DELETE /room/{roomName} -- Delete Room

```
DELETE https://<appname>.metered.live/api/v1/room/{roomName}?secretKey=<key>
```

Response 200:

```json
{ "success": true, "message": "Room successfully archived" }
```

---

### Token Endpoints

#### POST /token -- Generate Access Token

Generate a token for joining private rooms or assigning identity.

```
POST https://<appname>.metered.live/api/v1/token?secretKey=<key>
Content-Type: application/json
```

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| isAdmin | boolean | no | Grant admin privileges |
| roomName | string | no | Restrict token to specific room |
| globalToken | boolean | no | Token valid for all rooms |
| name | string | no | Participant display name |
| email | string | no | Participant email |
| meta | string | no | Custom metadata |
| externalUserId | string | no | Your system's user ID |
| expireUnixSec | integer | no | Token expiry (unix seconds) |
| notBeforeUnixSec | integer | no | Token not valid before (unix seconds) |
| ejectAfterElapsedTimeInSec | integer | no | Auto-eject after N seconds |
| joinVideoOn | boolean | no | Camera on by default (iframe) |
| joinAudioOn | boolean | no | Mic on by default (iframe) |
| disableVideo | boolean | no | Disable video (iframe) |
| disableAudio | boolean | no | Disable audio (iframe) |
| disableScreenSharing | boolean | no | Disable screen sharing (iframe) |

Response 200:

```json
{ "token": "<JWT>" }
```

#### POST /token/validate -- Validate Token

**Note:** This endpoint does NOT require the `secretKey` query parameter.

```
POST https://<appname>.metered.live/api/v1/token/validate
Content-Type: application/json
```

Request body:

| Field | Type | Required |
|---|---|---|
| token | string | yes |

Response 200:

```json
{ "name": "James Bond" }
```

---

### Meeting Session Endpoints

#### GET /rooms/active/meetingsessions -- Get Active Sessions

```
GET https://<appname>.metered.live/api/v1/rooms/active/meetingsessions?secretKey=<key>
```

Response 200: Array of active meeting sessions with embedded room objects.

```json
[{
  "_id": "string",
  "app": "string",
  "room": { ...room object... },
  "startTime": 1627654459,
  "state": "active"
}]
```

#### GET /room/{roomName}/meetingsessions -- Get All Sessions for Room

```
GET https://<appname>.metered.live/api/v1/room/{roomName}/meetingsessions?secretKey=<key>
```

Response 200: Paginated.

```json
{
  "pages": 4,
  "limit": 10,
  "skip": 0,
  "data": [{
    "_id": "string",
    "app": "string",
    "room": "string",
    "startTime": 1627598254,
    "state": "ended",
    "endTime": 1627598896,
    "participantSessions": [{
      "_id": "string",
      "name": "string",
      "joinTime": 1627598934,
      "leftTime": 1627599054,
      "state": "exited",
      "browser": "Chrome",
      "os": "Windows",
      "isAdmin": false,
      "authenticatedUsingToken": true,
      "externalUserId": "string",
      "email": "string"
    }]
  }]
}
```

#### GET /room/{roomName}/presence -- Get Meeting Presence

Get the current live presence for a room (active sessions with participants).

```
GET https://<appname>.metered.live/api/v1/room/{roomName}/presence?secretKey=<key>
```

Response 200: Array of active sessions with room details (same shape as active sessions).

---

### Recording Endpoints

#### GET /recordings -- Get All Recordings

```
GET https://<appname>.metered.live/api/v1/recordings?secretKey=<key>
```

Response 200:

```json
{
  "currEndId": "string",
  "total": 139,
  "limit": 50,
  "data": [{
    "_id": "string",
    "app": "string",
    "room": "string",
    "participantSession": "string",
    "meetingSession": "string",
    "participantUsername": "string",
    "fileName": "uuid.webm",
    "sizeInBytes": 4526446,
    "type": "video",
    "startTime": 1636847920,
    "endTime": 1636847953
  }]
}
```

#### GET /recordings/room/{roomName} -- Get Recordings for a Room

```
GET https://<appname>.metered.live/api/v1/recordings/room/{roomName}?secretKey=<key>
```

Response 200: Same paginated recording structure.

#### GET /recordings/meetingsession/{meetingSessionId} -- Get Recordings for a Meeting Session

```
GET https://<appname>.metered.live/api/v1/recordings/meetingsession/{meetingSessionId}?secretKey=<key>
```

Response 200: Same paginated recording structure.

#### GET /recordings/participantsession/{participantSessionId} -- Get Recordings for a Participant Session

```
GET https://<appname>.metered.live/api/v1/recordings/participantsession/{participantSessionId}?secretKey=<key>
```

Response 200: Same paginated recording structure.

#### GET /recording/{recordingId}/download -- Download Recording

Returns a pre-signed S3 URL for downloading.

```
GET https://<appname>.metered.live/api/v1/recording/{recordingId}/download?secretKey=<key>
```

Response 200:

```json
{ "url": "https://metered-recording.s3...presigned-url" }
```

#### DELETE /recording/{recordingId} -- Delete Recording

```
DELETE https://<appname>.metered.live/api/v1/recording/{recordingId}?secretKey=<key>
```

Response 200:

```json
{ "success": true, "recordingId": "string", "message": "recording deleted successfully" }
```

---

### Live Streaming (Real-Time) Endpoints

These endpoints manage dedicated real-time live streaming rooms (separate from meeting rooms).

#### POST /realtimelivestreaming/room -- Create Live Streaming Room

```
POST https://<appname>.metered.live/api/v1/realtimelivestreaming/room?secretKey=<key>
Content-Type: application/json
```

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| roomName | string | no | Auto-generated if omitted |
| enableLiveStreaming | boolean | no | Enable HLS streaming |
| displayMessage | string | no | Message when stream is offline |
| customCSS | string | no | Custom CSS for viewer |
| enableRecording | boolean | no | Record the livestream |
| recordComposition | boolean | no | Record composed audio+video |
| enableRTMPOut | boolean | no | Enable RTMP out |
| rtmpOutURL | string | no | Third-party RTMP ingest URL |

Response 200:

```json
{
  "_id": "string",
  "roomName": "mystreamingroom",
  "viewerURL": "https://<appname>.metered.live/<id>/player",
  "broadcastManager": "https://dashboard.metered.ca/livestreaming-rooms/<id>/app/<appId>/broadcast",
  "currentlyBroadcasting": false,
  "created": "ISO date"
}
```

#### PUT /realtimelivestreaming/room/{roomName} -- Update Live Streaming Room

```
PUT https://<appname>.metered.live/api/v1/realtimelivestreaming/room/{roomName}?secretKey=<key>
Content-Type: application/json
```

Request body: same fields as create. Response: same shape.

#### GET /realtimelivestreaming/rooms -- Get All Live Streaming Rooms

```
GET https://<appname>.metered.live/api/v1/realtimelivestreaming/rooms?secretKey=<key>
```

Response 200: Array of live streaming room objects.

#### GET /realtimelivestreaming/room/{roomName} -- Get Live Streaming Room

```
GET https://<appname>.metered.live/api/v1/realtimelivestreaming/room/{roomName}?secretKey=<key>
```

Response 200: Single live streaming room object.

#### GET /realtimelivestreaming/rooms/broadcasting -- Currently Broadcasting Rooms

```
GET https://<appname>.metered.live/api/v1/realtimelivestreaming/rooms/broadcasting?secretKey=<key>
```

Response 200: Array of rooms with `currentlyBroadcasting: true`.

---

## Recording

Two recording modes:

1. Individual recording: records each participant's audio and video as separate files. Enable with `recordRoom: true` when creating/updating a room.

2. Composed recording: records all participants combined into a single video/audio file. Enable with `recordComposition: true` and `enableComposition: true` on the room.

Enable recording via Dashboard (Room settings > Record Room toggle) or via REST API (POST/PUT /room).

Manage recordings via:
- Dashboard: Cloud Recording section for viewing, downloading, previewing, deleting.
- REST API: GET /recordings, GET /recordings/room/{roomName}, GET /recording/{id}/download, DELETE /recording/{id}.

Recording object shape:

```json
{
  "_id": "string",
  "app": "string",
  "room": "string",
  "participantSession": "string",
  "meetingSession": "string",
  "participantUsername": "string",
  "fileName": "uuid.webm",
  "sizeInBytes": 4526446,
  "type": "video",
  "startTime": 1636847920,
  "endTime": 1636847953
}
```

---

## Live Streaming

Live streaming sends an HLS stream of the meeting that can be viewed by millions of users.

Requirements:
- Composition must be enabled (it is auto-enabled when live streaming is turned on).
- Enable via Dashboard (Room settings > HLS/Dash Live Streaming toggle) or via API (`enableLiveStreaming: true`).

Composition layouts: `grid`, `active_speaker`.

HLS playback URL format:
```
https://live.metered.ca/hls/{PLAYBACK_ID}.m3u8
```

The HLS URL is visible in Dashboard under Room summary once live streaming is enabled.

Playing the stream in a browser (using hls.js):

```html
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="player" controls></video>
<script>
  const video = document.querySelector('#player');
  const src = 'https://live.metered.ca/hls/{PLAYBACK_ID}.m3u8';
  if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src; // Safari native HLS
  } else if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(src);
    hls.attachMedia(video);
  }
</script>
```

iOS (AVPlayer) and Android (ExoPlayer) support HLS natively.

Receiving composed streams in the SDK: set `receiveVideoStreamType: "only_composed"` or `"all"` in `join()` options, then listen for the `composedTrackStarted` event.

---

## Composition

Composition combines multiple participant audio/video streams into a single composed stream.

Use cases:
- Live streaming (required)
- Composed recording (single video file of the whole meeting)
- RTMP OUT to third-party services
- Low-bandwidth participants (receive one stream instead of N)

Enable via:
- Dashboard: Room settings > Composition toggle
- API: `enableComposition: true` on create/update room

Layouts: `grid` (default), `active_speaker`

Set layout via API: `compositionLayout: "grid"` or `"active_speaker"`

SDK integration: when joining a room with composition enabled, use `receiveVideoStreamType` / `receiveAudioStreamType` set to `"only_composed"` or `"all"` in the `join()` options. The composed stream arrives via the `composedTrackStarted` event (or `remoteTrackStarted` with `isComposedStream: true`).

---

## RTMP OUT

RTMP OUT sends the composed meeting stream to third-party RTMP services (YouTube Live, Facebook Live, Twitch, etc.).

Requirements:
- Composition is auto-enabled when RTMP OUT is turned on.
- An RTMP ingest URL from the third-party service.

Enable via:
- Dashboard: Room settings > Enable RTMP OUT, then provide the RTMP URL.
- API: set `enableRTMPOut: true` and `rtmpOutURL: "rtmp://..."` when creating/updating a room.

The meeting will be streamed to the RTMP URL whenever participants are in the room with composition active.

---

## Webhooks

Rooms support four webhook URLs set via create/update room API:

| Field | Trigger |
|---|---|
| meetingJoinWebhook | Participant joins the room |
| meetingLeftWebhook | Participant leaves the room |
| meetingStartedWebhook | A new meeting session starts |
| meetingEndedWebhook | A meeting session ends |

---

## Error Responses

All REST endpoints return errors in this format:

```json
{ "success": false, "message": "error description" }
```

Common HTTP status codes: 200 (success), 400 (bad request), 500 (server error).

---

## Complete Quick-Start Example (HTML)

This is a minimal but complete working example that creates a two-person video call:

```html
<!DOCTYPE html>
<html>
<head><title>Metered Quick Start</title></head>
<body>
  <h1>Metered Video Demo</h1>
  <div>
    <button onclick="joinMeeting()">Join Meeting</button>
    <button onclick="leaveMeeting()">Leave</button>
    <button onclick="toggleCamera()">Toggle Camera</button>
    <button onclick="toggleMic()">Toggle Mic</button>
  </div>
  <div>
    <h3>Local Video</h3>
    <video id="localvideo" autoplay muted playsinline style="width:300px"></video>
  </div>
  <div id="remoteVideoContainer">
    <h3>Remote Videos</h3>
  </div>

  <script src="https://cdn.metered.ca/sdk/video/1.4.6/sdk.min.js"></script>
  <script>
    let meeting;
    let cameraOn = false;
    let micOn = false;

    async function joinMeeting() {
      meeting = new Metered.Meeting();

      const meetingInfo = await meeting.join({
        roomURL: "yourapp.metered.live/your-room-name",
        name: "Participant"
      });
      console.log("Joined:", meetingInfo);

      // Start sharing camera and mic
      await meeting.startVideo();
      cameraOn = true;
      await meeting.startAudio();
      micOn = true;

      // Show local video
      meeting.on("localTrackStarted", function(item) {
        if (item.type === "video") {
          var track = item.track;
          var mediaStream = new MediaStream([track]);
          document.getElementById("localvideo").srcObject = mediaStream;
          document.getElementById("localvideo").play();
        }
      });

      // Handle local video stopping
      meeting.on("localTrackStopped", function(item) {
        if (item.type === "video") {
          document.getElementById("localvideo").srcObject = null;
        }
      });

      // Handle local track replacement (device switch, screen share toggle)
      meeting.on("localTrackUpdated", function(item) {
        if (item.type === "video") {
          var track = item.track;
          var mediaStream = new MediaStream([track]);
          document.getElementById("localvideo").srcObject = mediaStream;
        }
      });

      // Show remote participants' tracks
      meeting.on("remoteTrackStarted", function(remoteTrackItem) {
        var track = remoteTrackItem.track;
        var stream = new MediaStream([track]);

        if (remoteTrackItem.type === "video") {
          var videoTag = document.createElement("video");
          videoTag.autoplay = true;
          videoTag.playsinline = true;
          videoTag.srcObject = stream;
          videoTag.id = remoteTrackItem.streamId;
          videoTag.className = remoteTrackItem.participantSessionId;
          videoTag.style.width = "300px";
          document.getElementById("remoteVideoContainer").append(videoTag);
        }

        if (remoteTrackItem.type === "audio") {
          var audioTag = document.createElement("audio");
          audioTag.autoplay = true;
          audioTag.srcObject = stream;
          audioTag.id = remoteTrackItem.streamId;
          audioTag.className = remoteTrackItem.participantSessionId;
          document.getElementById("remoteVideoContainer").append(audioTag);
        }
      });

      // Remove remote tracks when stopped
      meeting.on("remoteTrackStopped", function(remoteTrackItem) {
        var el = document.getElementById(remoteTrackItem.streamId);
        if (el) el.remove();
      });

      // Clean up when participant leaves
      meeting.on("participantLeft", function(participantInfo) {
        Array.from(document.getElementsByClassName(participantInfo._id))
          .forEach(function(element) { element.remove(); });
      });

      // Connection state monitoring
      meeting.on("stateChanged", function(state) {
        console.log("Meeting state:", state);
      });

      // Active speaker detection
      meeting.on("activeSpeaker", function(speakerInfo) {
        console.log("Active speaker:", speakerInfo.name, "volume:", speakerInfo.volumeLevel);
      });

      // Meeting terminated externally
      meeting.on("meetingEnded", function() {
        alert("Meeting has ended");
      });
    }

    async function leaveMeeting() {
      if (meeting) {
        await meeting.leaveMeeting();
      }
    }

    async function toggleCamera() {
      if (cameraOn) {
        await meeting.stopVideo();
        cameraOn = false;
      } else {
        await meeting.startVideo();
        cameraOn = true;
      }
    }

    async function toggleMic() {
      if (micOn) {
        await meeting.muteLocalAudio();
        micOn = false;
      } else {
        meeting.unmuteLocalAudio();
        micOn = true;
      }
    }
  </script>
</body>
</html>
```

---

## Device Selection Pattern

List available devices and let the user choose before or during a call:

```javascript
// List cameras
const cameras = await meeting.listVideoInputDevices();
// cameras = [{ deviceId: "abc123", groupId: "grp1", label: "Built-in Camera" }, ...]

// List microphones
const mics = await meeting.listAudioInputDevices();

// List speakers (not supported in Firefox)
const speakers = await meeting.listAudioOutputDevices();

// Select a specific camera (can be called before or after join)
await meeting.chooseVideoInputDevice(cameras[1].deviceId);

// Select a specific microphone
await meeting.chooseAudioInputDevice(mics[0].deviceId);

// Select a specific speaker
await meeting.chooseAudioOutputDevice(speakers[0].deviceId);

// After selecting, start sharing
await meeting.startVideo();
await meeting.startAudio();
```

Note: In Firefox, the `label` property may be blank if the user has not checked
"Remember this decision" when granting permissions.

---

## Custom Video Track Pattern (Canvas, Processed Video)

Share a canvas element or processed video stream instead of a camera:

```javascript
// Example: Share a canvas as video
const canvas = document.getElementById('myCanvas');
const canvasStream = canvas.captureStream(30); // 30 FPS
const videoTrack = canvasStream.getVideoTracks()[0];
await meeting.shareCustomVideoTrack(videoTrack);

// Example: Apply a filter to camera using canvas
const localStream = await meeting.getLocalVideoStream();
const videoEl = document.createElement('video');
videoEl.srcObject = localStream;
await videoEl.play();

const canvas2 = document.createElement('canvas');
const ctx = canvas2.getContext('2d');

function drawFrame() {
  ctx.drawImage(videoEl, 0, 0);
  // Apply any canvas manipulations here (filters, overlays, etc.)
  ctx.filter = 'grayscale(100%)';
  ctx.drawImage(videoEl, 0, 0);
  requestAnimationFrame(drawFrame);
}
drawFrame();

const processedStream = canvas2.captureStream(30);
const processedTrack = processedStream.getVideoTracks()[0];
await meeting.shareCustomVideoTrack(processedTrack);
```

---

## Custom Audio Pattern (Web Audio API)

Share processed audio or synthesized audio instead of a microphone:

```javascript
const audioContext = new AudioContext();

// Example: Mix microphone with background audio
const micStream = await navigator.mediaDevices.getUserMedia({ audio: true });
const micSource = audioContext.createMediaStreamSource(micStream);
const destination = audioContext.createMediaStreamDestination();

// Add gain control
const gainNode = audioContext.createGain();
gainNode.gain.value = 0.8;
micSource.connect(gainNode);
gainNode.connect(destination);

// Share the processed audio
await meeting.shareCustomAudio(destination.stream);
```

---

## Private Rooms and Authentication Flow

1. Create a private room:
```
POST /api/v1/room?secretKey=<key>
{ "roomName": "secure-room", "privacy": "private" }
```

2. Generate an access token for each user (server-side):
```
POST /api/v1/token?secretKey=<key>
{
  "roomName": "secure-room",
  "name": "Alice",
  "isAdmin": false,
  "email": "alice@example.com",
  "externalUserId": "user-123",
  "ejectAfterElapsedTimeInSec": 3600
}
```
Response: `{ "token": "<JWT>" }`

3. Client joins with the token:
```javascript
const meetingInfo = await meeting.join({
  roomURL: "yourapp.metered.live/secure-room",
  name: "Alice",
  accessToken: "<JWT from server>"
});
```

4. Validate a token (optional, server-side):
```
POST /api/v1/token/validate
{ "token": "<JWT>" }
```
Response: `{ "name": "Alice" }`

Admin users can:
- Allow other users without tokens to join private meetings (request-to-join flow)
- Be the only ones who can broadcast (if `ownerOnlyBroadcast` is enabled on the room)

---

## REST API cURL Examples

Create a room:
```bash
curl -X POST \
  'https://yourapp.metered.live/api/v1/room?secretKey=YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "roomName": "my-meeting",
    "privacy": "public",
    "enableRecording": true,
    "ejectAfterElapsedTimeInSec": 7200
  }'
```

Get a room:
```bash
curl -X GET \
  'https://yourapp.metered.live/api/v1/room/my-meeting?secretKey=YOUR_SECRET_KEY' \
  -H 'Accept: application/json'
```

Update a room:
```bash
curl -X PUT \
  'https://yourapp.metered.live/api/v1/room/my-meeting?secretKey=YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "enableComposition": true,
    "compositionLayout": "active_speaker",
    "enableLiveStreaming": true,
    "enableRTMPOut": true,
    "rtmpOutURL": "rtmp://a.rtmp.youtube.com/live2/your-stream-key"
  }'
```

Delete a room:
```bash
curl -X DELETE \
  'https://yourapp.metered.live/api/v1/room/my-meeting?secretKey=YOUR_SECRET_KEY' \
  -H 'Accept: application/json'
```

Generate access token:
```bash
curl -X POST \
  'https://yourapp.metered.live/api/v1/token?secretKey=YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "roomName": "my-meeting",
    "name": "John Doe",
    "isAdmin": true,
    "externalUserId": "user-456",
    "ejectAfterElapsedTimeInSec": 1800
  }'
```

Get all recordings:
```bash
curl -X GET \
  'https://yourapp.metered.live/api/v1/recordings?secretKey=YOUR_SECRET_KEY' \
  -H 'Accept: application/json'
```

Download a recording:
```bash
curl -X GET \
  'https://yourapp.metered.live/api/v1/recording/RECORDING_ID/download?secretKey=YOUR_SECRET_KEY' \
  -H 'Accept: application/json'
```

Get active meeting sessions:
```bash
curl -X GET \
  'https://yourapp.metered.live/api/v1/rooms/active/meetingsessions?secretKey=YOUR_SECRET_KEY' \
  -H 'Accept: application/json'
```

Create a live streaming room:
```bash
curl -X POST \
  'https://yourapp.metered.live/api/v1/realtimelivestreaming/room?secretKey=YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "roomName": "my-livestream" }'
```

---

## Room Configuration Reference

These fields control room behavior and can be set via POST /room or PUT /room/{roomName}:

Core settings:
- `roomName` (string): URL-friendly room name; auto-generated if omitted.
- `privacy` ("public"|"private"): Public rooms are open; private rooms require an access token.
- `maxParticipants` (integer): Cap on concurrent participants.
- `expireUnixSec` (integer): Room expiry time in unix seconds.
- `notBeforeUnixSec` (integer): Earliest time users can join.
- `ejectAtRoomExp` (boolean): Kick everyone when room expires.
- `ejectAfterElapsedTimeInSec` (integer): Max time per participant in seconds.
- `endMeetingAfterNoActivityInSec` (integer): Auto-end if no one is sharing media.
- `audioOnlyRoom` (boolean): Restrict to audio-only (different pricing tier).

Media defaults (iframe only):
- `joinVideoOn` (boolean): Camera on when joining.
- `joinAudioOn` (boolean): Mic on when joining.
- `enableScreenSharing` (boolean): Allow screen sharing.
- `enableChat` (boolean): Enable text chat.
- `ownerOnlyBroadcast` (boolean): Only admins can share media.
- `autoJoin` (boolean): Auto-join without lobby.
- `enableRequestToJoin` (boolean): Allow non-token users to request joining private rooms.
- `newChatForMeetingSession` (boolean): Fresh chat per session.
- `showInviteBox` (boolean): Show invite UI when room is empty.

Recording:
- `enableRecording` (boolean): Allow manual recording.
- `recordRoom` (boolean): Auto-record every session.
- `recordComposition` (boolean): Record the composed (combined) stream.

Composition and streaming:
- `enableComposition` (boolean): Combine all streams into one. Required for live streaming and RTMP out.
- `compositionLayout` ("grid"|"active_speaker"): Layout for composed stream.
- `enableLiveStreaming` (boolean): Generate HLS URL for the meeting.
- `enableRTMPOut` (boolean): Push composed stream to RTMP endpoint.
- `rtmpOutURL` (string): RTMP ingest URL (e.g., YouTube Live, Twitch).

Webhooks:
- `meetingJoinWebhook` (string): URL called when a participant joins.
- `meetingLeftWebhook` (string): URL called when a participant leaves.
- `meetingStartedWebhook` (string): URL called when a meeting session starts.
- `meetingEndedWebhook` (string): URL called when a meeting session ends.

---

## Meeting State Lifecycle

```
not_joined -> joining -> connecting_streams -> joined
                                                  |
                                                  v
                                    network_connection_lost
                                                  |
                                                  v
                                    network_connection_restored
                                                  |
                                                  v
                                        reconnect_success -> joined

joined -> terminated (when meetingEnded fires)
joined -> not_joined (when leaveMeeting() called)
```

States:
- `not_joined`: Initial state or failed to join.
- `joining`: join() has been called, connecting to server.
- `connecting_streams`: Connected, receiving initial media streams.
- `joined`: Fully connected and operational.
- `network_connection_lost`: Network interruption detected.
- `network_connection_restored`: Network back, reconnecting.
- `reconnect_success`: Successfully reconnected.
- `terminated`: Meeting ended externally (admin eject, room expiry, duration limit).

---

## Live Streaming Playback Reference

HLS URL format: `https://live.metered.ca/hls/{PLAYBACK_ID}.m3u8`

The PLAYBACK_ID / HLS URL is available from the room details in the Metered dashboard
after enabling live streaming.

Browser playback with hls.js:
```html
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="player" controls style="width:100%;max-width:500px"></video>
<script>
  const video = document.querySelector('#player');
  const src = 'https://live.metered.ca/hls/PLAYBACK_ID.m3u8';
  if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src;
  } else if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(src);
    hls.attachMedia(video);
  }
</script>
```

React playback:
```jsx
import React, { useEffect, useRef } from "react";
import Hls from "hls.js";

export default function LivePlayer() {
  const videoRef = useRef(null);
  const src = "https://live.metered.ca/hls/PLAYBACK_ID.m3u8";

  useEffect(() => {
    let hls;
    if (videoRef.current) {
      const video = videoRef.current;
      if (video.canPlayType("application/vnd.apple.mpegurl")) {
        video.src = src;
      } else if (Hls.isSupported()) {
        hls = new Hls();
        hls.loadSource(src);
        hls.attachMedia(video);
      }
    }
    return () => { if (hls) hls.destroy(); };
  }, [videoRef]);

  return <video controls ref={videoRef} style={{ width: "100%", maxWidth: "500px" }} />;
}
```

Android (ExoPlayer):
```java
SimpleExoPlayer player = new SimpleExoPlayer.Builder(context).build();
player.setMediaItem(MediaItem.fromUri("https://live.metered.ca/hls/PLAYBACK_ID.m3u8"));
player.prepare();
```

iOS/tvOS (AVPlayer):
```swift
import AVKit
let player = AVPlayer(url: URL(string: "https://live.metered.ca/hls/PLAYBACK_ID.m3u8")!)
// Use with AVPlayerViewController or AVPlayerLayer
player.play()
```

Recommended players for web: hls.js (free), Plyr.io (free), JWPlayer, Brightcove, THEOplayer, Bitmovin.

---

## RTMP OUT Setup Examples

YouTube Live:
1. Go to YouTube Studio > Go Live > Stream
2. Copy the Stream URL and Stream Key
3. Combine them: `rtmp://a.rtmp.youtube.com/live2/YOUR_STREAM_KEY`
4. Set on room: `enableRTMPOut: true, rtmpOutURL: "rtmp://a.rtmp.youtube.com/live2/YOUR_STREAM_KEY"`

Facebook Live:
1. Go to Facebook Live Producer
2. Copy the Server URL and Stream Key
3. Set on room: `rtmpOutURL: "rtmps://live-api-s.facebook.com:443/rtmp/YOUR_STREAM_KEY"`

Twitch:
1. Go to Twitch Dashboard > Settings > Stream
2. Copy the Primary Stream Key
3. Set on room: `rtmpOutURL: "rtmp://live.twitch.tv/app/YOUR_STREAM_KEY"`

Other services: use the RTMP ingest URL provided by the service.

---

## Composed Stream Receiver Pattern

To receive and display only the composed (combined) stream instead of individual streams:

```javascript
const meeting = new Metered.Meeting();

await meeting.join({
  roomURL: "yourapp.metered.live/composed-room",
  name: "Viewer",
  receiveVideoStreamType: "only_composed",
  receiveAudioStreamType: "only_composed"
});

// The composed stream arrives via composedTrackStarted
meeting.on("composedTrackStarted", function(remoteTrackItem) {
  var track = remoteTrackItem.track;
  var stream = new MediaStream([track]);

  if (remoteTrackItem.type === "video") {
    document.getElementById("composedVideo").srcObject = stream;
  }
  if (remoteTrackItem.type === "audio") {
    var audio = document.createElement("audio");
    audio.autoplay = true;
    audio.srcObject = stream;
    document.body.append(audio);
  }
});
```

Note: when `receiveAudioStreamType` is `"only_composed"` and the participant is also sharing
their own audio, they will hear their own voice in the composed stream.

To receive both individual and composed streams, use `receiveVideoStreamType: "all"`. Individual
streams arrive via `remoteTrackStarted` and composed streams arrive via `composedTrackStarted`
(or `remoteTrackStarted` with `isComposedStream: true`).

---

## Server-Side Room Management Pattern (Node.js)

```javascript
const axios = require('axios');

const BASE_URL = 'https://yourapp.metered.live/api/v1';
const SECRET_KEY = process.env.METERED_SECRET_KEY;

// Create a room
async function createRoom(roomName, isPrivate) {
  const response = await axios.post(`${BASE_URL}/room`, {
    roomName: roomName,
    privacy: isPrivate ? 'private' : 'public',
    ejectAfterElapsedTimeInSec: 7200,
    enableRecording: true
  }, {
    params: { secretKey: SECRET_KEY }
  });
  return response.data;
}

// Generate token for a user
async function generateToken(roomName, userName, isAdmin) {
  const response = await axios.post(`${BASE_URL}/token`, {
    roomName: roomName,
    name: userName,
    isAdmin: isAdmin
  }, {
    params: { secretKey: SECRET_KEY }
  });
  return response.data.token;
}

// Get active sessions
async function getActiveSessions() {
  const response = await axios.get(`${BASE_URL}/rooms/active/meetingsessions`, {
    params: { secretKey: SECRET_KEY }
  });
  return response.data;
}

// Get recordings for a room
async function getRoomRecordings(roomName) {
  const response = await axios.get(`${BASE_URL}/recordings/room/${roomName}`, {
    params: { secretKey: SECRET_KEY }
  });
  return response.data;
}

// Download a recording
async function getRecordingDownloadURL(recordingId) {
  const response = await axios.get(`${BASE_URL}/recording/${recordingId}/download`, {
    params: { secretKey: SECRET_KEY }
  });
  return response.data.url;
}
```

---

## Part 2: TURN Server Service

# Metered TURN Server Service — llms.txt reference

Metered TURN Servers as a Service provide a globally distributed relay network for WebRTC traffic. The service guarantees connectivity through NATs and firewalls via TURN (Traversal Using Relays around NAT).

- 31+ regions, 100+ edge PoPs, <30 ms latency, 99.999% uptime SLA
- UDP, TCP, TLS, DTLS on ports 80/443. No bandwidth caps per allocation.
- Standards: STUN (RFC 5389), TURN (RFC 5766), ICE
- Private high-speed backbone for cross-continent relay
- REST API for credentials, usage tracking, project isolation
- Dashboard: https://dashboard.metered.ca | Pricing: https://www.metered.ca/pricing

## Getting Started

1. **Sign up** at https://dashboard.metered.ca/signup to create a free Metered account.
2. Your **app name** (e.g. `yourappname`) is shown on the Dashboard home page. It forms part of the REST API base URL: `https://yourappname.metered.live/api/v1/turn/`.
3. Go to **Dashboard → Developers** to find your **Secret Key**. Use this for all server-side API calls (creating credentials, fetching usage, managing projects). Never expose it in front-end code.
4. **Create a TURN credential**: Go to **Dashboard → TURN Server** and click **"Add Credential"**, or use the Create Credential REST API. Each credential gets:
   - `username` and `password` — used in the ICE server config for WebRTC connections
   - `apiKey` — a credential-scoped key, **safe for front-end use**, used only with the Get Credential API to fetch the ICE server config
5. Click **"Show ICE Servers Array"** on any credential in the Dashboard to get a ready-to-use ICE config for your WebRTC app.

**Three types of API keys:**
- **`secretKey`** — account-scoped, server-side only. Found in Dashboard → Developers.
- **`apiKey`** — credential-scoped, safe for front-end. Returned when creating a credential. Used only for the Get Credential endpoint.
- **`projectApiKey`** — project-scoped, alternative to secretKey for project-level operations. Found in Dashboard → TURN Server → Projects.

---

## Overview & Setup

ICE tries connections in order: host candidates (direct), STUN (public IP discovery), then TURN (full relay fallback). TURN guarantees connectivity through symmetric NAT, carrier-grade NAT, and strict firewalls. The relay forwards encrypted payloads (SRTP/DTLS) without decrypting them.

Use cases: voice/video calls, live streaming, IoT devices, AI/3D/AR/VR, surveillance, DataChannels (chat, gaming, file-share).

### Custom Domain

Point a CNAME at Metered infrastructure (global or region-specific hostname). TURN over TCP and UDP work with CNAME; TURN over TLS does not.

---

## TURN URLs & Ports

### Global Endpoint (recommended)

`global.relay.metered.ca` — automatic geo-routing to nearest edge. STUN: `stun:stun.relay.metered.ca:80`

| Port | Protocol | URI                                              |
|------|----------|--------------------------------------------------|
| 80   | UDP      | turn:global.relay.metered.ca:80                  |
| 80   | TCP      | turn:global.relay.metered.ca:80?transport=tcp    |
| 443  | UDP      | turn:global.relay.metered.ca:443                 |
| 443  | TLS      | turns:global.relay.metered.ca:443?transport=tcp  |

Best practice: include multiple entries (UDP first, then TCP/TLS) for ICE fallback.

### Recommended ICE Servers Array

```json
[
  { "urls": "stun:stun.relay.metered.ca:80" },
  { "urls": "turn:global.relay.metered.ca:80", "username": "<USERNAME>", "credential": "<PASSWORD>" },
  { "urls": "turn:global.relay.metered.ca:80?transport=tcp", "username": "<USERNAME>", "credential": "<PASSWORD>" },
  { "urls": "turn:global.relay.metered.ca:443", "username": "<USERNAME>", "credential": "<PASSWORD>" },
  { "urls": "turns:global.relay.metered.ca:443?transport=tcp", "username": "<USERNAME>", "credential": "<PASSWORD>" }
]
```

### Region-Specific Endpoints

All use ports 80/443. Paid plans only (free plan: `standard.relay.metered.ca` only).

| Region           | Endpoint                       | API region value    |
|------------------|--------------------------------|---------------------|
| Global           | global.relay.metered.ca        | global              |
| North America    | na.relay.metered.ca            | north_america       |
| Europe           | europe.relay.metered.ca        | europe              |
| European Union   | eu.relay.metered.ca            | eu                  |
| Asia             | asia.relay.metered.ca          | asia                |
| Oceania          | oceania.relay.metered.ca       | oceania             |
| US West          | us-west.relay.metered.ca       | us_west             |
| US Central       | us-central.relay.metered.ca    | us_central          |
| US East          | us-east.relay.metered.ca       | us_east             |
| Canada Central   | ca-central.relay.metered.ca    | canada_central      |
| Canada East      | ca-east.relay.metered.ca       | canada_east         |
| Europe West      | eu-west.relay.metered.ca       | europe_west         |
| Europe Central   | eu-central.relay.metered.ca    | europe_central      |
| Asia West        | asia-west.relay.metered.ca     | asia_west           |
| Asia East        | asia-east.relay.metered.ca     | asia_east           |
| Middle East      | middle-east.relay.metered.ca   | middle_east         |
| Canada           | ca.relay.metered.ca            | canada              |
| USA              | us.relay.metered.ca            | usa                 |
| UK               | uk.relay.metered.ca            | uk                  |
| Singapore        | sg.relay.metered.ca            | singapore           |
| India            | in.relay.metered.ca            | india               |
| Seoul            | seoul.relay.metered.ca         | seoul               |
| France           | fr.relay.metered.ca            | france              |
| Germany          | de.relay.metered.ca            | germany             |
| Italy            | it.relay.metered.ca            | italy               |
| Japan            | jp.relay.metered.ca            | japan               |
| Sweden           | se.relay.metered.ca            | sweden              |
| Spain            | es.relay.metered.ca            | spain               |
| Netherlands      | nl.relay.metered.ca            | netherlands         |
| Australia        | au.relay.metered.ca            | australia           |
| Qatar            | qa.relay.metered.ca            | qatar               |
| Standard (free)  | standard.relay.metered.ca      | standard            |

---

## Creating Credentials

**Dashboard**: Log into https://dashboard.metered.ca -> TURN Server page -> "Add Credential" -> "Show ICE Servers Array" to get the config.

**REST API**: POST to Create Credential endpoint (see below). Response includes `username`, `password`, and `apiKey`. Use the `apiKey` to call Get Credential from the front-end. The `apiKey` is credential-scoped and safe for front-end use. The `secretKey` must never be exposed in front-end code.

---

## Region Pinning

**Dashboard**: Select region from dropdown; "Show ICE Servers Array" returns region-scoped endpoints.

**API**: Pass `region` query param to Get Credential API for a specific region. Omit it to use the dashboard default. Different credentials can target different regions.

**Dynamic updates**: If you use the Get Credential API (with `apiKey`), changing the dashboard region automatically updates what the API returns.

---

## REST API — Authentication

Replace `<appname>` with your app name (Dashboard -> Developers).

**v1 endpoints** (base: `https://<appname>.metered.live/api/v1/turn/`):
Get Credential, Create Credential, Enable Credential, Disable Credential, Delete Credential, Current Usage, Current Usage by Date, Current Usage for User.

**v2 endpoints** (base: `https://<appname>.metered.live/api/v2/turn/`):
Update Credential Label, List Credentials, Current Usage by User, Daily Usage by User, Delete Credential by Label, all Project endpoints.

**v2 payment endpoint** (base: `https://<appname>.metered.live/api/v2/payment/`):
Get Usage Charges — note this uses `/api/v2/payment/`, NOT `/api/v2/turn/`.

Each endpoint below shows its full path including the correct version prefix.

Auth methods (all via query param):
1. `apiKey` — credential-scoped, safe for front-end. Only for Get Credential endpoint.
2. `secretKey` — account-scoped, server-side only. Dashboard -> Developers.
3. `projectApiKey` — project-scoped, alternative to secretKey for project endpoints.

---

## REST API — Credentials

### Get TURN Credential (ICE Servers Array)

Returns the ICE Servers array. Safe for front-end use.

```
GET /api/v1/turn/credentials?apiKey=<CREDENTIAL_API_KEY>
```

Query: `apiKey` (required), `region` (optional, overrides dashboard default).

Response `200 OK` — array of ICE server objects (STUN + TURN entries with urls, username, credential).
Errors: `400` (no API key), `401` (invalid API key).

### Create TURN Credential

```
POST /api/v1/turn/credential?secretKey=<SECRET_KEY>
Content-Type: application/json
```

Body (JSON):
- `expiryInSeconds` (integer, optional) — auto-expire after this many seconds
- `label` (string, optional) — a label for the credential

Response `200 OK` — object with `username`, `password`, `expiryInSeconds`, `label`, `apiKey`.

Errors: `400` (invalid expiry or not subscribed).

### Enable TURN Credential

Re-enables a previously disabled credential.

```
POST /api/v1/turn/credential/enable?secretKey=<SECRET_KEY>
```

Body: `{ "username": "<USERNAME>" }`

Response `200 OK`: `{ "message": "Credential enabled successfully" }`
Errors: `400` (missing username, already enabled), `401` (invalid key, not found).

### Disable TURN Credential

```
POST /api/v1/turn/credential/disable?secretKey=<SECRET_KEY>
```

Body: `{ "username": "<USERNAME>" }`

Response `200 OK`: `{ "message": "Turn credential disabled successfully" }`
Errors: `400` (missing username, already disabled), `401` (not found).

### Delete TURN Credential

```
DELETE /api/v1/turn/credential?secretKey=<SECRET_KEY>
```

Body: `{ "username": "<USERNAME>" }`

Response `200 OK`: `{ "success": true, "message": "credential removed" }`
Errors: `400` (credential not found).

### Update TURN Credential Label

```
POST /api/v2/turn/credential/update_label?secretKey=<SECRET_KEY>&username=<USERNAME>
```

Body: `{ "label": "<new_label>" }`

Response `200 OK` — object with `username`, `password`, `expiryInSeconds`, `label`, `apiKey`.
Errors: `400` (credential not found).

### List TURN Credentials (v2)

```
GET /api/v2/turn/credentials?secretKey=<SECRET_KEY>
```

Query params:
- `secretKey` (string, required)
- `all` (boolean, optional) — include expired credentials; default false
- `page` (integer, optional) — page number for pagination
- `label` (string, optional) — filter by label

Response `200 OK` — object with `data[]` and `pagination`.

Each credential in `data[]`: `username`, `password`, `apiKey`, `expiryInSeconds`, `label`, `expired` (bool).

`pagination`: `total_records`, `current_page`, `total_pages`, `next_page`, `prev_page`.

Errors: `400` (not subscribed, not available under free plan).

### Delete TURN Credential by Label

Deletes all active (non-expired) credentials matching a label.

```
DELETE /api/v2/turn/credential/by_label?secretKey=<SECRET_KEY>&label=<LABEL>
```

Query params:
- `secretKey` (string, required)
- `label` (string, required) — must be fewer than 100 characters

Response `200 OK`: `{ "deleted": 3 }`

Errors: `400` (missing/invalid secretKey, missing/invalid label, not subscribed).

---

## REST API — Usage

### Get Current Usage

Returns quota, usage, and overage for the current billing cycle.

```
GET /api/v1/turn/current_usage?secretKey=<SECRET_KEY>
```

Response `200 OK` — object with `quotaInGB` (number), `usageInGB` (number), `overageInGB` (number).

Errors: `400` (not subscribed), `500` (internal error).

### Get Current Usage by Date

Returns daily usage breakdown for the current billing cycle.

```
GET /api/v1/turn/current_usage_by_date?secretKey=<SECRET_KEY>
```

Response `200 OK` — array of `{ "date": "YYYY-MM-DD", "usageInGB": <number> }`.

Errors: `400` (not subscribed), `401` (invalid key), `500` (internal error).

### Get Current Usage by User (v2, paginated)

```
GET /api/v2/turn/current_usage_by_user?secretKey=<SECRET_KEY>&page=<PAGE>
```

Query params:
- `secretKey` (string, required)
- `page` (number, optional) — page number for pagination

Response `200 OK` — object with `data[]` (each: `label`, `username`, `usageInGB`) and `has_more` (bool).

Errors: `400` (not subscribed, free plan), `500` (internal error).

### Get Current Usage for a Specific User

```
GET /api/v1/turn/current_usage_for_user?secretKey=<SECRET_KEY>&username=<USERNAME>
```

Response `200 OK`: `{ "usageInGB": 5.2 }`

Errors: `400` (missing secretKey/username, not subscribed), `401` (invalid key, credential not found).

### Get Daily Usage by User (v2, paginated)

Returns daily TURN bandwidth per credential username within a date range.

```
GET /api/v2/turn/usage_daily_by_user?secretKey=<SECRET_KEY>
```

Query params:
- `secretKey` (string, required)
- `startDate` (string, optional) — YYYY-MM-DD, defaults to 6 days before endDate, max 3 months back
- `endDate` (string, optional) — YYYY-MM-DD, defaults to today
- `page` (number, optional) — 1-based, each page returns 7 days

Rate limit: 4 requests per minute per app.

Response `200 OK` — object with `data[]`, `pagination`, and `period`.

Each `data[]` item: `date` (YYYY-MM-DD), `usage[]` (sorted by descending usageInGB). Each usage item: `username`, `label` (or "unlabeled"), `usageInGB`.

`pagination`: `current_page`, `days_per_page` (fixed 7), `has_more`, `total_days`, `total_pages`.
`period`: `start`, `end`, `page_start`, `page_end`.

Errors: `400` (invalid key, not subscribed, free plan, invalid dates, date range >3 months), `500` (internal error).

### Get Usage Charges

Returns charges, payments, and subscription renewals in a date range.

```
GET /api/v2/payment/usage-charges?secretKey=<SECRET_KEY>&startDate=<YYYY-MM-DD>&endDate=<YYYY-MM-DD>
```

Query params:
- `secretKey` (string, required)
- `startDate` (string, required) — YYYY-MM-DD
- `endDate` (string, required) — YYYY-MM-DD

Rate limit: 4 requests per minute per app.

Response `200 OK` — object with `success`, `data[]`, `summary`, and `period`.

Each `data[]` item: `date` (YYYY-MM-DD), `type` (overage|subscription_renewal|recharge), `description`, `total` (USD), `status` (paid|pending). Overage items also have `usage`, `unit` (GB), `unitCharge`. Subscription items have `planName`. Recharge/subscription items have `paymentMethod` (automatic|manual|account_credit).

`summary`: `totalCharges`, `totalOverages`, `totalSubscriptions`, `totalRecharges`, `currency` (USD).
`period`: `startDate`, `endDate`.

Errors: `400` (missing dates, invalid format, end before start, not subscribed, free plan), `401` (invalid key), `500` (internal error).

---

## REST API — Projects

Projects (Business/Enterprise plans only) group TURN credentials with per-project API keys, quotas, notifications, and usage tracking. Each project has a unique ID and API key, optional quota (bytes; 0 = unlimited), exceeded action (`disable`|`notify`|`none`), up to 10 notification emails, and an optional HTTPS webhook URL. Notifications fire at 80% and 100% quota.

### Get Projects

```
GET /api/v2/turn/projects?secretKey=<SECRET_KEY>
```

Response `200 OK` — array of project objects.

Each project: `_id`, `projectName`, `quotaInBytes` (0 = no limit), `webhookUrl` (or null), `notificationEmails` (array), `quotaExceededAction` (disable|notify|none), `created` (ISO 8601).

Errors: `400` (invalid key, not subscribed).

### Create Project

```
POST /api/v2/turn/project?secretKey=<SECRET_KEY>
Content-Type: application/json
```

Body:
- `projectName` (string, required) — must be <100 characters
- `quotaInBytes` (number, optional) — integer >= 1 MiB (1048576); 0 or omitted = no limit
- `webhookUrl` (string, optional) — must start with https://
- `notificationEmails` (array, optional) — max 10 valid email addresses
- `quotaExceededAction` (string, optional) — `disable` (default), `notify`, or `none`

Response `200 OK` — project object with `_id`, `projectName`, `quotaInBytes`, `webhookUrl`, `notificationEmails`, `quotaExceededAction`, `apiKey`, `created` (ISO 8601).

Errors: `400` (invalid key, not subscribed, invalid name/quota/webhook/emails/action).

### Update Project

```
PUT /api/v2/turn/project/:projectId?secretKey=<SECRET_KEY>
Content-Type: application/json
```

Path param: `projectId` (string, required)

Body (all optional):
- `projectName` (string)
- `quotaInBytes` (number) — 0 or >= 1 MiB
- `webhookUrl` (string)
- `notificationEmails` (array)
- `quotaExceededAction` (string)

Response `200 OK`: same shape as Create Project (without `apiKey`).

Errors: `400` (invalid key, not subscribed, project not found, invalid fields).

### Delete Project

Permanently deletes the project and all credentials inside it.

```
DELETE /api/v2/turn/project/:projectId?secretKey=<SECRET_KEY>
```

Response `200 OK`: `{ "success": true }`

Errors: `400` (invalid key, missing/invalid projectId, project not found).

### Regenerate Project API Key

Invalidates the old API key and returns a new one.

```
POST /api/v2/turn/project/:projectId/regenerate_api_key?secretKey=<SECRET_KEY>
```

Response `200 OK`: `{ "apiKey": "pk_aaabbbbccdddd", "success": true }`

Errors: `400` (invalid key, missing/invalid projectId, project not found), `500` (internal error).

### Create Project TURN Credential

```
POST /api/v2/turn/project/:projectId/credential?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
Content-Type: application/json
```

Body:
- `expiryInSeconds` (number, optional) — positive integer; if omitted, no auto-expire
- `label` (string, optional)

Response `200 OK` — object with `username`, `password`, `expiryInSeconds`, `label`, `apiKey`.

Errors: `400` (invalid projectId, project not found, invalid expiry, not subscribed), `403` (max credential limit reached).

### Get Credentials for Project

```
GET /api/v2/turn/project/:projectId/credentials?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Query params:
- `page` (number, optional) — default 1, 50 records per page
- `all` (any, optional) — include expired credentials
- `label` (string, optional) — filter by label

Response `200 OK` — object with `data[]` and `pagination`.

Each credential in `data[]`: `_id`, `project`, `username`, `password`, `apiKey`, `manuallyDisabled` (bool), `disabledByProjectRule` (bool).

`pagination`: `total_records`, `current_page`, `total_pages`, `next_page`, `prev_page`.

Errors: `400` (invalid projectId, project not found, not subscribed).

### Delete Project Credential

```
DELETE /api/v2/turn/project/:projectId/credential?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
Content-Type: application/json
```

Body: `{ "username": "<USERNAME>" }`

Response `200 OK`: `{ "success": true, "message": "credential removed" }`

Errors: `400` (missing username, credential not found).

### Delete Project Credential by Label

Deletes all active (non-expired) credentials in the project matching a label.

```
DELETE /api/v2/turn/project/:projectId/credential/by_label?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
Content-Type: application/json
```

Body: `{ "label": "my-labeled-credential" }`

Response `200 OK`: `{ "deleted": 2 }`

Errors: `400` (missing/invalid label, not subscribed).

### Get Current Project Usage

```
GET /api/v2/turn/project/:projectId/current_usage?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Response `200 OK` — object with `quotaInBytes`, `usageInBytes`, `overageInBytes`.

Errors: `400` (not subscribed, project not found), `500` (internal error).

### Get Current Project Usage by Date

```
GET /api/v2/turn/project/:projectId/current_usage_by_date?secretKey=<SECRET_KEY>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Response `200 OK` — array of `{ "date": "YYYY-MM-DD", "usageInBytes": <number> }`.

Errors: `400` (project not found).

### Get Current Project Usage by User

```
GET /api/v2/turn/project/:projectId/current_usage_by_user?secretKey=<SECRET_KEY>&page=<PAGE>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Query params: `page` (number, optional) — default 1, 25 records per page.

Response `200 OK` — object with `data[]` (each: `label`, `username`, `usageInBytes`) and `has_more` (bool). Note: `usageInBytes` may be a string; parse as needed.

Errors: `400` (not subscribed, project not found).

### Get Project Usage for a Specific User

```
GET /api/v2/turn/project/:projectId/current_usage_for_user?secretKey=<SECRET_KEY>&username=<USERNAME>
  (or ?projectApiKey=<PROJECT_API_KEY>)
```

Response `200 OK` — object with `label` and `usageInBytes` (may be string).

Errors: `400` (missing username), `401` (credential not found).

---

## Expiring Credentials

Expiring credentials auto-disable after a set duration, preventing leaked credentials from being reused. Recommended for production.

**Flow**: Back-end calls Create Credential with `expiryInSeconds` (e.g., 14400 for 4 hours) -> gets `username`, `password`, `apiKey` -> returns `apiKey` to front-end -> front-end calls `GET /api/v1/turn/credentials?apiKey=<apiKey>` to get ICE Servers array -> credential auto-expires.

Always call the Create Credential API from the back-end (never front-end). Project-scoped credentials also support `expiryInSeconds`.

---

## Project Webhooks

When a project has a webhook URL, HTTP POST requests fire at two thresholds:
- `project_quota_80_percent` — usage crosses 80% of quota
- `project_quota_exceeded` — usage crosses 100% of quota

**Payload**: JSON with `event`, `project` (ID), `projectName`, `app` (ID), `quota` (bytes), `usage` (bytes).

**Security**: `X-Metered-Signature-256` header contains `sha256=<hex_hmac>`. Verify by computing HMAC-SHA256 of the raw body with Project API Key as secret.

**Requirements**: HTTPS endpoint, POST, return 2xx. System retries on failure.

**Notes**: Quota 0 = no events. One notification per threshold per quota setting. Modifying quota resets thresholds.

---

## Part 3: Global Cloud SFU

# Metered Global Cloud SFU -- llms.txt reference
(last updated: 2026-05-05)

> Metered Global Cloud SFU is a globally distributed Selective Forwarding Unit that acts as a PUB-SUB service for audio, video, and data channels. It uses plain WebRTC API and HTTP REST calls -- no third-party SDK required. Users are automatically geo-routed to the nearest SFU for lowest latency.

## Overview

Metered Global Cloud SFU lets you build any real-time application involving audio, video, or data channels. Participants publish media tracks to the SFU and subscribe to tracks from other participants. Users auto-connect to the nearest SFU by geography; media between regions routes over high-speed inter-SFU links.

**Connection Flow:**
1. **Establish Connection:** Create `peerConnection` (native WebRTC API), send SDP offer to SFU via HTTP, set returned SDP answer on `peerConnection`.
2. **Publish a Track:** Add track to `peerConnection`, generate new SDP offer, send to Publish Track API, set returned SDP answer.
3. **Subscribe to a Track:** Call Subscribe Track API with `remoteSessionId` + `remoteTrackId`, set returned SDP offer as remote description, create answer, call Renegotiate API. The `ontrack` event fires.

**Key Advantages:** Scalable (media sent once to SFU, forwarded to all subscribers); platform independent (native WebRTC + HTTP, no SDK); flexible pub-sub (no rooms); cost efficient (billed by GB downloaded, uploads free).

## Getting Started

1. **Sign up** at https://dashboard.metered.ca/signup to create a free Metered account.
2. Go to **Dashboard → Global SFU** and click **"Add SFU App"** to create an SFU application.
3. After creating the app, note your **SFU App ID** and **Secret** shown on the dashboard. You need both for all API calls.
4. The **SFU App ID** goes in the URL path. The **Secret** goes in the `Authorization: Bearer {secret}` header.
5. You can create multiple SFU apps for different environments (dev/staging/prod) or per-tenant isolation.

## Key Terms

- **SFU Application (App):** Container for sessions. Has `SFU_APP_ID` and `SFU_APP_SECRET`. Create from Dashboard → Global SFU. Use to scope dev/staging/prod or per-tenant.
- **Session:** Represents a single `peerConnection` to the SFU. Scoped within an App. Created via Create Session API which returns a `session_id` and remote SDP.
- **Track:** An audio or video stream published to the SFU. Has `trackId`, `mid` (SDP media line ID), optional `customTrackName`, and `trackKind` (video/audio). Multiple tracks per session.
- **No Rooms:** There is no room concept. Publish and subscribe freely within an App.

## Authentication

All API requests require a Bearer token in the `Authorization` header. The token is the `Secret` of your SFU App (found in Dashboard → Global SFU).

```
Authorization: Bearer {sfu_app_secret}
Content-Type: application/json
```

## Base URL

```
https://global.sfu.metered.ca/api/sfu/:sfu_app_id/
```

Replace `:sfu_app_id` with your SFU Application ID. STUN server for peerConnection (no TURN needed):

```
stun:stun.metered.ca:80
```

## Endpoint Summary

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/sfu/:sfu_app_id/session/new` | Create a new session |
| POST | `/api/sfu/:sfu_app_id/session/:session_id/track/publish` | Publish track(s) |
| POST | `/api/sfu/:sfu_app_id/session/:session_id/track/subscribe` | Subscribe to track(s) |
| POST | `/api/sfu/:sfu_app_id/session/:session_id/track/close` | Close a track |
| GET | `/api/sfu/:sfu_app_id/sessions` | List active sessions |
| GET | `/api/sfu/:sfu_app_id/session/:session_id/tracks` | List tracks for a session |
| PUT | `/api/sfu/:sfu_app_id/session/:session_id/renegotiate` | Renegotiate session SDP |

All endpoints require headers: `Authorization: Bearer {secret}` and `Content-Type: application/json`.

---

## REST API Endpoints

### Create Session

Creates a new session representing a `peerConnection`.

```
POST /api/sfu/:sfu_app_id/session/new
```

**URL Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sfu_app_id` | string | Your SFU App ID from the dashboard. |

**Request Body**

```json
{
    "sessionDescription": "<SDP offer from peerConnection>",
    "metadata": "optional descriptive text"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sessionDescription` | object | Yes | The SDP offer from the local `peerConnection`. |
| `metadata` | string | No | Custom text to store additional info about the session. |

**Response**

```json
{
    "sessionDescription": {
        "type": "answer",
        "sdp": "v=0\r\no=- 8184802762297966397 ..."
    },
    "sessionId": "session-101-fc756623-3be4-4c40-b651-20e22095ee07"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `sessionDescription` | object | Remote SDP answer. Set as remote description on `peerConnection`. |
| `sessionId` | string | Unique session identifier. Used in all subsequent API calls. |

---

### Publish Track

Publishes one or more tracks through an existing session. Add track(s) to `peerConnection`, generate new SDP offer, then call this endpoint.

```
POST /api/sfu/:sfu_app_id/session/:session_id/track/publish
```

**URL Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sfu_app_id` | string | Your SFU App ID. |
| `session_id` | string | Session ID from Create Session. |

**Request Body**

```json
{
    "tracks": [
        {
            "trackId": "local-track-uuid",
            "mid": "1",
            "customTrackName": "userA-video"
        }
    ],
    "sessionDescription": "<SDP offer>"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tracks` | array | Yes | Array of track objects to publish. |
| `sessionDescription` | object | Yes | New SDP offer after adding tracks to peerConnection. |

Each object in `tracks`:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `trackId` | string | Yes | Track ID from `transceiver.sender.track.id`. |
| `mid` | string | Yes | Media line ID from `transceiver.mid`. |
| `customTrackName` | string | No | Custom name to identify the track. |

**Response**

```json
{
    "sessionDescription": {
        "type": "answer",
        "sdp": "v=0\r\no=- 7170991192596339755 ..."
    },
    "sessionId": "session-101-03d73157-9df4-4bfc-91c9-01647bcfe80c"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `sessionDescription` | object | Remote SDP answer. Set as remote description on `peerConnection`. |
| `sessionId` | string | The session ID. |

**Code Example (publish a track to an existing session):**

```javascript
// Add a track to the existing peerConnection
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const track = stream.getVideoTracks()[0];
const transceiver = peerConnection.addTransceiver(track, { direction: "sendonly" });

const offer = await peerConnection.createOffer();
await peerConnection.setLocalDescription(offer);

const response = await fetch(
  `https://global.sfu.metered.ca/api/sfu/${sfuAppId}/session/${sessionId}/track/publish`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${sfuSecret}` },
    body: JSON.stringify({
      tracks: [{ trackId: track.id, mid: transceiver.mid, customTrackName: "my-video" }],
      sessionDescription: peerConnection.localDescription
    })
  }
);
const data = await response.json();
await peerConnection.setRemoteDescription(data.sessionDescription);
```

---

### Subscribe Track

Subscribes to one or more tracks published by another session. After calling this, you must complete renegotiation (see steps below).

```
POST /api/sfu/:sfu_app_id/session/:session_id/track/subscribe
```

**URL Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sfu_app_id` | string | Your SFU App ID. |
| `session_id` | string | Session ID of the subscribing session (your session). |

**Request Body**

```json
{
    "tracks": [
        {
            "remoteSessionId": "session-101-abc...",
            "remoteTrackId": "track-uuid..."
        }
    ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tracks` | array | Yes | Array of objects identifying remote tracks to subscribe to. |

Each object in `tracks`:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `remoteSessionId` | string | Yes | Session ID of the publisher. |
| `remoteTrackId` | string | Yes | Track ID of the remote track. |

**Response**

```json
{
    "immediateRenegotiationRequired": true,
    "sessionDescription": {
        "type": "offer",
        "sdp": "v=0\r\no=- 7684479339383422378 ..."
    },
    "sessionId": "session-101-5666e439-6660-414b-adc1-050ed4e8d666"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `immediateRenegotiationRequired` | boolean | If true, you must call Renegotiate API after setting remote description and creating an answer. |
| `sessionDescription` | object | Remote SDP offer. Set as remote description, then create an answer. |
| `sessionId` | string | The session ID. |

**Post-subscribe renegotiation steps:**
1. Set returned `sessionDescription` as remote description on `peerConnection`.
2. Create answer SDP via `peerConnection.createAnswer()`.
3. Set answer as local description.
4. Call Renegotiate API with the answer SDP.

---

### Close Track

Stops publishing a track. Remove the track from `peerConnection`, generate new SDP, send with track ID.

```
POST /api/sfu/:sfu_app_id/session/:session_id/track/close
```

**URL Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sfu_app_id` | string | Your SFU App ID. |
| `session_id` | string | Session ID that published the track. |

**Request Body**

```json
{
    "tracks": [
        {
            "trackId": "track-uuid-to-close"
        }
    ],
    "sessionDescription": "<SDP offer>"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tracks` | array | Yes | Array of track objects to close. Each must have `trackId`. |
| `sessionDescription` | object | Yes | New SDP offer after removing the track from peerConnection. |

**Response**

```json
{
    "sessionId": "session-101-...",
    "success": true,
    "sessionDescription": { "type": "answer", "sdp": "..." }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `sessionId` | string | The session ID. |
| `success` | boolean | Whether the track was closed successfully. |
| `sessionDescription` | object | Remote SDP answer. Set as remote description on `peerConnection`. |

**Code Example (close a published track):**

```javascript
const sender = peerConnection.getSenders().find(s => s.track && s.track.id === trackId);
peerConnection.removeTrack(sender);

const offer = await peerConnection.createOffer();
await peerConnection.setLocalDescription(offer);

const response = await fetch(
  `https://global.sfu.metered.ca/api/sfu/${sfuAppId}/session/${sessionId}/track/close`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json", "Authorization": `Bearer ${sfuSecret}` },
    body: JSON.stringify({
      tracks: [{ trackId: trackId }],
      sessionDescription: peerConnection.localDescription
    })
  }
);
const data = await response.json();
await peerConnection.setRemoteDescription(data.sessionDescription);
```

---

### Fetch Sessions

Returns all active sessions within an SFU App.

```
GET /api/sfu/:sfu_app_id/sessions
```

**URL Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sfu_app_id` | string | Your SFU App ID. |

No request body.

**Response**

```json
[
    { "connectionState": "connected", "metadata": "", "sessionId": "session-101-...", "sfuAppId": "66ad57c7..." }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `connectionState` | string | Connection state (e.g., "connected"). |
| `metadata` | string | Custom metadata from session creation. |
| `sessionId` | string | Unique session identifier. |
| `sfuAppId` | string | The SFU App ID. |

---

### Fetch Tracks

Returns all active tracks for a given session.

```
GET /api/sfu/:sfu_app_id/session/:session_id/tracks
```

**URL Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sfu_app_id` | string | Your SFU App ID. |
| `session_id` | string | Session ID to fetch tracks for. |

No request body.

**Response**

```json
[
    { "sessionId": "session-101-...", "sfuAppId": "66ad57c7...", "trackId": "33f140fc-...", "customTrackName": "userA-video", "mid": "1", "trackKind": "video" }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `sessionId` | string | Session that published this track. |
| `sfuAppId` | string | The SFU App ID. |
| `trackId` | string | Unique track identifier. Use when subscribing. |
| `customTrackName` | string | Custom name assigned during publish. |
| `mid` | string | Media line identifier from the SDP. |
| `trackKind` | string | `"video"` or `"audio"`. |

---

### Renegotiate

Updates SDP for an existing session. Required after subscribing to a track to send the answer SDP back.

```
PUT /api/sfu/:sfu_app_id/session/:session_id/renegotiate
```

**URL Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `sfu_app_id` | string | Your SFU App ID. |
| `session_id` | string | Session ID to renegotiate. |

**Request Body**

```json
{
    "sessionDescription": "<SDP answer>"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `sessionDescription` | object | Yes | The updated SDP (typically an answer) from `peerConnection`. |

**Response:** HTTP 200 on success.

---

## Quick Start Example

Publishes a webcam track (User A) and subscribes from a second session (User B).

```javascript
(async () => {
    const host = "https://global.sfu.metered.ca";
    const sfuAppId = "<YOUR_SFU_APP_ID>";
    const secret = "<YOUR_SFU_APP_SECRET>";

    // PUBLISHER (User A): create peerConnection, get webcam, create session
    const pcA = new RTCPeerConnection({
        iceServers: [{ urls: "stun:stun.metered.ca:80" }]
    });
    const stream = await navigator.mediaDevices.getUserMedia({ video: true });
    stream.getTracks().forEach(track => pcA.addTrack(track, stream));
    const offerA = await pcA.createOffer();
    await pcA.setLocalDescription(offerA);
    const resA = await fetch(`${host}/api/sfu/${sfuAppId}/session/new`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${secret}` },
        body: JSON.stringify({ sessionDescription: offerA })
    });
    const jsonA = await resA.json();
    const sessionIdA = jsonA.sessionId;
    await pcA.setRemoteDescription(jsonA.sessionDescription);
    // Wait for connection
    await new Promise(r => { pcA.oniceconnectionstatechange = () => { if (pcA.iceConnectionState === 'connected') r(); }; });

    // SUBSCRIBER (User B): create peerConnection, create session
    const pcB = new RTCPeerConnection({
        iceServers: [{ urls: "stun:stun.metered.ca:80" }]
    });
    pcB.addTransceiver('video');
    pcB.ontrack = (e) => {
        const video = document.createElement('video');
        video.srcObject = new MediaStream([e.track]);
        video.autoplay = true;
        document.body.appendChild(video);
    };
    const offerB = await pcB.createOffer();
    await pcB.setLocalDescription(offerB);
    const resB = await fetch(`${host}/api/sfu/${sfuAppId}/session/new`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${secret}` },
        body: JSON.stringify({ sessionDescription: offerB })
    });
    const jsonB = await resB.json();
    const sessionIdB = jsonB.sessionId;
    await pcB.setRemoteDescription(jsonB.sessionDescription);

    // Fetch tracks from User A, then subscribe
    const tracksRes = await fetch(`${host}/api/sfu/${sfuAppId}/session/${sessionIdA}/tracks`, {
        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${secret}` }
    });
    const tracks = await tracksRes.json();
    const trackId = tracks[0].trackId;
    const subRes = await fetch(`${host}/api/sfu/${sfuAppId}/session/${sessionIdB}/track/subscribe`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${secret}` },
        body: JSON.stringify({ tracks: [{ remoteSessionId: sessionIdA, remoteTrackId: trackId }] })
    });
    const subJson = await subRes.json();

    // Renegotiate to complete subscription
    await pcB.setRemoteDescription(new RTCSessionDescription(subJson.sessionDescription));
    const answer = await pcB.createAnswer();
    await pcB.setLocalDescription(answer);
    await fetch(`${host}/api/sfu/${sfuAppId}/session/${sessionIdB}/renegotiate`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${secret}` },
        body: JSON.stringify({ sessionDescription: answer })
    });
    // pcB.ontrack fires with User A's video
})();
```

### Flow Summary

1. **Create SFU App** in the Metered dashboard. Note `SFU_APP_ID` and `SECRET`.
2. **Create session** for publisher (`POST /session/new` with SDP offer).
3. **Publish tracks** (`POST /session/:id/track/publish` with tracks array + SDP).
4. **Create session** for subscriber (`POST /session/new` with SDP offer).
5. **Fetch tracks** from publisher's session (`GET /session/:id/tracks`).
6. **Subscribe** (`POST /session/:id/track/subscribe` with remoteSessionId + remoteTrackId).
7. **Renegotiate** (`PUT /session/:id/renegotiate` with answer SDP).
8. Subscriber's `ontrack` event fires with remote media track.

---

## Part 4: Embed SDK

# Metered Embed SDK -- llms.txt reference
(last updated: 2026-05-05)

> Complete API reference for the Metered Embed Frame SDK. Covers initialization, methods, events, and room-level iFrame options for embedding video chat into any website or app.

## Overview

Metered Embed allows you to embed video calls and text chat into any existing app or website in minutes. It is an iframe-based solution that provides video calling, screen-sharing, live streaming, and chat capabilities. You include the Frame SDK script, create a `MeteredFrame` instance, call `init()` with a room URL, and the SDK mounts an iframe into a target DOM element.

## Getting Started

1. **Sign up** at https://dashboard.metered.ca/signup to create a free Metered account.
2. Your **app name** (e.g. `yourappname`) is shown on the Dashboard home page. It forms your domain: `yourappname.metered.live`.
3. **Create a room**: Go to **Dashboard → Rooms** and click "Create Room", or use the REST API. Each room gets a URL: `yourappname.metered.live/roomname`.
4. For **private rooms**, generate access tokens via the REST API. The **Secret Key** for API calls is found in **Dashboard → Developers**. Never expose it in front-end code.
5. Use the room URL in the Embed SDK's `init()` call to embed video chat.

## Setup

### CDN URL

```html
<script src="https://cdn.metered.ca/sdk/frame/1.4.3/sdk-frame.min.js"></script>
```

### Minimal embed code

```html
<div id="metered-frame"></div>
<script src="https://cdn.metered.ca/sdk/frame/1.4.3/sdk-frame.min.js"></script>
<script>
    var frame = new MeteredFrame();
    frame.init({
        roomURL: "yourappname.metered.live/tutorial",
    }, document.getElementById("metered-frame"));
</script>
```

### How it works

1. Include the Frame SDK script tag.
2. Add a `<div>` element to your page where the embed should appear.
3. Create a new `MeteredFrame` instance: `var frame = new MeteredFrame();`
4. Call `frame.init(options, domElement)` to mount the iframe.

## Init Options

The `init()` method accepts an options object as its first argument. These options control the behavior and appearance of the embedded meeting.

| Option | Type | Required | Description | Default |
|---|---|---|---|---|
| `roomURL` | string | YES | URL of the Meeting Room (e.g. `yourappname.metered.live/roomname`). | -- |
| `width` | string | NO | Width of the embed (CSS value, e.g. `"100px"`, `"50%"`). | `"100%"` |
| `height` | string | NO | Height of the embed (CSS value). | `"600px"` |
| `autoJoin` | boolean | NO | When `true`, users skip the Lobby/Join Meeting page and enter the meeting directly. Overrides room settings. | `false` |
| `name` | string | NO | Name of the user. Used with `autoJoin` -- set `autoJoin: true` and provide a `name` to auto-join with that display name. | -- |
| `accessToken` | string | NO | Access token for authenticated joining (required for private rooms). Generate via the Video SDK REST API: `POST https://<appname>.metered.live/api/v1/token?secretKey=<key>` with body `{ "roomName": "...", "expirationDate": "ISO date" }`. Used with `autoJoin`. | -- |
| `joinVideoOn` | boolean | NO | Whether the camera is on when the user joins. Overrides room settings. | `true` |
| `joinAudioOn` | boolean | NO | Whether the microphone is on when the user joins. Overrides room settings. | `true` |
| `showInviteBox` | boolean | NO | When only one participant is in the meeting, an invite box with instructions is shown. Set to `false` to hide it. | `true` |
| `disableScreenSharing` | boolean | NO | Disables screen sharing for this embed instance. Cannot override room settings if already disabled there. | `false` |
| `disableChat` | boolean | NO | Disables chat for this embed instance. Overrides room settings for this specific embed. | `false` |

Example with multiple options:

```javascript
var frame = new MeteredFrame();
frame.init({
    roomURL: "yourappname.metered.live/my-room",
    width: "100%",
    height: "800px",
    autoJoin: true,
    name: "James Bond",
    joinVideoOn: false,
    joinAudioOn: true,
    disableChat: false,
    disableScreenSharing: false,
    showInviteBox: false,
}, document.getElementById("metered-frame"));
```

## Methods

### init(options, domElement)

Initializes and mounts the Metered Embed iframe. This method MUST be called -- the iframe is not mounted until `init()` is called. You can call it on page load or after a user interaction if you want the embed to appear on demand.

**Parameters:**

- `options` (Object, required) -- The init options object (see Init Options section above).
- `domElement` (HTMLElement, required) -- The DOM element where the iframe will be mounted.

**Returns:** void

```javascript
var frame = new MeteredFrame();
frame.init({
    roomURL: "appname.metered.live/my-room",
}, document.getElementById("metered-frame"));
```

### join(options)

Joins the participant to the meeting programmatically. Must be called after `init()`. Used when `autoJoin` is `false` and you want to trigger joining from your application code.

**Parameters:**

- `options` (Object, required) -- Must contain either `name` or `accessToken`.
  - `name` (string) -- Display name for the participant.
  - `accessToken` (string) -- Access token for authenticated joining.

**Returns:** void

Join by name:

```javascript
frame.join({
    name: "James Bond"
});
```

Join by access token:

```javascript
frame.join({
    accessToken: "..."
});
```

### leave()

Exits the meeting. Must be called after `join()`. Behaves the same as pressing the end-call button in the meeting frame.

**Parameters:** none

**Returns:** void

```javascript
frame.leave();
```

### openChat()

Opens the chat panel in the iframe. Only works when chat is enabled in the room settings. Behaves the same as pressing the chat button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.openChat();
```

### closeChat()

Closes the visible chat panel in the iframe. Behaves the same as pressing the close-chat button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.closeChat();
```

### startCamera()

Starts sharing the participant's camera in the meeting. Behaves the same as pressing the camera button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.startCamera();
```

### stopCamera()

Stops sharing the participant's camera. Behaves the same as pressing the stop-camera button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.stopCamera();
```

### startScreenShare()

Starts screen sharing. Behaves the same as pressing the share-screen button in the iframe.

**Parameters:** none

**Returns:** void

```javascript
frame.startScreenShare();
```

### stopScreenShare()

Stops screen sharing.

**Parameters:** none

**Returns:** void

```javascript
frame.stopScreenShare();
```

## Events

The Metered Embed Frame SDK emits events that you can listen to using `frame.on()`.

**Listener pattern:**

```javascript
frame.on("<eventName>", function(data) {
    // Handle event
});
```

### ready

Emitted when the Metered Frame iframe has loaded and is ready for interaction. No callback data is passed.

```javascript
frame.on("ready", function() {
    console.log("Metered Frame is ready");
});
```

### meetingJoined

Emitted when the current user successfully joins the meeting.

```javascript
frame.on("meetingJoined", function(meetingInfo) {
    console.log("Joined the meeting", meetingInfo);
});
```

### meetingLeft

Emitted when the current user leaves the meeting.

```javascript
frame.on("meetingLeft", function(meetingLeft) {
    console.log("Left the meeting");
});
```

### onlineParticipants

Emitted multiple times during the meeting. Contains an array of all participants currently in the meeting.

```javascript
frame.on("onlineParticipants", function(onlineParticipants) {
    console.log("Current participants:", onlineParticipants);
});
```

**Callback data:** `onlineParticipants` is an array of objects. Each object has:

| Property | Type | Description |
|---|---|---|
| `_id` | string | Participant session ID. |
| `name` | string | Display name of the user. |
| `sharingAudio` | boolean | Whether the user is currently sharing their microphone. |
| `sharingVideo` | boolean | Whether the user is currently sharing their camera. |
| `sharingScreen` | boolean | Whether the user is currently sharing their screen. |
| `disabledAudio` | boolean | Whether an admin has disabled the user's audio. |
| `disabledScreenSharing` | boolean | Whether an admin has disabled the user's screen sharing. |
| `disabledVideo` | boolean | Whether an admin has disabled the user's camera. |
| `isAdmin` | boolean | Whether the user is an admin. |
| `meetingSessionId` | string | The meeting session ID. |
| `roomId` | string | The room ID. |

### participantJoined

Emitted when a new participant joins the meeting.

```javascript
frame.on("participantJoined", function(participantInfo) {
    console.log("Participant joined:", participantInfo.name);
});
```

**Callback data:** `participantInfo` is an object with the same shape as each entry in the `onlineParticipants` array (see above): `_id`, `name`, `sharingAudio`, `sharingVideo`, `sharingScreen`, `disabledAudio`, `disabledScreenSharing`, `disabledVideo`, `isAdmin`, `meetingSessionId`, `roomId`.

### participantLeft

Emitted when a participant leaves the meeting. Callback data has the same shape as `participantJoined`.

```javascript
frame.on("participantLeft", function(participantInfo) {
    console.log("Participant left:", participantInfo.name);
});
```

### participantSharingStateUpdated

Emitted when a participant's sharing state changes (starts/stops camera, microphone, or screen share).

```javascript
frame.on("participantSharingStateUpdated", function(participantSharingState) {
    console.log("Sharing state changed:", participantSharingState.action);
});
```

**Callback data:** `participantSharingState` is an object with:

| Property | Type | Description |
|---|---|---|
| `action` | string (enum) | The action taken. One of: `startedSharingScreen`, `stoppedSharingScreen`, `startedSharingVideo`, `stoppedSharingVideo`, `startedSharingAudio`, `stoppedSharingAudio`. |
| `eventId` | string | Unique event ID for this action. |
| `participantSessionId` | string | The participant's session ID. |
| `sharingAudio` | boolean | Whether the user is currently sharing their microphone. |
| `sharingVideo` | boolean | Whether the user is currently sharing their camera. |
| `sharingScreen` | boolean | Whether the user is currently sharing their screen. |
| `disabledAudio` | boolean | Whether an admin has disabled the user's audio. |
| `disabledScreenSharing` | boolean | Whether an admin has disabled the user's screen sharing. |
| `disabledVideo` | boolean | Whether an admin has disabled the user's camera. |
| `meetingSessionId` | string | The meeting session ID. |

## iFrame Options

These are room-level configuration options set in the Metered Dashboard when creating or editing a room. They control the default behavior of the embedded meeting for all participants.

### Camera on join

When enabled, the participant's camera is automatically shared when they join the meeting. Used in conjunction with Auto Join. Users can still toggle their camera after joining. Can be overridden per-embed using the `joinVideoOn` init option.

### Microphone on join

When enabled, the participant's microphone is automatically shared when they join the meeting. Can be overridden per-embed using the `joinAudioOn` init option.

### Screen Sharing

When enabled, users can share their screen. When disabled, the screen-sharing button is hidden for all users. To disable screen sharing for specific users only, use the `disableScreenSharing` init option in the Embed Frame SDK.

### Text Chat

When enabled, users can text chat with each other. When disabled, text chat is not available in the meeting. To disable chat for specific users only, use the `disableChat` init option in the Embed Frame SDK.

### New Chat For Meeting Session

When enabled, a new chat room is created for each meeting session with separate chat history. When disabled, the chat is associated with the room itself, and all meeting sessions of that room share the same chat history.

### Request to Join

When the room privacy setting is set to `private` and Request to Join is enabled, users who do not have an `accessToken` can request to join the meeting. A notification is sent to the meeting admin, and when the admin accepts the request, the user is allowed to join.

### Show Invite Instruction

When there is only one participant in a meeting, invite instructions are displayed showing the meeting URL. Disabling this option hides the invite instructions. Can be overridden per-embed using the `showInviteBox` init option.

### Auto Join

When enabled, the Lobby / Join Meeting page is not displayed and the user directly enters the meeting. Can be overridden per-embed using the `autoJoin` init option.

### Admin Only Broadcast

When enabled, only admins can share their camera, microphone, and screen by default. Admins can selectively allow specific participants to share their camera, microphone, or screen during the meeting. All non-admin participants are view-only by default.

## Complete Example

```html
<div id="metered-frame"></div>
<button id="join-btn">Join</button>
<button id="leave-btn">Leave</button>

<script src="https://cdn.metered.ca/sdk/frame/1.4.3/sdk-frame.min.js"></script>
<script>
var frame = new MeteredFrame();

frame.init({
    roomURL: "yourappname.metered.live/my-room",
    autoJoin: false,
    joinVideoOn: true,
    joinAudioOn: true,
}, document.getElementById("metered-frame"));

frame.on("ready", function() { console.log("Frame ready"); });
frame.on("meetingJoined", function(info) { console.log("Joined", info); });
frame.on("meetingLeft", function() { console.log("Left meeting"); });
frame.on("onlineParticipants", function(list) { console.log(list.length, "online"); });
frame.on("participantJoined", function(p) { console.log(p.name, "joined"); });
frame.on("participantLeft", function(p) { console.log(p.name, "left"); });
frame.on("participantSharingStateUpdated", function(s) { console.log(s.action); });

document.getElementById("join-btn").onclick = function() { frame.join({ name: "User" }); };
document.getElementById("leave-btn").onclick = function() { frame.leave(); };
</script>
```