Playing streams via URL

Introduction

When a stream is published to a CDN using third-party streaming tools (OBS software, IP Camera, etc.), or a stream is relayed from ZEGO's real-time streaming server to a CDN, you can use the ZEGO Express SDK to play the stream directly from the CDN using the stream playback URL.

Prerequisites

Before implementing the "Playing Streams via URL" functions, please make sure:

• A project has been created in ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - How to view project information .
• ZEGO Express SDK has been integrated into the project to implement basic real-time audio and video functions. For details, please refer to Integrate the SDK and Implement a basic video call.

• Contact ZEGO technical support to activate the function of Playing streams via URL.

Configure the Stream Playback Parameters

To play the stream directly from a CDN URL, you need to create a ZegoCDNConfig object and config the "URL" parameter and the authentication parameter "authParam" (if required) accordingly.

• API Function Prototype:

  /// CDN configuration object 
  ///
  /// It includes the URL of the CDN and the authentication parameter
  @interface ZegoCDNConfig : NSObject
  
  /// The CDN URL
  @property (nonatomic, copy) NSString *url;
  
  /// The URL authentication parameter
  @property (nonatomic, copy) NSString *authParam;
  
  @end

• API Call Example:

  /** Set CDN parameters */
  ZegoCDNConfig *cdnConfig = [[ZegoCDNConfig alloc] init];
  // URL needs to be the CDN stream-playing address
  cdnConfig.url = @"rtmp://xxxx.yyy.zzz";
  // If you need authentication, you need to set the authentication parameters, if you don’t need authentication, you don’t need to set it (authentication parameters cannot contain "?" characters)
  cdnConfig.authParam = @"a=qqq&b=www";
  ZegoPlayerConfig *config = [[ZegoPlayerConfig alloc] init];
  config.cdnConfig = cdnConfig;

Start Playing the Streams

• API Function Prototype:

  /// Start playing the stream
  ///
  /// This API allows users to play a remote stream from the ZEGO real-time streaming server, or from the CDN URL if configured.
  /// Before starting to play the stream, you need to join a room first. For any new stream published to the room, you can obtain the stream ID by listening for the event callback [onRoomStreamUpdate].
  /// When the network quality is poor, the stream playback may get interrupted. The SDK will try to reconnect automatically. You can obtain the current state of the stream playback or any error that may occur by listening for the event callback [onPlayerStateUpdate].
  /// If the stream with the specified stream ID does not exist, the SDK will keep trying to pull the stream. Once the stream is published to the room, the SDK will start to play it. 
  /// The Canvas for displaying the received video can be updated by calling this API again (with the same stream ID).
  ///
  /// @param streamID: The stream ID of the stream to be played, a string with maximum length of 256 characters. A stream ID cannot contain any URL keyword, otherwise the stream playback will fail. It can only contain numbers, English letters, and special characters listed here: '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'.
  /// @param canvas: The view for displaying the received video. If the view is set to [nil], it will not be displayed.
  /// @param config: The advanced stream playback configurations.
  -(void)startPlayingStream:(NSString *)streamID canvas:(nullable ZegoCanvas *)canvas config:(ZegoPlayerConfig *)config;

• API Call Example:

  /** Start playing the stream */
  ZegoCDNConfig *cdnConfig = [[ZegoEngineConfig alloc] init];
  // URL needs to be the CDN stream-playing address 
  cdnConfig.url = @"rtmp://xxxxxxxx";
  // If you need authentication, you need to set the authentication parameters, if you don’t need authentication, you don’t need to set it (authentication parameters cannot carry "?" characters).
  cdnConfig.authParam = @"xxx";
  ZegoPlayerConfig *config = [[ZegoPlayerConfig alloc] init];
  config.cdnConfig = cdnConfig;
  // Start playing the stream
  [self.engine startPlayingStream:streamID canvas:playCanvas config:config];
  
  /** Stop playing the stream */
  [self.engine stopPlayingStream:self.streamID];

If there is an error while pulling the stream, please refer to Error Codes - 1004xxx Errors Related to Stream Playing.

(Optional) Monitor the Stream Playback Status