Playing Stream by URL
Overview
This document does not apply to the Web platform.
When the publishing end uses third-party publishing tools (such as OBS software, network camera IP Camera, etc.) to publish streams to CDN, or uses the ZEGO SDK's relaying to CDN feature to push audio and video to third-party CDNs, you can directly pass in the URL address to play streams.
Demo Source Code Download
Please refer to Download Demo Source Code to obtain the source code.
For related source code, please check the files in the "lib\topics\StreamAdvanced\stream_by_cdn" directory.
Prerequisites
Before implementing URL playing stream functionality, please ensure:
- You have integrated the ZEGO Express SDK into your project and implemented basic real-time audio and video functions. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
- You have created a project in the ZEGOCLOUD Console and obtained a valid AppID and AppSign. For details, please refer to Console - Project Information.
- You have contacted ZEGOCLOUD Technical Support to activate the URL playing stream feature.
- You have published the audio and video stream to CDN and know the corresponding URL. For details, please refer to Using CDN for Live Streaming.
Usage Steps
1 Configure playing stream parameters
To play streams directly through the CDN's URL address, you need to use the ZegoCDNConfig object to fill in the URL parameters. If the corresponding CDN is configured with playing stream authentication, you also need to fill in the authentication parameters through the authParam field.
- The authentication parameter refers to the string after the "?" in the URL (excluding "?"). For example, if the CDN playing stream URL is "rtmp://xxxx.yyy.zzz?a=qqq&b=www", the authentication parameter is "a=qqq&b=www".
- The authentication parameter in the playing stream URL is mainly used for anti-leeching. For specific rules, please consult your CDN provider or ZEGO Technical Support. If there is no authentication parameter, you can ignore the "authParam" field.
- Supported playing stream protocols include: RTMP, FLV, HLS (if you need to use HLS protocol for playing stream, please contact ZEGO Technical Support to enable it).
// Set CDN parameters
// URL is the CDN playing stream address
String url = "rtmp://xxxxxxxx";
// If authentication is required, set the authentication parameters. If authentication is not required, it can be left unset (authentication parameters cannot contain the "?" character)
String authParam = "xxx";
var config = ZegoCDNConfig(url, authParam);
var zegoPlayerConfig = ZegoPlayerConfig.defaultConfig();
zegoPlayerConfig.cdnConfig = config;2 Start playing stream
- Before playing stream by URL, please ensure that you have logged in to the room.
- When playing stream by URL, you cannot directly play stream by filling in the stream ID. The actual playing stream picture is based on the URL.
- Although the stream ID cannot be used to play stream at this time, the SDK still uses the stream ID as a unique identifier internally, which is used in subsequent playing stream related callbacks. Therefore, the stream ID still needs to be globally unique within the entire AppID.
Call the startPlayingStream interface to start playing stream.
When playing stream, if an error occurs, please refer to Common Error Codes - 1004xxx Playing Stream Related Error Codes.
// Start playing stream, set the remote playing stream rendering view canvas, and use the SDK's default view mode, which scales proportionally to fill the entire View
// If using Video Call SDK or audio and video scenarios, after filling in the URL parameter, the SDK will pull audio and video streams from the URL, but you still need to pass a unique streamID to the SDK, which will internally use this streamID to identify the stream
ZegoExpressEngine.instance.startPlayingStream("STREAM_ID", canvas: ZegoCanvas(viewID), config: zegoPlayerConfig);
// If using Voice Call SDK or audio-only scenarios, you do not need to pass the canvas parameter
// ZegoExpressEngine.instance.startPlayingStream("STREAM_ID", config: zegoPlayerConfig);3 Stop playing stream
To stop playing stream, call the stopPlayingStream interface.
// Stop playing stream
// The streamID passed when stopping playing stream is the streamID passed when playing stream
ZegoExpressEngine.instance.stopPlayingStream("STREAM_ID");4 (Optional) Listen to playing stream related event notifications
You can listen to the result of playing stream from CDN through onPlayerStateUpdate.
If you are not using ZEGO SDK to publish stream, but using third-party publishing tools to publish stream directly, and using ZEGO SDK to play stream, in this scenario, the publishing side has not used ZEGO SDK to join the room, and the playing side will not receive the callback of onRoomStreamUpdate by default.
ZegoExpressEngine.onPlayerStateUpdate(String streamID, ZegoPlayerState state, int errorCode, Map<String, dynamic> extendedData) = {
// After successfully calling the playing stream interface, when the player state changes, such as network interruption causing publishing stream abnormalities, the SDK will notify through this callback while retrying to play stream
// 1. When receiving this callback notification and state is Playing, it means playing stream succeeded
// 2. When receiving this callback notification and state is PlayRequesting, it means may be playing stream or the SDK is retrying to play stream due to network interruption or other reasons
// 3. When receiving this callback notification and state is NoPlay, it means playing stream stopped
// 4. When playing stream by URL, the streamID in the callback parameter is the stream ID when calling the playing stream API, used to uniquely identify the current playing stream event.
};