Loss and playout simulator

/tools/loss-playout/

One voice frame is lost. UDP conceals that one frame; TCP recovers it and holds every frame behind it, and each one whose playout time passes while it waits is lost to the listener anyway.

How it works

Loss and playout simulator#

A voice call sends a small frame of audio every 20 ms, and the receiver plays each one at a fixed time. One frame is lost. This tool answers what that costs the listener over UDP and over TCP: which frames still arrive before they have to play, and how much audio has to be concealed.

The short answer is that UDP loses the one frame, and TCP loses the one frame plus every frame queued behind it while it waits for the resend. The numbers show how many that is.

How to use it: an example#

Say you’re choosing a transport for a voice feature. Frames are 20 ms of Opus, the path is 30 ms each way, and the receiver holds 40 ms of buffer. One packet in the middle of a sentence, frame 5, is dropped.

1. Enter the call.

Input	You enter	Why
Frame size	`20 ms`	The usual Opus packet
One-way delay	`30`	Half the round trip
Jitter buffer	`40`	What the receiver waits before playing
Lost frame	`5`	Any frame with at least three after it
Retransmission timeout	`200`	Linux’s default minimum
Frames	`20`	Enough to see the queue drain

2. Press Run, and read the table at the top.

Frame 5 lost, at a 40 ms buffer: the audio each loses, the frames, and the buffer that would hide it

Transport	Audio	Frames	Buffer
UDP	20 ms	5 (lost)	never
TCP, fast retransmit	80 ms	5 to 8	120 ms
TCP, 200 ms timeout	160 ms	5 to 12	200 ms

In plain words: over UDP the listener hears one 20 ms gap, which the decoder papers over. Over TCP the same loss costs four frames at best and eight at worst, because TCP won’t hand over frame 6 until frame 5 has been resent. Frame 9 is held too, and still plays on time: it is released at 250 ms and plays at 250 ms.

3. Read the buffer column. That’s the trade in one column: TCP can hide the loss only with a buffer of 120 ms or 200 ms, 80 or 160 ms more than the 40 in use, and that delay is paid on every word of the call, not just the lost one. UDP never resends, so no buffer brings frame 5 back.

4. Check it. Press the Bigger buffer sample (120 ms) and Run. The fast retransmit row reads 0 ms and “none” frames: the resend lands at 250 ms, exactly when frame 5 has to play. The timeout still misses frames 5 to 8.

5. Read the chart under it. Each line is when the application gets a frame. Points on or under the deadline line play. The TCP lines go flat at the lost frame: that flat stretch is the queue being held, and every point on it above the deadline is audio nobody hears. Under the chart, the three timings it turns on: when frame 5 has to play, and when each kind of resend leaves.

The model#

Every number follows from a handful of rules, so every result can be checked by hand.

Frames 1 to N are sent every frame ms: frame n leaves at n x frame.
Each takes delay ms to arrive. Every frame takes exactly the same time: there is no jitter.
Frame n has to play by n x frame + delay + buffer. Arriving at or before that time is on time.
One frame, lost, is dropped once.
UDP never delivers the lost frame. The decoder conceals it, and every other frame arrives on time.
TCP delivers in order. Frames before the loss go up as they arrive. The lost frame and everything after it go up at whichever is later, their own arrival or the moment the resent copy arrives (resend + delay). That is the whole mechanism: a frame can arrive in time and still be held behind the gap.
Fast retransmit resends when the third duplicate ACK gets back to the sender: frame lost + 3 arrives, and its ACK takes another delay to return. That needs three frames after the loss; with fewer, it cannot fire and the timer resends instead.
The timeout resends rto ms after the lost frame was sent. 200 ms is Linux’s default minimum; RFC 6298 recommends 1 s. The timer is always running, so when it would fire before the third duplicate ACK (60 ms frames with a 200 ms timer, for instance) the fast-retransmit row resends on the timer too.
A frame is missed if it never arrives or arrives after its playout time. Concealed audio is missed frames times the frame size.
The buffer that hides a resend is resend - lost x frame: the repair arrives at resend + delay and the lost frame plays at lost x frame + delay + buffer, so the delay cancels. That’s the “Buffer” column, and everything above the buffer you have is added to every frame of the call.

At the defaults (20 ms frames, 30 ms each way, 40 ms of buffer, frame 5 lost):

Transport	Missed	Concealed
UDP	frame 5	20 ms
TCP, fast retransmit	frames 5 to 8, all released at 250 ms	80 ms
TCP, 200 ms timeout	frames 5 to 12, released at 330 ms	160 ms

A bigger buffer changes the TCP rows and not the UDP one. At 120 ms, fast retransmit’s repair arrives exactly on frame 5’s deadline and nothing is missed, while the timeout still costs frames 5 to 8. That buffer is also 80 ms of extra delay on every word of the call, which is the trade.

Reading the chart#

Each line is when the application gets a frame. A frame plays if its point is on or under the deadline line. UDP runs parallel to the deadline with one gap. The TCP lines go flat from the lost frame to where they rejoin their own arrival times: that flat stretch is the queue being held, and every frame on it above the deadline is audio nobody hears.

What a frame size costs#

The second chart, after the timings, is why 20 ms is the usual choice. Every packet carries 40 bytes of headers, IPv4’s 20 without options, UDP’s 8 and RTP’s 12, whatever the frame size, so a smaller frame sends more packets and more header bits: at 10 ms the headers cost as much as the sound itself. A bigger frame saves them and loses more audio per lost packet. The sound is fixed at Opus’s 32 kb/s, 80 bytes per 20 ms frame, so the chart compares sizes rather than codecs. SRTP’s authentication tag and any header extensions would add to every packet, and are left out.

What it deliberately does not model#

Jitter. Every frame takes the same time. Real paths vary, which is what the buffer is for, and variation makes both transports worse.
RACK. Current Linux detects loss with RACK (RFC 8985), which can resend sooner than three duplicate ACKs. The fast-retransmit row is the classic rule, not the newest one.
The congestion window. A loss also halves how much TCP will send, which can delay frames after the repair. Voice is so little data that this rarely binds, and it is left out.
Timer restarts. The timer is modelled from the lost frame’s own send time. Real TCP restarts it as other data is acknowledged, which only makes the timeout later, so the timeout row is a best case.
More than one loss, or a loss of the resent copy.
The end of the run. Misses are counted up to frame N. With a long timeout the stall runs past the last frame, and a longer run would miss more.

References#

RFC 5681 section 3.2: fast retransmit and the three duplicate ACKs.
RFC 6298: computing the retransmission timer, and the 1 s minimum.

Source and references

index.ts298 lines, TypeScript

1
/**
2
 * One lost voice frame, over UDP and over TCP.
3
 *
4
 * A voice call sends a small frame every 20 ms, and the receiver plays each one at a fixed time: when it was
5
 * sent, plus the trip, plus a jitter buffer. A frame that is not there by then is useless, however correct it
6
 * is when it finally turns up. So the question for a lost frame is not whether it is recovered but which
7
 * frames still make their playout deadline, and that is where the two transports differ.
8
 *
9
 * **UDP** loses the frame and carries on. The decoder conceals one frame's worth of audio and every later
10
 * frame plays on time. The cost of one loss is one frame.
11
 *
12
 * **TCP** recovers the frame, and delivers in order: nothing after the gap reaches the application until the
13
 * resent copy does. Every frame queued behind it is held and then released at once, and each one whose
14
 * deadline passed while it waited is as lost to the listener as if the network had dropped it. The cost of
15
 * one loss is every frame whose deadline falls before the repair, which is the point of the tool.
16
 *
17
 * Two ways the resend happens:
18
 *
19
 *  - **Fast retransmit** (RFC 5681 section 3.2): each frame after the gap draws a duplicate ACK, and the third
20
 *    one triggers the resend. That needs three frames to follow the loss, so it cannot fire near the end of a
21
 *    talk spurt.
22
 *  - **The retransmission timer** (RFC 6298): with nothing to draw duplicate ACKs, the sender waits out the
23
 *    timer. 200 ms is Linux's default minimum; the RFC recommends 1 s.
24
 *
25
 * ⚠️ Where this stops being true: no jitter, one loss, no congestion window effects, no RACK (which current
26
 * Linux uses and which can resend sooner than three duplicate ACKs), and the timer is started from the lost
27
 * frame's own send time rather than restarted by later ACKs. Each of those would make the TCP numbers worse
28
 * or better by a few frames, not change which transport a live voice stream wants.
29
 */
30
import type { Cell, Field, Output, Series, Tool } from "@toolbench/sdk";
31

32
type Input = { frame: string; delay: number; buffer: number; lost: number; rto: number; frames: number };
33

34
/** Named so the error path can say which input was wrong rather than "invalid input". */
35
class InputError extends Error {
36
  readonly input: string;
37

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

45
/** Codec frame sizes in common use: Opus runs 10 to 60, G.711 over RTP is usually 20. */
46
const FRAME_SIZES = [10, 20, 40, 60];
47

48
/**
49
 * For the frame-size chart: Opus at 32 kb/s, which is 80 bytes per 20 ms frame, and 40 bytes of headers per
50
 * packet, IPv4's 20 without options, UDP's 8 and RTP's 12 without CSRCs or extensions. Fixed sizes from the
51
 * RFCs and one stated bitrate, so the chart computes what a frame size costs rather than quoting anyone.
52
 */
53
const OPUS_KBPS = 32;
54
const HEADER_BYTES = 20 + 8 + 12;
55

56
/** Duplicate ACKs that trigger a resend without waiting for the timer, per RFC 5681. */
57
const DUP_ACKS = 3;
58

59
/** Frame number to the time the application gets it, or null when it never does. */
60
type Delivery = (number | null)[];
61

62
type Transport = {
63
  label: string;
64
  delivered: Delivery;
65
  missed: number[];
66
  /** When the resent copy reaches the receiver and releases the queue. Absent for UDP, which never resends. */
67
  repaired?: number;
68
};
69

70
/** "5", "19 and 20", "5 to 12", joined when a run breaks, so the note reads the way a person would say it. */
71
function frameList(frames: number[]): string {
72
  const runs: [number, number][] = [];
73
  for (const n of frames) {
74
    const last = runs.at(-1);
75
    if (last && n === last[1] + 1) last[1] = n;
76
    else runs.push([n, n]);
77
  }
78
  return runs
79
    .map(([a, b]) => (a === b ? `${a}` : b === a + 1 ? `${a} and ${b}` : `${a} to ${b}`))
80
    .join(", ");
81
}
82

83
const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? "" : "s"}`;
84

85
/**
86
 * Why 20 ms: what each frame size costs on the wire, beside how much audio one lost packet takes with it.
87
 * The sound costs the same at every size; the headers are paid per packet, so a smaller frame sends more
88
 * packets and more header bits. A bigger frame saves those and loses more audio per loss. Bars, stacked,
89
 * one row per size, because the question is a total and the share of it that is overhead.
90
 */
91
function frameCost(chosen: number): Output {
92
  const kbps = (n: number) => Math.round(n * 10) / 10;
93
  const headers = FRAME_SIZES.map((ms) => kbps((HEADER_BYTES * 8) / ms));
94
  const rows = FRAME_SIZES.map((ms) => `${ms} ms${ms === chosen ? " (this run)" : ""}`);
95
  return {
96
    kind: "series",
97
    chart: {
98
      xLabel: "Frame size",
99
      yLabel: "Bits on the wire",
100
      yUnit: "kb/s",
101
      x: rows,
102
      orientation: "horizontal",
103
      series: [
104
        // Named plainly: the key adds the unit, and the bitrate and header size are in each readout note.
105
        { label: "Opus", unit: "kb/s", shape: "bar", stack: "wire", points: FRAME_SIZES.map(() => OPUS_KBPS), notes: FRAME_SIZES.map((ms) => `${OPUS_KBPS} kb/s, ${(OPUS_KBPS * ms) / 8} bytes a frame`) },
106
        {
107
          label: "Headers",
108
          unit: "kb/s",
109
          shape: "bar",
110
          stack: "wire",
111
          points: headers,
112
          notes: headers.map((h) => `${h} kb/s, ${HEADER_BYTES} bytes a packet, ${Math.round((h / (h + OPUS_KBPS)) * 100)}% of the total`),
113
        },
114
      ],
115
      readout: {
116
        titles: FRAME_SIZES.map((ms) => `${ms} ms: ${kbps(1000 / ms)} packets a second, one loss erases ${ms} ms`),
117
      },
118
    },
119
  };
120
}
121

122
export default {
123
  run(input: Input) {
124
    try {
125
      const frameMs = Number(input.frame);
126
      const { delay: oneWay, buffer, lost, rto, frames } = input;
127

128
      if (!FRAME_SIZES.includes(frameMs)) throw new InputError(`Frame size must be one of ${FRAME_SIZES.join(", ")} ms.`, "frame");
129
      if (!(oneWay >= 0)) throw new InputError("One-way delay cannot be negative.", "delay");
130
      if (!(buffer >= 0)) throw new InputError("Jitter buffer cannot be negative.", "buffer");
131
      if (!(Number.isInteger(frames) && frames >= 1)) throw new InputError("Frames must be a whole number, at least 1.", "frames");
132
      if (!(Number.isInteger(lost) && lost >= 1)) throw new InputError("The lost frame must be a whole frame number, at least 1.", "lost");
133
      if (lost > frames) throw new InputError(`Frame ${lost} is never sent: the run has ${frames} frames.`, "lost");
134
      /*
135
       * A timer shorter than the round trip fires before any acknowledgement could have come back, so it
136
       * would resend frames that were never lost. Real TCP cannot get there: RFC 6298 builds the timer from
137
       * the measured round trip, so it is always at least that long.
138
       */
139
      if (!(rto >= 2 * oneWay)) {
140
        throw new InputError(
141
          `A retransmission timer shorter than the round trip fires before any ACK could return: at ${oneWay} ms each way it must be at least ${2 * oneWay} ms.`,
142
          "rto",
143
        );
144
      }
145

146
      const numbers = Array.from({ length: frames }, (_, i) => i + 1);
147
      const sent = (n: number) => n * frameMs;
148
      const arrives = (n: number) => sent(n) + oneWay;
149
      const deadline = (n: number) => sent(n) + oneWay + buffer;
150
      const missedIn = (delivered: Delivery) =>
151
        numbers.filter((n) => {
152
          const t = delivered[n - 1];
153
          return t === null || t === undefined || t > deadline(n);
154
        });
155

156
      /*
157
       * In-order delivery is the whole mechanism: a frame after the gap can arrive in time and still be held,
158
       * because the application only ever sees the stream up to the first hole. So each later frame goes up
159
       * at whichever is later, its own arrival or the repair.
160
       */
161
      const tcp = (label: string, resendAt: number): Transport => {
162
        const repaired = resendAt + oneWay;
163
        const delivered = numbers.map((n) => (n < lost ? arrives(n) : Math.max(arrives(n), repaired)));
164
        return { label, delivered, missed: missedIn(delivered), repaired };
165
      };
166

167
      const udpDelivered = numbers.map((n) => (n === lost ? null : arrives(n)));
168
      const udp: Transport = { label: "UDP", delivered: udpDelivered, missed: missedIn(udpDelivered) };
169

170
      const timerAt = sent(lost) + rto;
171
      const canFastRetransmit = lost + DUP_ACKS <= frames;
172
      // The third frame after the gap arrives, and its duplicate ACK spends one more trip getting back.
173
      const thirdDupAck = canFastRetransmit ? sent(lost + DUP_ACKS) + 2 * oneWay : null;
174
      /*
175
       * The timer is running whether or not duplicate ACKs come, so the resend is whichever fires first. With
176
       * 60 ms frames the third duplicate ACK can be slower than a 200 ms timer, and showing it as the later
177
       * of the two would describe a sender that does not exist.
178
       */
179
      const fastAt = thirdDupAck === null ? timerAt : Math.min(thirdDupAck, timerAt);
180
      const fast = tcp("TCP, fast retransmit", fastAt);
181
      const timeout = tcp(`TCP, ${rto} ms timeout`, timerAt);
182
      const transports = [udp, fast, timeout];
183

184
      let fastNote: string;
185
      if (thirdDupAck === null) {
186
        const after = frames - lost;
187
        const follow = after === 0 ? "no frame follows" : `only ${plural(after, "frame")} ${after === 1 ? "follows" : "follow"}`;
188
        fastNote = `It cannot fire: ${follow} the loss and ${DUP_ACKS} are needed, so the timer resends.`;
189
      } else if (thirdDupAck > timerAt) {
190
        fastNote = `The timer fires first: the third duplicate ACK would reach the sender at ${thirdDupAck} ms.`;
191
      } else {
192
        fastNote = `The third duplicate ACK, drawn by frame ${lost + DUP_ACKS}, reaches the sender.`;
193
      }
194

195
      /*
196
       * The answer is a comparison, so it is a table: the three transports in one frame, what each loses, which
197
       * frames, and the buffer that would hide the loss. No tone and no "nothing to change" row: the reader is
198
       * choosing between the three, and none of them is the tool's to approve.
199
       *
200
       * The buffer that hides a resend: the repair reaches the receiver at resend + delay and the lost frame plays
201
       * at sent + delay + buffer, so the buffer that just covers it is resend - sent, and the delay cancels. Every
202
       * millisecond of it is also added to every frame of the call, which is why the answer for live voice is
203
       * usually UDP. UDP never resends, so no buffer hides its loss.
204
       */
205
      const ms = (t: Transport) => t.missed.length * frameMs;
206
      const comparison: Output = {
207
        kind: "table",
208
        role: "comparison",
209
        // Short headers, because a comparison keeps its columns on a phone; the caption says what each one is.
210
        caption: `Frame ${lost} lost, at a ${buffer} ms buffer: the audio each loses, the frames, and the buffer that would hide it`,
211
        columns: [
212
          { label: "Transport", wrap: "prose", rowHeader: true },
213
          { label: "Audio", align: "end", mono: true, wrap: "none" },
214
          { label: "Frames", align: "end", mono: true, wrap: "none" },
215
          { label: "Buffer", align: "end", mono: true, wrap: "none" },
216
        ],
217
        rows: transports.map((t): Cell[] => [
218
          t.label,
219
          `${ms(t)} ms`,
220
          t.missed.length === 0 ? "none" : t.repaired === undefined ? `${frameList(t.missed)} (lost)` : frameList(t.missed),
221
          t.repaired === undefined ? "never" : `${t.repaired - oneWay - sent(lost)} ms`,
222
        ]),
223
      };
224

225
      const fields: Field[] = [
226
        {
227
          label: `Frame ${lost} plays at`,
228
          value: `${deadline(lost)} ms`,
229
          note: `It is sent at ${sent(lost)} ms, arrives at ${arrives(lost)} ms, then waits ${buffer} ms in the buffer.`,
230
        },
231
        { label: "Fast retransmit resends at", value: `${fastAt} ms`, note: fastNote },
232
        { label: "Timeout resends at", value: `${timerAt} ms`, note: `That is ${rto} ms after frame ${lost} was sent.` },
233
      ];
234

235
      /*
236
       * Delivery time against frame number, beside the deadline. A frame plays when its point is on or below
237
       * the deadline line. The TCP lines run flat from the loss to where they meet their own arrival times
238
       * again: that flat stretch is the queue being held, and everything on it above the deadline is audio
239
       * the listener never hears.
240
       */
241
      const line = (label: string, points: (number | null)[]): Series => ({ label, unit: "ms", shape: "line", points });
242
      const chart = {
243
        /*
244
         * Linked to the per-frame table below, both ways: pointing at a frame lights its row, and pointing
245
         * at a row moves the readout to that frame. The chart's own data table lights too, once opened.
246
         */
247
        id: "playout",
248
        readout: { highlightTable: true },
249
        xLabel: "Frame",
250
        yLabel: "Time",
251
        yUnit: "ms",
252
        x: numbers,
253
        /*
254
         * Markers on the transports, not on the deadline: frames are separate events, so each delivery is
255
         * a point and the line through them only guides the eye. The markers also keep UDP findable on
256
         * frames 1 to 4, where all three transports deliver at the same moment and their lines coincide.
257
         * The deadline is a rule, a line is exactly what it is.
258
         */
259
        series: [line("Playout deadline", numbers.map(deadline)), ...transports.map((t) => ({ ...line(t.label, t.delivered), markers: true }))],
260
        annotations: [{ x: lost, label: `frame ${lost} lost` }],
261
      };
262

263
      const cell = (n: number, t: number | null | undefined): Cell => {
264
        if (t === null || t === undefined) return { text: "lost", mono: true, tone: "bad" };
265
        return t > deadline(n) ? { text: `${t} ms, late`, mono: true, tone: "warn" } : { text: `${t} ms, on time`, mono: true };
266
      };
267
      const rows: Cell[][] = numbers.map((n) => [n, sent(n), deadline(n), ...transports.map((t) => cell(n, t.delivered[n - 1]))]);
268

269
      /*
270
       * The comparison, the timeline that explains it, the timings the timeline turns on, then the frame-size
271
       * chart, which answers a different question, and last the per-frame audit trail. A page showing the first
272
       * four parts shows both charts and leaves the per-frame table behind "show more".
273
       */
274
      const parts: Output[] = [
275
        comparison,
276
        { kind: "series", chart },
277
        { kind: "fields", fields },
278
        frameCost(frameMs),
279
        {
280
          kind: "table",
281
          caption: "Every frame: when the application gets it, against when it has to play",
282
          columns: [
283
            { label: "Frame", align: "end", mono: true, wrap: "none", rowHeader: true },
284
            { label: "Sent (ms)", align: "end", mono: true, wrap: "none" },
285
            { label: "Play by (ms)", align: "end", mono: true, wrap: "none" },
286
            ...transports.map((t) => ({ label: t.label, align: "end" as const, mono: true, wrap: "none" as const })),
287
          ],
288
          rows,
289
          link: { chart: "playout", keys: numbers },
290
        },
291
      ];
292
      return { kind: "group", parts };
293
    } catch (error) {
294
      if (error instanceof InputError) return { kind: "error", message: error.message, input: error.input };
295
      throw error;
296
    }
297
  },
298
} satisfies Tool<Input>;

2 items

Sep 11, 2026 16 min read Networking & media

What's inside one voice packet

Twenty milliseconds of speech becomes an 80-byte Opus frame inside a 120-byte packet. Why each header is there, and why one lost packet costs 20 ms over UDP and 80 or more over TCP.

Real-time voice, from the packet upaudionetworkingwebrtc
6 posts Series

Real-time voice, from the packet up

How a voice call actually works, one layer at a time.

Networking & media

What's inside one voice packet

Twenty milliseconds of speech becomes an 80-byte Opus frame inside a 120-byte packet. Why each header is there, and why one lost packet costs 20 ms over UDP and 80 or more over TCP.

audionetworking
Sep 2026
Series

Real-time voice, from the packet up

How a voice call actually works, one layer at a time.

6 posts