From 2808060fe15cf92aee7a2818017b9f12762accf4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?I=C3=B1aki=20Baz=20Castillo?= Date: Tue, 31 Oct 2023 13:49:46 +0100 Subject: [PATCH 1/6] mediasoup: document new `ListenInfo` object --- .../v3/mediasoup/api/PipeTransport.md | 5 +++ .../v3/mediasoup/api/PlainTransport.md | 2 ++ .../documentation/v3/mediasoup/api/Router.md | 31 +++++++++++++------ .../v3/mediasoup/api/Transport.md | 25 ++++++++++++++- .../v3/mediasoup/api/WebRtcServer.md | 24 ++------------ .../v3/mediasoup/api/WebRtcTransport.md | 9 ++++-- 6 files changed, 61 insertions(+), 35 deletions(-) diff --git a/_includes/documentation/v3/mediasoup/api/PipeTransport.md b/_includes/documentation/v3/mediasoup/api/PipeTransport.md index 5a517bc..b27d468 100644 --- a/_includes/documentation/v3/mediasoup/api/PipeTransport.md +++ b/_includes/documentation/v3/mediasoup/api/PipeTransport.md @@ -26,6 +26,7 @@ When calling [consume()](#transport-consume) on a pipe transport, all RTP stream Field | Type | Description | Required | Default ------------- | ------- | ------------- | -------- | --------- +`listenInfo` | [TransportListenInfo](#TransportListenInfo)| Listening information. | Yes | `listenIp` | [TransportListenIp](#TransportListenIp)\|String| Listening IP address. | Yes | `port` | Number | Fixed port to listen on instead of selecting automatically from Worker's port range. | No | `enableSctp` | Boolean | Create a SCTP association. | No | `false` @@ -38,6 +39,10 @@ Field | Type | Description | Required | Default +
+* `listenIp` and `port` are **DEPRECATED**. Use `listenInfo` instead. +
+ diff --git a/_includes/documentation/v3/mediasoup/api/PlainTransport.md b/_includes/documentation/v3/mediasoup/api/PlainTransport.md index a248943..c8897fd 100644 --- a/_includes/documentation/v3/mediasoup/api/PlainTransport.md +++ b/_includes/documentation/v3/mediasoup/api/PlainTransport.md @@ -22,6 +22,7 @@ A plain transport represents a network path through which RTP, RTCP (optionally Field | Type | Description | Required | Default ------------- | ------- | ------------- | -------- | --------- +`listenInfo` | [TransportListenInfo](#TransportListenInfo)| Listening information. | Yes | `listenIp` | [TransportListenIp](#TransportListenIp)\|String| Listening IP address. | Yes | `port` | Number | Fixed port to listen on instead of selecting automatically from Worker's port range. | No | `rtcpMux` | Boolean | Use RTCP-mux (RTP and RTCP in the same port). | No | `true` @@ -37,6 +38,7 @@ Field | Type | Description | Required | Default
+* `listenIp` and `port` are **DEPRECATED**. Use `listenInfo` instead. * Note that `comedia` mode just makes sense when the remote endpoint is gonna produce RTP on this plain transport. Otherwise, if the remote endpoint does not send any RTP (or SCTP) packet to mediasoup, there is no way to detect its remote RTP IP and port, so the endpoint won't receive any packet from mediasoup. * In other words, do not use `comedia` mode if the remote endpoint is not going to produce RTP but just consume it. In those cases, do not set `comedia` flag and call [connect()](#plainTransport-connect) with the IP and port(s) of the remote endpoint.
diff --git a/_includes/documentation/v3/mediasoup/api/Router.md b/_includes/documentation/v3/mediasoup/api/Router.md index d04cb98..d81c0d6 100644 --- a/_includes/documentation/v3/mediasoup/api/Router.md +++ b/_includes/documentation/v3/mediasoup/api/Router.md @@ -44,6 +44,7 @@ Field | Type | Description | Required | Default `producerId` | String | Producer id. | No | `dataProducerId` | String | Data producer id. | No | `router` | [Router](#Router) | Destination router to pipe the given producer. | Yes | +`listenInfo` | [TransportListenInfo](#TransportListenInfo)| Listening information to connect both routers in the same host. | No | `{ protocol: "udp", ip: "127.0.0.1" }` `listenIp` | String | IP to connect both routers in the same host. | No | "127.0.0.1" `enableSctp` | Boolean | Create a SCTP association. | No | `true` `numSctpStreams` | [NumSctpStreams](#NumSctpStreams) | SCTP streams number. | No | @@ -53,6 +54,7 @@ Field | Type | Description | Required | Default
+* `listenIp` is **DEPRECATED**. Use `listenInfo` instead. * Only one of `producerId` and `dataProducerId` must be provided. * SCTP arguments will only apply the first time the underlying transports are created.
@@ -167,12 +169,23 @@ TypeScript argument | Type | Description | Required | Default ```javascript const transport = await router.createWebRtcTransport( { - // Use webRtcServer or listenIps webRtcServer : webRtcServer - listenIps : [ { ip: "192.168.0.111", announcedIp: "88.12.10.41" } ], enableUdp : true, - enableTcp : true, - preferUdp : true + enableTcp : false + }); +``` + +```javascript +const transport = await router.createWebRtcTransport( + { + listenInfos : + [ + { + protocol : "udp", + ip : "192.168.0.111", + announcedIp : "88.12.10.41" + } + ] }); ``` @@ -205,9 +218,9 @@ TypeScript argument | Type | Description | Required | Default ```javascript const transport = await router.createPlainTransport( { - listenIp : "a1:22:aA::08", - rtcpMux : true, - comedia : true + listenInfo : { protocol: "udp", ip: "a1:22:aA::08" }, + rtcpMux : true, + comedia : true }); ``` @@ -240,7 +253,7 @@ TypeScript argument | Type | Description | Required | Default ```javascript const transport = await router.createPipeTransport( { - listenIp : "192.168.1.33" + listenInfo : { protocol: "udp", ip: "192.168.1.33" }, }); ``` @@ -274,7 +287,7 @@ TypeScript argument | Type | Description | Required | Default const transport = await router.createDirectTransport(); ``` -#### router.pipeToRouter({ producerId, dataProducerId, router, listenIp }) +#### router.pipeToRouter(options) {: #router-pipeToRouter .code} Pipes the given media or data producer into another router in the same host. It creates an underlying [PipeTransport](#PipeTransport) (if not previously created) that interconnects both routers. diff --git a/_includes/documentation/v3/mediasoup/api/Transport.md b/_includes/documentation/v3/mediasoup/api/Transport.md index a2c5964..964b3ee 100644 --- a/_includes/documentation/v3/mediasoup/api/Transport.md +++ b/_includes/documentation/v3/mediasoup/api/Transport.md @@ -22,6 +22,28 @@ mediasoup implements the following transport classes:
+#### TransportListenInfo +{: #TransportListenInfo .code} + +
+ +Field | Type | Description | Required | Default +------------- | ------- | ------------- | -------- | --------- +`protocol` | String | Protocol ("udp" / "tcp"). | Yes | +`ip` | String | Listening IPv4 or IPv6. | Yes | +`announcedIp` | String | Announced IPv4 or IPv6 (useful when running mediasoup behind NAT with private IP). | No | +`port` | Number | Listening port. | No | If not given, a random available port from the Worker's port range will be used. +`sendBufferSize` | Number | Send buffer size (in bytes). | No | +`recvBufferSize` | Number | Receive buffer size (in bytes). | No | + +
+ +
+If you use "0.0.0.0" or "::" as `ip` value, then you need to also provide `announcedIp`. +
+ +
+ #### TransportListenIp {: #TransportListenIp .code} @@ -35,7 +57,8 @@ Field | Type | Description | Required | Default
-If you use "0.0.0.0" or "::" as `ip` value, then you need to also provide `announcedIp`. +* **DEPRECATED:** Use [TransportListenInfo](#TransportListenInfo) instead. +* If you use "0.0.0.0" or "::" as `ip` value, then you need to also provide `announcedIp`.
#### TransportTuple diff --git a/_includes/documentation/v3/mediasoup/api/WebRtcServer.md b/_includes/documentation/v3/mediasoup/api/WebRtcServer.md index e75745d..f7fe77d 100644 --- a/_includes/documentation/v3/mediasoup/api/WebRtcServer.md +++ b/_includes/documentation/v3/mediasoup/api/WebRtcServer.md @@ -3,7 +3,7 @@
-A WebRTC server brings the ability to listen on a single UDP/TCP port to [WebRtcTransports](#WebRtcTransport). Instead of passing `listenIps` to [router.createWebRtcTransport()](#router-createWebRtcTransport) pass `webRtcServer` with an instance of a `WebRtcServer` so the new WebRTC transport will not listen on its own IP:port(s) but will have its network traffic handled by the WebRTC server instead. +A WebRTC server brings the ability to listen on a single UDP/TCP port to [WebRtcTransports](#WebRtcTransport). Instead of passing `listenInfos` to [router.createWebRtcTransport()](#router-createWebRtcTransport) pass `webRtcServer` with an instance of a `WebRtcServer` so the new WebRTC transport will not listen on its own IP:port(s) but will have its network traffic handled by the WebRTC server instead.
* A WebRTC server exists within the context of a [Worker](#Worker), meaning that if your app launches N workers it also needs to create N WebRTC servers listening on different ports (to not collide). @@ -12,26 +12,6 @@ A WebRTC server brings the ability to listen on a single UDP/TCP port to [WebRtc
- -### Dictionaries -{: #WebRtcServer-dictionaries} - -
- -#### WebRtcServerListenInfo -{: #WebRtcServerListenInfo .code} - -
- -Field | Type | Description | Required | Default -------------- | ------- | ------------- | -------- | --------- -`protocol` | String | Protocol ("udp" / "tcp"). | Yes | -`ip` | String | Listening IPv4 or IPv6. | Yes | -`announcedIp` | String | Announced IPv4 or IPv6 (useful when running mediasoup behind NAT with private IP). | No | -`port` | Number | Listening port. | No | If not given, a random available port from the Worker's port range will be used. - -
- #### WebRtcServerOptions {: #WebRtcServerOptions .code} @@ -39,7 +19,7 @@ Field | Type | Description | Required | Default Field | Type | Description | Required | Default ------------ | ------- | ------------- | -------- | --------- -`listenInfos` | Array<[WebRtcServerListenInfo](#WebRtcServerListenInfo)> | Listening protocol, IP and port objects in order of preference (first one is the preferred one). | Yes | +`listenInfos` | Array<[TransportListenInfo](#TransportListenInfo)\|String> | Listening information in order of preference (first one is the preferred one). | No | `appData` | [AppData](#AppData) | Custom application data. | No | `{ }` diff --git a/_includes/documentation/v3/mediasoup/api/WebRtcTransport.md b/_includes/documentation/v3/mediasoup/api/WebRtcTransport.md index aecac3e..10d44bb 100644 --- a/_includes/documentation/v3/mediasoup/api/WebRtcTransport.md +++ b/_includes/documentation/v3/mediasoup/api/WebRtcTransport.md @@ -27,6 +27,7 @@ The WebRTC transport implementation of mediasoup is [ICE Lite](https://tools.iet Field | Type | Description | Required | Default ------------ | ------- | ------------- | -------- | --------- `webRtcServer` | [WebRtcServer](#WebRtcServer) | Instead of opening its own listening port(s) let a WebRTC server handle the network traffic of this transport. | No | +`listenInfos` | Array<[TransportListenInfo](#TransportListenInfo)\|String> | Listening information in order of preference (first one is the preferred one). | No | `listenIps` | Array<[TransportListenIp](#TransportListenIp)\|String> | Listening IP address or addresses in order of preference (first one is the preferred one). | No | `port` | Number | Fixed port to listen on instead of selecting automatically from Worker's port range. | No | `enableUdp` | Boolean | Listen in UDP. | No | `true` @@ -43,10 +44,12 @@ Field | Type | Description | Required | Default
-* One of `webRtcServer` or `listenIps` must be given when creating a WebRTC transport. -* The IP in each entry in `listenIps` must be a bindable IP in the host. -* If you use "0.0.0.0" or "::" in an entry in `listenIps`, then you need to also provide `announcedIp` in the corresponding entry in `listenIps`. +* `listenIps` is **DEPRECATED**. Use `listenInfos` instead. +* One of `webRtcServer` or `listenInfos` or `listenIps` must be given when creating a WebRTC transport. +* The IP in each entry in `listenInfos` or `listenIps` must be a bindable IP in the host. +* If you use "0.0.0.0" or "::" in an entry in `listenInfos` or `listenIps`, then you need to also provide `announcedIp` in the corresponding entry. * `initialAvailableOutgoingBitrate` is just applied when the consumer endpoint supports REMB or Transport-CC. +* `enableUdp`, `enableTcp`, `preferUdp` and `preferTcp` are only processed if `webRtcServer` is given, and they filter and define the priority of the ICE candidates available in the `webRtcServer`.
From 94fe22ee5eba76f1d4976629c0d12dc406ca0ffd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?I=C3=B1aki=20Baz=20Castillo?= Date: Tue, 31 Oct 2023 14:14:28 +0100 Subject: [PATCH 2/6] mediasoup PlainTransportOptions: document new rtcpListenInfo --- _includes/documentation/v3/mediasoup/api/PlainTransport.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_includes/documentation/v3/mediasoup/api/PlainTransport.md b/_includes/documentation/v3/mediasoup/api/PlainTransport.md index c8897fd..c16747d 100644 --- a/_includes/documentation/v3/mediasoup/api/PlainTransport.md +++ b/_includes/documentation/v3/mediasoup/api/PlainTransport.md @@ -23,6 +23,7 @@ A plain transport represents a network path through which RTP, RTCP (optionally Field | Type | Description | Required | Default ------------- | ------- | ------------- | -------- | --------- `listenInfo` | [TransportListenInfo](#TransportListenInfo)| Listening information. | Yes | +`rtcpListenInfo` | [TransportListenInfo](#TransportListenInfo)| RTCP listening information. If not given and `rtcpPort` is not `false`, RTCP will use same listening info than RTP. | No | `listenIp` | [TransportListenIp](#TransportListenIp)\|String| Listening IP address. | Yes | `port` | Number | Fixed port to listen on instead of selecting automatically from Worker's port range. | No | `rtcpMux` | Boolean | Use RTCP-mux (RTP and RTCP in the same port). | No | `true` @@ -39,6 +40,7 @@ Field | Type | Description | Required | Default
* `listenIp` and `port` are **DEPRECATED**. Use `listenInfo` instead. +* `rtcpPort` is **DEPRECATED**. Use `rtcpListenInfo` instead to setup different listening information for RTCP. * Note that `comedia` mode just makes sense when the remote endpoint is gonna produce RTP on this plain transport. Otherwise, if the remote endpoint does not send any RTP (or SCTP) packet to mediasoup, there is no way to detect its remote RTP IP and port, so the endpoint won't receive any packet from mediasoup. * In other words, do not use `comedia` mode if the remote endpoint is not going to produce RTP but just consume it. In those cases, do not set `comedia` flag and call [connect()](#plainTransport-connect) with the IP and port(s) of the remote endpoint.
From 41afe6ff50c635a2ab6324a29801d2ed4439eb81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?I=C3=B1aki=20Baz=20Castillo?= Date: Tue, 31 Oct 2023 14:38:24 +0100 Subject: [PATCH 3/6] mediasoup: Document the new pause/resume feature in DataProducer and DataConsumer --- .../v3/mediasoup/api/DataConsumer.md | 49 +++++++++++++++++++ .../v3/mediasoup/api/DataProducer.md | 32 ++++++++++++ .../v3/mediasoup/api/Producer.md | 2 - 3 files changed, 81 insertions(+), 2 deletions(-) diff --git a/_includes/documentation/v3/mediasoup/api/DataConsumer.md b/_includes/documentation/v3/mediasoup/api/DataConsumer.md index bb99be7..faafeb3 100644 --- a/_includes/documentation/v3/mediasoup/api/DataConsumer.md +++ b/_includes/documentation/v3/mediasoup/api/DataConsumer.md @@ -24,6 +24,7 @@ Field | Type | Description | Required | Default `ordered` | Boolean | Just if consuming over SCTP. Whether data messages must be received in order. If `true` the messages will be sent reliably. | No | The value in the data producer (if it's of type 'sctp') or `true` (if it's of type 'direct'). `maxPacketLifeTime` | Number | Just if consuming over SCTP. When `ordered` is `false`, it indicates the time (in milliseconds) after which a SCTP packet will stop being retransmitted. | No | The value in the data producer (if it's of type 'sctp') or unset (if it's of type 'direct'). `maxRetransmits` | Number | Just if consuming over SCTP. When `ordered` is `false`, it indicates the maximum number of times a packet will be retransmitted. | No | The value in the data producer (if it's of type 'sctp') or unset (if it's of type 'direct'). +`paused` | Boolean | Whether the data consumer must start in paused mode. | No | `false` `appData` | [AppData](#AppData) | Custom application data. | No | `{ }` @@ -105,6 +106,20 @@ The data consumer sub-protocol. > `@type` String , read only +#### dataConsumer.paused +{: #dataConsumer-paused .code} + +Whether the data consumer is paused. + +> `@type` Boolean, read only + +#### dataConsumer.dataProducerPaused +{: #dataConsumer-dataProducerPaused .code} + +Whether the associated data producer is paused. + +> `@type` Boolean, read only + #### dataConsumer.appData {: #dataConsumer-appData .code} @@ -207,6 +222,20 @@ If the data cannot be sent due to the underlying SCTP send buffer being full, th > `@async` +#### dataConsumer.pause() +{: #dataConsumer-pause .code} + +Pauses the data consumer (no messages are sent to the consuming endpoint). + +> `@async` + +#### dataConsumer.resume() +{: #dataConsumer-resume .code} + +Resumes the data consumer (messages are sent again to the consuming endpoint). + +> `@async` +
@@ -239,6 +268,16 @@ dataConsumer.on("dataproducerclose", () => }); ``` +#### dataConsumer.on("dataproducerpause", fn()) +{: #dataConsumer-on-dataproducerpause .code} + +Emitted when the associated data producer is paused. + +#### dataConsumer.on("dataproducerresume", fn()) +{: #dataConsumer-on-dataproducerresume .code} + +Emitted when the associated data producer is resumed. + #### dataConsumer.on("message", fn(message, ppid)) {: #dataConsumer-on-message .code} @@ -306,4 +345,14 @@ See the [Observer API](#observer-api) section below. Emitted when the data consumer is closed for whatever reason. +#### dataConsumer.observer.on("pause", fn()) +{: #dataConsumer-observer-on-dataproducerpause .code} + +Emitted when the data consumer is paused. + +#### dataConsumer.observer.on("resume", fn()) +{: #dataConsumer-observer-on-dataproducerresume .code} + +Emitted when the data consumer is resumed. +
diff --git a/_includes/documentation/v3/mediasoup/api/DataProducer.md b/_includes/documentation/v3/mediasoup/api/DataProducer.md index fd7dea6..53bca2e 100644 --- a/_includes/documentation/v3/mediasoup/api/DataProducer.md +++ b/_includes/documentation/v3/mediasoup/api/DataProducer.md @@ -23,6 +23,7 @@ Field | Type | Description | Required | Default `sctpStreamParameters` | [SctpStreamParameters](/documentation/v3/mediasoup/sctp-parameters/#SctpStreamParameters) | SCTP parameters defining how the endpoint is sending the data. Required if SCTP/DataChannel is used. Must not be given if the data producer is created on a `DirectTransport`. | No | `label` | String | A label which can be used to distinguish this DataChannel from others. | No | `protocol` | String | Name of the sub-protocol used by this DataChannel. | No | +`paused` | Boolean | Whether the data producer must start in paused mode. | No | `false` `appData` | [AppData](#AppData) | Custom application data. | No | `{ }` @@ -97,6 +98,13 @@ The data producer sub-protocol. > `@type` String , read only +#### dataProducer.paused +{: #dataProducer-paused .code} + +Whether the data producer is paused. + +> `@type` Boolean, read only + #### dataProducer.appData {: #dataProducer-appData .code} @@ -163,6 +171,20 @@ dataProducer.send(stringMessage); dataProducer.send(binaryMessage); ``` +#### dataProducer.pause() +{: #dataProducer-pause .code} + +Pauses the data producer (no messages are sent to its associated data consumers). Triggers a ["dataproducerpause"](#dataConsumer-on-dataproducerpause) event in all its associated data consumers. + +> `@async` + +#### dataProducer.resume() +{: #dataProducer-resume .code} + +Resumes the data producer (messages are sent again to its associated data consumers). Triggers a ["dataproducerresume"](#dataConsumer-on-dataproducerresume) event in all its associated data consumers. + +> `@async` +
@@ -200,4 +222,14 @@ See the [Observer API](#observer-api) section below. Emitted when the producer is closed for whatever reason. +#### dataProducer.observer.on("pause", fn()) +{: #dataProducer-observer-on-pause .code} + +Emitted when the data producer is paused. + +#### dataProducer.observer.on("resume", fn()) +{: #dataProducer-observer-on-resume .code} + +Emitted when the data producer is resumed. + diff --git a/_includes/documentation/v3/mediasoup/api/Producer.md b/_includes/documentation/v3/mediasoup/api/Producer.md index e87a3f9..18a391a 100644 --- a/_includes/documentation/v3/mediasoup/api/Producer.md +++ b/_includes/documentation/v3/mediasoup/api/Producer.md @@ -222,7 +222,6 @@ Check the [RTC Statistics](/documentation/v3/mediasoup/rtc-statistics/) section Pauses the producer (no RTP is sent to its associated consumers). Triggers a ["producerpause"](#consumer-on-producerpause) event in all its associated consumers. - > `@async` #### producer.resume() @@ -230,7 +229,6 @@ Pauses the producer (no RTP is sent to its associated consumers). Triggers a ["p Resumes the producer (RTP is sent again to its associated consumers). Triggers a ["producerresume"](#consumer-on-producerresume) event in all its associated consumers. - > `@async` #### producer.enableTraceEvent(types) From 558f4e334589a670abff2d1a460e18e387a6e2be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?I=C3=B1aki=20Baz=20Castillo?= Date: Tue, 31 Oct 2023 14:38:39 +0100 Subject: [PATCH 4/6] fix typo --- _includes/documentation/v3/mediasoup/api/DataConsumer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_includes/documentation/v3/mediasoup/api/DataConsumer.md b/_includes/documentation/v3/mediasoup/api/DataConsumer.md index faafeb3..f68a456 100644 --- a/_includes/documentation/v3/mediasoup/api/DataConsumer.md +++ b/_includes/documentation/v3/mediasoup/api/DataConsumer.md @@ -346,12 +346,12 @@ See the [Observer API](#observer-api) section below. Emitted when the data consumer is closed for whatever reason. #### dataConsumer.observer.on("pause", fn()) -{: #dataConsumer-observer-on-dataproducerpause .code} +{: #dataConsumer-observer-on-pause .code} Emitted when the data consumer is paused. #### dataConsumer.observer.on("resume", fn()) -{: #dataConsumer-observer-on-dataproducerresume .code} +{: #dataConsumer-observer-on-resume .code} Emitted when the data consumer is resumed. From 6d4d41c09c986237bfcf1a5c4268dbd1102b4e48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?I=C3=B1aki=20Baz=20Castillo?= Date: Tue, 31 Oct 2023 17:36:28 +0100 Subject: [PATCH 5/6] mediasoup: document DataProducer/DataConsumer subchannels --- .../v3/mediasoup/api/DataConsumer.md | 46 +++++++++++++++++-- .../v3/mediasoup/api/DataProducer.md | 16 +++++-- 2 files changed, 52 insertions(+), 10 deletions(-) diff --git a/_includes/documentation/v3/mediasoup/api/DataConsumer.md b/_includes/documentation/v3/mediasoup/api/DataConsumer.md index f68a456..0ecaacf 100644 --- a/_includes/documentation/v3/mediasoup/api/DataConsumer.md +++ b/_includes/documentation/v3/mediasoup/api/DataConsumer.md @@ -25,10 +25,15 @@ Field | Type | Description | Required | Default `maxPacketLifeTime` | Number | Just if consuming over SCTP. When `ordered` is `false`, it indicates the time (in milliseconds) after which a SCTP packet will stop being retransmitted. | No | The value in the data producer (if it's of type 'sctp') or unset (if it's of type 'direct'). `maxRetransmits` | Number | Just if consuming over SCTP. When `ordered` is `false`, it indicates the maximum number of times a packet will be retransmitted. | No | The value in the data producer (if it's of type 'sctp') or unset (if it's of type 'direct'). `paused` | Boolean | Whether the data consumer must start in paused mode. | No | `false` +`subchannels` | Array<Number> | Subchannels (unsigned 16 bit integers) this data consumer initially subscribes to. | No | `appData` | [AppData](#AppData) | Custom application data. | No | `{ }` +
+`subchannels` are only used in case this data consumer receives messages from a data producer created on a direct transport that specifies subchannel(s) when calling [dataProducer.send()](#dataProducer-send). +
+ @@ -120,6 +125,17 @@ Whether the associated data producer is paused. > `@type` Boolean, read only +#### dataConsumer.subchannels +{: #dataConsumer-subchannels .code} + +Subchannels (unsigned 16 bit integers) this data consumer is currently subscribed to. + +> `@type` Array<Number>, read only + +
+`subchannels` are only used in case this data consumer receives messages from a data producer created on a direct transport that specifies subchannel(s) when calling [dataProducer.send()](#dataProducer-send). +
+ #### dataConsumer.appData {: #dataConsumer-appData .code} @@ -196,7 +212,8 @@ Whenever the underlaying SCTP association buffered bytes drop to this value, [bu Sends direct messages from the Node.js process.
-Just available in data consumers of type "SCTP". +- Just available in data consumers of type "SCTP". +- If the data cannot be sent due to the underlying SCTP send buffer being full, the method will fail with an Error instance which `message` equals `sctpsendbufferfull`.
@@ -216,10 +233,6 @@ dataConsumer.send(stringMessage); dataConsumer.send(binaryMessage); ``` -
-If the data cannot be sent due to the underlying SCTP send buffer being full, the method will fail with an Error instance which `message` equals `sctpsendbufferfull`. -
- > `@async` #### dataConsumer.pause() @@ -236,6 +249,29 @@ Resumes the data consumer (messages are sent again to the consuming endpoint). > `@async` +#### dataConsumer.setSubchannels(subchannels) +{: #dataConsumer-setSubchannels .code} + +Update subchannels this data consumer is subscribed to. + +
+ +Argument | Type | Description | Required | Default +--------- | ------- | ----------- | -------- | ---------- +`subchannels` | Array<Number> | Subchannels (unsigned 16 bit integers) this data consumer is subscribed to. | Yes | + +
+ +> `@async` + +
+`subchannels` are only used in case this data consumer receives messages from a data producer created on a direct transport that specifies subchannel(s) when calling [dataProducer.send()](#dataProducer-send). +
+ +```javascript +dataConsumer.setSubchannels([ 1, 4 ]); +``` + diff --git a/_includes/documentation/v3/mediasoup/api/DataProducer.md b/_includes/documentation/v3/mediasoup/api/DataProducer.md index 53bca2e..9bc0dea 100644 --- a/_includes/documentation/v3/mediasoup/api/DataProducer.md +++ b/_includes/documentation/v3/mediasoup/api/DataProducer.md @@ -145,24 +145,26 @@ Returns current statistics of the data producer. Check the [RTC Statistics](/documentation/v3/mediasoup/rtc-statistics/) section for more details.
-#### dataProducer.send(message, ppid) +#### dataProducer.send(message, ppid, subchannels, requiredSubchannel) {: #dataProducer-send .code} Sends direct messages from the Node.js process. -
-Just available in direct transports, this is, those created via `router.createDirectTransport()`. -
-
Argument | Type | Description | Required | Default --------- | ------- | ----------- | -------- | ---------- `message` | String\|Buffer | Message to be sent (can be binary by using a Node.js Buffer). | Yes | `ppid` | Number | Mimics the [SCTP Payload Protocol Identifier](https://www.iana.org/assignments/sctp-parameters/sctp-parameters.xhtml#sctp-parameters-25). In most cases it must not be set. | No | 51 (`WebRTC String`) if `message` is a String and 53 (`WebRTC Binary`) if it's a Buffer. +`subchannels` | Array<Number> | Only data consumers subscribed to at least one of these subchannels (unsigned 16 bit integers) will receive the message. | No | +`requiredSubchannel` | Number | Only data consumers subscribed to this subchannel (unsigned 16 bit integer) will receive the message. | No |
+
+Just available in direct transports, this is, those created via `router.createDirectTransport()`. +
+ ```javascript const stringMessage = "hello"; const binaryMessage = Buffer.from([ 1, 2, 3, 4 ]); @@ -171,6 +173,10 @@ dataProducer.send(stringMessage); dataProducer.send(binaryMessage); ``` +```javascript +dataProducer.send("bye", /*ppid*/ undefined, /*subchannels*/ [ 24 ]); +``` + #### dataProducer.pause() {: #dataProducer-pause .code} From 6a4f060d152eef0115825bbb74b46a78ed5ca434 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?I=C3=B1aki=20Baz=20Castillo?= Date: Thu, 2 Nov 2023 11:49:27 +0100 Subject: [PATCH 6/6] fix mediasoup/rtp-parameters-and-capabilities.md --- documentation/v3/mediasoup/rtp-parameters-and-capabilities.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/v3/mediasoup/rtp-parameters-and-capabilities.md b/documentation/v3/mediasoup/rtp-parameters-and-capabilities.md index 7a98e77..3552227 100644 --- a/documentation/v3/mediasoup/rtp-parameters-and-capabilities.md +++ b/documentation/v3/mediasoup/rtp-parameters-and-capabilities.md @@ -54,7 +54,7 @@ Field | Type | Description | Required | Default `mid` | String | The MID RTP extension value as defined in the [BUNDLE](https://tools.ietf.org/html/draft-ietf-mmusic-sdp-bundle-negotiation) specification. | No | `codecs` | Array<[RtpCodecParameters](#RtpCodecParameters)> | Media and RTX codecs in use. | Yes | `headerExtensions` | Array<[RtpHeaderExtensionParameters](#RtpHeaderExtensionParameters)> | RTP header extensions in use. | No | `[ ]` -`encodings` | Array<[RtpEncodingParameters](#RtpEncodingParameters)> | Transmitted RTP streams and their settings. | Yes | +`encodings` | Array<[RtpEncodingParameters](#RtpEncodingParameters)> | Transmitted RTP streams and their settings. | No | `rtcp` | [RtcpParameters](#RtcpParameters) | Parameters used for RTCP. | No | @@ -70,6 +70,7 @@ The RTP send parameters describe a media stream received by mediasoup from an en * These parameters may include a `mid` value that the mediasoup transport will use to match received RTP packets based on their MID RTP extension value. * mediasoup allows RTP send parameters with a single encoding and with multiple encodings (simulcast). In the latter case, each entry in the `encodings` array must include a `ssrc` field or a `rid` field (the RID RTP extension value). * If a single encoding is given, RTP send parameters must include `mid` value or the encoding must indicate the `ssrc` of the stream. +* If no encoding is given (so this is a simple stream without layers), then RTP send parameters must include `mid` value.
Check the [Simulcast](#Simulcast) and [SVC](#SVC) sections for more information.