1# Patterns & Use Cases
2 
3## Architecture
4 
5```
6Client (WebRTC) <---> CF Edge <---> Backend (HTTP)
7                           |
8                    CF Backbone (310+ DCs)
9                           |
10                    Other Edges <---> Other Clients
11```
12 
13Anycast: Last-mile <50ms (95%), no region select, NACK shield, distributed consensus
14 
15Cascading trees auto-scale to millions:
16```
17Publisher -> Edge A -> Edge B -> Sub1
18                    \-> Edge C -> Sub2,3
19```
20 
21## Use Cases
22 
23**1:1:** A creates session+publishes, B creates+subscribes to A+publishes, A subscribes to B
24**N:N:** All create session+publish, backend broadcasts track IDs, all subscribe to others
25**1:N:** Publisher creates+publishes, viewers each create+subscribe (no fan-out limit)
26**Breakout:** Same PeerConnection! Backend closes/adds tracks, no recreation
27 
28## PartyTracks (Recommended)
29 
30Observable-based client with automatic device/network handling:
31 
32```typescript
33import {PartyTracks} from 'partytracks';
34 
35// Create client
36const pt = new PartyTracks({
37  apiUrl: '/api/calls',
38  sessionId: 'my-session',
39  onTrack: (track, peer) => {
40    const video = document.getElementById(`video-${peer.id}`) as HTMLVideoElement;
41    video.srcObject = new MediaStream([track]);
42  }
43});
44 
45// Publish camera (push API)
46const camera = await pt.getCamera(); // Auto-requests permissions, handles device changes
47await pt.publishTrack(camera, {trackName: 'my-camera'});
48 
49// Subscribe to remote track (pull API)
50await pt.subscribeToTrack({trackName: 'remote-camera', sessionId: 'other-session'});
51 
52// React hook example
53import {useObservableAsValue} from 'observable-hooks';
54 
55function VideoCall() {
56  const localTracks = useObservableAsValue(pt.localTracks$);
57  const remoteTracks = useObservableAsValue(pt.remoteTracks$);
58  
59  return <div>{/* Render tracks */}</div>;
60}
61 
62// Screenshare
63const screen = await pt.getScreenshare();
64await pt.publishTrack(screen, {trackName: 'my-screen'});
65 
66// Handle device changes (automatic)
67// PartyTracks detects device changes (e.g., Bluetooth headset) and renegotiates
68```
69 
70## Backend
71 
72Express:
73```js
74app.post('/api/new-session', async (req, res) => {
75  const r = await fetch(`${CALLS_API}/apps/${process.env.CALLS_APP_ID}/sessions/new`,
76    {method: 'POST', headers: {'Authorization': `Bearer ${process.env.CALLS_APP_SECRET}`}});
77  res.json(await r.json());
78});
79```
80 
81Workers: Same pattern, use `env.CALLS_APP_ID` and `env.CALLS_APP_SECRET`
82 
83DO Presence: See configuration.md for boilerplate
84 
85## Audio Level Detection
86 
87```typescript
88// Attach analyzer to audio track
89function attachAudioLevelDetector(track: MediaStreamTrack) {
90  const ctx = new AudioContext();
91  const analyzer = ctx.createAnalyser();
92  const src = ctx.createMediaStreamSource(new MediaStream([track]));
93  src.connect(analyzer);
94  
95  const data = new Uint8Array(analyzer.frequencyBinCount);
96  const checkLevel = () => {
97    analyzer.getByteFrequencyData(data);
98    const level = data.reduce((a, b) => a + b) / data.length;
99    if (level > 30) console.log('Speaking:', level); // Trigger UI update
100    requestAnimationFrame(checkLevel);
101  };
102  checkLevel();
103}
104```
105 
106## Connection Quality Monitoring
107 
108```typescript
109pc.getStats().then(stats => {
110  stats.forEach(report => {
111    if (report.type === 'inbound-rtp' && report.kind === 'video') {
112      const {packetsLost, packetsReceived, jitter} = report;
113      const lossRate = packetsLost / (packetsLost + packetsReceived);
114      if (lossRate > 0.05) console.warn('High packet loss:', lossRate);
115      if (jitter > 100) console.warn('High jitter:', jitter);
116    }
117  });
118});
119```
120 
121## Stage Management (Limit Visible Participants)
122 
123```typescript
124// Subscribe to top 6 active speakers only
125let activeSubscriptions = new Set<string>();
126 
127function updateStage(topSpeakers: string[]) {
128  const toAdd = topSpeakers.filter(id => !activeSubscriptions.has(id)).slice(0, 6);
129  const toRemove = [...activeSubscriptions].filter(id => !topSpeakers.includes(id));
130  
131  toRemove.forEach(id => {
132    pc.getSenders().find(s => s.track?.id === id)?.track?.stop();
133    activeSubscriptions.delete(id);
134  });
135  
136  toAdd.forEach(async id => {
137    await fetch(`/api/subscribe`, {method: 'POST', body: JSON.stringify({trackId: id})});
138    activeSubscriptions.add(id);
139  });
140}
141```
142 
143## Advanced
144 
145Bandwidth mgmt:
146```ts
147const s = pc.getSenders().find(s => s.track?.kind === 'video');
148const p = s.getParameters();
149if (!p.encodings) p.encodings = [{}];
150p.encodings[0].maxBitrate = 1200000; p.encodings[0].maxFramerate = 24;
151await s.setParameters(p);
152```
153 
154Simulcast (CF auto-forwards best layer):
155```ts
156pc.addTransceiver('video', {direction: 'sendonly', sendEncodings: [
157  {rid: 'high', maxBitrate: 1200000},
158  {rid: 'med', maxBitrate: 600000, scaleResolutionDownBy: 2},
159  {rid: 'low', maxBitrate: 200000, scaleResolutionDownBy: 4}
160]});
161```
162 
163DataChannel:
164```ts
165const dc = pc.createDataChannel('chat', {ordered: true, maxRetransmits: 3});
166dc.onopen = () => dc.send(JSON.stringify({type: 'chat', text: 'Hi'}));
167dc.onmessage = (e) => console.log('RX:', JSON.parse(e.data));
168```
169 
170**WHIP/WHEP:** For streaming interop (OBS → SFU, SFU → video players), use WHIP (ingest) and WHEP (egress) protocols. See Cloudflare Stream integration docs.
171 
172Integrations: R2 for recording `env.R2_BUCKET.put(...)`, Queues for analytics
173 
174Perf: 100-250ms connect, ~50ms latency (95%), 200-400ms glass-to-glass, no participant limit (client: 10-50 tracks)
175