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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
---
title: RTCTrackEvent
slug: Web/API/RTCTrackEvent
tags:
- API
- Interface
- Media
- NeedsTranslation
- RTCTrackEvent
- Reference
- TopicStub
- WebRTC
- WebRTC API
- events
- rtc
- track
translation_of: Web/API/RTCTrackEvent
---
<div>{{APIRef("WebRTC")}}</div>
<p><span class="seoSummary">The <a href="/en-US/docs/Web/API/WebRTC_API">WebRTC API</a> interface <code><strong>RTCTrackEvent</strong></code> represents the {{event("track")}} event, which is sent when a new {{domxref("MediaStreamTrack")}} is added to an {{domxref("RTCRtpReceiver")}} which is part of the {{domxref("RTCPeerConnection")}}.</span> The target is the <code>RTCPeerConnection</code> object to which the track is being added.</p>
<p>This event is sent by the WebRTC layer to the web site or application, so you will not typically need to instantiate an <code>RTCTrackEvent</code> yourself.</p>
<h2 id="Constructor">Constructor</h2>
<dl>
<dt>{{domxref("RTCTrackEvent.RTCTrackEvent", "RTCTrackEvent()")}}</dt>
<dd>Creates and returns a new <code>RTCTrackEvent</code> object, initialized with properties taken from the specified {{domxref("RTCTrackEventInit")}} dictionary. You will probably not need to create new track events yourself, since they're typically created by the WebRTC infrastructure and sent to the connection's {{domxref("RTCPeerConnection.ontrack", "ontrack")}} event handler.</dd>
</dl>
<h2 id="Properties">Properties</h2>
<p><em>Since <code>RTCTrackEvent</code> is based on {{domxref("Event")}}, its properties are also available.</em></p>
<dl>
<dt>{{domxref("RTCTrackEvent.receiver", "receiver")}} {{ReadOnlyInline}}</dt>
<dd>The {{domxref("RTCRtpReceiver")}} used by the track that's been added to the <code>RTCPeerConnection</code>.</dd>
<dt>{{domxref("RTCTrackEvent.streams", "streams")}} {{ReadOnlyInline}} {{optional_inline}}</dt>
<dd>An array of {{domxref("MediaStream")}} objects, each representing one of the media streams to which the added {{domxref("RTCTrackEvent.track", "track")}} belongs. By default, the array is empty, indicating a streamless track.</dd>
<dt>{{domxref("RTCTrackEvent.track", "track")}} {{ReadOnlyInline}}</dt>
<dd>The {{domxref("MediaStreamTrack")}} which has been added to the connection.</dd>
<dt>{{domxref("RTCTrackEvent.transceiver", "transceiver")}} {{ReadOnlyInline}}</dt>
<dd>The {{domxref("RTCRtpTransceiver")}} being used by the new track.</dd>
</dl>
<h2 id="Track_event_types">Track event types</h2>
<p>There is only one type of track event.</p>
<h3 id="track"><code>track</code></h3>
<p>The {{domxref("RTCPeerConnection.track_event", "track")}} event is sent to the {{domxref("RTCPeerConnection")}} when a new track has been added to the connection. By the time the <code>track</code> event is delivered to the <code>RTCPeerConnection</code>'s {{domxref("RTCPeerConnection.ontrack", "ontrack")}} handler, the new media has completed its negotiation for a specific {{domxref("RTCRtpReceiver")}} (which is specified by the event's {{domxref("RTCTrackEvent.receiver", "receiver")}} property).</p>
<p>In addition, the {{domxref("MediaStreamTrack")}} specified by the receiver's {{domxref("RTCRtpReceiver.track", "track")}} is the same one specified by the event's {{domxref("RTCTrackEvent.track", "track")}}, and the track has been added to any associated remote {{domxref("MediaStream")}} objects.</p>
<p>You can add a <code>track</code> event listener to be notified when the new track is available so that you can, for example, attach its media to a {{HTMLElement("video")}} element, using either {{domxref("EventTarget.addEventListener", "RTCPeerConnection.addEventListener()")}} or the <code>ontrack</code> event handler property.</p>
<div class="note">
<p><strong>Note:</strong> It may be helpful to keep in mind that you receive the <code>track</code> event when a new inbound track has been added to your connection, and you call {{domxref("RTCPeerConnection.addTrack", "addTrack()")}} to add a track to the far end of the connection, thereby triggering a <code>track</code> event on the remote peer.</p>
</div>
<h2 id="Example">Example</h2>
<p>This simple example creates an event listener for the {{domxref("RTCPeerConnection.track_event", "track")}} event which sets the {{domxref("HTMLMediaElement.srcObject", "srcObject")}} of the {{HTMLElement("video")}} element with the ID <code>videobox</code> to the first stream in the list passed in the event's {{domxref("RTCTrackEvent.streams", "streams")}} array.</p>
<pre class="brush: js notranslate">peerConnection.addEventListener("track", e => {
let videoElement = document.getElementById("videobox");
videoElement.srcObject = e.streams[0];
}, false);</pre>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<thead>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>{{SpecName('WebRTC 1.0', '#dom-rtctrackevent', 'RTCTrackEvent')}}</td>
<td>{{Spec2('WebRTC 1.0')}}</td>
<td>Initial specification.</td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{Compat("api.RTCTrackEvent")}}</p>
|
