Skip to content

Commit 230f64f

Browse files
Philipel-WebRTCPhilipel-WebRTC
committed
Merge the API into one file
1 parent 0c18a92 commit 230f64f

File tree

3 files changed

+180
-192
lines changed

3 files changed

+180
-192
lines changed

‎api-outline.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# API Outline
2+
3+
```javascript
4+
interface RtpPacket {
5+
constructor(required RtpPacketInit);
6+
readonly attribute bool marker;
7+
readonly attribute octet payloadType;
8+
readonly attribute unsigned short sequenceNumber;
9+
readonly attribute unsigned long timestamp;
10+
readonly attribute unsigned long ssrc;
11+
readonly attribute sequence<unsigned long> csrcs;
12+
readonly attribute sequence<RtpHeaderExtension> headerExtensions;
13+
14+
// Write payload to the specified (Shared-)ArrayBuffer/ArrayBufferView,
15+
// allowing for BYOB.
16+
undefined copyPayloadTo(AllowSharedBufferSource destination);
17+
18+
// OPTIONAL: Duplicate with header extensions, but conveniently parsed
19+
readonly attribute DOMString? mid;
20+
readonly attribute DOMString? rid;
21+
attribute octet? audioLevel;
22+
attribute octet? videoRotation;
23+
readonly attribute unsigned long long? remoteSendTimestamp;
24+
25+
// OPTIONAL: Extra information that may be useful to know
26+
readonly attribute DOMHighResTimeStamp receivedTime;
27+
readonly attribute unsigned long sequenceNumberRolloverCount;
28+
29+
void setHeaderExtension(RtpHeaderExtension);
30+
}
31+
32+
interface RtpHeaderExtension {
33+
constructor(required RtpHeaderExtensionInit);
34+
readonly attribute DOMString uri;
35+
readonly attribute ArrayBuffer value;
36+
undefined copyValueTo(AllowSharedBufferSource destination);
37+
}
38+
39+
dictionary RtpPacketInit {
40+
bool marker = false;
41+
required octet payloadType;
42+
required unsigned long timestamp;
43+
sequence<unsigned long> csrcs = [];
44+
// Cannot be MID, RID, or congestion control sequence number
45+
sequence<RtpHeaderExtensionInit> headerExtensions = [];
46+
required AllowSharedBufferSource payload;
47+
48+
// Convenience for adding to headerExtensions
49+
octet audioLevel;
50+
octet videoRotation;
51+
}
52+
53+
dictionary RtpHeaderExtensionInit {
54+
required DOMString uri;
55+
required AllowSharedBufferSource value;
56+
}
57+
58+
```
59+
### PeerConnection, RtpSendStream, RtpReceiveStream Extensions
60+
61+
```javascript
62+
partial interface PeerConnection {
63+
// There may be an RtpTransport with no RtpSenders and no RtpReceivers.
64+
readonly attribute RtpTransport? rtpTransport;
65+
}
66+
67+
// Add this to RTCConfiguration
68+
dictionary RTCConfiguration {
69+
// Means "continue to encode and packetize packets, but don't send them.
70+
// Instead give them to me via onpacketizedrtpavailable/readPacketizedRtp
71+
// and I will send them."
72+
// TODO: Think of a better name
73+
bool customPacer;
74+
}
75+
76+
partial interface RtpSender {
77+
// shared between RtpSenders in the same BUNDLE group
78+
readonly attribute RtpTransport? rtpTransport;
79+
Promise<sequence<RtpSendStream>> replaceSendStreams();
80+
}
81+
82+
partial interface RtpReceiver {
83+
// shared between RtpSenders in the same BUNDLE group
84+
readonly attribute RtpTransport? rtpTransport;
85+
Promise<sequence<RtpReceiveStream>> replaceReceiveStreams();
86+
}
87+
88+
interface RtpTransport {
89+
Promise<RtpSendStream> addRtpSendStream(RtpSendStreamInit);
90+
Promise<RtpReceiveStream> addRtpReceiveStream(RtpReceiveStreamInit);
91+
attribute EventHandler onrtpsent; // RtpSent
92+
attribute EventHandler onrtpacksreceived; // RtpAcks
93+
attribute EventHandler onpacketizedrtpavailable; // No payload. Call readPacketizedRtp
94+
sequence<RtpPacket> readPacketizedRtp(maxNumberOfPackets);
95+
96+
readonly attribute unsigned long bandwidthEstimate; // bps
97+
readonly attribute unsigned long allocatedBandwidth; // bps
98+
attribute unsigned long customAllocatedBandwidth; // writable
99+
// Means "when doing bitrate allocation and rate control, don't use more than this"
100+
attribute unsigned long customMaxBandwidth;
101+
// Means "make each packet smaller by this much so I can put custom stuff in each packet"
102+
attribute unsigned long customPerPacketOverhead;
103+
}
104+
105+
// RFC 8888 or Transport-cc feedback
106+
interface RtpAcks {
107+
readonly attribute sequence<RtpAck> acks;
108+
readonly attribute unsigned long long remoteSendTimestamp;
109+
readonly attribute DOMHighResTimeStamp receivedTime;
110+
readonly attribute ExplicitCongestionNotification explicitCongestionNotification; // AKA "ECN"
111+
}
112+
113+
interface RtpAck {
114+
// Correlated with RtpSent.ackId
115+
readonly attribute unsigned long long ackId;
116+
readonly attribute unsigned long long remoteReceiveTimestamp;
117+
}
118+
119+
// See RFC 3991 and RFC 3168
120+
enum ExplicitCongestionNotification {
121+
// ECT = ECN-Capable Transport
122+
"unset", // AKA "Not-ECT"; Bits: 00
123+
"scalable-congestion-not-experienced", // AKA "ECT(1)" or "Scalable" or "L4S" ; Bits: 01
124+
"classic-congestion-not-experienced", // AKA "ECT(0)" or "Classic" or "not L4S"; Bits: 10
125+
"congestion-experienced" // AKA "CE" or "ECN-marked" or "marked"; Bits: 11
126+
}
127+
128+
[Exposed=(Window,Worker), Transferable]
129+
interface RtpSendStream {
130+
readonly attribute DOMString mid?; // Shared among many RtpSendStreams
131+
readonly attribute DOMString rid?; // Unique to RtpSendStream (scoped to MID)
132+
readonly attribute unsigned long ssrc;
133+
readonly attribute unsigned long rtxSsrc;
134+
135+
attribute EventHandler onpacketizedrtp;
136+
sequence<RtpPacket> readPacketizedRtp(long maxNumberOfPackets);
137+
138+
// https://github.com/w3c/webrtc-rtptransport/issues/32
139+
void sendRtp(RtpPacket packet);
140+
Promise<RtpSendResult> sendRtp(RtpPacketInit packet, RtpSendOptions options);
141+
142+
// Amount allocated by the browser
143+
readonly attribute unsigned long allocatedBandwidth;
144+
}
145+
146+
interface RtpSendResult {
147+
readonly attribute RtpSent sent?;
148+
readonly attribute RtpUnsentReason unsent?;
149+
}
150+
151+
interface RtpSent {
152+
readonly attribute DOMHighResTimeStamp time;
153+
154+
// Can be correlated with acks
155+
readonly attribute unsigned long long ackId?;
156+
readonly attribute unsigned long long size;
157+
}
158+
159+
enum RtpUnsentReason {
160+
"overuse",
161+
"transport-unavailable",
162+
};
163+
164+
dictionary RtpSendOptions {
165+
DOMHighResTimeStamp sendTime;
166+
}
167+
168+
[Exposed=(Window,Worker), Transferable]
169+
interface RtpReceiveStream {
170+
readonly attribute DOMString mid?; // Shared among many RtpReceivetreams
171+
readonly attribute DOMString rid?; // Unique to RtpReceiveStream (scoped to MID)
172+
readonly attribute sequence<unsigned long> ssrcs;
173+
readonly attribute sequence<unsigned long> rtxSsrcs;
174+
175+
attribute EventHandler onreceivedrtp;
176+
sequence<RtpPacket> readReceivedRtp(long maxNumberOfPackets);
177+
178+
void receiveRtp(RtpPacket packet)
179+
}
180+
```

‎explainer-use-case-1.md‎

Lines changed: 0 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -34,123 +34,6 @@ Complexities of sending and receiving RTP other than these requirements are stil
3434
particular Pacing of sent packets on the wire, inclusion of padding to support bandwidth probing, and RTP Sequence
3535
Numbering taking into account such padding.
3636

37-
## API Outline
38-
39-
### RtpPacket, RtcpPacket
40-
41-
```javascript
42-
interface RtpPacket {
43-
constructor(required RtpPacketInit);
44-
readonly attribute bool marker;
45-
readonly attribute octet payloadType;
46-
readonly attribute unsigned short sequenceNumber;
47-
readonly attribute unsigned long timestamp;
48-
readonly attribute unsigned long ssrc;
49-
readonly attribute sequence<unsigned long> csrcs;
50-
readonly attribute sequence<RtpHeaderExtension> headerExtensions;
51-
52-
// Write payload to the specified (Shared-)ArrayBuffer/ArrayBufferView,
53-
// allowing for BYOB.
54-
undefined copyPayloadTo(AllowSharedBufferSource destination);
55-
56-
// OPTIONAL: Duplicate with header extensions, but conveniently parsed
57-
readonly attribute DOMString? mid;
58-
readonly attribute DOMString? rid;
59-
attribute octet? audioLevel;
60-
attribute octet? videoRotation;
61-
readonly attribute unsigned long long? remoteSendTimestamp;
62-
63-
// OPTIONAL: Extra information that may be useful to know
64-
readonly attribute DOMHighResTimeStamp receivedTime;
65-
readonly attribute unsigned long sequenceNumberRolloverCount;
66-
67-
void setHeaderExtension(RtpHeaderExtension);
68-
}
69-
70-
interface RtpHeaderExtension {
71-
constructor(required RtpHeaderExtensionInit);
72-
readonly attribute DOMString uri;
73-
undefined copyValueTo(AllowSharedBufferSource destination);
74-
}
75-
76-
dictionary RtpPacketInit {
77-
bool marker = false;
78-
required octet payloadType;
79-
required unsigned long timestamp;
80-
sequence<unsigned long> csrcs = [];
81-
// Cannot be MID, RID, or congestion control sequence number
82-
sequence<RtpHeaderExtensionInit> headerExtensions = [];
83-
required AllowSharedBufferSource payload;
84-
85-
// Convenience for adding to headerExtensions
86-
octet audioLevel;
87-
octet videoRotation;
88-
}
89-
90-
dictionary RtpHeaderExtensionInit {
91-
required DOMString uri;
92-
required AllowSharedBufferSource value;
93-
}
94-
95-
```
96-
### RTCPeerConnection, RTCRtpSender, RTCRtpReceiver Extensions
97-
98-
```javascript
99-
partial interface PeerConnection {
100-
// There may be an RtpTransport with no RtpSenders and no RtpReceivers.
101-
readonly attribute RtpTransport? rtpTransport;
102-
}
103-
partial interface RtpSender {
104-
// shared between RtpSenders in the same BUNDLE group
105-
readonly attribute RtpTransport? rtpTransport;
106-
Promise<sequence<RtpSendStream>> replaceSendStreams();
107-
}
108-
partial interface RtpReceiver {
109-
// shared between RtpSenders in the same BUNDLE group
110-
readonly attribute RtpTransport? rtpTransport;
111-
Promise<sequence<RtpReceiveStream>> replaceReceiveStreams();
112-
}
113-
114-
interface RtpTransport {
115-
Promise<RtpSendStream> addRtpSendStream(RtpSendStreamInit);
116-
Promise<RtpReceiveStream> addRtpReceiveStream(RtpReceiveStreamInit);
117-
readonly attribute unsigned long bandwidthEstimate; // bps
118-
readonly attribute unsigned long allocatedBandwidth; // bps
119-
attribute unsigned long customAllocatedBandwidth; // writable
120-
}
121-
122-
[Exposed=(Window,Worker), Transferable]
123-
interface RtpSendStream {
124-
readonly attribute DOMString mid?; // Shared among many RtpSendStreams
125-
readonly attribute DOMString rid?; // Unique to RtpSendStream (scoped to MID)
126-
readonly attribute unsigned long ssrc;
127-
readonly attribute unsigned long rtxSsrc;
128-
129-
attribute EventHandler onpacketizedrtp;
130-
sequence<RtpPacket> readPacketizedRtp(long maxNumberOfPackets);
131-
132-
// Takes a synchronous copy of packet.payload and packet.headerExtensions[*].value,
133-
// allowing the underlying buffers to be reused immediately.
134-
void sendRtp(RtpPacket packet);
135-
136-
// Amount allocated by the browser
137-
readonly attribute unsigned long allocatedBandwidth;
138-
}
139-
140-
[Exposed=(Window,Worker), Transferable]
141-
interface RtpReceiveStream {
142-
readonly attribute DOMString mid?; // Shared among many RtpReceivetreams
143-
readonly attribute DOMString rid?; // Unique to RtpReceiveStream (scoped to MID)
144-
readonly attribute sequence<unsigned long> ssrcs;
145-
readonly attribute sequence<unsigned long> rtxSsrcs;
146-
147-
attribute EventHandler onreceivedrtp;
148-
sequence<RtpPacket> readReceivedRtp(long maxNumberOfPackets);
149-
150-
void receiveRtp(RtpPacket packet)
151-
}
152-
```
153-
15437
## Examples
15538

15639
### Example 1: Send customized RTP header extension (audio level)

‎explainer-use-case-2.md‎

Lines changed: 0 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -19,81 +19,6 @@ Applications can do custom bandwidth estimation via:
1919
- Knowledge of when an application packet is not sent, and why.
2020
- Efficient control of when packets are sent, in order to do custom pacing and probing.
2121

22-
## API Outline
23-
24-
25-
```javascript
26-
partial interface RtpSendStream {
27-
Promise<RtpSendResult> sendRtp(RtpPacketInit packet, RtpSendOptions options);
28-
}
29-
30-
dictionary RtpSendOptions {
31-
DOMHighResTimeStamp sendTime;
32-
}
33-
34-
interface RtpSendResult {
35-
readonly attribute RtpSent sent?;
36-
readonly attribute RtpUnsentReason unsent?;
37-
}
38-
39-
interface RtpSent {
40-
readonly attribute DOMHighResTimeStamp time;
41-
42-
// Can be correlated with acks
43-
readonly attribute unsigned long long ackId?;
44-
readonly attribute unsigned long long size;
45-
}
46-
47-
enum RtpUnsentReason {
48-
"overuse",
49-
"transport-unavailable",
50-
};
51-
52-
// Add this to RTCConfiguration
53-
dictionary RTCConfiguration {
54-
// Means "continue to encode and packetize packets, but don't send them.
55-
// Instead give them to me via onpacketizedrtpavailable/readPacketizedRtp
56-
// and I will send them."
57-
// TODO: Think of a better name
58-
bool customPacer;
59-
}
60-
61-
partial interface RtpTransport {
62-
attribute EventHandler onrtpsent; // RtpSent
63-
attribute EventHandler onrtpacksreceived; // RtpAcks
64-
// Means "when doing bitrate allocation and rate control, don't use more than this"
65-
attribute unsigned long customMaxBandwidth;
66-
// Means "make each packet smaller by this much so I can put custom stuff in each packet"
67-
attribute unsigned long customPerPacketOverhead;
68-
69-
attribute EventHandler onpacketizedrtpavailable; // No payload. Call readPacketizedRtp
70-
sequence<RtpPacket> readPacketizedRtp(maxNumberOfPackets);
71-
}
72-
73-
// RFC 8888 or Transport-cc feedback
74-
interface RtpAcks {
75-
readonly attribute sequence<RtpAck> acks;
76-
readonly attribute unsigned long long remoteSendTimestamp;
77-
readonly attribute DOMHighResTimeStamp receivedTime;
78-
readonly attribute ExplicitCongestionNotification explicitCongestionNotification; // AKA "ECN"
79-
}
80-
81-
interface RtpAck {
82-
// Correlated with RtpSent.ackId
83-
readonly attribute unsigned long long ackId;
84-
readonly attribute unsigned long long remoteReceiveTimestamp;
85-
}
86-
87-
// See RFC 3991 and RFC 3168
88-
enum ExplicitCongestionNotification {
89-
// ECT = ECN-Capable Transport
90-
"unset", // AKA "Not-ECT"; Bits: 00
91-
"scalable-congestion-not-experienced", // AKA "ECT(1)" or "Scalable" or "L4S" ; Bits: 01
92-
"classic-congestion-not-experienced", // AKA "ECT(0)" or "Classic" or "not L4S"; Bits: 10
93-
"congestion-experienced" // AKA "CE" or "ECN-marked" or "marked"; Bits: 11
94-
}
95-
```
96-
9722
## Examples
9823

9924
## Example 1: Custom BWE

0 commit comments

Comments
 (0)