blob: 109f76f726a08332de95356a22bd8750f9489ae7 [file] [log] [blame] [view]
Thomas Guilbert43ad2f72023-04-06 01:57:331# Audio Latency Tracing
2
3The `“audio.latency”` tracing category is a tool to measure internal chromium
4audio latency, without any hardware dependencies. This document outlines how
5to record and analyse a latency trace, and offers suggestions as to how to
6construct test pages.
7
8[TOC]
9
10## Overview
11
12![audio.latency tracing overview](latency_tracing_overview.png)
13
14When an input stream detects an audio signal peak (e.g. clapping hands in front
15of microphone), we start an “audio.latency” trace event. When the output stream
16detects an audio peak, we stop the tracing event. The duration of the trace
17event should give us the total internal Chrome latency. **This excludes any
18latency incured from hardware** such as a microphone or sound card's internal
19buffers.
20
21## Measuring Latency
22
23### Prerequisites
24
25* The computer must have a microphone input accessible through `getUserMedia()`
26* Only the test page and `chrome://tracing` should be open.
27* The test page must have one call to `getUserMedia()` + one audio output
28 (e.g. one media element OR one WebAudio graph).
29* The surrounding area should be relatively quiet.
30* If echo cancellation is disabled, consider lowering speaker volume or OS
31 volume.
32* **Trace recording must be started before any streams are created** by the test
33 page, or there will be no traces. One can check that there are no `Input
34 Controllers` or `Output Streams` in the chrome://media-internals audio tab, as
35 pictured below.
36 ![No streams](latency_tracing_media_internals.png)
37
38
39### Steps
40
41* Open the latest version of Chrome (114.0.5695.0 or later).
42* Open chrome://tracing.
43* Record a new trace selecting the “audio” and the “audio.latency” categories.
44 ![Selecting tracing categories](latency_tracing_tracing_categories.png)
45* In a separate tab, open the [test page](#Test-pages).
46* Initialize the test page, so that it is capturing audio using `getUserMedia()`
47 and playing out the captured stream.
48* Repeatedly clap next to the microphone, clearly and loudly, waiting roughly 1
49 second between claps.
50* Stop the trace.
51* Look for the `AmplitudePeak` trace event: the wall duration corresponds to the
52 measured latency
53 ![Viewing results](latency_tracing_results.png)
54
55## Test pages
56
57### Baseline latency test page
58
59The simplest latency test page involves directly routing a `getUserMedia()`
60MediaStream to an `<audio>` element or WebAudio. Such a web page should
61allow us to measure the round trip latency within Chrome, between the audio
62service and the renderer process. For convenience, a simple test page is checked
63in under
64[`third_party/blink/manual_tests/audio_latency.html`](/third_party/blink/manual_tests/audio_latency.html).
65The audio signal flow for this test pages matches the diagram in the
66[overview](#Overview).
67
68### Codec latency test page
69
70Adding an encoding and decoding step to a simple baseline test web page should
71allow us to measure the extra latency incurred by encoding and decoding audio.
72No such test page is provided, but the signal flow should follow this diagram:
73
74![Codec latency test page diagram](latency_tracing_codec.png)
75
76### Network end-to-end latency test
77
78Adding a network round trip to a codec latency test page should simulate the
79expected end-to-end latency in real-world scenarios. The sender and receiver
80test pages can live in two tabs, if only one page calls `getUserMedia()` and one
81page plays out audio. Again, no example test page is provided, but the signal
82flow should follow this diagram:
83
84![Network latency test page diagram](latency_tracing_network.png)