Android SDK Release Notes - PhenixRTS Docs

Release Notes

The most current release version is 2025.0.0.

Release notes for this version are shown below, followed by notes from prior releases.

To get the Android SDK for a specific version, update the Phenix SDK version in build.gradle file to match the version number, e.g., 2022.0.3. Some versions require additional integration steps; these are called out in the version-specific release notes.

v2025.0.0 Release Notes

Release Date: 2025.01.22

Features/Improvements

Updated to reflect the latest Phenix guidance on providing a preview during publishing. Preview is primarily needed before the content is published. This means that, although a preview renderer exists within prior versions of the SDK (withPreviewRenderOptions), the preview functionality should be managed by the application.

v2024.4.0 Release Notes

Release Date: 2024.10.30

Features/Improvements

Enhancements

Fixes/Updates

Deprecations

None.

v2023.0.0 Release Notes

Release Date: 2024.02.02

Features/Improvements

Setting an authentication token in the SDK triggers re-authentication if the current SDK AuthenticationStatus is unauthenticated. Otherwise, the new authentication token will be used during the next SDK re-authentication attempt.

To support this, there is a new API function for setting an authentication token: PCastExpress.setAuthenticationToken

To subscribe to authentication status events, subscribe to the AuthenticationStatus observable through the API: PCastExpress.getObservableAuthenticationStatus

These are documented in the PCastExpress API.

Enhancements

unrecoverableErrorCallback

It is now mandatory to supply an unrecoverableErrorCallback when creating a PCastExpress instance. Developers must handle unrecoverable errors and prevent an application exit as the default behavior if the callback is not set. If you attempt to create a PCastExpress instance without this parameter, the creation will not be successful.

The function to include a mandatory unrecoverableErrorCallback is PCastExpressFactory.createPCastExpressOptionsBuilder, as shown below.

PCastExpressFactory.createPCastExpressOptionsBuilder((status, description) -> {
\t// Best option is to try rebuilding the ChannelExpress
\t// instance and/or quit your app
})
.buildPCastExpressOptions();
Cancelation Now Cancellation

In the SDK, the spelling of EchoCancelation has been corrected to EchoCancellation, adding the missing letter L.

When you create new UserMedia, EchoCancellation is part of the MediaOptions that can be specified.

Tokens Now Required

Channels and Rooms can ONLY be joined using tokens. Channels and Rooms can no longer be joined with IDs or Aliases as input parameters to the API. When joining Channels and Rooms with tokens, the tokens need to contain either a Channel/Room ID or Alias. Please see the deprecations section for functions that have been deprecated as they use IDs and Aliases to join Rooms or Channels.

Joining Channels occurs now using the following existing ChannelOptions configuration method PhenixJoinChannelOptionsBuilder.withStreamToken

Joining Rooms occurs now using the new RoomOptions configuration method PhenixJoinRoomOptionsBuilder.withStreamToken

For authenticating with the Phenix Platform, either a authToken or an edgeauthToken is supplied to the existing PCastExpressOptionsBuilder.withAuthenticationToken(authToken)

Requests Include UserAgent String

To support analytics, the WebSocket and HTTP requests now send a formatted User-Agent string, which includes relevant client application and platform information.

Examples of these are:

Bug Fixes

All Publish and Subscribe APIs will now wait until a valid session is available before proceeding.

Fixed memory leak when an application is entering the background. The issue could be observed when monitoring an application's memory consumption through Android's Memory Profiler.

Fixed a crash when repeatedly re-instantiating ChannelExpress and RoomExpress instances.

Fixed a crash when an application is backgrounded and brought back to the foreground where internal services try to re-initialize while they are still shutting down.

Fixed microphone audio capture, which led to a diminished captured audio volume, when configuring Echo Cancellation on devices running Android 10 and above. The fix applies to setting UserMedia audio options in the Android where we set echo cancellation. An example of audio options that enable Echo Cancellation in Kotlin is shown below.

UserMediaOptions userMediaConstraints = new UserMediaOptions();
userMediaConstraints.audioOptions.enabled = true
userMediaConstraints
audioOptions.capabilityConstraints[DeviceCapability.AUDIO_ECHO_CANCELLATION_MODE]
= listOf(DeviceConstraint(AudioEchoCancellationMode.ON))

Deprecations

It is now mandatory to supply an unrecoverableErrorCallback when creating a PCastExpress instance. The function for configuring unrecoverableErrorCallback, PCastExpressOptionsBuilder.WithUnrecoverableErrorCallback, has been removed.

Channels and Rooms can no longer be joined with IDs or Aliases, as discussed in the token section above. Removed functions are:

Creation and deletion of Channels and Rooms can no longer be performed by the Android SDK. This now requires a service that interfaces with the platform REST API. Please contact Phenix if you require assistance in setting up your service. Removed functions are:

Remote publishing is no longer allowed via the Android SDK. Removed functions are:

Creating PCastAdmin has been removed from the SDK. The function PCastFactory.createPCastAdmin has been removed.

As re-authorization was removed with the removal of AdminAPI, WithSkipRetryOnUnauthorized was removed from SDK API interfaces. Note that re-authentication support has been added through PCastExpress.SetAuthenticationToken and observing authentication status through PCastExpress.getObservableAuthenticationStatus. Removed functions are:

The SDK no longer allows the user to set the PCast URI, which is the URI to the Platform backend, through code. The PhenixPCastExpressOptionsBuilder.withPCastUri function has been removed. PCastUri configuration for a session now exclusively occurs through an optional URI parameter set in the authToken or an edgeToken. To set backend URIs in tokens using the edgeAuth library, use the -y or --uri parameter. A token's backend URI parameter value can be verified by decoding tokens within Portal. When no URI parameter is supplied in the authToken or edgeToken, the production Platform backend, https://pcast.phenixrts.com/, is configured in the SDK.

v2022.0.3 Release Notes

Release Date: 2022.07.27

Features/Improvements

Fixes

v2022.0.3 Notes

CDN Domain support

The SDK can now send HTTP requests to URLs that redirect to non-Phenix CDNs for replays or for VOD playlists.

To use alternate CDN domains, use the capability cdn-domain on viewing channels, with the CDN domain as its value. Do not include the protocol prefix (e.g., https://) in the value. For example: cdn-domain=mycdn.mycompany.com

The platform will replace the default streaming domain with the specified CDN domain in playlist URLs for the primary manifest of the content.

PCast™ URI in tokens

A PCast™ URI contained in the token will now be used instead of a URI passed as a parameter. Putting the URI in the token is now the preferred behavior, and passing in a PCast™ URI as a parameter is now deprecated. To include the URI in the token, add the uri capability as described in the EdgeAuth library documentation.

If the token contains a URI that differs from the one passed as a parameter, the URI from the token is used and a warning is written to the log.

Room/Channel ID/Alias in tokens

A room/channel ID or alias passed in the token will be used to join the respective room or channel. As with the PCast™ URI, putting the Room or Channel ID or Alias in the token is now the preferred behavior, and passing in that information as a parameter is now deprecated and will generate a deprecation warning in the log. To include the Room or Channel information in the token, add the roomId, channelId, roomAlias or channelAlias capability as described in the EdgeAuth library documentation.

If a value is provided both as a direct parameter and in the token, the values must match; otherwise the operation will fail.

Improved network usage

When using previous releases, Room members rejoining after network changes would sometimes cause zombie room members. This has been improved and the behavior in case of network changes is more consistent.

In addition, network usage is reduced when downloading stream replay segments.

Fixed chat room messages loss in case of network issues

Previously, any messages still cached by the SDK during reconnection after a network change were silently discarded. Now they are preserved and will be returned by the next call to GetLastMessages. In addition, an issue has been fixed where new messages were discarded instead of old ones when there were many cached and incoming messages.

Upon lost network connectivity, the SDK will now keep trying to reconnect instead of ceasing to retry after a few minutes.

v2021.0.15 Pre-release Notes

Release Date: 2021.08.18

Features/Improvements

No customer-impacting changes.

v2021.0.14 Pre-release Notes

Release Date: 2021.08.09

Features/Improvements

No customer-impacting changes.

v2021.0.11 Pre-release Notes

Release Date: 2021.06.08

Features/Improvements

Fixes

v2021.0.8 Pre-release Notes

Release Date: 2021.05.14

Features/Improvements

Notes on Integrating the Android SDK

UserMediaStream on Android.

v2021.0.7 Pre-release Notes

Release Date: 2021.05.06

Features/Improvements

Issues addressed in this release

v2021.0.5 Pre-release Notes

Release Date: 2021.04.12

Features/Improvements

Issues addressed in this release

v2021.0.2 Pre-release Notes

Release Date: 2021.03.02

Features/Improvements

Issues addressed in this release

v2021.0.0 Pre-release Notes

Release Date: 2021.01.07

Features/Improvements

Issues addressed in this release

v2020.1.76 Pre-release Notes

Release Date: 2020.12.22

Features/Improvements

Issues addressed in this release

Notes on Integrating the Android SDK

// The current implementation of `TimeShift` leverages HLS chunks.
// It is possible that retrieval of such chunks can take a very long time.
// This will impact playback if the playback head catches up with the end
// of the prefetch window, which will lead to a stall.
// By default, a timeout of 10 seconds for each chunk retrieval is used
// to avoid holding off playback for too long (worst case a chunk will be
// skipped and playback may pause temporarily).
// This timeout is configurable by setting the following option (it defaults
// to 0, which indicates that we should use the internal default):
var timeoutInMilliseconds = 5000L
rendererOptions.timeShiftOptions.chunkRetrievalTimeoutInMilliseconds
  = timeoutInMilliseconds

v2020.1.75 Pre-release Notes

Release Date: 2020.12.11

Features/Improvements

Issues addressed in this release

v2020.1.68 Pre-release Notes

Release Date: 2020.11.12

Features/Improvements

Issues addressed in this release

Notes on Integrating the Android SDK

In order to support BlueTooth functionality, add the following to the manifest: <uses-permission android:name="android.permission.BLUETOOTH" />

v2020.1.61 Pre-release Notes

Release Date: 2020.09.22

Features/Improvements

Issues addressed in this release

v2020.1.60 Pre-release Notes

Release Date: 2020.09.16

IMPORTANT

We only recommend this update for the VOD applications ( not Live). This release has an issue that affects Live timeshifts.

Features/Improvements

Issues addressed in this release

v2020.1.56 Pre-release Notes

Release Date: 2020.08.31

Features/Improvements

Issues addressed in this release

Notes on Integrating the Android SDK

In order to support BlueTooth SCO headsets

  1. Configure the sample rate overrides for recording and playback to values that are required by SCO:
try {
  Os.setenv("PHENIX_AUDIO_PLAYBACK_SAMPLE_RATE_OVERRIDE", "16000", true);
  Os.setenv("PHENIX_AUDIO_RECORDING_SAMPLE_RATE_OVERRIDE", "8000", true);
} catch (ErrnoException e) {
  // handle exception
}
  1. Enable SCO in the AudioManager (this example assumes the code is placed in your Application subclass):
AudioManager audioManager = (AudioManager)getSystemService(Context.AUDIO_SERVICE);

// call at appropriate time - detection of BT on
audioManager.startBluetoothSco();

// call at appropriate time - detection of BT off
audioManager.stopBluetoothSco();
  1. For both publishing and subscribing, make sure that audio echo cancellation is enabled in the respective options:
// publishing
final UserMediaOptions mediaConstraints = new UserMediaOptions();
mediaConstraints.getAudioOptions().capabilityConstraints.put(
        DeviceCapability.AUDIO_ECHO_CANCELATION_MODE,
        singletonList(new DeviceConstraint(AudioEchoCancelationMode.ON)));
PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
    .withMediaConstraints(mediaConstraints)
    // add any other options
    .buildPublishOptions();
// subscribing
final RendererOptions rendererOptions = new RendererOptions();
rendererOptions.audioEchoCancelationMode = AudioEchoCancelationMode.ON;
JoinChannelOptionsBuilder joinChannelOptionsBuilder = ChannelExpressFactory
    .createJoinChannelOptionsBuilder()
    .withRendererOptions(rendererOptions)
    // add any other options
    .buildJoinChannelOptions()
  1. Note that only mono streams are supported by SCO.

Notes

To take advantage of the new functionality in support of stream restarts on change in network type, it works as follows:

Based on the options initially passed to subscribeToMemberStream, the app can either let the SDK create the renderer, or the app can create a renderer itself.

v2020.1.47 Pre-release Notes

Release Date: 2020.08.20

Features/Improvements

Issues addressed in this release

v2020.1.43 Pre-release Notes

Release Date: 2020.08.18

Features/Improvements

Issues addressed in this release

v2020.1.40 Pre-release Notes

Release Date: 2020.08.12

Features/Improvements

Issues addressed in this release

v2020.1.38 Pre-release Notes

Release Date: 2020.08.07

Features/Improvements

Issues addressed in this release

v2020.1.33 Pre-release Notes

Release Date: 2020.07.16

Features/Improvements

Issues addressed in this release

v2020.1.30 Pre-release Notes

Release Date: 2020.07.08

Features/Improvements

Issues addressed in this release