1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
---
title: Frame Timing API
slug: Web/API/Frame_Timing_API
tags:
- Guide
- NeedsTranslation
- Overview
- TopicStub
- Web Performance
translation_of: Web/API/Frame_Timing_API
---
<div>{{DefaultAPISidebar("Frame Timing API")}}{{SeeCompatTable}}</div>
<p>The <strong><code>PerformanceFrameTiming</code></strong> interface provides <em>frame</em> timing data about the browser's event loop. A <em>frame</em> represents the amount of work a browser does in <a href="https://html.spec.whatwg.org/multipage/webappapis.html#processing-model-8">one event loop iteration</a> such as processing DOM events, resizing, scrolling, rendering, CSS animations, etc. A <em>frame rate</em> of 60 fps (frames per second) for a 60 Hz refresh rate is a common target for a good <em>responsive</em> user experience. This means the browser should process a frame in about 16.7 ms.</p>
<p>An application can register a {{domxref("PerformanceObserver")}} for "<code>frame</code>" {{domxref("PerformanceEntry","performance entry types")}}. The <em>observer</em> (callback) will be notified when new "<code>frame</code>" events are added to the browser's <em>performance timeline</em> and the frame's {{domxref("PerformanceEntry.duration","duration")}} (length of time) will be available. This data can be used to help identify areas that take too long to provide a good user experience.</p>
<p>Example code of the interfaces described in this document is included in <em><a href="/Web/API/Frame_Timing_API/Using_the_Frame_Timing_API">Using the Frame Timing API</a></em>.</p>
<h2 id="Performance_frames">Performance <code>frames</code></h2>
<p>The {{domxref("PerformanceFrameTiming")}} interface extends the following {{domxref("PerformanceEntry")}} properties (for "<code>frame</code>" {{domxref("PerformanceEntry.entryType","performance entry types")}}) by qualifying and constrainting the properties as follows:</p>
<dl>
<dt>{{domxref("PerformanceEntry.entryType")}}</dt>
<dd>Set to "<code>frame</code>".</dd>
<dt>{{domxref("PerformanceEntry.name")}}</dt>
<dd>Set to the <a href="https://dom.spec.whatwg.org/#concept-document-url">document's address</a>.</dd>
<dt>{{domxref("PerformanceEntry.startTime")}}</dt>
<dd>Set to the {{domxref("DOMHighResTimeStamp")}} when the frame was started.</dd>
<dt>{{domxref("PerformanceEntry.duration")}}</dt>
<dd>Set to a {{domxref("DOMHighResTimeStamp","timestamp")}} indicating the difference between the <code>startTime</code>s of two successive frames.</dd>
</dl>
<p>This data, particularly the <code>duration</code> timestamp, can be used to help identify performance problems.</p>
<h2 id="Frame_observers">Frame observers</h2>
<p>{{experimental_inline}}The <em>performance observer</em> interfaces allow an application to register an <em>observer</em> for specific {{domxref("PerformanceEntry","performance event types")}}. When one of those event types is recorded in the browser's <em>performance timeline</em>, the application is notified of the event via the observer's callback function that was specified when the observer was created.</p>
<p>To observe "<code>frame</code>" performance entry types, the application first creates a {{domxref("PerformanceObserver")}} object with a specific frame observer callback (function). Next, {{domxref("PerformanceObserver.observe()")}} is used to specify the set of performance events to observe - in this case, just the "<code>frame</code>" event type. When the browser adds a new frame to the performance timeline, the specified observer callback will be invoked.</p>
<h2 id="Accessing_frame_data">Accessing frame data</h2>
<p>When a frame {{domxref("PerformanceObserver","observer")}} is invoked, frame {{domxref("PerformanceEntry","performance entries")}} can be retrieved by calling {{domxref("PerformanceObserverEntryList.getEntriesByType()")}} with an argument of "<code>frame</code>". This method returns a list of "<code>frame</code>" {{domxref("PerformanceEntry")}} objects. Each frame object's {{domxref("PerformanceEntry.duration","duration")}} property returns the timestamp of two consecutive frames. If this value is greater than the time needed to provide a good user experience, further analysis might be warranted.</p>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{experimental_inline}}As shown in the {{domxref("PerformanceFrameTiming")}} interface's <a href="/Web/API/PerformanceFrameTiming#Browser_compatibility">Browser Compatibility</a> table, this interface has no implementations.</p>
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/docs/Tools/Performance/Frame_rate">Frame Rate (Firefox Performance Tool)</a></li>
<li><a href="/Web/API/Frame_Timing_API/Using_the_Frame_Timing_API">Using the Frame Timing API</a></li>
</ul>
|
