1
/**
2
 * An SDP explainer: paste an offer or an answer and see every line, what it sets, and which phase of the call reads
3
 * it: ICE finding the path, DTLS making the keys, RTP and its codec carrying the sound, RTCP reporting on it.
4
 *
5
 * Three things a reader cannot easily do by eye, each a place a hand-written description goes wrong:
6
 *
7
 *  1. **Group the lines by the phase that reads them.** An SDP is written in RFC 8866's fixed order, which is the
8
 *     order a parser wants and not the order a call uses it in. The phase table is the model's, and a line it does
9
 *     not know is "Other": the tool says so rather than guessing, as RFC 8866 tells a parser to ignore what it does
10
 *     not understand.
11
 *  2. **Check it against the rules a WebRTC stack applies**, each with the RFC sentence behind it: an error for a
12
 *     MUST broken, a warning for a SHOULD or a value real stacks accept anyway, a note for a decoded oddity.
13
 *  3. **Read two descriptions as a pair**: who controls ICE, who sends the DTLS ClientHello, which codec both list.
14
 *
15
 * The fixtures were first the output of a reference model written beside the post; the rules have moved on since
16
 * (simulcast, data channels, bundle-only sections, and the tls-id rule real stacks ignore), each with its own
17
 * fixture and test. Candidate priorities are decoded the way the ICE pair ranker decodes them, and never recomputed: they are what
18
 * the agent sent.
19
 *
20
 * What it deliberately cannot do: check a fingerprint against a certificate. It has no certificate, so it can only
21
 * say one is present and whether the two sides' differ. The DTLS handshake does the real check.
22
 */
23
import type { Cell, Field, Output, TextTone, Tool } from "@toolbench/sdk";
24

25
type Input = { sdp: string; other: string; show: string };
26

27
class InputError extends Error {
28
  readonly input: string;
29
  constructor(message: string, input: string) {
30
    super(message);
31
    this.input = input;
32
  }
33
}
34

35
export const PHASES = ["Session", "ICE (path)", "DTLS (keys)", "RTP (streams)", "Codec", "RTCP (feedback)"] as const;
36
export type Phase = (typeof PHASES)[number] | "Other";
37
const SHORT: Record<Phase, string> = {
38
  Session: "Session",
39
  "ICE (path)": "ICE",
40
  "DTLS (keys)": "DTLS",
41
  "RTP (streams)": "RTP",
42
  Codec: "Codec",
43
  "RTCP (feedback)": "RTCP",
44
  Other: "Other",
45
};
46

47
/*
48
 * Which phase reads each attribute. `c=` is ICE's because it is the default candidate's address, which an ICE agent
49
 * replaces with the candidates; `a=group` is ICE's because BUNDLE is what lets one path carry every section.
50
 */
51
const ATTR_PHASE: Record<string, Phase> = {
52
  group: "ICE (path)",
53
  "ice-options": "ICE (path)",
54
  "ice-ufrag": "ICE (path)",
55
  "ice-pwd": "ICE (path)",
56
  "ice-lite": "ICE (path)",
57
  candidate: "ICE (path)",
58
  "end-of-candidates": "ICE (path)",
59
  fingerprint: "DTLS (keys)",
60
  setup: "DTLS (keys)",
61
  "tls-id": "DTLS (keys)",
62
  mid: "RTP (streams)",
63
  msid: "RTP (streams)",
64
  "msid-semantic": "RTP (streams)",
65
  ssrc: "RTP (streams)",
66
  "ssrc-group": "RTP (streams)",
67
  rid: "RTP (streams)",
68
  simulcast: "RTP (streams)",
69
  "bundle-only": "RTP (streams)",
70
  "sctp-port": "RTP (streams)",
71
  "max-message-size": "RTP (streams)",
72
  extmap: "RTP (streams)",
73
  "extmap-allow-mixed": "RTP (streams)",
74
  sendrecv: "RTP (streams)",
75
  sendonly: "RTP (streams)",
76
  recvonly: "RTP (streams)",
77
  inactive: "RTP (streams)",
78
  rtpmap: "Codec",
79
  fmtp: "Codec",
80
  ptime: "Codec",
81
  maxptime: "Codec",
82
  rtcp: "RTCP (feedback)",
83
  "rtcp-mux": "RTCP (feedback)",
84
  "rtcp-mux-only": "RTCP (feedback)",
85
  "rtcp-rsize": "RTCP (feedback)",
86
  "rtcp-fb": "RTCP (feedback)",
87
};
88

89
export function phaseOf(line: string): Phase {
90
  const head = line.slice(0, 2);
91
  if (head === "v=" || head === "o=" || head === "s=" || head === "t=") return "Session";
92
  if (head === "c=") return "ICE (path)";
93
  if (head === "m=") return "RTP (streams)";
94
  if (head === "a=") return ATTR_PHASE[line.slice(2).split(":", 1)[0]!] ?? "Other";
95
  return "Other";
96
}
97

98
const TYPE_PREF: Record<number, string> = { 126: "host", 110: "prflx", 100: "srflx", 0: "relay" };
99

100
/** RFC 8445 section 5.1.2.1: priority = 2^24 x type preference + 2^8 x local preference + (256 - component). */
101
export function decodePriority(p: number) {
102
  return { type: Math.floor(p / 2 ** 24), local: Math.floor(p / 2 ** 8) % 2 ** 16, component: 256 - (p % 256) };
103
}
104

105
export type Severity = "error" | "warning" | "note";
106
export interface Problem {
107
  severity: Severity;
108
  message: string;
109
  /** Index into `Model.lines`: the line the problem is about, or the m= line of the section that lacks something. */
110
  at: number;
111
}
112

113
interface Line {
114
  /** Its line number in the pasted text, blank lines included, so a reader can find it. */
115
  n: number;
116
  text: string;
117
  phase: Phase;
118
  what: string;
119
}
120

121
interface Candidate {
122
  at: number;
123
  foundation: string;
124
  component: number;
125
  transport: string;
126
  priority: number;
127
  address: string;
128
  port: number;
129
  type: string;
130
  raddr?: string;
131
  rport?: string;
132
}
133

134
export interface Model {
135
  lines: Line[];
136
  problems: Problem[];
137
  kind: "offer" | "answer" | "unknown";
138
  setup: string;
139
  lite: boolean;
140
  ufrag: string;
141
  candidates: Candidate[];
142
  trickle: string;
143
  fingerprints: string[];
144
  media: string[];
145
  codecs: string[];
146
  bundle: string[] | null;
147
  rtcpMux: boolean;
148
  counts: Record<Phase, number>;
149
}
150

151
const ICE_CHAR = /^[A-Za-z0-9+/]+$/;
152
const KIND_OF_SETUP: Record<string, Model["kind"]> = { actpass: "offer", active: "answer", passive: "answer" };
153
const ROLE: Record<string, string> = {
154
  actpass: "either; the answerer chooses",
155
  active: "DTLS client: sends the ClientHello",
156
  passive: "DTLS server: waits for the ClientHello",
157
};
158

159
/** Every `a=<name>` or `a=<name>:<value>` in a block of line indices, with where it is. */
160
function attrs(lines: string[], block: number[], name: string): { value: string; at: number }[] {
161
  const out: { value: string; at: number }[] = [];
162
  for (const i of block) {
163
    const x = lines[i]!;
164
    if (x === `a=${name}`) out.push({ value: "", at: i });
165
    else if (x.startsWith(`a=${name}:`)) out.push({ value: x.slice(name.length + 3), at: i });
166
  }
167
  return out;
168
}
169

170
function parseCandidate(value: string, at: number): Candidate | null {
171
  const f = value.split(/\s+/);
172
  if (f.length < 8 || f[6] !== "typ" || !/^\d+$/.test(f[1]!) || !/^\d+$/.test(f[3]!) || !/^\d+$/.test(f[5]!)) return null;
173
  const raddr = f.indexOf("raddr");
174
  const rport = f.indexOf("rport");
175
  return {
176
    at,
177
    foundation: f[0]!,
178
    component: Number(f[1]),
179
    transport: f[2]!,
180
    priority: Number(f[3]),
181
    address: f[4]!,
182
    port: Number(f[5]),
183
    type: f[7]!,
184
    ...(raddr > 7 && f[raddr + 1] ? { raddr: f[raddr + 1] } : {}),
185
    ...(rport > 7 && f[rport + 1] ? { rport: f[rport + 1] } : {}),
186
  };
187
}
188

189
/**
190
 * RFC 8853's simulcast: `a=simulcast:send h;m;l` names the encodings a sender offers, and each name must be declared by
191
 * an `a=rid:<name> send` line in the same section (RFC 8853 section 5.1; RFC 8851 section 4). A `~` before a name pauses
192
 * that encoding, and `,` separates alternatives for one encoding.
193
 */
194
function checkSimulcast(lines: string[], m: number[], i: number, add: (s: Severity, message: string, at: number) => void): void {
195
  const rids = new Map(attrs(lines, m, "rid").map((r) => {
196
    const [id, dir] = r.value.split(/\s+/);
197
    return [id ?? "", dir ?? ""] as const;
198
  }));
199
  for (const sim of attrs(lines, m, "simulcast")) {
200
    const f = sim.value.trim().split(/\s+/);
201
    for (let k = 0; k + 1 < f.length; k += 2) {
202
      const dir = f[k]!;
203
      if (dir !== "send" && dir !== "recv") {
204
        add("error", `m= section ${i}: a=simulcast direction "${dir}" is not send or recv (RFC 8853 section 5.1)`, sim.at);
205
        continue;
206
      }
207
      for (const name of f[k + 1]!.split(/[;,]/).map((x) => x.replace(/^~/, ""))) {
208
        const declared = rids.get(name);
209
        if (declared === undefined) add("error", `m= section ${i}: a=simulcast names rid ${name}, which no a=rid line in this section declares (RFC 8853 section 5.1)`, sim.at);
210
        else if (declared !== dir) add("error", `m= section ${i}: rid ${name} is declared ${declared} but a=simulcast lists it to ${dir} (RFC 8853 section 5.1)`, sim.at);
211
      }
212
    }
213
  }
214
}
215

216
/**
217
 * Reads one description. Exported for the tests, which check its properties over every sample.
218
 *
219
 * Lines are trimmed and blank ones dropped, so CRLF, LF and a description copied with an RFC's indentation all
220
 * read the same.
221
 */
222
export function explain(text: string, input = "sdp"): Model {
223
  const numbered: { n: number; text: string }[] = [];
224
  text.split(/\r?\n/).forEach((raw, i) => {
225
    const t = raw.trim();
226
    if (t) numbered.push({ n: i + 1, text: t });
227
  });
228
  const lines = numbered.map((l) => l.text);
229
  if (lines[0] !== "v=0") throw new InputError("Not SDP: the first line must be v=0 (RFC 8866 section 5.1)", input);
230

231
  const sessionBlock: number[] = [];
232
  const mediaBlocks: number[][] = [];
233
  lines.forEach((x, i) => {
234
    if (x.startsWith("m=")) mediaBlocks.push([]);
235
    (mediaBlocks.at(-1) ?? sessionBlock).push(i);
236
  });
237
  const problems: Problem[] = [];
238
  const add = (severity: Severity, message: string, at: number) => problems.push({ severity, message, at });
239
  const anyAttr = (block: number[], name: string) => {
240
    const own = attrs(lines, block, name);
241
    return own.length ? own : attrs(lines, sessionBlock, name);
242
  };
243

244
  const liteAt = attrs(lines, sessionBlock, "ice-lite");
245
  const lite = liteAt.length > 0;
246
  for (const m of mediaBlocks) for (const a of attrs(lines, m, "ice-lite")) add("error", "a=ice-lite is session-level only (RFC 8839 section 5.3)", a.at);
247
  const setups = mediaBlocks.flatMap((m) => anyAttr(m, "setup"));
248
  const setup = setups[0]?.value ?? "";
249
  const kind = KIND_OF_SETUP[setup] ?? "unknown";
250

251
  const candidates: Candidate[] = [];
252
  const mids: string[] = [];
253
  const media: string[] = [];
254
  const codecs: string[] = [];
255
  const fingerprints: string[] = [];
256
  let rtcpMux = mediaBlocks.length > 0;
257
  let hasTlsId = false;
258
  mediaBlocks.forEach((m, k) => {
259
    const i = k + 1;
260
    const mAt = m[0]!;
261
    const mline = lines[mAt]!.slice(2).split(/\s+/);
262
    const port = Number(mline[1]);
263
    const proto = mline[2] ?? "";
264
    if (mline.length < 4 || !/^\d+$/.test(mline[1] ?? "")) {
265
      add("error", `m= section ${i}: the m= line is not <media> <port> <proto> <fmt> (RFC 8866 section 5.14)`, mAt);
266
    }
267
    /*
268
     * A data channel is an m=application section of SCTP over DTLS, RFC 8841, and has no RTP: no RTP profile, no
269
     * rtcp-mux, no codecs. Holding it to the audio rules flagged every offer with a data channel as broken.
270
     */
271
    const data = mline[0] === "application";
272
    if (data ? !/^(UDP|TCP)\/DTLS\/SCTP$/.test(proto) : proto !== "UDP/TLS/RTP/SAVPF") {
273
      add("error", `m= section ${i}: proto ${proto}, not ${data ? "UDP/DTLS/SCTP (RFC 8841 section 4.2)" : "UDP/TLS/RTP/SAVPF (RFC 9429 section 5.1.2)"}`, mAt);
274
    }
275
    const bundleOnly = port === 0 && attrs(lines, m, "bundle-only").length > 0;
276
    const cLines = m.filter((j) => lines[j]!.startsWith("c="));
277
    const c = cLines.length ? cLines : sessionBlock.filter((j) => lines[j]!.startsWith("c="));
278
    const cAddr = c.length ? (lines[c[0]!]!.split(/\s+/)[2] ?? "") : "";
279
    if (!c.length) add("error", `m= section ${i}: no c= line (RFC 8866 section 5.7)`, mAt);
280
    const mid = attrs(lines, m, "mid");
281
    mids.push(...mid.map((x) => x.value));
282
    media.push(mid[0]?.value === undefined ? `${mline[0]}, no mid` : `${mline[0]} mid ${mid[0].value}`);
283
    if (!mid.length) add("error", `m= section ${i}: no a=mid (RFC 9429 section 5.2.1)`, mAt);
284

285
    const ufrag = anyAttr(m, "ice-ufrag")[0];
286
    const pwd = anyAttr(m, "ice-pwd")[0];
287
    for (const [name, a, min] of [["ice-ufrag", ufrag, 4], ["ice-pwd", pwd, 22]] as const) {
288
      const len = a?.value.length ?? 0;
289
      if (len < min) add("error", `m= section ${i}: ${name} is ${len} characters, at least ${min} (RFC 8839 section 5.4)`, a?.at ?? mAt);
290
      else if (len > 256) add("error", `m= section ${i}: ${name} is ${len} characters, at most 256 (RFC 8839 section 5.4)`, a?.at ?? mAt);
291
    }
292
    for (const [name, a] of [["ice-ufrag", ufrag], ["ice-pwd", pwd]] as const) {
293
      if (a?.value && !ICE_CHAR.test(a.value)) {
294
        const bad = [...new Set(a.value.replace(/[A-Za-z0-9+/]/g, ""))].sort();
295
        add("warning", `m= section ${i}: ${name} has ${bad.map((b) => `'${b}'`).join(" ")}, not an ice-char (RFC 8839 section 5.1)`, a.at);
296
      }
297
    }
298
    const fp = anyAttr(m, "fingerprint");
299
    fingerprints.push(...fp.map((x) => x.value));
300
    if (!fp.length) add("error", `m= section ${i}: no a=fingerprint, so negotiation fails (RFC 9429 section 5.1.2)`, mAt);
301
    if (anyAttr(m, "tls-id").length) hasTlsId = true;
302
    if (!data && !attrs(lines, m, "rtcp-mux").length) {
303
      rtcpMux = false;
304
      add("error", `m= section ${i}: no a=rtcp-mux (RFC 5761; RFC 8834 section 4.5)`, mAt);
305
    }
306
    for (const r of attrs(lines, m, "rtpmap")) {
307
      const [pt, enc] = r.value.split(/\s+/, 2);
308
      if (!pt || !enc) {
309
        add("error", `a=rtpmap is not <payload type> <encoding>/<clock rate> (RFC 8866 section 6.6)`, r.at);
310
        continue;
311
      }
312
      codecs.push(`${enc} pt ${pt}`);
313
      if (enc.toLowerCase().startsWith("opus/") && enc.toLowerCase() !== "opus/48000/2") {
314
        add("error", `opus must be opus/48000/2 (RFC 7587 section 7), not ${enc}`, r.at);
315
      }
316
    }
317
    const cands: Candidate[] = [];
318
    for (const a of attrs(lines, m, "candidate")) {
319
      const cand = parseCandidate(a.value, a.at);
320
      if (!cand) {
321
        add("error", "a=candidate is not <foundation> <component> <transport> <priority> <address> <port> typ <type> (RFC 8839 section 5.1)", a.at);
322
        continue;
323
      }
324
      cands.push(cand);
325
      const d = decodePriority(cand.priority);
326
      if (TYPE_PREF[d.type] !== cand.type || d.component !== cand.component) {
327
        add(
328
          "note",
329
          `candidate ${cand.foundation} (${cand.type}): priority ${cand.priority} decodes to type preference ${d.type}, local preference ${d.local}, component ${d.component}; not RFC 8445's recommended values for ${cand.type}`,
330
          a.at,
331
        );
332
      }
333
      if (cand.type !== "host" && !(cand.raddr && cand.rport)) add("error", `candidate ${cand.foundation} (${cand.type}) has no raddr/rport (RFC 8839 section 5.1)`, a.at);
334
    }
335
    candidates.push(...cands);
336
    if (cands.length && c.length && !cands.some((x) => x.address === cAddr && x.port === port)) {
337
      add("warning", `m= section ${i}: m= port and c= address match no candidate (RFC 8839 section 4.2.1.2)`, mAt);
338
    }
339
    // A bundle-only section has port 0 on purpose: it is carried on the bundle's transport (RFC 9143 section 6).
340
    if (!cands.length && c.length && !bundleOnly && !(port === 9 && cAddr === "0.0.0.0")) {
341
      add("warning", `m= section ${i}: no candidates, so port 9 and IN IP4 0.0.0.0 expected (RFC 9429 section 5.2.1)`, mAt);
342
    }
343
    checkSimulcast(lines, m, i, add);
344
    const notHost = cands.find((x) => x.type !== "host");
345
    if (lite && notHost) add("error", "ICE-lite agents only use host candidates (RFC 8445 section 2.5)", notHost.at);
346
  });
347
  /*
348
   * ⚠️ Once per description, and a note, not a warning on every section. RFC 8842 sections 5.2 and 5.3 do ask for
349
   * a=tls-id, but libwebrtc (Chrome, Safari), Firefox and aiortc never write one, and every one of them accepts a
350
   * description without it. A warning on every section of every browser's offer is noise that hides real problems.
351
   */
352
  if (mediaBlocks.length && !hasTlsId) {
353
    add("note", "no a=tls-id: RFC 8842 asks for one, but Chrome, Firefox and aiortc never send it, and all of them accept a description without it", mediaBlocks[0]![0]!);
354
  }
355
  const groups = sessionBlock.filter((j) => lines[j]!.startsWith("a=group:BUNDLE"));
356
  for (const g of groups) {
357
    for (const mid of lines[g]!.split(/\s+/).slice(1)) {
358
      if (!mids.includes(mid)) add("error", `BUNDLE names mid ${mid}, which no m= section has (RFC 9143)`, g);
359
    }
360
  }
361
  if (kind === "offer" && lite) add("note", "a=ice-lite in an offer: a JSEP endpoint never sends this (RFC 9429 section 5.2.1)", liteAt[0]!.at);
362

363
  const ctx = { kind, setup, lite };
364
  const described = numbered.map((l) => ({ ...l, phase: phaseOf(l.text), what: describe(l.text, ctx) }));
365
  const counts = Object.fromEntries([...PHASES, "Other"].map((p) => [p, 0])) as Record<Phase, number>;
366
  for (const l of described) counts[l.phase]++;
367
  const hasEnd = mediaBlocks.some((m) => attrs(lines, m, "end-of-candidates").length > 0);
368
  const firstUfrag = mediaBlocks[0] ? anyAttr(mediaBlocks[0], "ice-ufrag")[0] : attrs(lines, sessionBlock, "ice-ufrag")[0];
369
  const bundle = groups.length ? lines[groups[0]!]!.split(/\s+/).slice(1) : null;
370
  return {
371
    lines: described,
372
    problems,
373
    kind,
374
    setup,
375
    lite,
376
    ufrag: firstUfrag?.value ?? "",
377
    candidates,
378
    trickle: hasEnd ? "complete (a=end-of-candidates)" : candidates.length ? "more may trickle" : "none yet",
379
    fingerprints,
380
    media,
381
    codecs,
382
    bundle,
383
    rtcpMux,
384
    counts,
385
  };
386
}
387

388
// ---------------------------------------------------------------------------------------------------------------
389
// What each line sets. One plain sentence each, and only for what the model knows: an attribute it does not know is
390
// said to be unknown rather than given a plausible meaning.
391
// ---------------------------------------------------------------------------------------------------------------
392

393
const UNKNOWN = "Not a line this explainer knows, so it does not guess; an SDP parser ignores attributes it does not understand (RFC 8866 section 5).";
394

395
const EXTENSIONS: Record<string, string> = {
396
  "urn:ietf:params:rtp-hdrext:ssrc-audio-level": "the sender's audio level (RFC 6464), which SRTP authenticates but does not encrypt, so it is readable on the path",
397
  "urn:ietf:params:rtp-hdrext:csrc-audio-level": "the level of each voice a mixer mixed (RFC 6465), authenticated by SRTP but not encrypted",
398
  "urn:ietf:params:rtp-hdrext:sdes:mid": "the section's mid, so a receiver can tell which m= section a packet belongs to on a bundled port (RFC 9143)",
399
  "urn:ietf:params:rtp-hdrext:sdes:rtp-stream-id": "the RtpStreamId, which names one encoding of a simulcast source (RFC 8852)",
400
  "urn:ietf:params:rtp-hdrext:sdes:repaired-rtp-stream-id": "the RtpStreamId of the stream a repair stream repairs (RFC 8852)",
401
  "urn:ietf:params:rtp-hdrext:toffset": "the transmission time offset, how late a packet left after its timestamp (RFC 5450)",
402
};
403

404
const CODECS: Record<string, string> = {
405
  pcmu: "G.711 mu-law",
406
  pcma: "G.711 A-law",
407
  g722: "G.722",
408
  "telephone-event": "DTMF digits and other telephony events, sent as events rather than sound (RFC 4733)",
409
  cn: "comfort noise (RFC 3389)",
410
  red: "redundant audio (RFC 2198)",
411
  rtx: "retransmission of lost packets (RFC 4588)",
412
  ulpfec: "forward error correction (RFC 5109)",
413
  vp8: "VP8 video (RFC 7741)",
414
  vp9: "VP9 video",
415
  h264: "H.264 video (RFC 6184)",
416
  h265: "H.265 video (RFC 7798)",
417
  av1: "AV1 video",
418
};
419

420
const FMTP: Record<string, (v: string) => string> = {
421
  minptime: (v) => `minptime=${v}, at least ${v} ms of audio a packet, a parameter RFC 7587 does not define`,
422
  useinbandfec: (v) => (v === "1" ? "useinbandfec=1, the decoder can use Opus's in-band FEC (RFC 7587)" : `useinbandfec=${v} (RFC 7587)`),
423
  usedtx: (v) => `usedtx=${v}, whether the decoder prefers silence to be sent as DTX (RFC 7587)`,
424
  stereo: (v) => `stereo=${v}, ${v === "1" ? "the decoder prefers stereo" : "the decoder prefers mono"} (RFC 7587)`,
425
  "sprop-stereo": (v) => `sprop-stereo=${v}, whether the sender is likely to send stereo (RFC 7587)`,
426
  cbr: (v) => `cbr=${v}, whether the decoder prefers a constant bitrate (RFC 7587)`,
427
  maxaveragebitrate: (v) => `maxaveragebitrate=${v}, the most the receiver wants on average, in b/s (RFC 7587)`,
428
  maxplaybackrate: (v) => `maxplaybackrate=${v}, a hint at the receiver's highest output sample rate (RFC 7587)`,
429
  apt: (v) => `apt=${v}, it retransmits payload type ${v} (RFC 4588)`,
430
  "packetization-mode": (v) => `packetization-mode=${v} (RFC 6184)`,
431
  "profile-level-id": (v) => `profile-level-id=${v} (RFC 6184)`,
432
  "level-asymmetry-allowed": (v) => `level-asymmetry-allowed=${v} (RFC 6184)`,
433
};
434

435
const FEEDBACK: Record<string, string> = {
436
  nack: "generic NACK, asking for lost packets again (RFC 4585)",
437
  "nack pli": "picture loss indication, asking for a new picture (RFC 4585)",
438
  "nack sli": "slice loss indication (RFC 4585)",
439
  "nack rpsi": "reference picture selection indication (RFC 4585)",
440
  "ccm fir": "full intra request, asking for a key frame (RFC 5104)",
441
  "ccm tmmbr": "a temporary maximum bitrate request (RFC 5104)",
442
  "transport-cc": "transport-wide congestion control feedback, from an IETF draft rather than an RFC",
443
  "goog-remb": "Google's REMB bandwidth estimate, from an IETF draft rather than an RFC",
444
};
445

446
const DIRECTION: Record<string, string> = {
447
  sendrecv: "This side sends and receives media in this section (RFC 8866 section 6.7).",
448
  sendonly: "This side only sends media in this section (RFC 8866 section 6.7).",
449
  recvonly: "This side only receives media in this section (RFC 8866 section 6.7).",
450
  inactive: "This side neither sends nor receives media in this section (RFC 8866 section 6.7).",
451
};
452

453
const CAND_NAME: Record<string, string> = { host: "Host", srflx: "Server-reflexive", prflx: "Peer-reflexive", relay: "Relayed" };
454

455
function describeCandidate(value: string): string {
456
  const c = parseCandidate(value, 0);
457
  if (!c) return "A candidate line that does not parse, so its address cannot be read (RFC 8839 section 5.1).";
458
  const d = decodePriority(c.priority);
459
  const comp = c.component === 1 ? "for RTP" : c.component === 2 ? "for RTCP" : `for component ${c.component}`;
460
  const related = c.raddr && c.rport ? `${c.raddr}:${c.rport}` : "";
461
  const how =
462
    c.type === "srflx" && related
463
      ? `, the NAT's mapping of ${related}`
464
      : c.type === "relay"
465
        ? `, an address on a TURN server${related ? ` that saw this side as ${related}` : ""}`
466
        : c.type === "prflx"
467
          ? ", learned from a connectivity check"
468
          : "";
469
  return `${CAND_NAME[c.type] ?? `A "${c.type}"`} candidate ${c.address}:${c.port} over ${c.transport.toUpperCase()} ${comp}${how}; priority ${c.priority} is type preference ${d.type}, local preference ${d.local}, component ${d.component} (RFC 8445 section 5.1.2).`;
470
}
471

472
function describe(line: string, ctx: { kind: Model["kind"]; setup: string; lite: boolean }): string {
473
  const type = line.slice(0, 2);
474
  const value = line.slice(2);
475
  const f = value.split(/\s+/);
476
  switch (type) {
477
    case "v=":
478
      return "The SDP version; 0 is the only one there is (RFC 8866 section 5.1).";
479
    case "o=": {
480
      const addr = f[5] === "0.0.0.0" ? "; its address, 0.0.0.0, is a placeholder so no local IP leaks (RFC 9429 section 5.2.1)" : `, from ${f[5]}`;
481
      return `The origin: session id ${f[1]} and version ${f[2]}, which goes up whenever the description changes (RFC 8866 section 5.2)${addr}.`;
482
    }
483
    case "s=":
484
      return value === "-" || value === "" ? "The session name; a dash means it has none (RFC 8866 section 5.3)." : `The session name, "${value}" (RFC 8866 section 5.3).`;
485
    case "t=":
486
      return value === "0 0" ? "When the session is active; 0 0 means it is unbounded and permanent (RFC 8866 section 5.9)." : `When the session is active: ${value}, as NTP seconds (RFC 8866 section 5.9).`;
487
    case "c=":
488
      return f[2] === "0.0.0.0"
489
        ? "The connection address, 0.0.0.0: a placeholder, since no candidate is known yet (RFC 9429 section 5.2.1)."
490
        : `The connection address, ${f[2]}, the default candidate's; an ICE agent uses the candidates instead (RFC 8839 section 4.2.1.2).`;
491
    case "m=": {
492
      const port = f[1] === "9" ? "port 9, the placeholder before any candidate is known" : f[1] === "0" ? "port 0, so it is rejected, or bundle-only and carried on another section's port" : `port ${f[1]}`;
493
      const proto =
494
        f[2] === "UDP/TLS/RTP/SAVPF"
495
          ? "UDP/TLS/RTP/SAVPF, which is RTP with feedback, protected by SRTP whose keys come from DTLS, over UDP"
496
          : f[2] === "UDP/DTLS/SCTP"
497
            ? "UDP/DTLS/SCTP, a data channel: SCTP messages inside the DTLS connection, over UDP"
498
            : `profile ${f[2]}`;
499
      if (f[3] === "webrtc-datachannel") return `Starts a data channel section on ${port}: SCTP messages inside the DTLS connection, over ${f[2]?.startsWith("TCP") ? "TCP" : "UDP"} (RFC 8841 section 4.2).`;
500
      const fmts = f.slice(3);
501
      return `Starts ${/^[aeiou]/.test(f[0] ?? "") ? "an" : "a"} ${f[0]} section on ${port}, ${proto}, offering payload type${fmts.length === 1 ? "" : "s"} ${fmts.join(", ")} (RFC 8866 section 5.14).`;
502
    }
503
    case "b=":
504
      return `A bandwidth limit, ${value}; none of the six phases owns it (RFC 8866 section 5.8).`;
505
    case "i=":
506
      return "A free-text title (RFC 8866 section 5.4); nothing in the call reads it.";
507
  }
508
  if (type !== "a=") return UNKNOWN;
509
  const colon = value.indexOf(":");
510
  const name = colon < 0 ? value : value.slice(0, colon);
511
  const v = colon < 0 ? "" : value.slice(colon + 1);
512
  const vf = v.split(/\s+/);
513
  switch (name) {
514
    case "group":
515
      if (vf[0] === "BUNDLE")
516
        return `Bundles the sections with mid ${vf.slice(1).join(", ")} onto one transport, so one ICE path and one DTLS handshake serve them all (RFC 9143).`;
517
      if (vf[0] === "LS") return `Lip sync: the sections with mid ${vf.slice(1).join(", ")} are played in sync (RFC 5888).`;
518
      return `Groups the sections with mid ${vf.slice(1).join(", ")} under the semantics "${vf[0]}" (RFC 5888).`;
519
    case "ice-options": {
520
      const known: Record<string, string> = {
521
        trickle: "trickle, so candidates may follow the description (RFC 8840)",
522
        ice2: "ice2, the ICE of RFC 8445 rather than the older RFC 5245 (RFC 8445 section 10)",
523
      };
524
      return `ICE options: ${vf.map((o) => known[o] ?? `${o}, which this explainer does not know`).join("; ")}.`;
525
    }
526
    case "ice-ufrag":
527
      return `The ICE username fragment, ${v}; checks sent to this side carry it first in their STUN USERNAME (RFC 8445 section 7.2.2).`;
528
    case "ice-pwd":
529
      return `The ICE password, ${v.length} characters; checks sent to this side are signed with it, in MESSAGE-INTEGRITY (RFC 8445 section 7.2.2).`;
530
    case "ice-lite":
531
      return "This side is ICE-lite: it has only host candidates and answers checks without sending any, so a full agent on the other side controls (RFC 8445 sections 2.5 and 6.1.1).";
532
    case "candidate":
533
      return describeCandidate(v);
534
    case "end-of-candidates":
535
      return "No more candidates will trickle for this section (RFC 8840 section 8).";
536
    case "fingerprint":
537
      return `The ${vf[0]} hash of the certificate this side will present in the DTLS handshake, which the other side must match or end the call; a hash, not a key (RFC 5763 section 5).`;
538
    case "setup":
539
      if (v === "actpass") return "DTLS role: either; the answerer picks, and SHOULD pick active, so the offerer usually waits for a ClientHello (RFC 9429 section 5.3.1).";
540
      if (v === "active") return "DTLS role: client, so this side sends the ClientHello (RFC 5763 section 5).";
541
      if (v === "passive") return "DTLS role: server, so this side waits for the other side's ClientHello (RFC 5763 section 5).";
542
      return `DTLS role "${v}", which is not one of actpass, active and passive (RFC 5763 section 5).`;
543
    case "tls-id":
544
      return "This side's half of the name of the DTLS association; the two sides' tls-id values together identify it, and a new value means a new handshake (RFC 8842 section 4).";
545
    case "mid":
546
      return `Names this section "${v}"; BUNDLE lists it, and the mid header extension stamps it on packets so a receiver can tell sections apart on one port (RFC 9143).`;
547
    case "msid":
548
      return vf[1]
549
        ? `Ties this section to media stream ${vf[0]}, track ${vf[1]}, the ids the other side's WebRTC API sees (RFC 8830).`
550
        : `Ties this section to media stream ${vf[0]}, the id the other side's WebRTC API sees (RFC 8830).`;
551
    case "msid-semantic":
552
      return "Announces WebRTC media stream ids; it comes from early drafts of msid, and RFC 8830 removed that mechanism, so nothing needs it.";
553
    case "ssrc": {
554
      const [ssrc, ...rest] = vf;
555
      const attr = rest.join(" ");
556
      const ai = attr.indexOf(":");
557
      const aname = ai < 0 ? attr : attr.slice(0, ai);
558
      const aval = ai < 0 ? "" : attr.slice(ai + 1);
559
      return aname === "cname"
560
        ? `SSRC ${ssrc}, the id in every RTP packet of this stream, with canonical name ${aval} (RFC 5576).`
561
        : `SSRC ${ssrc}'s "${aname}"${aval ? ` is ${aval}` : ""} (RFC 5576).`;
562
    }
563
    case "rid": {
564
      const [id, dir, ...rest] = vf;
565
      const limits = rest.join(" ");
566
      return `Declares rid ${id}, one encoding this side will ${dir === "recv" ? "receive" : "send"}${limits ? `, limited to ${limits}` : ""}; a=simulcast lists these, and each packet names its encoding in the rtp-stream-id header extension (RFC 8851).`;
567
    }
568
    case "simulcast": {
569
      const pieces: string[] = [];
570
      for (let k = 0; k + 1 < vf.length; k += 2) {
571
        const names = vf[k + 1]!.split(";");
572
        const paused = names.filter((x) => x.startsWith("~")).map((x) => x.slice(1));
573
        pieces.push(`${vf[k] === "recv" ? "receive" : "send"} ${names.length} encoding${names.length === 1 ? "" : "s"}, ${names.map((x) => x.replace(/^~/, "")).join(", ")}${paused.length ? `, with ${paused.join(", ")} paused for now` : ""}`);
574
      }
575
      return `Simulcast: this side will ${pieces.join(", and ")}, each one a separate copy of the same source at its own resolution or bitrate, so a server can forward each viewer the one that fits (RFC 8853).`;
576
    }
577
    case "bundle-only":
578
      return "This section has no transport of its own: it only works if the other side bundles it, which is why its port is 0 (RFC 9143 section 6).";
579
    case "sctp-port":
580
      return `The data channel's SCTP port, ${v}, inside the DTLS connection, not a UDP port (RFC 8841 section 5).`;
581
    case "max-message-size":
582
      return `The largest data channel message this side can take, ${v} bytes${v === "0" ? ", where 0 means no limit" : ""} (RFC 8841 section 6).`;
583
    case "ssrc-group":
584
      if (vf[0] === "SIM") return `Legacy simulcast: SSRCs ${vf.slice(1).join(", ")} are the same source at different qualities. Chrome's older way of saying what a=simulcast and a=rid now say, a semantics no RFC registers (RFC 8853 replaces it).`;
585
      return vf[0] === "FID"
586
        ? `Pairs SSRC ${vf[1]} with ${vf.slice(2).join(", ")}, its retransmission stream (RFC 5576, RFC 4588).`
587
        : `Groups SSRCs ${vf.slice(1).join(", ")} under the semantics "${vf[0]}" (RFC 5576).`;
588
    case "extmap": {
589
      const id = vf[0] ?? "";
590
      const uri = vf[1] ?? "";
591
      const known = EXTENSIONS[uri];
592
      return known
593
        ? `Header extension ${id} (RFC 8285) carries ${known}.`
594
        : `Maps header extension ${id} to ${uri}, which this explainer does not know (RFC 8285).`;
595
    }
596
    case "extmap-allow-mixed":
597
      return "One-byte and two-byte header extensions may be mixed in one stream (RFC 8285 section 6).";
598
    case "sendrecv":
599
    case "sendonly":
600
    case "recvonly":
601
    case "inactive":
602
      return DIRECTION[name]!;
603
    case "rtpmap": {
604
      const [pt, enc] = vf;
605
      if (!pt || !enc) return "An rtpmap that does not parse (RFC 8866 section 6.6).";
606
      const [codec, rate, channels] = enc.split("/");
607
      const lower = (codec ?? "").toLowerCase();
608
      if (lower === "opus")
609
        return `Payload type ${pt} is Opus at a ${rate} Hz RTP clock; the /${channels ?? ""} is required for every Opus session and does not mean stereo (RFC 7587 section 7).`;
610
      const what = CODECS[lower] ?? `${codec}, a codec this explainer does not describe (RFC 8866 section 6.6)`;
611
      return `Payload type ${pt} is ${what}, with an RTP clock of ${rate} Hz${channels ? ` and ${channels} channels` : ""}.`;
612
    }
613
    case "fmtp": {
614
      const [pt, ...rest] = vf;
615
      const params = rest.join(" ");
616
      if (/^\d+(-\d+)?(,\d+(-\d+)?)*$/.test(params))
617
        return `Payload type ${pt} carries events ${params}${params === "0-15" ? ", the 16 DTMF keys" : ""} (RFC 4733).`;
618
      const parts = params
619
        .split(";")
620
        .map((p) => p.trim())
621
        .filter(Boolean)
622
        .map((p) => {
623
          const [k, val = ""] = p.split("=");
624
          return FMTP[k ?? ""]?.(val) ?? `${p}, which this explainer does not describe`;
625
        });
626
      return `Format parameters for payload type ${pt}: ${parts.join("; ")}.`;
627
    }
628
    case "ptime":
629
      return `${v} ms of media in each packet (RFC 8866 section 6.4).`;
630
    case "maxptime":
631
      return `At most ${v} ms of media in each packet (RFC 8866 section 6.5).`;
632
    case "rtcp":
633
      return vf[0] === "9" && vf[3] === "0.0.0.0"
634
        ? "Where RTCP would go without rtcp-mux: port 9 and 0.0.0.0, placeholders, since no candidate is known (RFC 3605; RFC 9429 section 5.2.1)."
635
        : `Where RTCP goes if the other side does not multiplex it: port ${vf[0]}${vf[3] ? ` at ${vf[3]}` : ""} (RFC 3605).`;
636
    case "rtcp-mux":
637
      return ctx.kind === "answer"
638
        ? "Agrees to send RTCP on the RTP port, so one ICE path and one NAT binding carry both (RFC 5761)."
639
        : "Asks to send RTCP on the RTP port, so one ICE path and one NAT binding carry both (RFC 5761).";
640
    case "rtcp-mux-only":
641
      return "This side will only send RTCP on the RTP port, with no separate RTCP port to fall back to (RFC 8858).";
642
    case "rtcp-rsize":
643
      return "This side can use reduced-size RTCP, packets that need not be full compound reports (RFC 5506).";
644
    case "rtcp-fb": {
645
      const [pt, ...rest] = vf;
646
      const fb = rest.join(" ");
647
      const what = FEEDBACK[fb] || `${fb}, a feedback type this explainer does not describe`;
648
      return `Feedback for ${pt === "*" ? "every payload type" : `payload type ${pt}`}: ${what}.`;
649
    }
650
  }
651
  return UNKNOWN;
652
}
653

654
// ---------------------------------------------------------------------------------------------------------------
655
// Output.
656
// ---------------------------------------------------------------------------------------------------------------
657

658
const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
659

660
function problemCounts(problems: Problem[]) {
661
  const n = (s: Severity) => problems.filter((p) => p.severity === s).length;
662
  return { errors: n("error"), warnings: n("warning"), notes: n("note") };
663
}
664

665
/** "an offer", "an answer", as the start of a sentence or after a label. */
666
const kindName = (m: Model) => (m.kind === "unknown" ? "Neither offer nor answer" : m.kind === "offer" ? "Offer" : "Answer");
667

668
/**
669
 * What this SDP sets up, as a spec sheet: the path, the keys and the media, under their own headings. No tone: a
670
 * description that parses is not good news, and a problem is toned on its own row in the findings.
671
 */
672
function summary(m: Model, problems: Problem[]): Field[] {
673
  const byType = new Map<string, number>();
674
  for (const c of m.candidates) byType.set(c.type, (byType.get(c.type) ?? 0) + 1);
675
  const types = [...byType].sort(([a], [b]) => (a < b ? -1 : 1));
676
  const algs = [...new Set(m.fingerprints.map((f) => f.split(/\s+/)[0]!))].sort();
677
  const p = problemCounts(problems);
678
  const found = [p.errors ? plural(p.errors, "error") : "", p.warnings ? plural(p.warnings, "warning") : ""].filter(Boolean);
679
  const verdict = found.length
680
    ? `${found.join(" and ")} found by these checks${p.errors ? ": a WebRTC stack may refuse it" : ""}.`
681
    : `No problems found by these checks${p.notes ? `, and ${plural(p.notes, "note")}` : ""}.`;
682
  return [
683
    {
684
      label: "This SDP",
685
      value: `${kindName(m)}${m.setup ? ` (a=setup:${m.setup})` : ""}, ${plural(m.media.length, "media section")}`,
686
      note: verdict,
687
    },
688
    { group: "Transport", label: "ICE", value: `${m.lite ? "lite" : "full"}, ufrag ${m.ufrag}` },
689
    types.length
690
      ? { group: "Transport", label: "Candidates", value: types.map(([t, n]) => `${n} ${t}`).join(", "), note: m.trickle }
691
      : { group: "Transport", label: "Candidates", value: m.trickle },
692
    { group: "Transport", label: "BUNDLE", value: m.bundle?.length ? `mid ${m.bundle.join(" ")}` : "none" },
693
    { group: "Security", label: "DTLS role", value: ROLE[m.setup] ?? "not stated" },
694
    {
695
      group: "Security",
696
      label: "Fingerprints",
697
      value: m.fingerprints.length ? algs.join(", ") : "none",
698
      ...(m.fingerprints.length > 1 ? { note: plural(m.fingerprints.length, "fingerprint") } : {}),
699
    },
700
    { group: "Media", label: "Sections", value: m.media.join("; ") || "none" },
701
    { group: "Media", label: "Codecs", value: m.codecs.join(", ") || "none", note: plural(m.codecs.length, "payload type") },
702
    { group: "Media", label: "rtcp-mux", value: m.rtcpMux ? "yes" : "no" },
703
  ];
704
}
705

706
/** How the reading was done: what decides offer or answer, what was counted, and what the SDP cannot show. */
707
function method(sides: Model[]): Field[] {
708
  const lines = (m: Model) =>
709
    [...PHASES, "Other" as const]
710
      .filter((ph) => m.counts[ph] > 0)
711
      .map((ph) => `${SHORT[ph]} ${m.counts[ph]}`)
712
      .join(", ");
713
  return [
714
    { label: "Offer or answer", value: "from a=setup", note: "actpass is an offer, active or passive an answer" },
715
    ...sides.map((m, i) => ({ label: sides.length > 1 ? (i === 0 ? "Lines, this SDP" : "Lines, the other side") : "Lines", value: String(m.lines.length), note: lines(m) })),
716
    { label: "Severity", value: "error, warning, note", note: "an error is a MUST broken, a warning a SHOULD or a value real stacks accept anyway, a note a decoded oddity" },
717
    { label: "Fingerprints", value: "present or not", note: "only the DTLS handshake can check one against the certificate" },
718
    { label: "SRTP", value: "no line of its own", note: "its keys come from DTLS; the only trace is the profile UDP/TLS/RTP/SAVPF and the fingerprint" },
719
  ];
720
}
721

722
/** The pair readout: what two descriptions settle between them, by the rules in RFC 8445, RFC 5763 and RFC 9429. */
723
function pair(a: Model, b: Model): Field[] {
724
  const group = "Pair";
725
  const out: Field[] = [];
726
  const offerer = a.kind === "offer" && b.kind === "answer" ? "a" : b.kind === "offer" && a.kind === "answer" ? "b" : null;
727
  const who = (s: "a" | "b") => (s === "a" ? "this side" : "the other side");
728
  out.push(
729
    offerer === "a"
730
      ? { group, label: "Offer and answer", value: "this SDP offers, the other answers" }
731
      : offerer === "b"
732
        ? { group, label: "Offer and answer", value: "the other side offers, this SDP answers" }
733
        : a.kind === "offer" && b.kind === "offer"
734
          ? { group, label: "Offer and answer", value: "both are offers (a=setup:actpass twice)", tone: "bad", note: "an answer must say active or passive (RFC 9429 section 5.3.1)" }
735
          : a.kind === "answer" && b.kind === "answer"
736
            ? { group, label: "Offer and answer", value: "both are answers", tone: "bad" }
737
            : { group, label: "Offer and answer", value: "not settled: a side has no a=setup", tone: "bad" },
738
  );
739

740
  if (a.lite !== b.lite) {
741
    const full = a.lite ? "b" : "a";
742
    out.push({ group, label: "ICE roles", value: `${who(full)} controls`, note: "full against lite: the full agent controls (RFC 8445 section 6.1.1)" });
743
  } else {
744
    const both = a.lite ? "both lite" : "both full";
745
    out.push(
746
      offerer
747
        ? { group, label: "ICE roles", value: `${who(offerer)} controls`, note: `${both}: the offerer controls (RFC 8445 section 6.1.1)` }
748
        : { group, label: "ICE roles", value: "not settled", note: `${both}: the offerer controls, and neither is the one offer (RFC 8445 section 6.1.1)`, tone: "bad" },
749
    );
750
  }
751

752
  const sa = a.setup;
753
  const sb = b.setup;
754
  let hello: Field;
755
  if (sa === "actpass" && sb === "actpass") {
756
    hello = { group, label: "ClientHello sent by", value: "not settled: both are offers (actpass twice), so no DTLS role can be settled", tone: "bad" };
757
  } else if (sb === "active" && (sa === "actpass" || sa === "passive")) {
758
    hello = { group, label: "ClientHello sent by", value: "the other side (a=setup:active)" };
759
  } else if (sa === "active" && (sb === "actpass" || sb === "passive")) {
760
    hello = { group, label: "ClientHello sent by", value: "this side (a=setup:active)" };
761
  } else if (sb === "passive" && sa === "actpass") {
762
    hello = { group, label: "ClientHello sent by", value: "this side (actpass against passive)" };
763
  } else if (sa === "passive" && sb === "actpass") {
764
    hello = { group, label: "ClientHello sent by", value: "the other side (actpass against passive)" };
765
  } else {
766
    hello = { group, label: "ClientHello sent by", value: `not settled: a=setup:${sa || "none"} against a=setup:${sb || "none"}`, tone: "bad" };
767
  }
768
  hello.note = "the side whose a=setup resolves to active (RFC 5763 section 5)";
769
  out.push(hello);
770

771
  const theirs = new Set(b.codecs.map((c) => c.toLowerCase()));
772
  const agreed = a.codecs.filter((c) => theirs.has(c.toLowerCase()));
773
  out.push(
774
    agreed.length
775
      ? { group, label: "Codec agreed", value: agreed.join(", "), note: "payload type and encoding both list" }
776
      : { group, label: "Codec agreed", value: "none in common", note: "no payload type with the same encoding on both sides", tone: "bad" },
777
  );
778

779
  const ba = a.bundle?.join(" ");
780
  const bb = b.bundle?.join(" ");
781
  out.push(
782
    ba !== undefined && ba === bb
783
      ? { group, label: "BUNDLE", value: `mid ${ba}, on both` }
784
      : ba === undefined && bb === undefined
785
        ? { group, label: "BUNDLE", value: "neither side bundles", tone: "warn" }
786
        : { group, label: "BUNDLE", value: `this side ${ba ?? "none"}, the other ${bb ?? "none"}`, note: "the same mids should be grouped on both sides (RFC 9143)", tone: "warn" },
787
  );
788

789
  out.push(
790
    a.rtcpMux && b.rtcpMux
791
      ? { group, label: "rtcp-mux", value: "on both" }
792
      : { group, label: "rtcp-mux", value: `missing on ${a.rtcpMux ? "the other side" : b.rtcpMux ? "this side" : "both"}`, note: "RFC 8834 section 4.5", tone: "bad" },
793
  );
794

795
  const fa = new Set(a.fingerprints.map((f) => f.toUpperCase()));
796
  const shared = b.fingerprints.some((f) => fa.has(f.toUpperCase()));
797
  out.push(
798
    !a.fingerprints.length || !b.fingerprints.length
799
      ? { group, label: "Fingerprints", value: `missing on ${a.fingerprints.length ? "the other side" : b.fingerprints.length ? "this side" : "both"}`, tone: "bad" }
800
      : shared
801
        ? { group, label: "Fingerprints", value: "present on both, the same certificate", note: "two peers with one certificate, or one SDP pasted twice", tone: "warn" }
802
        : { group, label: "Fingerprints", value: "present on both, different certificates", note: "only the DTLS handshake can check either against its certificate" },
803
  );
804
  return out;
805
}
806

807
/** Every line, whole: a cut line hides the attribute value a reader came to check. */
808
function lineTable(m: Model, onlyProblems: boolean, caption: string): Output | null {
809
  const flagged = new Set(m.problems.map((p) => p.at));
810
  const rows: Cell[][] = [];
811
  m.lines.forEach((l, i) => {
812
    if (onlyProblems && !flagged.has(i)) return;
813
    rows.push([{ text: String(l.n), mono: true, tone: "muted" }, { text: l.text, mono: true }, l.what, l.phase]);
814
  });
815
  if (!rows.length) return null;
816
  return {
817
    kind: "table",
818
    role: "decoded",
819
    caption,
820
    columns: [
821
      { label: "#", align: "end", mono: true, wrap: "none", rowHeader: true },
822
      { label: "Line", mono: true, wrap: "prose" },
823
      { label: "What it sets", wrap: "prose" },
824
      { label: "Read by", wrap: "prose" },
825
    ],
826
    rows,
827
  };
828
}
829

830
const SEVERITY_TONE: Record<Severity, TextTone> = { error: "bad", warning: "warn", note: "muted" };
831
const SEVERITY_ORDER: Severity[] = ["error", "warning", "note"];
832

833
/**
834
 * Whether two descriptions settle a call, as the first field of the pair readout. A failed rule between them, or
835
 * an error on either side, means they do not, and that is the one place a tone is earned without a reader's limit.
836
 */
837
function pairVerdict(pairFields: Field[], problems: Problem[]): Field {
838
  const p = problemCounts(problems);
839
  const reasons = pairFields.filter((f) => f.tone === "bad").map((f) => UNSETTLED[f.label] ?? `${f.label} is not agreed`);
840
  if (p.errors) reasons.push(`${plural(p.errors, "error")} break${p.errors === 1 ? "s" : ""} a rule a WebRTC stack enforces`);
841
  if (reasons.length) {
842
    const joined = reasons.length === 1 ? reasons[0]! : `${reasons.slice(0, -1).join(", ")} and ${reasons.at(-1)}`;
843
    return { label: "These two", value: "do not settle a call", note: `${joined[0]!.toUpperCase()}${joined.slice(1)}.`, tone: "bad" };
844
  }
845
  const ice = pairFields.find((f) => f.label === "ICE roles")?.value ?? "";
846
  const hello = pairFields.find((f) => f.label === "ClientHello sent by")?.value.replace(/ \(.*\)$/, "") ?? "";
847
  const [enc = "", , pt = ""] = (pairFields.find((f) => f.label === "Codec agreed")?.value.split(",")[0] ?? "").split(" ");
848
  const name = enc.split("/")[0] ?? "";
849
  const codec = `${name.toLowerCase() === "opus" ? "Opus" : name} as payload type ${pt}`;
850
  const said = `${ice[0]!.toUpperCase()}${ice.slice(1)} ICE, ${hello} sends the DTLS ClientHello, and both list ${codec}.`;
851
  return { label: "These two", value: "settle a call", note: p.warnings ? `${said} ${plural(p.warnings, "warning")} worth a look.` : said };
852
}
853

854
/** What each unsettled pair field means for the call, in a clause the verdict can join. */
855
const UNSETTLED: Record<string, string> = {
856
  "Offer and answer": "they are not one offer and one answer",
857
  "ICE roles": "neither side is known to control ICE",
858
  "ClientHello sent by": "no side is set to start the DTLS handshake",
859
  "Codec agreed": "they list no codec in common",
860
  "rtcp-mux": "rtcp-mux is missing on a side",
861
  Fingerprints: "a side has no certificate fingerprint",
862
};
863

864
export default {
865
  run(input: Input) {
866
    try {
867
      const a = explain(input.sdp ?? "", "sdp");
868
      const b = (input.other ?? "").trim() ? explain(input.other, "other") : null;
869
      const onlyProblems = input.show === "problems";
870
      const sides = b ? [a, b] : [a];
871

872
      // Worst first, then in line order, since that is the order to fix them in.
873
      const problems = (b ? ([[a, "this SDP, "], [b, "the other side, "]] as const) : ([[a, ""]] as const)).flatMap(([m, where]) =>
874
        m.problems.map((p) => ({
875
          p,
876
          n: m.lines[p.at]!.n,
877
          row: [{ text: p.severity, tone: SEVERITY_TONE[p.severity] }, { text: `${where}line ${m.lines[p.at]!.n}`, mono: true }, p.message] as Cell[],
878
        })),
879
      );
880
      const problemRows = problems.sort((x, y) => SEVERITY_ORDER.indexOf(x.p.severity) - SEVERITY_ORDER.indexOf(y.p.severity) || x.n - y.n).map((x) => x.row);
881
      const all = sides.flatMap((m) => m.problems);
882
      const pairFields = b ? pair(a, b) : [];
883

884
      /*
885
       * The answer in the form the input asks for. Two descriptions lead with what they settle between them; one
886
       * leads with what it sets up, unless it breaks a rule, when the problems lead, located by line. A table of
887
       * notes only is something to know, not to fix, so it follows the summary. Each part has an id.
888
       */
889
      const fixable = all.some((p) => p.severity !== "note");
890
      const findings: Output | null = problemRows.length
891
        ? {
892
            kind: "table",
893
            role: "findings",
894
            id: "problems",
895
            caption: fixable ? "What to fix, worst first" : "Worth knowing, nothing to fix",
896
            columns: [
897
              { label: "Severity", wrap: "none" },
898
              { label: "Where", wrap: "none" },
899
              { label: "Problem", wrap: "prose" },
900
            ],
901
            rows: problemRows,
902
          }
903
        : null;
904
      const parts: Output[] = [];
905
      if (b) parts.push({ kind: "fields", role: "answer", id: "pair", fields: [pairVerdict(pairFields, all), ...pairFields] });
906
      if (findings && fixable) parts.push(findings);
907
      parts.push({ kind: "fields", role: b ? "decoded" : "answer", id: "summary", fields: summary(a, b ? a.problems : all) });
908
      if (findings && !fixable) parts.push(findings);
909
      const what = onlyProblems ? "The lines with a problem" : "Every line";
910
      const tableA = lineTable(a, onlyProblems, `${what} of this SDP, and the phase that reads it`);
911
      if (tableA) parts.push(tableA);
912
      const tableB = b ? lineTable(b, onlyProblems, `${what} of the other side's SDP`) : null;
913
      if (tableB) parts.push(tableB);
914
      parts.push({ kind: "fields", role: "method", id: "method", fields: method(sides) });
915
      return { kind: "group", parts };
916
    } catch (error) {
917
      if (error instanceof InputError) return { kind: "error", message: error.message, input: error.input };
918
      throw error;
919
    }
920
  },
921
} satisfies Tool<Input>;