Play Stream by URL
Feature Overview
When the publishing end uses third-party publishing tools (such as OBS software, network camera IPCamera, etc.) to publish streams to CDN, or pushes audio/video screens to third-party CDNs through ZEGO SDK's CDN relay function, you can directly pass in the URL address to play streams.
If you need to switch from the CDN stream playing scenario to the video call scenario, please refer to the Switch from CDN Stream Playing to Video Call Scenario document.
Prerequisites
Before implementing the URL stream playing function, 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 the project and implemented basic audio and video publishing and playing functions. For details, please refer to Quick Start - Integration and Quick Start - Implementation Flow.
-
You have contacted ZEGOCLOUD Technical Support to enable the URL stream playing function.
-
You have pushed audio/video streams to CDN and know the corresponding URL. For details, please refer to Use CDN for Live Streaming.
Usage Steps
1 Configure Stream Playing Parameters
To play streams directly through CDN's URL address, you need to use the ZegoCDNConfig object to fill in the URL parameters. When there is stream playing authentication when playing from CDN, 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
ZegoCDNConfig cdnConfig;
// URL is the CDN stream playing address
cdnConfig.url = "rtmp://xxxxxxxx";
// If authentication is required, set the authentication parameters. If authentication is not required, you can leave it unset (authentication parameters cannot contain the "?" character)
cdnConfig.authParam = "xxx";
ZegoPlayerConfig config;
config.cdnConfig = &cdnConfig;2 Start Playing Stream
Start playing stream by calling the startPlayingStream interface.
When playing stream, if an error occurs, please refer to Stream Playing Error Codes.
- Before playing stream by URL, please ensure you have logged in the room.
- When playing stream by URL, you cannot directly play stream by filling in the Stream ID. The actual playing screen is subject to the URL.
- Although the Stream ID cannot be used for stream playing at this time, the SDK internally still uses the Stream ID as the unique identifier for subsequent stream playing related callbacks. Therefore, the Stream ID still needs to be globally unique within the entire AppID.
// Start playing stream, set the remote playing rendering view canvas, and use the SDK's default view mode, aspect ratio scaling to fill the entire View
ZegoCanvas canvas((void*)view);
// After filling in the URL parameter, the SDK will pull the audio/video stream 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
engine->startPlayingStream(streamID, &canvas, config);3 Stop Playing Stream
To stop playing stream, call the stopPlayingStream interface.
// Stop playing stream
engine->stopPlayingStream(streamID);4 (Optional) Listen to Stream Playing Related Event Notifications
You can listen to the result of stream playing 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, in this scenario the publishing end has not used ZEGO SDK to join the room, and the playing end will not receive the onRoomStreamUpdate callback by default. You can use the Add Room Stream and Delete Room Stream functions to let the playing end receive the onRoomStreamUpdate callback.
// Please note, do not call any SDK interfaces in the SDK callback thread, you need to manually switch to another thread, otherwise a deadlock will occur
class MyEventHandler :public IZegoEventHandler
{
public:
void onPlayerStateUpdate(const std::string& /*streamID*/, ZegoPlayerState /*state*/, int /*errorCode*/, const std::string& /*extendedData*/) {
/** After calling the stream playing interface successfully, when the player's state changes, such as when a network interruption causes streaming abnormalities, the SDK will notify through this callback while retrying stream playing */
/** Not playing state, in this state before playing stream. If a steady exception occurs during the stream playing process, such as incorrect AppID, AppSign, or Token, it will enter the not playing state */
//ZEGO_PLAYER_STATE_NO_PLAY = 0,
/** Requesting playing state, after the stream playing operation is executed successfully, it will enter the requesting playing state, usually used for application interface display. If an interruption occurs due to poor network quality, the SDK will internally retry and also return to the requesting playing state */
//ZEGO_PLAYER_STATE_PLAY_REQUESTING = 1,
/** Playing state, entering this state indicates that stream playing has succeeded and users can communicate normally */
//ZEGO_PLAYER_STATE_PLAYING = 2
//When playing by URL, the stream_id in the callback parameters is the stream ID when calling the stream playing API, used to uniquely identify the current stream playing event.
}
};
auto handler=std::make_shared<MyEventHandler>();
engine->setEventHandler(handler);