|
| 1 | +<h3 align="center"> |
| 2 | + <img src="../assets/Red5_Truetime_black.png" alt="Red5 Pro Logo" height="65" /> |
| 3 | +</h3> |
| 4 | +<p align="center"> |
| 5 | + <a href="../README.md">Quick Start</a> • |
| 6 | + <a href="whip-client.md">Publishing</a> • |
| 7 | + <a href="whep-client.md">Subscribing</a> • |
| 8 | + <a href="#">Message Channel</a> • |
| 9 | + <a href="pubnub-client.md">PubNub Client</a> |
| 10 | +</p> |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +# MessageChannel |
| 15 | + |
| 16 | +The `MessageChannel` client is an ingest-based (read: "broadcast") client that extends `WHIPClient` as its underlying framework and capabilities are very similar, with the differing aspect of `MessageChannel` not supporting any media streaming. |
| 17 | + |
| 18 | +## A Note on WHIP/WHEP & DataChannel |
| 19 | + |
| 20 | +It should be noted if that `WHIPClient` and `WHEPClient` - used for publishing and subscribing streams, respectively - by default, include a messaging channel (a.k.a., `DataChannel`) through their underlying `RTCPeerConnection`. |
| 21 | + |
| 22 | +Due to these clients' streaming nature, that underlying messaging channel will be closed once the respective stream is closed - meaning the messaging channel will not remain open if not broadcasting or consuming a stream. |
| 23 | + |
| 24 | +In most cases, this is common scenario. However, if you would like to maintain a messaging channel _along-side_ a streaming client, you can utilize the `MessageChannel` client. |
| 25 | + |
| 26 | +> Be aware that since the `MessageChannel` is not inherently associated with a stream, synchronizations between messages and any associative, external streams will not be available. |
| 27 | +
|
| 28 | +* [Usage](#usage) |
| 29 | +* [Init Configuration](#init-configuration) |
| 30 | +* [Send API](#send-api) |
| 31 | +* [Events](#events) |
| 32 | +* [Statistics](#statistics) |
| 33 | +* [Stream Manager 2.0](#stream-manager-20) |
| 34 | + |
| 35 | +# Usage |
| 36 | + |
| 37 | +Because `MessageChannel` is a subclass of `WHIPClient` (the media streaming broadcaster), much of the init setup and event structure is similar. |
| 38 | + |
| 39 | +To create and use a `MessageChannel` client: |
| 40 | + |
| 41 | +```js |
| 42 | +let messageChannel |
| 43 | +try { |
| 44 | + messageChannel = new MessageChannel() |
| 45 | + messageChannel.on('*', , (event) => console.log(event)) |
| 46 | + |
| 47 | + // See next section: Init Configuration, for more details. |
| 48 | + await messageChannel.init(configuration) |
| 49 | + await messageChannel.open() |
| 50 | +} catch (error) { |
| 51 | + // Something went wrong... |
| 52 | +} |
| 53 | + |
| 54 | +// ... when ready to close the connection ... |
| 55 | +messageChannel?.close() |
| 56 | +``` |
| 57 | +
|
| 58 | +## MessageChannel & the SDK |
| 59 | +
|
| 60 | +Dependening on how you include the SDK into your project, you can access the `MessageClient` from the following: |
| 61 | +
|
| 62 | +_NPM install_: |
| 63 | +
|
| 64 | +```js |
| 65 | +import { MessageChannel } from 'red5pro-webrtc-sdk' |
| 66 | +``` |
| 67 | +
|
| 68 | +_Browser, CDN_: |
| 69 | +
|
| 70 | +```js |
| 71 | +const { MessageChannel } = red5prosdk |
| 72 | +``` |
| 73 | +
|
| 74 | +> For more in-depth information related to usage, please refer to the [WHIPClient](whip-client.md#usage) documentation. |
| 75 | +
|
| 76 | +# Init Configuration |
| 77 | +
|
| 78 | +Because `MessageChannel` inherits from `WHIPClient`, its initialization configuration shares the same properties and structure, however many attributes will be ignored as they pertain to streaming media on a `WHIPClient` which have no regard to the role of a `MessageChannel`. |
| 79 | +
|
| 80 | +The following properties are respected by the `MessageChannel` client: |
| 81 | +
|
| 82 | +| Property | Required | Default | Description | |
| 83 | +| :--- | :---: | :---: | :--- | |
| 84 | +| `host` | [x] | *None* | The IP or address that the WebSocket server resides on. | |
| 85 | +| `streamName` | [x] | *None* | The name of the message channel to use in association. | |
| 86 | +| `protocol` | [x] | `https` | The protocol of the host for the signaling communication. | |
| 87 | +| `port` | [x] | `443` | The port on the host that the Red5 server listens on; `5080` or `443` (insecure or secure, respectively). | |
| 88 | +| `app` | [x] | `live` | The webapp context name that the stream is on. | |
| 89 | +| `endpoint` | [-] | `undefined` | The full URL of the endpoint to stream to. **This is primarily used in Stream Manager 2.0 integration for clients.** |
| 90 | +| `rtcConfiguration` | [-] | _Basic_ | The `RTCConfiguration` to use in setting up `RTCPeerConnection`. [RTCConfiguration](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection#RTCConfiguration_dictionary)| |
| 91 | +| `dataChannelConfiguration` | [-] | `{name: "red5pro"}` | An object used in configuring a n `RTCDataChannel`. _Only used when `includeDataChannel` is defined as `true`_ | |
| 92 | +| `connectionParams` | [-] | `undefined` | An object of connection parameters to send to the server upon connection request. | |
| 93 | +
|
| 94 | +## Init Example |
| 95 | +
|
| 96 | +The following is an example of using the init configuration for a `MessageChannel` client on a Standalone deployment of the Red5 Server: |
| 97 | +
|
| 98 | +```js |
| 99 | +try { |
| 100 | + // If the standalone Red5 server is hosted over HTTPS, most other attributes can be left to default. |
| 101 | + const configuration = { |
| 102 | + host: 'mydeployment.red5.net', |
| 103 | + streamName: `${uuid}-message-channel`, |
| 104 | + dataChannelConfiguration: { |
| 105 | + name: 'my-channel-name' |
| 106 | + } |
| 107 | + } |
| 108 | + const messageChannel = new MessageChannel() |
| 109 | + messageChannel.on('*', , (event) => console.log(event)) |
| 110 | + await messageChannel.init(configuration) |
| 111 | + await messageChannel.open() |
| 112 | +} catch (error) { |
| 113 | + // Something went wrong... |
| 114 | +} |
| 115 | +``` |
| 116 | +
|
| 117 | +# Send API |
| 118 | +
|
| 119 | +The `MessageChannel` has a few options for broadcasting messages out to other clients connected to the channel: |
| 120 | +
|
| 121 | +## send(methodName: string, data: any) |
| 122 | +
|
| 123 | +The `send` method is an override of the `MessageChannel` underlying `WHIPClient` implementation. It essentially is an override to ensure the message data is delivered on other connected clients to the specified DataChannel. |
| 124 | +
|
| 125 | +> The `data` is expected as either a string or an `Object` that can be serialized to JSON. |
| 126 | +
|
| 127 | +## sendMessage(message: any) |
| 128 | +
|
| 129 | +The `sendMessage` method is a convenience method of which the `send()` call invokes - delivering JSON data to all clients connected to the specified DataChannel |
| 130 | +
|
| 131 | +> The `message` is expected as either a string or an `Object` that can be serialized to JSON. |
| 132 | +
|
| 133 | +## sendData(data: any) |
| 134 | +
|
| 135 | +The `sendData` method will attempt to send any type of data, untouched, along the DataChannel - as such, with it comes great power; use wisely. |
| 136 | +
|
| 137 | +# Events |
| 138 | +
|
| 139 | +Because `MessageChannel` inherits from `WHIPClient`, events unrelated to streaming - such as those related to the underlying WebRTC connection (e.g., `WebRTC.*`) - will be dispatched from `MessageChannel`. |
| 140 | +
|
| 141 | +There are a few that are specific to `MessageChannel` that are available and enumerated on the `MessageChannelEventTypes` object: |
| 142 | +
|
| 143 | +| Access | Event Type | Meaning | |
| 144 | +| :--- | :--- | :--- | |
| 145 | +| `OPEN` | 'MessageChannel.Open' | When the message channel has successfully opened and available to send and receive messages. | |
| 146 | +| `SEND` | 'MessageChannel.Send' | When the message channel has sent a message along the message channel. _Note: This is not confirmation that the server received the actual message._ | |
| 147 | +| `RECEIVE` | 'MessageChannel.Receive' | When the message channel has received a message. | |
| 148 | +| `CLOSE` | 'MessageChannel.Close' | When the message channel has been closed. | |
| 149 | +| `FAIL` | 'MessageChannel.Fail' | When the message channel has failed to open properly. | |
| 150 | +| `ERROR` | 'MessageChannel.Error' | When an error has occurred in opening or during a message channel session. | |
| 151 | +
|
| 152 | +> Please visit the [WHIPClient](whip-client.md#events) documentation for more in-depth listing of events. |
| 153 | +
|
| 154 | +# Statistics |
| 155 | +
|
| 156 | +Similar to being able to monitor for statistics on the underlying `RTCPeerConnection` of other clients from the SDK, statistics related to the `MessageChannel` can be monitored as well - though the data gathered will pertain mostly to the connection and `data-channel`. |
| 157 | +
|
| 158 | +## Stats Configuration |
| 159 | +
|
| 160 | +The configuration used for statistics monitoring has the following structure: |
| 161 | +
|
| 162 | +```js |
| 163 | +{ |
| 164 | + // Optional. |
| 165 | + // If provided, it will POST stats to this endpoint. |
| 166 | + // If undefined or `data-channel`, it will post stats to message transport. |
| 167 | + // If null or `event-transport`, it will only emit status events. |
| 168 | + endpoint: red5prosdk.StatsEndpointType.DATA_CHANNEL, |
| 169 | + additionalHeaders: undefined, |
| 170 | + interval: 5000, // Interval to poll stats, in milliseconds. |
| 171 | + include: [], // Empty array allows SDK to be judicious about what stats to include. |
| 172 | +} |
| 173 | +``` |
| 174 | +
|
| 175 | +### endpoint |
| 176 | +
|
| 177 | +* If the `endpoint` is defined with a URL, the SDK will attempt to make `POST` requests with a JSON body representing each individual report. |
| 178 | +* If the `endpoint` is set to `data-channel` or `undefined`, the SDK will post metadata with type `stats-report` on the underlying message transport (DataChannel) if available. |
| 179 | +* If the `endpoint` is set to `event-transport` or `null`, the SDK will only emit events with the metadata on the `WebRTC.StatsReport` event. |
| 180 | +
|
| 181 | +### additionalHeaders |
| 182 | +
|
| 183 | +By default, if an `endpoint` is defined, the `POST` request body will be in JSON and have the `{ 'Content-Type': 'application/json' }` header set. If requirements - such as authentication - are required, a map of additional headers can be provided to be sent along with the request. |
| 184 | +
|
| 185 | +### interval |
| 186 | +
|
| 187 | +The polling interval (in milliseconds) to access the `RTCStatsReport` from the underlying `RTCPeerConnection` of the publisher client. |
| 188 | +
|
| 189 | +### include |
| 190 | +
|
| 191 | +An array of static type strings. These directly map to the listing of type available for `RTCStatsReport` objects. If left empty or undefined, the SDK will report the statistics it deems suitable for tracking proper broadcast conditions. |
| 192 | +
|
| 193 | +e.g., |
| 194 | +
|
| 195 | +```js |
| 196 | +include: ['data-channel', 'transport'] |
| 197 | +``` |
| 198 | + |
| 199 | +> More information about the statistic types are available at [https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport#the_statistic_types](https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport#the_statistic_types) |
| 200 | +
|
| 201 | +## Invocation |
| 202 | + |
| 203 | +To start statistics monitoring, you have a couple of options: |
| 204 | + |
| 205 | +* You can provide a `stats` attribute with the [stats configuration object](#stats-configuration) to the [init configuration](#webrtc-configuration-parameters). |
| 206 | +* You can call `monitorStats` on the publisher client with the optional [stats configuration object](#stats-configuration) parameter. |
| 207 | + |
| 208 | +> Additionally, you can stop monitoring by calling `unmonitorStats` on the publisher client. |
| 209 | +
|
| 210 | +## Additional Information |
| 211 | + |
| 212 | +Attached to the metadata that is reported are additional properties that pertain to the publisher client. |
| 213 | + |
| 214 | +As well, Along with the metadata releated to the `RTCStatsReport` objects emitted by the underlying `RTCPeerConnection`, the statistics monitoring also sends out a few event and action metadata related to the operation of a publisher client. |
| 215 | + |
| 216 | +> See the following section for examples. |
| 217 | +
|
| 218 | +## Example of Statistics Metadata |
| 219 | + |
| 220 | +The following is an example of a statistics metadata that is emitted in a `WebRTC.StatsReport` event and POSTed to any defined optional endpoint: |
| 221 | + |
| 222 | +```json |
| 223 | +{ |
| 224 | + "name": "MessageChannelStats", |
| 225 | + "created": 1771514183637, |
| 226 | + "fingerprint": "165799de-87ac-4c13-95d3-66c7512080fe", |
| 227 | + "device": { |
| 228 | + "appVersion": "5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36", |
| 229 | + "platform": "MacIntel", |
| 230 | + "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36", |
| 231 | + "vendor": "Google Inc." |
| 232 | + }, |
| 233 | + "client": { |
| 234 | + "host": "myred5.deploy", |
| 235 | + "streamName": "dc-1771514183635", |
| 236 | + "connectionParams": { |
| 237 | + "capabilities": 4 |
| 238 | + } |
| 239 | + }, |
| 240 | + "publicIP": "174.169.251.174", |
| 241 | + "type": "stats-report", |
| 242 | + "timestamp": 1771514658751, |
| 243 | + "data": { |
| 244 | + "id": "D159", |
| 245 | + "timestamp": 1771514658751.39, |
| 246 | + "type": "data-channel", |
| 247 | + "label": "red5pro", |
| 248 | + "state": "open", |
| 249 | + "messagesSent": 45, |
| 250 | + "messagesReceived": 93, |
| 251 | + "bytesSent": 4815, |
| 252 | + "bytesReceived": 12556 |
| 253 | + } |
| 254 | +} |
| 255 | +``` |
| 256 | +# Stream Manager 2.0 |
| 257 | + |
| 258 | +> This section provides information that relate to the release of Stream Manager 2.0 and its integration with WHIP/WHEP clients, and MessageChannel. |
| 259 | +
|
| 260 | +The Stream Manager 2.0 simplifies the proxying of web clients to Origin and Edge nodes. As such, an initialization configuration property called `endpoint` was added to the WebRTC SDK. This `endpoint` value should be the full URL path to the proxy endpoint on the Stream Manager as is used as such: |
| 261 | + |
| 262 | +## WHIP Proxy |
| 263 | + |
| 264 | +```javascript |
| 265 | +const host = 'my-deployment.red5.net' |
| 266 | +const streamName = `${uuid}-message-channel` |
| 267 | +const nodeGroup = 'my-node-group' |
| 268 | +const endpoint = `https://${host}/as/v1/proxy/whip/live/${streamName}` |
| 269 | +const config = { |
| 270 | + endpoint, |
| 271 | + streamName, |
| 272 | + connectionParams: { |
| 273 | + nodeGroup |
| 274 | + }, |
| 275 | + dataChannelConfiguration: { |
| 276 | + name: 'my-channel' |
| 277 | + } |
| 278 | + // additional configurations |
| 279 | +} |
| 280 | +const messageChannel = await new MessageChannel().init(config) |
| 281 | +messageChannel.on('*', (event) => console.log(event)) |
| 282 | +await messageChannel.open() |
| 283 | +``` |
0 commit comments