---
# Red5 HTML SDK Migration Guide
This documentation serves as a guide in migrating client-side code where a breaking change to the API has been made in a distribution.
- [14.x to 15.0.0](#migrating-from-14x-to-1500)
- [13.x to 14.0.0](#migrating-from-13x-to-1400)
- [12.x to 13.0.0](#migrating-from-12x-to-1300)
- [10.x to 11.0.0](#migrating-from-10x-to-1100)
- [8.0.0 to 9.1.0](#migrating-from-800-to-910)
- [7.2.0 to 8.0.0](#migrating-from-720-to-800)
- [5.4.0 to 5.5.0](#migrating-from-540-to-550)
- [5.0.0 to 5.4.0](#migrating-from-500-to-540)
- [4.0.0 to 5.0.0](#migrating-from-400-to-500)
- [3.5.0 to 4.0.0](#migrating-from-350-to-400)
# Migrating from `14.x` to `15.0.0`
**ALERT: Breaking Changes**
The `15.0.0` release of the Red5 HTML SDK is a complete rewrite of the SDK! Developed in TypeScript from the ground-up, we eliminated a lot of cruft and APIs that had become obsolete and deprecated over the years.
With the slimming-down approach to the SDK also came the major breaking change of removing the WebSocket based clients: `RTCPublisher` and `RTCSubscriber`. As such, the clients introduced in the `11.0.0` release of the SDK are now the main actors and should be exclusively used: `WHIPClient` and `WHEPClient`.
The [WebRTC-HTTP ingestion](https://www.ietf.org/archive/id/draft-ietf-wish-whip-01.html)(WHIP) and [WebRTC-HTTP egress](https://www.ietf.org/archive/id/draft-murillo-whep-00.html)(WHEP) protocols provide the ability to negotation and establish a connection using HTTP/S requests. This removes the requirement for a WebSocket, which historically has been used for the role of negotiation and connection.
> Not only that, but their connection times are blazingly fast!
If you have already been using the `WHIPClient` and `WHEPClient` from the Red5 HTML SDK, you shouldn't find any hiccups and will not need to update anything - simply enjoy the benefits of a slimmer SDK and the inclusion of types!
If you have been using the WebSocket-based `RTCPublisher` and `RTCSubscriber` clients, we have hopefully made it painless enough to simply swap out that instantiation with their corresponding WHIP/WHEP client - the initialization and API is all the same.
For example, if you were previously establishing a publisher as such:
```js
const config = {
host: 'myred5.cloud',
streamName: 'mystream'
}
const publisher = new RTCPublisher()
publisher.on('*', event => console.log(event))
await publisher.init(config)
await publisher.publish()
```
You can simply swap over to using the `WHEPClient` like so:
```js
const config = {
host: 'myred5.cloud',
streamName: 'mystream'
}
const publisher = new WHIPClient()
publisher.on('*', event => console.log(event))
await publisher.init(config)
await publisher.publish()
```
> The same is true for moving from `RTCSubscriber` to `WHEPClient`!
# Migrating from `13.x` to `14.0.0`
Though the version number shows a major change, it was more to be in line with the semver of the Red5 Pro Server release. _No breaking changes._
# Migrating from `12.x` to `13.0.0`
The SDK release of `13.0.0` has additional configuration requirements when integrating with Stream Manager 2.0 deployments. This release sees the introduction of the `endpoint` initialization configuration on which you provide the full URL path to the Stream Manager 2.0 proxy. The proxy will handle directing the clients to the target Origin and Edge nodes.
The `endpoint` init config param is to be used in tandem with a `nodeGroup` connection parameter specifying the name of the target Node Group within the Stream Manager dpeloyment that you intend to target.
More Information related to this configuration is detailed in the following documents:
* [WHIPClient](docs/whip-client.md#stream-manager-20)
* [WHEPClient](docs/whep-client.md#stream-manager-20)
> [NOTE] SharedObject support has been removed in 13.0.0
# Migrating from `10.x` to `11.0.0`
The SDK release of `11.0.0` provides the capability of utilizing the [WHIP](https://www.ietf.org/archive/id/draft-ietf-wish-whip-01.html) and [WHEP](https://www.ietf.org/archive/id/draft-murillo-whep-00.html) protocols newly introduced on the `11.0.0` release of the Red5 Pro Server!
The [WebRTC-HTTP ingestion](https://www.ietf.org/archive/id/draft-ietf-wish-whip-01.html)(WHIP) and [WebRTC-HTTP egress](https://www.ietf.org/archive/id/draft-murillo-whep-00.html)(WHEP) protocols provide the ability to negotation and establish a connection using HTTP/S requests. This removes the requirement for a WebSocket, which historically has been used for the role of negotiation and connection.
> Read more about [WHIPClient](docs/whip-client.md) and [WHEPClient](docs/whep-client.md).
# Migrating from `8.0.0` to `9.1.0`
No major bug fixes were introduced in `9.1.0`. The biggest update to `9.1.0` was the introduction of the `sendLog` API for `RTCPublisher` and `RTCSubscriber`.
The `sendLog` API allows you - the developer - to send messages to the server while connected with a `RTCPublisher` or `RTCSubscriber` instance.
The message signature for `sendLog` on both the `RTCPublisher` and `RTCSubscriber` is:
```sh
sendLog( level, message )
```
Valid `level` values are:
- `TRACE`
- `INFO`
- `DEBUG`
- `WARN`
- `ERROR`
Example (after already establishing an `RTCPublisher` session):
```javascript
rtcPublisher.sendLog('INFO', 'hello world')
```
or
```javascript
rtcPublisher.sendLog('INFO', JSON.stringify({ hello: 'world' }))
```
# Important Note About `8.0.0` Release
**Red5 HTML SDK has been published on NPM!**
While currently not open source, the SDK build has been published to NPM to allow you to integrate into your projects with greater ease and dependency management.
## Install as `script` in HTML page
```
```
... or if you know the version:
```
```
## Install using `npm` or `yarn` for you browser-based projects
```
npm install --save-dev red5pro-webrtc-sdk
```
```
yarn install --dev red5pro-webrtc-sdk
```
### Usage
All members exposed on the otherwise global `window.red5prosdk` if loading as a script on an HTML page are importable from the `red5pro-webrtc-sdk` module:
_publisher-example.js_
```
import { RTCPublisher } from 'red5pro-webrtc-sdk'
```
# Migrating from `7.2.0` to `8.0.0`
The `8.0.0` release of the Red5 Pro HTML SDK includes the ability for WebRTC based clients - `RTCPublisher` and `RTCSubscriber` - to use WebSockets only for signaling purposes. Once they have finished their negotiation process and have begun broadcasting or consuming a stream, repsectively, they will open a `RTCDataChannel` connection and close the underlying `WebSocket` used for signaling.
The benefit of closing the `WebSocket` and switching to a `RTCDataChannel` after signaling is complete is cutting down on the number of open socket connections to the server; in a Stream Manager Proxy scenario, this can be a significant benefit as the Proxy is no longer needed to keep alive while the stream is being delivered to the Origin(s) or from the Edge(s).
## Configuration
The initialization configuration object for the `RTCPublisher` and `RTCSubscriber` have the following attribute that flags whether to use the `WebSocket` only as a signaling connection:
- `signalingSocketOnly`
If `true`, the `RTCPublisher` and `RTCSubscriber` will use a `WebSocket` to establish an `RTCPeerConnection` and once established, will switch over to using a `RTCDataChannel` to do any event handling and futher communication with the server. _It is set to `true`, by default._
> Further communication could be calling the Mute API for `RTCPublisher` and Standby API for `RTCSubscriber`.
By setting `signalingSocketOnly` to `true` the switch works seemlessly under the hood, allowing you - as a developer - to not care about how to switch the message transport layers explicitly.
An additional initialization configuration is also available as it relates to the switch to `RTCDataChannel` after signalling is complete:
- `dataChannelConfiguration`
By default, the `dataChannelConfiguration` has the following structure and declaration:
```js
dataChannelConfiguration = {
name: 'red5pro',
}
```
The `name` value will be used in the underlying `RTCDataChannel` created from the `RTCPeerConnection`.
> It should be noted that any `Red5ProSharedObject` instances created using an underlying connection through a `RTCPublisher` or `RTCSubscriber` will be switched over to using `RTCDataChannel` for communication.
## Access
Once the `RTCDataChannel` has been switched to from the `WebSocket`, you can access the instance from `RTCPublisher` and `RTCSubsciber` by calling the following:
```js
;+getDataChannel()
```
The will return the actual underlying `RTCDataChannel` instance used in communication.
## Events
The following events have been added to the `RTCPublisher` and `RTCSubscriber` that can be listened to:
| `DATA_CHANNEL_AVAILABLE` | 'WebRTC.DataChannel.Available' | the underlying `RTCDataChannel` is available when `signalingSocketOnly` configuration is used. |
| `DATA_CHANNEL_OPEN` | 'WebRTC.DataChannel.Open' | When the underlying `RTCDataChannel` is opened when `signalingSocketOnly` configuration is used.
| `DATA_CHANNEL_CLOSE` | 'WebRTC.DataChannel.Close' | When the underlying `RTCDataChannel` is closed when `signalingSocketOnly` configuration is used. |
| `DATA_CHANNEL_ERROR` | 'WebRTC.DataChannel.Error' | When an error has occurred within the underlying `RTCDataChannel` when `signalingSocketOnly` configuration is used. |
| `DATA_CHANNEL_MESSAGE` | 'WebRTC.DataChannel.Message' | When a message has been delivered over the underlying `RTCDataChannel` when `signalingSocketOnly` configuration is used. |
---
# Migrating from `5.4.0` to `5.5.0`
The `5.5.0` release of the Red5 Pro HTML SDK including some modifications to `SharedObjects` to allow for "decoupling" the managament and communication API from the underlying connections for Publishers and Subscribers. In the `5.5.0` release, `SharedObjects` can now be used by themselves without requiring an already established connection to the server.
- The `SharedObject` API has been decoupled from requiring previously established stream clients (Publisher and/or Subscriber).
- By decoupling the previous _requirement_ to use a established stream client, `SharedObjects` can now be used with establishing a `WebSocket` connection and providing that as the connection to communicate over `SharedObjects`.
- The Red5 Pro HTML SDK provides a `Red5ProSharedObjectSocket` class to serve as a proxy to an underlying `WebSocket` and convenience in communicating to and from the Red5 Pro Server when using `SharedObjects`.
- The `SharedObject` API can still be employed using a stream client connection as was possible in previous SDK versions.
Additionally, notification support for latest browser vendor restictions on the `autoplay` policy have been included.
- Utilize the `muteOnAutoplayRestriction` initialization configuration property for Subscriber clients in order to attempt auto-muting of subscribers to allow - at least - video auto-playback when browsers enforce the muted autoplay policy.
- Listen for events related to `autoplay` restictions in order to provide a better User Experience for your customers.
- Please refer to the `Autoplay Restictions` section from the _Subscriber_ documentation.
# Migrating from `5.0.0` to `5.4.0`
The `5.4.0` release of the Red5 Pro HTML SDK saw some minor changes related to WebRTC clients, and in particular how WebSoskcet and RTCPeerConnections are made:
- The default ports used for WebSocket connection change from `8081` and `8083` (insecure and secure, respectively) to `5080` and `443` (insecure and secure, respectively.
- WebSocket communication with the Red5 Pro Server will now be made over the same port for HTTP/S.
- To support backward compatiibilty for webapps out in the wild, the HTML SDK will recognize previously defaulted values and silently change the values to new default values.
- The `iceServers` configuration property has been deprecated in favor of the new `rtcConfiguration` configuration property.
- [Refer to section: RTCConfiguration](#rtcconfiguration)
## RTCConfiguration
Prior to the `5.4.0` release of the Red5 Pro HTML SDK, configuration of underlying `RTCPeerConnection`s for both publisher and subscriber clients was constructed "under the hood". The only property exposed on the initialization configuration was the `iceServers` property.
Using the `iceServers` configuration property, developers could deine the set of ICE endpoints desired in the peer negotiation process.
The `iceServers` configuration property has been deprecated in favor of the newly introduced `rtcConfiguration` property, exposing to developers more control over the `RTCConfiguration` used when establishing `RTCPeerConnection`s for both publisher and subscriber clients.
The `rtcConfiguration` is an object that directly correlates to the `RTCConfiguration` object that is handed to a `RTCPeerConnection` upon instantiation:
[https://developer.mozilla.org/en-US/docs/Web/API/RTCConfiguration](https://developer.mozilla.org/en-US/docs/Web/API/RTCConfiguration)
### RTCConfiguration Example
Previously, developers would define the desired ICE endpoints for negotiation using the `iceServers` initialization configuration property:
```js
const config = {
host: 'myserver.com',
protocol: 'wss',
port: 443,
app: 'live',
streamName: 'mystream',
iceServers: [{ urls: 'stun:stun2.l.google.com:19302' }],
}
var publisher = new red5prosdk.RTCPublisher()
publisher
.init(config)
.then(() => {
publisher.publish()
})
.catch((error) => {
// handle error.
})
```
With the introduction of the `rtcConfiguration` initialization configuration property, developers can still define the desired `iceServers` but as a nested attribute in the `rtcConfiguration` map:
```js
const config = {
host: 'myserver.com',
protocol: 'wss',
port: 443,
app: 'live',
streamName: 'mystream',
rtcConfiguration: {
iceServers: [{ urls: 'stun:stun2.l.google.com:19302' }],
iceCandidatePoolSize: 2,
bundlePolicy: 'max-bundle',
},
}
var publisher = new red5prosdk.RTCPublisher()
publisher
.init(config)
.then(() => {
publisher.publish()
})
.catch((error) => {
// handle error.
})
```
> The `rtcConfiguration` is an object that directly correlates to the `RTCConfiguration` object that is handed to a `RTCPeerConnection` upon instantiation: [https://developer.mozilla.org/en-US/docs/Web/API/RTCConfiguration](https://developer.mozilla.org/en-US/docs/Web/API/RTCConfiguration)
# Migrating from `4.0.0` to `5.0.0`
The `5.0.0` release of the Red5 Pro HTML SDK mainly focused on internal bug fixes and compliancy changes to match updates to the Red5 Pro Server v5.0.0 release.
To see updates that may cause possible issues in integration with your webapp(s), please refer to the _CHANGES_ documentation distributed with the Red5 Pro HTML SDK available from your [Red5 Pro Account](https://account.red5.net/).
# Migrating from `3.5.0` to `4.0.0`
The `4.0.0` release of the Red5 Pro HTML SDK saw some major changes in the following features:
- Internalizing the `getUserMedia` request in order to simplify the intialization-to-broadcast sequence of **Publishers**.
- While the default process of accessing a stream through the `getUserMedia` API of the browser has been internalized to the SDK, we have also exposed a way to override this default to allow developers to specifically handle this process as per requirements.
- [Refer to section: Internalizing gUM Requests](#internalizing-gum-requests)
- Removal of explicitly defining and assigning views for **Publishers** and **Subscribers**.
- The process of associating a view display to either a **Publisher** or a **Subscriber** has been internalized with access to DOM elements using a default `mediaElementId` configuration property.
- This change simplifies the creation and initialization process for both **Publishers** and **Subscribers**.
- While the default process of associating a view to a broadcast or subscriber session is based on a `mediaElementId` configuration property, developers are able to define which `video` or `audio` DOM element they prefer to use as the display by providing its `id` attribute value.
- [Refer to section: Removal of View Attachment](#removal-of-view-attachment)
- Introduction of Red5 Pro HTML SDK Playback Controls.
- In response to numerous requests regarding playback controls across the several **Subscriber** platforms we support, we have exposed an API for playback control and provide default UI elements and styles.
- This allows for consistent cross-browser look-and-feel of playback controls across all playback formats: WebRTC, Flash, and HLS.
- The Red5 Pro HTML SDK Playback Controls UI is completely customizable in styling to meet the branding requirements for developers.
- By exposing a playback API, we allow developers to create their own custom controls - not relying on the Red5 Pro HTML SDK Playback Controls UI - to meet their own product requirements.
- [Refer to section: Red5 Pro HTML SDK Playback Controls](#red5-pro-html-sdk-playback-controls)
- Change in **Subscriber** API from `play()` to `subscribe()` as request to start playback.
- This change is in keeping the Red5 PRo HTML SDK Playback Controls API in-line with consistent method names that properly describe their intent - e.g., `play`, `pause`, `resume`, etc.
- The method change to `subscribe` also keeps consistent method naming convention for **Publishers** and **Subscribers**, as the method name to request publishing for **Publishers** is `publish`.
- [Refer to section: Subscriber API Changes](#subscriber-api-changes)
- Change in **Subscriber** API from `stop()` to `unsubscribe()` as request to cancel current playback.
- This change is in keeping the Red5 PRo HTML SDK Playback Controls API in-line with consistent method names that properly describe their intent - e.g., `play`, `pause`, `resume`, etc.
- The method change to `unsubscribe` also keeps consistent method naming convention for **Publishers** and **Subscribers**, as the method name to request cancel of publishing for **Publishers** is `unpublish`.
- [Refer to section: Subscriber API Changes](#subscriber-api-changes)
- Removal of auto-play from **Subscriber** functionality.
- In previous versions of the Red5 Pro HTML SDK, all **Subscriber** types (WebRTC, Flash, and HLS) would begin playback automatically upon successful connection and subscription to a broadcast stream. This functionality has been removed.
- Instead, the node properties of the [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) (e.g., `
