Red5 Pro iOS Mobile 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.

Migrating from 5.7.0 to 6.0.0

The 6.0.0 release of the Red5 Pro iOS Mobile SDK includes perfomance upgrades for decoding streams for live playback, as well as the modification of R5Connection to allow for decoupled SharedObjects (no longer requiring a pre-established stream in order to use SharedObjects for communication).

6.0.0 Playback Improvements

With regards to the improvements to decoding performance, prior to 6.0.0, decoding of frames for playback were converted from YUV to RGB on the software-side. With the 6.0.0 release, the frames are accepted and stored in YUV (420p) and offloading the YUV to RGB conversion to the GPU during the rendering stage.

This greatly improves the playback performance and is now the default decode procedure used.

Developers utilizing the Subscriber APIs do not have to update their code to take advantage of this default implementation, however they can utilize an additional API method (play:withForcedRGBDecode) if they prefer to use the older implementation of YUV to RGB conversion on the software-side (as detailed below).

Additionally, the iOS SDK playback performance is further improved by providing the ability to utilize VideoToolbox to convert the incoming frames to a CVPixelBufferRef (YUV 420v, bi-planar) on the GPU (API addition: play:useHardwareAcceleration). Using hardware acceleration to decode frames prior to rendering stage not only speeds up performance, but opens up the possibility for developers to provide their own custom rendering routines - as is demonstrated in a 360 Camera Playback example in the 6.0.0 public release of the Red5 Pro iOS Testbed.

R5Stream

The following documents the updates and additions to the R5Stream class.

+ (void) play:streamName

This method has been updated to be backward compatible and default to store the incoming frames for playback in YUV (420p) to be converted to RGB using the GPU during the rendering stage.

+ (void) play:usingHardwareAcceleration

This API addition is a request to playback using hardware acceleration for frame decode, utilizing VideoToolbox to generate a CVPixelBufferRef in YUV (420v bi-planar).

+ (void) play:withForcedRGBDecode

This API addition allows developers to choose the pre-6.0.0 decoding implementation which converts incoming YUV frames to RGB o the software-side prior to the rendering stage.

+ (void) setFrameListener:(void (^)(void *, enum r5_stream_format, int, int, int))

The setFrameListener callback signature has changed to provide the r5_stream_format (second argument) that the raw data (first argument) relates to. This allows developers to handle the incoming data appropriately, being in following formats:

  • r5_stream_format_rgb: RGB
  • r5_stream_format_yuv_planar: YUV 420p (3 planes)
  • r5_stream_format_yuv_biplanar: YUV 420v (2 planes), the CVPixelBufferRef
+ (CVPixelBufferRef) getStreamPixelBuffer

This API addition returns the current CVPixelBufferRef of the frame in playback if play:useHardwareAcceleration was used in playback.

+ (UIImage *) getStreamImage

This API update accounts for generating a UIImage instance from the optional CVPixelBufferRef of the current frame.

+ (uint8_t *) getStreamImageBytes

This API update accounts for returning a casted CVPixelBufferRef is play:useHardwareAcceleration was used in playback.

R5VideoViewController

+ (void) setRenderer:

The rendering operations within the R5VideoViewController have been offloaded to an R5VideoViewRenderer instance in the 6.0.0 version of the iOS SDK. There is a default R5VideoViewRenderer instance used within the SDK, however developers can use the setRenderer: method to provide a custom renderer.

+ (R5VideoViewRenderer *) getRenderer

This API addition returns the current R5VideoViewRenderer instance being used by the R5VideoViewController.

R5VideoViewRenderer

Described in the previous section, this class addition to the 6.0.0 release of the iOS SDK now handles the interaction with the underlying GLKView as the default rendering routine. Developers can extend the R5VideoViewRenderer and override the onDrawFrame:andScaleMode: method to perform any required operations and bypass the default rendering.

Visit the 360 Camera Playback example in the public Red5 Pro iOS Testbed to see how a custom R5VideoViewRenderer instance is used for playback of a 360 stream.

6.0.0 Decoupled Shared Objects

Prior to the 6.0.0 release, usage of Shared Objects relied on a previous connection to the server established by a stream - either publisher or subscriber. The 6.0.0 release allows for establishing a Shared Object connection and data communication without the need for a previously established stream.

View the Decoupled Shared Objects example from the public Red5 Pro Android Testbed.

R5Connection

When using Shared Objects from an previously established R5Stream instance, the underlying R5Connection is used as the communication channel. In a decoupled Shared Object scenario, a R5Connection is used to start a "data-only" connection. The following methods have been added to the R5Connection API, to achieve a data-only connection:

+ (void) startDataOnlyStream

This method attempts to open a connection to be used for messaging through Shared Objects. Events are provided to assigned R5ConnectionDelegate receivers.

This method cannot be used in conjunction with a R5Connection already established from an R5Stream.

+ (void) stopDataOnlyStream

This method attempts to close the previously established "data-only" connection.

This method cannot be used in conjunction with a R5Connection already established from an R5Stream.

R5ConnectionDelegate

The delegate protocol receives event and status information over a R5Connection instance.

+ (void) onR5ConnectionStatus:withStatus:withMessage

Similar to the R5StreamDelegate protocol available for R5Stream:delegate prior to the Red5 Pro iOS Mobile SDK 6.0.0 release.