Playing Stream by URL
Feature Overview
When the publishing end uses third-party publishing tools (such as OBS software, network camera IP Camera, etc.) to publish streams to CDN, or pushes audio and video content to third-party CDNs through ZEGO SDK's relay-to-CDN feature, you can directly pass in the URL address to play streams.
If you need to switch from CDN play stream scenario to co-hosting scenario, please refer to Switching from CDN Play Stream to Co-hosting Scenario documentation.
Example Source Code Download
Please refer to Download Example Source Code to get the source code.
For related source code, please check the files in the "/ZegoExpressExample/AdvancedStreaming/src/main/java/im/zego/advancedstreaming/streamByCdn" directory.
Prerequisites
Before implementing URL play stream functionality, please ensure:
-
You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.
-
You have integrated ZEGO Express SDK in your project and implemented basic audio and video publish/play stream functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
-
You have contacted ZEGO Technical Support to enable the URL play stream feature.
-
You have published audio and video streams to CDN and know the corresponding URL. For details, please refer to Using CDN for Live Streaming.
Usage Steps
1 Configure Play Stream Parameters
To play streams directly through CDN URL addresses, you need to use the ZegoCDNConfig object to fill in URL parameters. If the corresponding CDN has configured play stream authentication, you also need to fill in 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
ZegoCDNConfig cdnConfig = new ZegoCDNConfig();
// URL is the CDN play stream address
cdnConfig.url = "rtmp://xxxxxxxx";
// If authentication is required, set authentication parameters. If authentication is not required, this can be left unset (authentication parameters cannot contain "?" character)
cdnConfig.authParam = "xxx";
ZegoPlayerConfig zegoPlayerConfig = new ZegoPlayerConfig();
zegoPlayerConfig.cdnConfig = cdnConfig;2 Start Playing Stream
Start playing stream by calling the startPlayingStream interface.
When playing streams, if an error occurs, please refer to Common Error Codes - 1004xxx Play Stream Related Error Codes.
- Before playing stream by URL, 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 play stream content is based on the URL.
- Although the stream ID cannot be used for playing stream at this time, the SDK internally still uses the stream ID as the unique identifier for subsequent play stream related callbacks. Therefore, the stream ID still needs to be globally unique within the entire AppID.
// Start playing stream, set remote play stream rendering view ZegoCanvas, using SDK's default view mode, proportional scaling to fill the entire View
// After filling in the url parameter, the SDK will pull audio and video streams from the url, but still needs to pass a unique streamID to the SDK, which will use this streamID to identify the stream internally
engine.startPlayingStream("STREAM_ID", new ZegoCanvas(play_view), 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 starting to play stream
engine.stopPlayingStream("STREAM_ID");4 (Optional) Listen to Play Stream Related Event Notifications
You can listen to the result of playing stream from CDN through onPlayerStateUpdate.
If you are not using ZEGO SDK for publishing but using third-party publishing tools to publish directly, but using ZEGO SDK for playing streams, in this scenario the publishing end has not joined the room using ZEGO SDK, and the playing end will not receive onRoomStreamUpdate callbacks by default. You can use the Add Room Stream and Delete Room Stream functions to allow the playing end to receive onRoomStreamUpdate callbacks.
engine.setEventHandler(new IZegoEventHandler(){
// Other overridden callbacks
...
@Override
public void onPlayerStateUpdate(String streamID, ZegoPlayerState state, int errorCode, JSONObject extendedData) {
// After successfully calling the play stream interface, when the player state changes, such as network interruption causing publishing exceptions, etc., the SDK will notify through this callback while retrying to play stream
// When receiving this callback notification and state is PLAYING, it means play stream succeeded
// When receiving this callback notification and state is PLAY_REQUESTING, it means either playing stream or SDK is retrying to play stream due to network interruption, etc.
// When receiving this callback notification and state is NO_PLAY, it means play stream has stopped
// When playing stream by URL, the stream_id in the callback parameters is the stream ID when calling the play stream API, used to uniquely identify the current play stream event.
}
// Other overridden callbacks
...
});