1
/**
2
 * Jitter, loss and the ways a receiver covers for them, over a few seconds of one voice stream.
3
 *
4
 * A frame leaves every 20 ms and must play at a fixed time: when it was sent, plus the one-way delay, plus the
5
 * jitter buffer. Each packet's trip gets a random extra delay on top of the fixed one, so some arrive after
6
 * their time and are as good as lost. Some are lost outright, at random or in bursts. What the listener hears
7
 * for each frame is one of three things:
8
 *
9
 *  - **played**: the packet itself arrived in time;
10
 *  - **recovered**: it did not, but a later packet carrying a copy of it did, in time for this frame's slot;
11
 *  - **concealed**: neither, so the decoder makes up 20 ms from the audio before.
12
 *
13
 * The copy comes from one of two schemes. **Opus in-band FEC** (RFC 7587 section 3.3) puts a lower-bitrate
14
 * re-encoding of frame n-1 inside packet n, so it reaches back one packet. **RED** (RFC 2198) carries whole
15
 * earlier frames as redundant blocks, here one or two of them, so it can bridge a burst of two.
16
 *
17
 * ⚠️ What it assumes, so the numbers are read as a model and not a measurement:
18
 *
19
 *  - every packet carries an FEC copy. Real Opus only re-encodes frames it judges important, so this is the
20
 *    best FEC can do, not what it does;
21
 *  - the extra delay per packet is exponential with the mean given, independent from packet to packet. Real
22
 *    queues correlate, which makes late packets bunch together, much like bursts of loss;
23
 *  - bursts follow a two-state Gilbert model: once in the lossy state, each next packet stays lost with
24
 *    probability 1 - 1/burst, so bursts average the length given;
25
 *  - the buffer is fixed. An adaptive one, as libwebrtc's is, would move it with the jitter it measures.
26
 *
27
 * Seeded, so the same inputs always give the same run, and a different seed is a different few seconds. That is
28
 * also what makes the advice honest: every change it suggests is the same minute of network replayed with that change.
29
 */
30
import type { Field, Output, Series, Tool } from "@toolbench/sdk";
31

32
type Input = { delay: number; jitter: number; buffer: number; loss: number; burst: number; protection: string; packets: number; seed: number };
33

34
class InputError extends Error {
35
  readonly input: string;
36

37
  constructor(message: string, input: string) {
38
    super(message);
39
    this.name = "InputError";
40
    this.input = input;
41
  }
42
}
43

44
const FRAME_MS = 20;
45

46
/**
47
 * The arrivals chart shows the first five seconds; the numbers come from the whole run. A minute of packets is
48
 * what makes a percentage of a few percent settle: over five seconds one burst more or less moves it by half.
49
 */
50
const PLOTTED = 250;
51

52
/**
53
 * The line the advice aims at, as a share of frames the decoder makes up. The tool's own choice, not a standard,
54
 * which is why it is drawn on the buffer chart and never used to colour a result.
55
 */
56
const CLEAN = 1;
57

58
/** How far back each scheme's copies reach: Opus FEC carries one earlier frame, RED as many as it is set to. */
59
const SCHEMES: { id: string; label: string; reach: number; cost: string }[] = [
60
  { id: "none", label: "None", reach: 0, cost: "nothing extra sent" },
61
  /*
62
   * Opus FEC and one RED copy reach back the same one packet, so they recover the same frames here. They
63
   * differ in what the copy is and what it costs, which the protection table says in words.
64
   */
65
  { id: "fec", label: "Opus FEC", reach: 1, cost: "a lower-bitrate copy, paid for inside the Opus bitrate" },
66
  { id: "red1", label: "RED, 1 copy", reach: 1, cost: "a full copy, so about twice the audio bitrate" },
67
  { id: "red2", label: "RED, 2 copies", reach: 2, cost: "two full copies, about three times the audio bitrate" },
68
];
69

70
/** Mulberry32: small, fast, and the same sequence in every JavaScript engine for the same seed. */
71
function random(seed: number): () => number {
72
  let a = seed >>> 0;
73
  return () => {
74
    a = (a + 0x6d2b79f5) >>> 0;
75
    let t = a;
76
    t = Math.imul(t ^ (t >>> 15), t | 1);
77
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
78
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
79
  };
80
}
81

82
type Packet = { sent: number; arrives: number | null };
83

84
/**
85
 * One run's packets: their send times, and when each arrives or that it never does. Delays and losses are drawn
86
 * once, so changing the buffer or the protection replays the same network rather than a new one.
87
 */
88
function network(input: Input): Packet[] {
89
  const next = random(input.seed);
90
  const loss = input.loss / 100;
91
  // Gilbert: leave the lossy state with probability 1/burst, enter it at the rate that gives the loss rate asked.
92
  const leave = 1 / input.burst;
93
  const enter = loss >= 1 ? 1 : (leave * loss) / (1 - loss);
94
  let lossy = next() < loss;
95
  const out: Packet[] = [];
96
  for (let n = 1; n <= input.packets; n++) {
97
    if (n > 1) lossy = lossy ? next() >= leave : next() < enter;
98
    const extra = -input.jitter * Math.log(1 - next());
99
    const sent = n * FRAME_MS;
100
    out.push({ sent, arrives: lossy ? null : Math.round((sent + input.delay + extra) * 10) / 10 });
101
  }
102
  return out;
103
}
104

105
type Outcome = "played" | "recovered" | "concealed";
106

107
/** What the listener gets for each frame, given the buffer and how far back the copies reach. */
108
function outcomes(packets: Packet[], delay: number, buffer: number, reach: number): Outcome[] {
109
  return packets.map((p, i) => {
110
    const deadline = p.sent + delay + buffer;
111
    if (p.arrives !== null && p.arrives <= deadline) return "played";
112
    for (let k = 1; k <= reach; k++) {
113
      const later = packets[i + k];
114
      if (later?.arrives !== null && later?.arrives !== undefined && later.arrives <= deadline) return "recovered";
115
    }
116
    return "concealed";
117
  });
118
}
119

120
/** A stretch of audio: "400 ms", "9.1 s". */
121
const span = (ms: number) => (ms < 1000 ? `${ms} ms` : `${Math.round(ms / 100) / 10} s`);
122

123
const pct = (count: number, of: number) => Math.round((count / of) * 1000) / 10;
124
const count = (list: Outcome[], what: Outcome) => list.filter((o) => o === what).length;
125

126
/**
127
 * Shares to one decimal that always add up, so every scheme's bar on one network has the same height, which is
128
 * the point of drawing them side by side. Concealed is rounded from its own count and recovered takes the
129
 * remainder, not the other way round: concealment is what the buffer chart plots, and rounding it second let
130
 * a deeper buffer appear to conceal 0.1% more.
131
 */
132
function shares(list: Outcome[]): { played: number; recovered: number; concealed: number } {
133
  const missed = pct(list.length - count(list, "played"), list.length);
134
  const concealed = pct(count(list, "concealed"), list.length);
135
  return { played: Math.round((100 - missed) * 10) / 10, recovered: Math.round((missed - concealed) * 10) / 10, concealed };
136
}
137

138
/** The longest run of concealed frames, which is what a listener notices: one 20 ms gap is a click, ten are a dropout. */
139
function longestGap(list: Outcome[]): number {
140
  let longest = 0;
141
  let run = 0;
142
  for (const o of list) {
143
    run = o === "concealed" ? run + 1 : 0;
144
    longest = Math.max(longest, run);
145
  }
146
  return longest;
147
}
148

149
export default {
150
  run(input: Input) {
151
    try {
152
      const { delay, jitter, buffer, loss, burst, packets: total, seed } = input;
153
      if (!(delay >= 0)) throw new InputError("One-way delay cannot be negative.", "delay");
154
      if (!(jitter >= 0)) throw new InputError("Jitter cannot be negative.", "jitter");
155
      if (!(buffer >= 0)) throw new InputError("The jitter buffer cannot be negative.", "buffer");
156
      if (!(loss >= 0 && loss < 100)) throw new InputError("Loss must be at least 0% and below 100%.", "loss");
157
      if (!(burst >= 1)) throw new InputError("Bursts average at least one packet: 1 means losses are independent.", "burst");
158
      if (!(Number.isInteger(total) && total >= 10 && total <= 6000)) throw new InputError("Packets must be a whole number from 10 to 6,000.", "packets");
159
      if (!Number.isInteger(seed)) throw new InputError("The seed must be a whole number.", "seed");
160
      const scheme = SCHEMES.find((s) => s.id === input.protection);
161
      if (!scheme) throw new InputError(`Protection must be one of ${SCHEMES.map((s) => s.id).join(", ")}.`, "protection");
162

163
      const packets = network(input);
164
      const here = outcomes(packets, delay, buffer, scheme.reach);
165
      const lost = packets.filter((p) => p.arrives === null).length;
166
      const late = packets.filter((p) => p.arrives !== null && p.arrives > p.sent + delay + buffer).length;
167
      const played = count(here, "played");
168
      const recovered = count(here, "recovered");
169
      const concealed = count(here, "concealed");
170
      const gap = longestGap(here);
171

172
      const share = shares(here);
173
      const playsAt = delay + buffer;
174

175
      /*
176
       * The buffer sweep, done once and read three times: by the advice, by the chart, and by the annotation. In
177
       * steps of 10 ms from 0 to 200, or further when the run's own buffer is deeper, with the run's own depth
178
       * added when it is not a multiple of 10, so "this run" is always a point on the line.
179
       */
180
      const top = Math.max(200, Math.ceil(buffer / 10) * 10);
181
      const depths = [...new Set([...Array.from({ length: top / 10 + 1 }, (_, i) => i * 10), buffer])].sort((x, y) => x - y);
182
      const concealedAt = depths.map((b) => shares(outcomes(packets, delay, b, scheme.reach)).concealed);
183
      const enough = depths.find((_, i) => (concealedAt[i] ?? 100) < CLEAN);
184

185
      /*
186
       * The answer: how much was made up, the longest stretch of it, and what the buffer costs every frame. No tone,
187
       * because the only line it could be judged against is one this tool chose, and the buffer chart draws that.
188
       */
189
      const answer: Output = {
190
        kind: "fields",
191
        role: "answer",
192
        fields: [
193
          {
194
            label: "Concealed",
195
            value: `${share.concealed}%`,
196
            note: concealed === 0 ? `Nothing made up in ${span(total * FRAME_MS)}` : `${span(concealed * FRAME_MS)} made up in ${span(total * FRAME_MS)}`,
197
          },
198
          {
199
            label: "Longest gap",
200
            value: `${gap * FRAME_MS} ms`,
201
            note: gap > 1 ? `${gap} frames in a row were made up.` : gap === 1 ? "Only single frames were made up." : "No frame was made up.",
202
          },
203
          {
204
            label: "Playout delay",
205
            value: `${playsAt} ms`,
206
            note: buffer === 0 ? "No buffer: all of it is the trip" : `${buffer} ms of it is the buffer`,
207
          },
208
        ],
209
      };
210

211
      /*
212
       * What to change, from the same network replayed: the shallowest buffer that brings made-up audio under 1%
213
       * with this protection, and every other protection that would make up less at this buffer. Each row is a
214
       * replay, not a rule of thumb, and they are sorted by what they leave made up, least first.
215
       */
216
      type Advice = { change: string; after: number; delay: string; cost: string };
217
      const advice: Advice[] = [];
218
      const costOf = (s: (typeof SCHEMES)[number]) => `${s.cost.charAt(0).toUpperCase()}${s.cost.slice(1)}.`;
219
      const shift = (to: number) =>
220
        to > buffer ? `${to - buffer} ms more on every frame` : to < buffer ? `${buffer - to} ms less on every frame` : "No change";
221
      for (const other of SCHEMES) {
222
        const same = other.id === scheme.id;
223
        const sweep = same ? concealedAt : depths.map((b) => shares(outcomes(packets, delay, b, other.reach)).concealed);
224
        // The shallowest buffer that gets this protection under 1%, and what it does at this run's buffer.
225
        const at = depths.findIndex((_, i) => (sweep[i] ?? 100) < CLEAN);
226
        const here = sweep[depths.indexOf(buffer)] ?? 100;
227
        const to = at === -1 ? undefined : depths[at];
228
        if (to !== undefined && to !== buffer && (to > buffer ? share.concealed >= CLEAN : true)) {
229
          const move = to > buffer ? `Raise the buffer to ${to} ms` : `Lower the buffer to ${to} ms`;
230
          advice.push({
231
            change: same ? move : `${move} and switch to ${other.label}`,
232
            after: sweep[at] ?? 0,
233
            delay: shift(to),
234
            cost: same ? (to < buffer ? "Nothing extra sent, and the conversation is quicker." : "Nothing extra sent.") : costOf(other),
235
          });
236
        }
237
        if (!same && here < share.concealed && (to === undefined || to >= buffer)) {
238
          advice.push({ change: `Switch to ${other.label}`, after: here, delay: "No change", cost: costOf(other) });
239
        }
240
      }
241
      /*
242
       * Opus FEC and one RED copy reach back the same packet, so at the same buffer they rebuild the same frames.
243
       * SCHEMES is in order of cost, so keeping the first of two rows with the same delay and the same result keeps
244
       * the cheaper one, and the table never recommends paying twice the bitrate for nothing.
245
       */
246
      const seen = new Set<string>();
247
      const distinct = advice.filter((x) => {
248
        const key = `${x.delay}|${x.after}`;
249
        if (seen.has(key)) return false;
250
        seen.add(key);
251
        return true;
252
      });
253
      distinct.sort((x, y) => x.after - y.after);
254
      /*
255
       * When nothing reaches 1%, the reader still needs to know how far the settings can go: the least made-up audio
256
       * any protection reaches at any buffer swept, cheapest and shallowest first among equals.
257
       */
258
      if (distinct.length === 0 && share.concealed >= CLEAN) {
259
        let best = { after: share.concealed, depth: buffer, at: scheme };
260
        for (const other of SCHEMES) {
261
          for (const b of depths) {
262
            const after = shares(outcomes(packets, delay, b, other.reach)).concealed;
263
            if (after < best.after) best = { after, depth: b, at: other };
264
          }
265
        }
266
        distinct.push(
267
          best.after < share.concealed
268
            ? {
269
                change: `The most these settings reach: a ${best.depth} ms buffer with ${best.at.label}`,
270
                after: best.after,
271
                delay: shift(best.depth),
272
                cost: best.at.id === scheme.id ? "Nothing extra sent." : costOf(best.at),
273
              }
274
            : { change: "Nothing tried here makes up less", after: share.concealed, delay: "No change", cost: "The network has to improve." },
275
        );
276
      }
277
      const actions: Output = {
278
        kind: "table",
279
        role: "actions",
280
        caption:
281
          distinct.every((x) => x.after >= CLEAN)
282
            ? `No buffer up to ${top} ms gets made-up audio under 1% with any protection on this network. It is ${share.concealed}% now.`
283
            : `What to change, each tried on this same minute of network. Made-up audio is ${share.concealed}% now.`,
284
        columns: [
285
          { label: "Change", wrap: "prose" },
286
          { label: "Made-up audio after", align: "end", mono: true, wrap: "none" },
287
          { label: "Delay", wrap: "prose" },
288
          { label: "What it costs", wrap: "prose" },
289
        ],
290
        rows: distinct.map((a) => [a.change, { text: `${a.after}%`, mono: true }, a.delay, a.cost]),
291
      };
292

293
      /*
294
       * Where the frames went, quietly, under the comparison. The longest gap and the buffer's delay are in the answer,
295
       * so they are not said again here.
296
       */
297
      const metrics: Field[] = [
298
        { label: "Played on time", value: `${share.played}%`, note: `${played} of ${total} frames` },
299
        { label: "Rebuilt from a copy", value: `${share.recovered}%`, note: scheme.id === "none" ? "No copies are sent" : `${recovered} frames` },
300
        { label: "Lost by the network", value: `${pct(lost, total)}%`, note: `${lost} packets` },
301
        { label: "Arrived too late", value: `${pct(late, total)}%`, note: late === 0 ? `None after ${playsAt} ms` : `${late} packets, after ${playsAt} ms` },
302
      ];
303

304
      /*
305
       * What Alice hears: the first five seconds, a row per second and a column per 20 ms frame, with only the
306
       * incidents drawn. Played frames are left out: at 95% of the minute they gave the ordinary case far more ink
307
       * than the frames that went wrong, so a run of made-up frames is now the only thing in its row.
308
       *
309
       * Two categories, two point series, each with its own colour and marker, rather than a heatmap whose key would
310
       * show them as amounts. A series with no points in the window is left out, so the key names only what is drawn.
311
       */
312
      const perSecond = 1000 / FRAME_MS;
313
      const window = here.slice(0, PLOTTED);
314
      const label: Record<Exclude<Outcome, "played">, string> = { concealed: "Made up by the decoder", recovered: "Rebuilt from a copy" };
315
      // Made-up frames first, so the problem takes the strongest colour.
316
      const incidents = (["concealed", "recovered"] as const).flatMap((kind): Series[] => {
317
        const at = window.flatMap((o, i) => (o === kind ? [i] : []));
318
        if (at.length === 0) return [];
319
        return [
320
          {
321
            label: label[kind],
322
            shape: "points",
323
            x: at.map((i) => (i % perSecond) + 1),
324
            points: at.map((i) => Math.floor(i / perSecond) + 1),
325
            notes: at.map((i) => `frame ${i + 1}, at ${((i * FRAME_MS) / 1000).toFixed(2)} s: ${label[kind].toLowerCase()}`),
326
          },
327
        ];
328
      });
329
      const seconds = Math.ceil(window.length / perSecond);
330
      const strip: Output | null =
331
        incidents.length === 0
332
          ? null
333
          : {
334
              kind: "series",
335
              chart: {
336
                xLabel: "Frame within the second",
337
                yLabel: seconds > 1 ? `Second, the first ${seconds}` : "Second",
338
                /*
339
                 * The series carry their own x. These two hold the x axis to the whole second, frame 1 to 50, which
340
                 * the incidents alone would not: without them a second whose only gap is at frame 12 draws frame 12
341
                 * at the edge.
342
                 */
343
                x: [1, Math.min(perSecond, window.length)],
344
                series: incidents,
345
                readout: { mode: "point" },
346
              },
347
            };
348

349
      /*
350
       * C: every packet's trip against the time it had. Two point series, on time and too late, so the colour
351
       * and the legend both say which side of the rule a packet fell; lost packets have no trip to plot.
352
       */
353
      const shown = packets.slice(0, PLOTTED);
354
      const numbers = shown.map((_, i) => i + 1);
355
      const trip = (p: Packet) => (p.arrives === null ? null : Math.round((p.arrives - p.sent) * 10) / 10);
356
      const onTime = shown.map((p) => (p.arrives !== null && p.arrives <= p.sent + delay + buffer ? trip(p) : null));
357
      const tooLate = shown.map((p) => (p.arrives !== null && p.arrives > p.sent + delay + buffer ? trip(p) : null));
358
      const arrivals: Output = {
359
        kind: "series",
360
        chart: {
361
          xLabel: total > PLOTTED ? `Packet, the first ${PLOTTED} of ${total}` : "Packet",
362
          yLabel: "Trip",
363
          yUnit: "ms",
364
          x: numbers,
365
          series: [
366
            { label: "On time", unit: "ms", shape: "points", points: onTime },
367
            { label: "Too late", unit: "ms", shape: "points", points: tooLate },
368
          ],
369
          thresholds: [{ y: delay + buffer, label: `plays at ${delay + buffer} ms`, tone: "warn" }],
370
          readout: { mode: "point" },
371
        },
372
      };
373

374
      /*
375
       * D: the buffer's trade, over the same packets. More buffer catches more late packets and adds that much
376
       * delay to every frame. Two lines: what arrives too late, and what is still concealed after the copies.
377
       */
378
      const lateAt = depths.map((b) => pct(packets.filter((p) => p.arrives !== null && p.arrives > p.sent + delay + b).length, total));
379
      const trade: Output = {
380
        kind: "series",
381
        chart: {
382
          xLabel: "Jitter buffer",
383
          xUnit: "ms",
384
          yLabel: "Frames",
385
          yUnit: "%",
386
          x: depths,
387
          /*
388
           * Log, because the trade spans orders of magnitude: with no buffer nearly every packet is late,
389
           * and the decisions are made down where it is a few percent or less. A share of zero cannot sit on
390
           * a log axis; the runtime leaves those points out and the data table says so.
391
           */
392
          yScale: "log",
393
          series: [
394
            { label: "Arrive too late", unit: "%", shape: "line", markers: true, points: lateAt },
395
            { label: scheme.id === "none" ? "Concealed" : `Concealed, with ${scheme.label}`, unit: "%", shape: "line", markers: true, points: concealedAt },
396
          ],
397
          /*
398
           * Both marks the decision needs: where this run sits, and the shallowest buffer that gets under the
399
           * line. When they are the same depth, one mark says both rather than two labels colliding.
400
           */
401
          annotations:
402
            enough === buffer
403
              ? [{ x: buffer, label: "this run, the shallowest under 1%" }]
404
              : [{ x: buffer, label: "this run" }, ...(enough !== undefined ? [{ x: enough, label: "shallowest under 1%" }] : [])],
405
          thresholds: [{ y: CLEAN, label: "1% made up", tone: "warn" }],
406
        },
407
      };
408

409
      /*
410
       * E: what each scheme buys on this run's network, at this buffer. A table rather than bars, because it is what a
411
       * reader compares digit by digit, and bars of the same two columns only repeated it: what each recovers, what it
412
       * still leaves made up, its longest gap, and what it costs on the wire. The run's own scheme is named in words
413
       * rather than coloured, since being the current choice is not a judgement on it.
414
       */
415
      const byScheme = SCHEMES.map((s) => outcomes(packets, delay, buffer, s.reach));
416
      const protection: Output = {
417
        kind: "table",
418
        role: "comparison",
419
        caption: `Protection, at a ${buffer} ms buffer`,
420
        columns: [
421
          { label: "Protection", wrap: "prose", rowHeader: true },
422
          { label: "Recovered", align: "end", mono: true, wrap: "none" },
423
          { label: "Concealed", align: "end", mono: true, wrap: "none" },
424
          { label: "Longest gap", align: "end", mono: true, wrap: "none" },
425
          // Words, not a measurement: start-aligned, so on a phone it falls under the row's name as a note.
426
          { label: "What it sends", wrap: "prose" },
427
        ],
428
        rows: SCHEMES.map((s, i) => {
429
          const o = byScheme[i] ?? [];
430
          return [s.id === scheme.id ? `${s.label} (this run)` : s.label, `${shares(o).recovered}%`, `${shares(o).concealed}%`, `${longestGap(o) * FRAME_MS} ms`, costOf(s)];
431
        }),
432
      };
433

434
      return {
435
        kind: "group",
436
        /*
437
         * The answer, then the buffer trade it turns on, then what to change when there is something to change,
438
         * then the protections side by side and the counts behind them. The pictures of individual frames and
439
         * packets come after, as the evidence: they show the first five seconds, and the numbers are the minute.
440
         */
441
        parts: [
442
          answer,
443
          trade,
444
          ...(distinct.length > 0 || share.concealed >= CLEAN ? [actions] : []),
445
          protection,
446
          { kind: "fields", role: "metrics", fields: metrics },
447
          ...(strip ? [strip] : []),
448
          arrivals,
449
        ],
450
      };
451
    } catch (error) {
452
      if (error instanceof InputError) return { kind: "error", message: error.message, input: error.input };
453
      throw error;
454
    }
455
  },
456
} satisfies Tool<Input>;