Cloud Media Relay

Cross-Channel Media Relay

pauseAllChannelMediaRelay

Pauses the media stream relay to all destination channels.

virtual int pauseAllChannelMediaRelay() = 0;

You can call this method after starting the media stream relay across channels to pause the relay to all destination channels. To resume the relay, call the resumeAllChannelMediaRelay method.

Note: Call this method after calling the startOrUpdateChannelMediaRelay method.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -5: The call is rejected. There is no ongoing media stream relay across channels.

pauseAllChannelMediaRelayEx

Pauses media stream relay to all destination channels.

virtual int pauseAllChannelMediaRelayEx(const RtcConnection& connection) = 0;

You can call this method after starting media stream relay across channels to pause relaying to all destination channels. To resume relaying, call the resumeAllChannelMediaRelay method.

Note: Call this method after calling startOrUpdateChannelMediaRelayEx.

Scenario

This method is applicable in multi-channel scenarios.

Parameters

connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -5: Call rejected. No ongoing media stream relay across channels.

resumeAllChannelMediaRelay

Resumes the media stream relay to all destination channels.

virtual int resumeAllChannelMediaRelay() = 0;
Note: Call this method after calling the pauseAllChannelMediaRelay method.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -5: The call is rejected. There is no paused media stream relay across channels.

resumeAllChannelMediaRelayEx

Resumes media stream relay to all destination channels.

virtual int resumeAllChannelMediaRelayEx(const RtcConnection& connection) = 0;
Note: Call this method after calling pauseAllChannelMediaRelayEx.

Scenario

This method is applicable in multi-channel scenarios.

Parameters

connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -5: Call rejected. No paused media stream relay across channels.

startOrUpdateChannelMediaRelay

Starts media stream relay across channels or updates the target channels for the relay.

virtual int startOrUpdateChannelMediaRelay(const ChannelMediaRelayConfiguration &configuration) = 0;
Since
Available since v4.2.0.

The first successful call to this method relays the media stream from the source channel to the target channel. To relay to additional channels or stop relaying to a specific channel, you can call this method again to update the target channels. Up to six target channels are supported.

Note:
  • Call this method after joining a channel.
  • This method is only effective when you are a host in a live broadcast channel.
  • The media stream relay across channels feature must be enabled by contacting technical support.
  • This method does not support string user accounts.

Related Callbacks

After this method is successfully called, the SDK triggers the onChannelMediaRelayStateChanged callback to report the media stream relay status. Common statuses include:
  • If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_RUNNING (2) and RELAY_OK (0), it means the SDK has successfully started relaying the media stream from the source channel to the target channel.
  • If the onChannelMediaRelayStateChanged callback returns RELAY_STATE_FAILURE (3), it indicates an error occurred during the media stream relay.

Parameters

configuration
The configuration for media stream relay. See ChannelMediaRelayConfiguration.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurred.
    • -2: Invalid parameter.
    • -8: Internal state error, possibly because the user is not a host.

startOrUpdateChannelMediaRelayEx

Starts or updates the media stream relay across channels.

virtual int startOrUpdateChannelMediaRelayEx(const ChannelMediaRelayConfiguration& configuration, const RtcConnection& connection) = 0;
Since
Available since v4.2.0.
The first successful call to this method starts relaying media streams from the source channel to the destination channel. To relay to additional channels or stop relaying to a specific channel, call this method again to update the destination channels. This feature supports relaying to up to six destination channels. After a successful call, the SDK triggers the onChannelMediaRelayStateChanged callback to report the relay status:
  • When the callback returns RELAY_STATE_RUNNING (2) and RELAY_OK (0), it indicates that the media stream has started relaying from the source channel to the destination channel.
  • When the callback returns RELAY_STATE_FAILURE (3), it indicates an error occurred during the media stream relay.
Note:
  • Call this method after joining the channel.
  • This method takes effect only when you are a host in a live broadcast channel.
  • To enable the media stream relay across channels feature, contact technical support.
  • This method does not support string user accounts.

Scenario

This method applies to multi-channel scenarios.

Parameters

configuration
The configuration for media stream relay. See ChannelMediaRelayConfiguration.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: A general error occurred (no specific reason).
    • -2: Invalid parameter.
    • -8: Internal state error, possibly because the user is not a host.

stopChannelMediaRelay

Stops the media stream relay across channels.

virtual int stopChannelMediaRelay() = 0;

Call this method to stop the media stream relay across channels. Once the relay stops, the host leaves all destination channels.

Note: If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback and returns the error code RELAY_ERROR_SERVER_NO_RESPONSE (2) or RELAY_ERROR_SERVER_CONNECTION_LOST (8). You can also call the leaveChannel method to leave the channel, and the media stream relay will automatically stop.

Related Callbacks

After this method is successfully called, the SDK triggers the onChannelMediaRelayStateChanged callback to report the state of the media stream relay.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -5: The call is rejected. There is no ongoing media stream relay across channels.

stopChannelMediaRelayEx

Stops media stream relay across channels.

virtual int stopChannelMediaRelayEx(const RtcConnection& connection) = 0;

Call this method to stop media stream relay across channels. Once the relay stops, the host leaves all destination channels.

Note: If the method call fails, the SDK triggers the onChannelMediaRelayStateChanged callback and returns the status code RELAY_ERROR_SERVER_NO_RESPONSE (2) or RELAY_ERROR_SERVER_CONNECTION_LOST (8). You can also call the leaveChannel method to leave the channel, and the media stream relay across channels stops automatically.

Scenario

This method is applicable in multi-channel scenarios.

Related Callbacks

After this method is successfully called, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback returns RELAY_STATE_IDLE (0) and RELAY_OK (0), it indicates that the host has successfully stopped the relay.

Parameters

connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -5: Call rejected. No ongoing media stream relay across channels.

Media Push

startRtmpStreamWithoutTranscoding

Starts pushing media streams to CDN without transcoding.

virtual int startRtmpStreamWithoutTranscoding(const char* url) = 0;

Agora recommends using a more comprehensive server-side streaming feature. See [Implement server-side CDN streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). You can call this method to push audio or video streams to a specified CDN address. This method can only push media streams to one CDN address at a time. To push to multiple addresses, call this method multiple times.

Note:
  • Call this method after joining a channel.
  • Only the host role in LIVE_BROADCASTING mode can call this method.
  • If a retry is needed after a streaming failure, call stopRtmpStream first to stop streaming, then call this method again to retry. Otherwise, the SDK returns the same error code as the previous failure.

Related Callbacks

After successfully calling this method, the SDK triggers the onRtmpStreamingStateChanged callback to report the streaming state.

Parameters

url
CDN streaming URL. Format must be RTMP or RTMPS. The string length must not exceed 1024 bytes.
Note: Chinese and other special characters are not supported.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid url or transcoding configuration. Please check the url and transcoding configuration.
    • -7: SDK is not initialized before calling this method.
    • -19: The CDN streaming URL is already in use. Please use a different URL.

startRtmpStreamWithoutTranscodingEx

Starts pushing media streams to the CDN without transcoding.

virtual int startRtmpStreamWithoutTranscodingEx(const char* url, const RtcConnection& connection) = 0;

Agora recommends using the more robust server-side streaming feature. See [Implement server-side CDN streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). You can call this method to push audio or video streams to a specified CDN address. This method supports pushing to only one CDN address at a time. To push to multiple addresses, call this method multiple times. After calling this method, the SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the streaming status.

Note:
  • Call this method after joining a channel.
  • Only a host in a LIVE_BROADCASTING channel can call this method.
  • If you need to retry after a failed push, call stopRtmpStream to stop streaming before retrying. Otherwise, the SDK returns the same error code as the previous failure.

Scenario

This method applies to multi-channel scenarios.

Related Callbacks

After successfully calling this method, the SDK triggers the onRtmpStreamingStateChanged callback to report the streaming status.

Parameters

url
The CDN streaming URL. Must be in RTMP or RTMPS format. The character length must not exceed 1024 bytes. Special characters such as Chinese are not supported.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid URL or transcoding configuration. Check the URL and transcoding configuration.
    • -7: The SDK is not initialized before calling this method.
    • -19: The stream URL is already in use. Use a different URL.

startRtmpStreamWithTranscoding

Starts CDN streaming with transcoding configuration.

virtual int startRtmpStreamWithTranscoding(const char* url, const LiveTranscoding& transcoding) = 0;

Agora recommends using a more comprehensive server-side streaming feature. See [Implement server-side CDN streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). You can call this method to push real-time audio and video streams to a specified CDN address and set the transcoding configuration. This method can only push media streams to one CDN address at a time. To push to multiple addresses, call this method multiple times. Under the same Agora project, a maximum of 200 concurrent media stream pushing tasks is supported by default. Contact technical support if you need a higher quota.

Note:
  • Call this method after joining a channel.
  • Only the host role in the interactive live streaming channel scenario can call this method.
  • If you want to retry streaming after a failure, call stopRtmpStream first to stop streaming, then call this method again to retry. Otherwise, the SDK returns the same error code as the previous failure.

Parameters

url
CDN streaming URL. Format must be RTMP or RTMPS. The URL length must not exceed 1024 bytes. Chinese and other special characters are not supported.
transcoding
Transcoding configuration for CDN streaming. See LiveTranscoding.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid URL or transcoding configuration. Please check url and transcoding.
    • -7: SDK is not initialized before calling this method.
    • -19: The CDN streaming URL is already in use. Please use a different URL.

startRtmpStreamWithTranscodingEx

Starts RTMP streaming and sets the transcoding configuration.

virtual int startRtmpStreamWithTranscodingEx(const char* url, const LiveTranscoding& transcoding, const RtcConnection& connection) = 0;

Agora recommends using the more comprehensive server-side streaming feature. See [Implement server-side streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). You can call this method to push real-time audio and video streams to the specified CDN address and set the transcoding configuration. This method can only push media streams to one CDN address at a time. To push to multiple addresses, call this method multiple times.

Note:
  • Before using this method, make sure the RTMP streaming service is enabled.
  • Call this method after joining the channel.
  • Only hosts in a live broadcast scenario can call this method.
  • If you need to retry after a streaming failure, call stopRtmpStreamEx to stop the stream first, then call this method again. Otherwise, the SDK returns the same error code as the last failure.

Scenario

This method applies to multi-channel scenarios.

Parameters

url
The RTMP streaming address, in RTMP or RTMPS format. The character length cannot exceed 1024 bytes. Special characters such as Chinese are not supported.
transcoding
The transcoding configuration for RTMP streaming. See LiveTranscoding.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -2: Invalid URL or transcoding configuration. Check url and the transcoding configuration.
    • -7: SDK not initialized before calling this method.
    • -19: The RTMP stream address is already in use. Please use a different address.

stopRtmpStream

Stops pushing media streams to the specified CDN address.

virtual int stopRtmpStream(const char* url) = 0;

Agora recommends using a more comprehensive server-side streaming feature. See [Implement Server-Side Streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). You can call this method to stop live streaming to the specified CDN address. This method can only stop one address at a time. To stop multiple addresses, call this method multiple times.

Related Callbacks

After successfully calling this method, the SDK triggers the onRtmpStreamingStateChanged callback to report the streaming status.

Parameters

url
The media streaming URL, in RTMP or RTMPS format. The character length must not exceed 1024 bytes.
Note: Special characters such as Chinese are not supported.

Return Values

  • 0: Success.
  • < 0: Failure.

stopRtmpStreamEx

Stops pushing media streams to the specified CDN address.

virtual int stopRtmpStreamEx(const char* url, const RtcConnection& connection) = 0;

Agora recommends using the more comprehensive server-side streaming feature. See [Implement server-side streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). You can call this method to stop pushing media streams to the specified CDN address. This method can only stop streaming to one address at a time. To stop streaming to multiple addresses, call this method multiple times.

Scenario

This method applies to multi-channel scenarios.

Related Callbacks

After successfully calling this method, the SDK triggers the onRtmpStreamingStateChanged callback to report the streaming status.

Parameters

url
The RTMP streaming address, in RTMP or RTMPS format. The character length cannot exceed 1024 bytes. Special characters such as Chinese are not supported.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

updateRtmpTranscoding

Updates the transcoding configuration for CDN streaming.

virtual int updateRtmpTranscoding(const LiveTranscoding& transcoding) = 0;

Agora recommends using a more comprehensive server-side streaming feature. See [Implement server-side CDN streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). After starting to push media streams to CDN with transcoding, you can dynamically update the transcoding configuration based on actual scenarios. After updating the configuration, the SDK triggers the onTranscodingUpdated callback.

Parameters

transcoding
Transcoding configuration for CDN streaming. See LiveTranscoding.

Return Values

  • 0: Success.
  • < 0: Failure.

updateRtmpTranscodingEx

Updates the transcoding configuration for RTMP streaming.

virtual int updateRtmpTranscodingEx(const LiveTranscoding& transcoding, const RtcConnection& connection) = 0;

Agora recommends using the more comprehensive server-side streaming feature. See [Implement server-side streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). After starting to push media streams to the CDN using transcoding, you can dynamically update the transcoding configuration based on the actual scenario. After the configuration is updated, the SDK triggers the onTranscodingUpdated callback.

Scenario

This method applies to multi-channel scenarios.

Parameters

transcoding
The transcoding configuration for RTMP streaming. See LiveTranscoding.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

onRtmpStreamingEvent

Reports events during RTMP streaming.

virtual void onRtmpStreamingEvent(const char* url, RTMP_STREAMING_EVENT eventCode)

Parameters

url
The RTMP streaming URL.
eventCode
RTMP streaming event code. See RTMP_STREAMING_EVENT.

onRtmpStreamingStateChanged

Callback triggered when the RTMP streaming state changes.

virtual void onRtmpStreamingStateChanged(const char* url, RTMP_STREAM_PUBLISH_STATE state, RTMP_STREAM_PUBLISH_REASON reason)

When the RTMP streaming state changes, the SDK triggers this callback and reports the corresponding URL and current streaming state. In case of an exception, you can refer to the error code parameter for troubleshooting.

Parameters

url
The URL whose RTMP streaming state has changed.
state
Current RTMP streaming state. See RTMP_STREAM_PUBLISH_STATE.
reason
Reason for the RTMP streaming state change. See RTMP_STREAM_PUBLISH_REASON.

CDN Streaming

setDirectCdnStreamingAudioConfiguration

Sets the audio configuration for audio streams directly pushed to the CDN by the host.

virtual int setDirectCdnStreamingAudioConfiguration(AUDIO_PROFILE_TYPE profile) = 0;
Deprecated
Deprecated since v4.6.0.

When you set publishMicrophoneTrack or publishCustomAudioTrack to true in DirectCdnStreamingMediaOptions, you can call this method to configure the audio profile.

Parameters

profile
Audio profile, including sample rate, bitrate, encoding mode, and number of channels. See AUDIO_PROFILE_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.

setDirectCdnStreamingVideoConfiguration

Sets the video properties for streams directly pushed to the CDN by the host.

virtual int setDirectCdnStreamingVideoConfiguration(const VideoEncoderConfiguration& config) = 0;
Deprecated
Deprecated since v4.6.0.

This method only affects video streams captured from the camera, screen, or custom video source. When you set publishCameraTrack or publishCustomVideoTrack to true in DirectCdnStreamingMediaOptions, you can call this method to configure the video properties. If the local camera does not support the specified video resolution, the SDK automatically adjusts it to the closest supported resolution while maintaining the aspect ratio. You can get the actual video resolution through the onDirectCdnStreamingStats callback.

Note: During CDN live streaming, only ORIENTATION_MODE_FIXED_LANDSCAPE or ORIENTATION_MODE_FIXED_PORTRAIT is supported for ORIENTATION_MODE.

Parameters

config
Video properties. See VideoEncoderConfiguration.
Note: During CDN live streaming, only ORIENTATION_MODE_FIXED_LANDSCAPE or ORIENTATION_MODE_FIXED_PORTRAIT is supported for ORIENTATION_MODE.

Return Values

  • 0: Success.
  • < 0: Failure.

startDirectCdnStreaming

Starts pushing media streams directly to the CDN.

virtual int startDirectCdnStreaming(IDirectCdnStreamingEventHandler* eventHandler, const char* publishUrl, const DirectCdnStreamingMediaOptions& options) = 0;
Deprecated
Deprecated since v4.6.0.
Agora does not support pushing media streams to the same URL multiple times. Agora does not support setting both publishCameraTrack and publishCustomVideoTrack to true, or both publishMicrophoneTrack and publishCustomAudioTrack to true. When selecting media settings (DirectCdnStreamingMediaOptions), refer to the following example: If you want to push audio and video streams collected from a custom source, set the media options as follows:
  • Set publishCustomAudioTrack to true and call pushAudioFrame;
  • Set publishCustomVideoTrack to true and call pushVideoFrame;
  • Set publishCameraTrack to false (default);
  • Set publishMicrophoneTrack to false (default).
Since v4.2.0, the Agora SDK supports audio-only live streaming. You can set publishCustomAudioTrack or publishMicrophoneTrack to true in DirectCdnStreamingMediaOptions and call pushAudioFrame to push the audio stream.
Note: Agora only supports pushing one audio-video stream or one audio stream to the CDN.

Parameters

eventHandler
Event callback interface. See IDirectCdnStreamingEventHandler.
publishUrl
CDN streaming URL.
options
Media settings for the host. See DirectCdnStreamingMediaOptions.

Return Values

  • 0: Success.
  • < 0: Failure.

stopDirectCdnStreaming

Stops pushing streams to the CDN.

virtual int stopDirectCdnStreaming() = 0;
Deprecated
Deprecated since v4.6.0.

Return Values

  • 0: Success.
  • < 0: Failure.

onDirectCdnStreamingStateChanged

Callback for CDN streaming state changes.

virtual void onDirectCdnStreamingStateChanged(DIRECT_CDN_STREAMING_STATE state, DIRECT_CDN_STREAMING_REASON reason, const char* message)

When the host streams directly to the CDN and the streaming state changes, the SDK triggers this callback to report the new streaming state, error code, and related information.

Parameters

state
Current CDN streaming state. See DIRECT_CDN_STREAMING_STATE.
reason
Reason for the CDN streaming state change. See DIRECT_CDN_STREAMING_REASON.
message
Additional information about the streaming state change.

onDirectCdnStreamingStats

Callback for reporting CDN streaming statistics.

virtual void onDirectCdnStreamingStats(const DirectCdnStreamingStats& stats)

Trigger Timing

When the host pushes media streams directly to the CDN, the SDK triggers this callback once per second.

Parameters

stats
Current CDN streaming statistics. See DirectCdnStreamingStats.