Media Push

startRtmpStreamWithoutTranscoding

Starts pushing audio and video streams to the CDN without transcoding.

public abstract int startRtmpStreamWithoutTranscoding(String url);

Agora recommends using a more complete server-side streaming solution. See [Implement server-side live 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 URL. This method can only push media streams to one CDN URL at a time. To push to multiple URLs, call this method multiple times.

Note:

Call this method after joining a channel.
Only users with the broadcaster role in LIVE_BROADCASTING mode can call this method.
If you need to retry after a streaming failure, first call stopRtmpStream to stop streaming, then call this method again; otherwise, the SDK will return the same error code as the previous failure.

Related Callbacks

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

Parameters

url: The streaming URL in RTMP or RTMPS format. The length must not exceed 1024 bytes. Chinese or other special characters are not supported.

Return Values

0: Success.
< 0: Failure.
- -2: Invalid url.
- -7: SDK not initialized before calling this method.
- -19: Streaming URL already in use. Please use a different URL.

startRtmpStreamWithoutTranscodingEx

Starts pushing the media stream to the CDN without transcoding.

public abstract int startRtmpStreamWithoutTranscodingEx(String url, RtcConnection connection);

Agora recommends using the more comprehensive server-side streaming service. 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 only supports pushing 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 users in the LIVE_BROADCASTING channel profile and with broadcaster role can call this method.
If the stream fails and you need to retry, call stopRtmpStream first to stop the stream, then call this method again. Otherwise, the SDK returns the same error code as the previous failure.

Scenario

This method applies to multi-channel scenarios.

Related Callbacks

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

Parameters

url: The CDN streaming URL. Must be in RTMP or RTMPS format, and no longer than 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. Please check the URL and transcoding settings.
- -7: SDK not initialized before calling this method.
- -19: The CDN streaming URL is already in use. Please use a different URL.

startRtmpStreamWithTranscoding

Starts live streaming with transcoding configuration.

public abstract int startRtmpStreamWithTranscoding(String url, LiveTranscoding transcoding);

Agora recommends using a more complete server-side streaming solution. See [Implement server-side live 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 URL and set the transcoding configuration. This method can only push media streams to one CDN URL at a time. To push to multiple URLs, call this method multiple times. By default, a maximum of 200 streaming tasks can be run simultaneously under one Agora project. For higher limits, contact technical support.

Note:

Call this method after joining a channel.
Only users with the broadcaster role in an interactive live streaming channel can call this method.
If you need to retry after a streaming failure, first call stopRtmpStream to stop streaming, then call this method again; otherwise, the SDK will return the same error code as the previous failure.

Related Callbacks

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

Parameters

url: The streaming URL in RTMP or RTMPS format. The length must not exceed 1024 bytes. Chinese or other special characters are not supported.
transcoding: The transcoding configuration for live streaming. See LiveTranscoding.

Return Values

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

startRtmpStreamWithTranscodingEx

Starts CDN streaming with transcoding configuration.

public abstract int startRtmpStreamWithTranscodingEx(String url, LiveTranscoding transcoding, RtcConnection connection);

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

Note:

Before using this method, make sure CDN streaming is enabled.
Call this method after joining a channel.
Only broadcasters in a LIVE_BROADCASTING channel can call this method.
If the stream fails and you need to retry, call stopRtmpStreamEx first to stop the stream, then call this method again. Otherwise, the SDK returns the same error code as the previous failure.

Scenario

This method applies to multi-channel scenarios.

Parameters

url: The CDN streaming URL. Must be in RTMP or RTMPS format, and no longer than 1024 bytes. Special characters such as Chinese are not supported.
transcoding: The transcoding configuration for CDN streaming. See LiveTranscoding.
connection: Connection information. See RtcConnection.

Return Values

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

stopRtmpStream

Stops pushing media streams to the specified CDN URL.

public abstract int stopRtmpStream(String url);

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

Parameters

url: The streaming URL in RTMP or RTMPS format. The length must not exceed 1024 bytes. Chinese or other special characters are not supported.

Return Values

0: Success.
< 0: Failure.

stopRtmpStreamEx

Stops pushing media streams to the specified CDN address.

public abstract int stopRtmpStreamEx(String url, RtcConnection connection);

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

Scenario

This method applies to multi-channel scenarios.

Related Callbacks

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

Parameters

url: The CDN streaming URL. Must be in RTMP or RTMPS format, and no longer than 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 live streaming.

public abstract int updateRtmpTranscoding(LiveTranscoding transcoding);

Agora recommends using a more complete server-side streaming solution. See [Implement server-side live streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page).

Parameters

transcoding: The transcoding configuration for live streaming. See LiveTranscoding.

Return Values

0: Success.
< 0: Failure.

updateRtmpTranscodingEx

Updates the transcoding configuration for CDN streaming.

public abstract int updateRtmpTranscodingEx(LiveTranscoding transcoding, RtcConnection connection);

Agora recommends using the more comprehensive server-side streaming service. See [Implement Server-side CDN Streaming](https://doc.shengwang.cn/doc/media-push/restful/landing-page). After starting CDN streaming with transcoding, you can dynamically update the configuration as needed. After the update, the SDK triggers the onTranscodingUpdated callback.

Scenario

This method applies to multi-channel scenarios.

Parameters

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

Return Values

0: Success.
< 0: Failure.

onRtmpStreamingEvent

Callback for RTMP streaming events.

public void onRtmpStreamingEvent(String url, int event)

Since: Available since v3.1.0.

Parameters

url

The RTMP streaming URL.

event

The event code for RTMP streaming:

RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE (1): Error occurred when adding background or watermark image.
RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE (2): The streaming URL is already in use. Use a new URL to start a new stream.
RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT (3): This feature is not supported.
RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN (4): Reserved parameter.

onRtmpStreamingStateChanged

Callback for RTMP streaming state changes.

public void onRtmpStreamingStateChanged(String url, int state, int reason)

This callback indicates the state of RTMP streaming. When the state changes, the SDK triggers this callback and returns the corresponding URL and current streaming state. If an exception occurs, refer to the error code parameter for detailed error information.

Trigger Timing

This callback is triggered when the RTMP streaming state changes.

Parameters

url

The RTMP streaming URL whose state has changed.

state

The current RTMP streaming state:

RTMP_STREAM_PUBLISH_STATE_IDLE(0): RTMP streaming has not started or has ended.
RTMP_STREAM_PUBLISH_STATE_CONNECTING(1): Connecting to the streaming and CDN servers.
RTMP_STREAM_PUBLISH_STATE_RUNNING(2): Streaming is ongoing. The SDK successfully pushes the RTMP or RTMPS stream and returns this state.
RTMP_STREAM_PUBLISH_STATE_RECOVERING(3): Attempting to recover the stream. When an exception occurs or streaming is interrupted, the SDK tries to recover and returns this state.
- If recovery succeeds, returns RTMP_STREAM_PUBLISH_STATE_RUNNING(2).
- If recovery fails within 60 seconds or a server error occurs, returns RTMP_STREAM_PUBLISH_STATE_FAILURE(4). You can also call startRtmpStreamWithTranscoding, startRtmpStreamWithoutTranscoding, or stopRtmpStream to reconnect.
RTMP_STREAM_PUBLISH_STATE_FAILURE(4): Streaming failed. Refer to the error code for details or try streaming again.
RTMP_STREAM_PUBLISH_STATE_DISCONNECTING(5): The SDK is disconnecting from the Agora streaming and CDN servers. When you call stopRtmpStream to stop streaming, the SDK returns RTMP_STREAM_PUBLISH_STATE_DISCONNECTING followed by RTMP_STREAM_PUBLISH_STATE_IDLE.

reason

The reason for the RTMP streaming state change:

RTMP_STREAM_PUBLISH_REASON_OK(0): Streaming succeeded.
RTMP_STREAM_PUBLISH_REASON_INVALID_ARGUMENT(1): Invalid parameter. Check parameter settings.
RTMP_STREAM_PUBLISH_REASON_ENCRYPTED_STREAM_NOT_ALLOWED(2): Encrypted stream cannot be pushed.
RTMP_STREAM_PUBLISH_REASON_CONNECTION_TIMEOUT(3): Streaming timeout. Try streaming again.
RTMP_STREAM_PUBLISH_REASON_INTERNAL_SERVER_ERROR(4): Internal error on Agora streaming server. Try streaming again.
RTMP_STREAM_PUBLISH_REASON_RTMP_SERVER_ERROR(5): CDN server error.
RTMP_STREAM_PUBLISH_REASON_TOO_OFTEN(6): Reserved parameter.
RTMP_STREAM_PUBLISH_REASON_REACH_LIMIT(7): The number of pushed URLs exceeds 10. Stop pushing to unnecessary URLs.
RTMP_STREAM_PUBLISH_REASON_NOT_AUTHORIZED(8): The broadcaster operated on another broadcaster’s URL, such as updating or stopping their stream. Check your app logic.
RTMP_STREAM_PUBLISH_REASON_STREAM_NOT_FOUND(9): The Agora server could not find the media stream for RTMP streaming.
RTMP_STREAM_PUBLISH_REASON_FORMAT_NOT_SUPPORTED(10): Unsupported RTMP streaming URL format. Check if the URL format is correct.
RTMP_STREAM_PUBLISH_REASON_NOT_BROADCASTER(11): The user is not a broadcaster and cannot use RTMP streaming. Check your app code logic.
RTMP_STREAM_PUBLISH_REASON_TRANSCODING_NO_MIX_STREAM(13): Called updateRtmpTranscoding in a non-transcoding RTMP streaming scenario. Check your app code logic.
RTMP_STREAM_PUBLISH_REASON_NET_DOWN(14): Network issue on the broadcaster's side.
RTMP_STREAM_PUBLISH_REASON_INVALID_PRIVILEGE(16): The project does not have permission to use RTMP streaming.
RTMP_STREAM_UNPUBLISH_REASON_OK(100): RTMP streaming stopped normally. Returned after calling stopRtmpStream.

onTranscodingUpdated

Callback for updates to publisher's cloud transcoding configuration.

public void onTranscodingUpdated() {}

When calling startRtmpStreamWithTranscoding to update the LiveTranscoding configuration, the SDK triggers this callback to report the update.

Note: This callback is not triggered when startRtmpStreamWithTranscoding is called for the first time to set the LiveTranscoding configuration.

Trigger Timing

This callback is triggered when the publisher's cloud transcoding configuration is updated.