AgoraRtcChannel Class Reference
Inherits from | NSObject |
---|---|
Declared in | AgoraRtcChannel.h |
– destroy
Destroys the AgoraRtcChannel instance.
- (int)destroy
Return Value
- 0: Success.
< 0: Failure.
AgoraErrorCodeNotInitialized
(-7): The AgoraRtcChannel instance is not initialized before calling this method.
Declared In
AgoraRtcChannel.h
– setRtcChannelDelegate:
Sets the channel delegate.
- (void)setRtcChannelDelegate:(id<AgoraRtcChannelDelegate> _Nullable)channelDelegate
Parameters
channelDelegate |
The delegate of the AgoraRtcChannel instance. For details, see AgoraRtcChannelDelegate. |
---|
Discussion
After setting the channel delegate, you can listen for channel events and receive the statistics of the corresponding AgoraRtcChannel instance.
Declared In
AgoraRtcChannel.h
– getChannelId
Gets the channel ID of the current AgoraRtcChannel instance.
- (NSString *_Nullable)getChannelId
Return Value
- The channel ID of the current AgoraRtcChannel instance, if the method call succeeds.
- The empty string “”, if the method call fails.
Declared In
AgoraRtcChannel.h
– getCallId
Gets the current call ID.
- (NSString *_Nullable)getCallId
Return Value
- The current call ID, if the method call succeeds.
- The empty string “”, if the method call fails.
Discussion
Note: Ensure that you call this method after joining a channel.
Declared In
AgoraRtcChannel.h
– getConnectionState
Gets the connection state of the SDK.
- (AgoraConnectionStateType)getConnectionState
Return Value
The connection state, see AgoraConnectionStateType:
AgoraConnectionStateDisconnected
(1): The SDK is disconnected from Agora’s edge server.AgoraConnectionStateConnecting
(2): The SDK is connecting to Agora’s edge server.AgoraConnectionStateConnected
(3): The SDK joined a channel and is connected to Agora’s edge server. You can now publish or subscribe to a media stream in the channel.AgoraConnectionStateReconnecting
(4): The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues.AgoraConnectionStateFailed
(5): The SDK fails to join the channel.
Discussion
You can call this method either before or after joining a channel.
Declared In
AgoraRtcChannel.h
– joinChannelByToken:info:uid:options:
Joins the channel with a user ID.
- (int)joinChannelByToken:(NSString *_Nullable)token info:(NSString *_Nullable)info uid:(NSUInteger)uid options:(AgoraRtcChannelMediaOptions *_Nonnull)options
Parameters
token |
The token for authentication:
|
---|---|
info |
Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. |
uid |
The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If |
options |
The channel media options: AgoraRtcChannelMediaOptions |
Return Value
0
(AgoraRtmpStreamingErrorCodeOK
): Success.<
0
: Failure.-2
(AgoraErrorCodeInvalidArgument
): The parameter is invalid.-3
(AgoraErrorCodeNotReady
): The SDK fails to be initialized. You can try re-initializing the SDK.-5
(AgoraErrorCodeRefused
): The request is rejected. This may be caused by the following:- You have created an
AgoraRtcChannel
object with the same channel name. - You have joined and published a stream in a channel created by the
AgoraRtcChannel
object.
- You have created an
Discussion
This method differs from the joinChannelByToken method in the AgoraRtcEngineKit class in the following aspects:
AgoraRtcChannel joinChannelByToken | AgoraRtcEngineKit joinChannelByToken |
---|---|
Does not contain the channelId parameter, because channelId is specified when creating the AgoraRtcChannel instance. |
Contains the channelId parameter, which specifies the channel to join. |
Contains the options parameter, which decides whether to subscribe to all streams before joining the channel. |
Does not contain the options parameter. By default, users subscribe to all streams when joining the channel. |
Users can join multiple channels simultaneously by creating multiple AgoraRtcChannel instances and calling the joinChannelByToken method of each instance. |
Users can join only one channel. |
By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. | By default, the SDK publishes streams once the user joins the channel. |
Note
- If you are already in a channel, you cannot rejoin it with the same
uid
. - We recommend using different
uid
for different channels. - If you want to join the same channel from different devices, ensure that the
uid
in all devices are different. - Ensure that the app ID you use to generate the token is the same with the app ID used when creating the AgoraRtcEngineKit instance.
Declared In
AgoraRtcChannel.h
– joinChannelByUserAccount:token:options:
Joins a channel with the user account.
- (int)joinChannelByUserAccount:(NSString *_Nonnull)userAccount token:(NSString *_Nullable)token options:(AgoraRtcChannelMediaOptions *_Nonnull)options
Parameters
userAccount |
The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null.
|
---|---|
token |
The token generated at your server:
|
options |
The channel media options: AgoraRtcChannelMediaOptions |
Return Value
- 0: Success.
< 0: Failure.
AgoraErrorCodeInvalidArgument
(-2)AgoraErrorCodeNotReady
(-3)AgoraErrorCodeRefused
(-5)
Discussion
This method differs from the joinChannelByUserAccount method in the AgoraRtcEngineKit class in the following aspects:
AgoraRtcChannel joinChannelByUserAccount | AgoraRtcEngineKit joinChannelByUserAccount |
---|---|
Does not contain the channelId parameter, because channelId is specified when creating the AgoraRtcChannel instance. |
Contains the channelId parameter, which specifies the channel to join. |
Contains the options parameter, which decides whether to subscribe to all streams before joining the channel. |
Does not contain the options parameter. By default, users subscribe to all streams when joining the channel. |
Users can join multiple channels simultaneously by creating multiple AgoraRtcChannel instances and calling the joinChannelByUserAccount method of each instance. |
Users can join only one channel. |
By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. | By default, the SDK publishes streams once the user joins the channel. |
Note
- If you are already in a channel, you cannot rejoin it with the same
uid
. - We recommend using different
uid
for different channels. - If you want to join the same channel from different devices, ensure that the
uid
in all devices are different. - Ensure that the app ID you use to generate the token is the same with the app ID used when creating the AgoraRtcEngineKit instance.
Declared In
AgoraRtcChannel.h
– leaveChannel
Leaves the current channel.
- (int)leaveChannel
Return Value
0
(AgoraRtmpStreamingErrorCodeOK
): Success.<
0
: Failure.-1
(AgoraErrorCodeFailed
): A general error occurs (no specified reason).-2
(AgoraErrorCodeInvalidArgument
): The parameter is invalid.-7
(AgoraErrorCodeNotInitialized
): The SDK is not initialized.
Discussion
A successful leaveChannel
method call triggers the following callbacks:
- The local client: rtcChannelDidLeaveChannel.
- The remote client: didOfflineOfUid, if the user leaving the channel is in a Communication channel, or is a host in a Live-Broadcast channel.
Declared In
AgoraRtcChannel.h
– publish
Publishes the local stream to the channel.
- (int)publish
Return Value
- 0: Success.
< 0: Failure.
AgoraErrorCodeRefused
(-5): The method call is refused.
Discussion
You must keep the following restrictions in mind when calling this method. Otherwise, the SDK returns the AgoraErrorCodeRefused(-5):
- This method publishes one stream only to the channel corresponding to the current AgoraRtcChannel instance.
- In a Live-Broadcast channel, only a host can call this method. To switch the client role, call setClientRole of the current AgoraRtcChannel instance.
- You can publish a stream to only one channel at a time. For details, see the advanced guide Join Multiple Channels.
Declared In
AgoraRtcChannel.h
– unpublish
Stops publishing a stream to the channel.
- (int)unpublish
Return Value
- 0: Success.
< 0: Failure.
AgoraErrorCodeRefused
(-5): The method call is refused.
Discussion
If you call this method in a channel where you are not publishing streams, the SDK returns AgoraErrorCodeRefused(-5).
Declared In
AgoraRtcChannel.h
– setClientRole:
Sets the role of a user.
- (int)setClientRole:(AgoraClientRole)role
Parameters
role |
The role of the user:
|
---|
Return Value
0
(AgoraRtmpStreamingErrorCodeOK
): Success.<
0
: Failure.-1
(AgoraErrorCodeFailed
): A general error occurs (no specified reason).-2
(AgoraErrorCodeInvalidArgument
): The parameter is invalid.-7
(AgoraErrorCodeNotInitialized
): The SDK is not initialized.
Discussion
This method sets the role of a user, such as a host or an audience. In an interactive live streaming channel, only a host can call the publish method in the AgoraRtcChannel class.
A successful call of this method triggers the following callbacks:
- The local client: didClientRoleChanged.
- The remote client: didJoinedOfUid or didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience).
Declared In
AgoraRtcChannel.h
– setClientRole:options:
Sets the role of a user in a interactive live streaming.
- (int)setClientRole:(AgoraClientRole)role options:(AgoraClientRoleOptions *_Nullable)options
Parameters
role |
The role of a user in a interactive live streaming. See AgoraClientRole. |
---|---|
options |
The detailed options of a user, including user level. See AgoraClientRoleOptions. |
Return Value
- 0(
AgoraRtmpStreamingErrorCodeOK
): Success. < 0: Failure.
-1
(AgoraErrorCodeFailed
): A general error occurs (no specified reason).-2
(AgoraErrorCodeInvalidArgument
): The parameter is invalid.-7
(AgoraErrorCodeNotInitialized
): The SDK is not initialized.
Availability
v3.2.0
You can call this method either before or after joining the channel to set the user role as audience or host. If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks:
- The local client: didClientRoleChanged.
- The remote client: didJoinedOfUid or didOfflineOfUid.
Note:
This method applies to the
LiveBroadcasting
profile only (when theprofile
parameter in setChannelProfile is set asAgoraChannelProfileLiveBroadcasting
).The difference between this method and setClientRole1 is that this method can set the user level in addition to the user role.
- The user role determines the permissions that the SDK grants to a user, such as permission to send local streams, receive remote streams, and push streams to a CDN address.
- The user level determines the level of services that a user can enjoy within the permissions of the user’s role. For example, an audience can choose to receive remote streams with low latency or ultra low latency. Levels affect prices.
Declared In
AgoraRtcChannel.h
– renewToken:
Renews the token when the current token expires.
- (int)renewToken:(NSString *_Nonnull)token
Parameters
token |
The new token. |
---|
Return Value
0
(AgoraRtmpStreamingErrorCodeOK
): Success.<
0
: Failure.-1
(AgoraErrorCodeFailed
): A general error occurs (no specified reason).-2
(AgoraErrorCodeInvalidArgument
): The parameter is invalid.-7
(AgoraErrorCodeNotInitialized
): The SDK is not initialized.
Discussion
In the following situations, the SDK decides that the current token has expired:
- The SDK triggers the tokenPrivilegeWillExpire callback, or
- The connectionChangedToState callback reports the AgoraConnectionChangedTokenExpired(9) error.
You should get a new token from your server and call this method to renew it. Failure to do so results in the SDK disconnecting from the Agora server.
Note
Agora recommends using the rtcChannelRequestToken callback to report the AgoraErrorCodeTokenExpired(-109) error, not using the didOccurError callback.
Declared In
AgoraRtcChannel.h
– setEncryptionSecret:
Enables built-in encryption with an encryption password before joining a channel.
- (int)setEncryptionSecret:(NSString *_Nullable)secret
Parameters
secret |
Encryption password. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
DEPRECATED from v3.1.0. Use enableEncryption instead.
All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user leaves the channel.
If the encryption password is not specified or set to empty, the encryption functionality is disabled.
Note
- Do not use this method for CDN live streaming.
- For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.
Declared In
AgoraRtcChannel.h
– setEncryptionMode:
Sets the built-in encryption mode.
- (int)setEncryptionMode:(NSString *_Nullable)encryptionMode
Parameters
encryptionMode |
Sets the encryption mode.
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
DEPRECATED from v3.1.0. Use enableEncryption instead.
The SDK supports built-in encryption, which is set to the “aes-128-xts” mode by default. Call this method to use other encryption modes.
All users in the same channel must use the same encryption mode and password.
Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.
Note
- Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.
- Do not use this method for CDN live streaming.
Declared In
AgoraRtcChannel.h
– enableEncryption:encryptionConfig:
Enables/Disables the built-in encryption.
- (int)enableEncryption:(bool)enabled encryptionConfig:(AgoraEncryptionConfig *_Nonnull)config
Parameters
enabled |
Whether to enable the built-in encryption:
|
---|---|
config |
Configurations of built-in encryption schemas. See AgoraEncryptionConfig. |
Return Value
- 0: Success.
< 0: Failure.
- -2 (
AgoraErrorCodeInvalidArgument
): An invalid parameter is used. Set the parameter with a valid value. - -7 (
AgoraErrorCodeNotInitialized
): The SDK is not initialized. Initialize theAgoraRtcEngineKit
instance before calling this method. - -4 (
AgoraErrorCodeNotSupported
): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
- -2 (
Availability
v3.1.0
In scenarios requiring high security, Agora recommends calling enableEncryption
to enable the built-in encryption before joining a channel.
All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared.
Note
- If you enable the built-in encryption, you cannot use the RTMP or RTMPS streaming function.
- Agora supports four encryption modes. If you choose an encryption mode (excepting
SM4_128_ECB
mode), you need to add an external encryption library when integrating the iOS SDK. See Channel Encryption.
Declared In
AgoraRtcChannel.h
– setRemoteUserPriority:type:
Sets the priority of a remote user’s stream.
- (int)setRemoteUserPriority:(NSUInteger)uid type:(AgoraUserPriority)userPriority
Parameters
uid |
The ID of the remote user. |
---|---|
userPriority |
The priority of the remote user, see AgoraUserPriority. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The SDK ensures the high-priority user gets the best possible stream quality.
Note
The SDK supports setting userPriority as high for one user only.
Declared In
AgoraRtcChannel.h
– setRemoteVoicePosition:pan:gain:
Sets the sound position and gain of a remote user.
- (int)setRemoteVoicePosition:(NSUInteger)uid pan:(double)pan gain:(double)gain
Parameters
uid |
The ID of the remote user. |
---|---|
pan |
The sound position of the remote user. The value ranges from -1.0 to 1.0:
|
gain |
Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.
Note
- Ensure that you call this method after joining a channel. For this method to work, enable stereo panning for remote users by calling enableSoundPositionIndication before joining a channel. This method requires hardware support.
For the best effect, we recommend using the following audio output devices:
- (iOS) A stereo headset.
- (macOS) A stereo loudspeaker.
Declared In
AgoraRtcChannel.h
– setRemoteRenderMode:renderMode:mirrorMode:
Updates the display mode of the video view of a remote user.
- (int)setRemoteRenderMode:(NSUInteger)uid renderMode:(AgoraVideoRenderMode)renderMode mirrorMode:(AgoraVideoMirrorMode)mirrorMode
Parameters
uid |
The ID of the remote user. |
---|---|
renderMode |
The rendering mode of the remote video view. See AgoraVideoRenderMode. |
mirrorMode |
The mirror mode of the remote video view. See AgoraVideoMirrorMode. Note The SDK disables the mirror mode by default. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.
Note
- Ensure that you have called setupRemoteVideo to initialize the remote video view before calling this method.
- During a call, you can call this method as many times as necessary to update the display mode of the video view of a remote user.
Declared In
AgoraRtcChannel.h
– setDefaultMuteAllRemoteAudioStreams:
Sets whether to receive all remote audio streams by default.
- (int)setDefaultMuteAllRemoteAudioStreams:(BOOL)mute
Parameters
mute |
Sets whether to receive/stop receiving all remote audio streams by default:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
You can call this method either before or after joining a channel. If you call setDefaultMuteAllRemoteAudioStreams (YES)
after joining a channel, the remote audio streams of all subsequent users are not received.
Note: If you want to resume receiving the audio stream, call muteRemoteAudioStream (NO), and specify the ID of the remote user whose audio stream you want to receive. To receive the audio streams of multiple remote users, call muteRemoteAudioStream (NO)
as many times. Calling setDefaultMuteAllRemoteAudioStreams (NO)
resumes receiving the audio streams of subsequent users only.
Declared In
AgoraRtcChannel.h
– setDefaultMuteAllRemoteVideoStreams:
Sets whether to receive all remote video streams by default.
- (int)setDefaultMuteAllRemoteVideoStreams:(BOOL)mute
Parameters
mute |
Sets whether to receive/stop receiving all remote video streams by default.
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
You can call this method either before or after joining a channel. If you call setDefaultMuteAllRemoteVideoStreams (YES)
after joining a channel, the remote video streams of all subsequent users are not received.
Note: If you want to resume receiving the video stream, call muteRemoteVideoStream (NO), and specify the ID of the remote user whose video stream you want to receive. To receive the video streams of multiple remote users, call muteRemoteVideoStream (NO)
as many times. Calling setDefaultMuteAllRemoteVideoStreams (NO)
resumes receiving the video streams of subsequent users only.
Declared In
AgoraRtcChannel.h
– muteRemoteAudioStream:mute:
Receives/Stops receiving a specified remote user’s audio stream.
- (int)muteRemoteAudioStream:(NSUInteger)uid mute:(BOOL)mute
Parameters
uid |
User ID of the specified remote user. |
---|---|
mute |
Sets whether to receive/stop receiving a specified remote user’s audio stream:
|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Note
- You can call this method either before or after joining a channel. If you call it before joining a channel, you need to maintain the
uid
of the remote user on your app level. - If you call the muteAllRemoteAudioStreams method and set
mute
asYES
to mute all remote audio streams, call themuteAllRemoteAudioStreams
method again and setmute
asNO
before calling this method. ThemuteAllRemoteAudioStreams
method sets all remote streams, while themuteRemoteAudioStream
method sets a specified stream.
Declared In
AgoraRtcChannel.h
– adjustUserPlaybackSignalVolume:volume:
Adjust the playback signal volume of a specified remote user.
- (int)adjustUserPlaybackSignalVolume:(NSUInteger)uid volume:(int)volume
Parameters
uid |
The ID of the remote user. |
---|---|
volume |
The playback volume of the specified remote user. The value ranges from 0 to 100:
|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.
Note
- Call this method after joining a channel.
- The playback volume here refers to the mixed volume of a specified remote user.
- This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.
Declared In
AgoraRtcChannel.h
– muteAllRemoteAudioStreams:
Receives/Stops receiving all remote audio streams.
- (int)muteAllRemoteAudioStreams:(BOOL)mute
Parameters
mute |
Sets whether to receive/stop receiving all remote audio streams:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
You can call this method either before or after joining a channel.
Declared In
AgoraRtcChannel.h
– muteRemoteVideoStream:mute:
Receives/Stops receiving a specified remote user’s video stream.
- (int)muteRemoteVideoStream:(NSUInteger)uid mute:(BOOL)mute
Parameters
uid |
User ID of the specified remote user. |
---|---|
mute |
Sets whether to receive/stop receiving a specified remote user’s video stream.
|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
You can call this method either before or after joining a channel. If you call it before joining a channel, you need to maintain the uid
of the remote user on your app level.
Note
If you call the muteAllRemoteVideoStreams method and set mute
as YES
to stop receiving all remote video streams, call the muteAllRemoteVideoStreams
method again and set mute
as NO
before calling this method.
Declared In
AgoraRtcChannel.h
– muteAllRemoteVideoStreams:
Receives/Stops receiving all remote video streams.
- (int)muteAllRemoteVideoStreams:(BOOL)mute
Parameters
mute |
Sets whether to receive/stop receiving all remote video streams:
|
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
You can call this method either before or after joining a channel.
Declared In
AgoraRtcChannel.h
– setRemoteVideoStream:type:
Sets the stream type of the remote video.
- (int)setRemoteVideoStream:(NSUInteger)uid type:(AgoraVideoStreamType)streamType
Parameters
uid |
ID of the remote user sending the video stream. |
---|---|
streamType |
Sets the video-stream type. See AgoraVideoStreamType. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode(NO)enableDualStreamMode(NO), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-quality video stream (the low resolution, and low bitrate video stream).
By default, users receive the high-quality video stream. Call this method if you want to switch to the low-quality video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources.
The aspect ratio of the low-quality video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-quality video stream.
The SDK reports the result of calling this method in the didApiCallExecute callback.
Note: You can call this method either before or after joining a channel. If you call both setRemoteVideoStream
and setRemoteDefaultVideoStreamType, the SDK applies the settings in the setRemoteVideoStream
method.
Declared In
AgoraRtcChannel.h
– setRemoteDefaultVideoStreamType:
Sets the default video-stream type for the video received by the local user when the remote user sends dual streams.
- (int)setRemoteDefaultVideoStreamType:(AgoraVideoStreamType)streamType
Parameters
streamType |
Sets the default video-stream type. See AgoraVideoStreamType. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Note: You can call this method either before or after joining a channel. If you call both setRemoteDefaultVideoStreamType
and setRemoteVideoStream, the SDK applies the settings in the setRemoteDefaultVideoStreamType
method.
Declared In
AgoraRtcChannel.h
– addInjectStreamUrl:config:
Adds a voice or video stream CDN streaming URL to the interactive live streaming.
- (int)addInjectStreamUrl:(NSString *_Nonnull)url config:(AgoraLiveInjectStreamConfig *_Nonnull)config
Parameters
url |
URL address to be added to the ongoing interactive live streaming. Valid protocols are RTMP, HLS, and HTTP-FLV.
|
---|---|
config |
AgoraLiveInjectStreamConfig object which contains the configuration information for the added voice or video stream. |
Return Value
- 0: Success.
< 0: Failure.
AgoraErrorCodeInvalidArgument
(-2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.AgoraErrorCodeNotReady
(-3): The user is not in the channel.AgoraErrorCodeNotSupported
(-4): The channel profile is not Live Broadcast.AgoraErrorCodeNotInitialized
(-7): The SDK is not initialized. Ensure that the AgoraRtcChannel object is initialized before using this method.
Discussion
If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other.
The addInjectStreamUrl
method call triggers the following callbacks:
The local client:
- streamInjectedStatusOfUrl, with the state of the injecting the online stream.
- didJoinedOfUid(uid: 666), if the method call is successful and the online media stream is injected into the channel.
The remote client:
- didJoinedOfUid(uid: 666), if the method call is successful and the online media stream is injected into the channel.
Note:
- Ensure that you call this method after joining a channel.
- You can inject only one media stream into the channel at the same time.
- Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
- This method applies to the Native SDK v2.4.1 and later.
Declared In
AgoraRtcChannel.h
– removeInjectStreamUrl:
Removes the voice or video stream CDN streaming URL from the interactive live streaming.
- (int)removeInjectStreamUrl:(NSString *_Nonnull)url
Parameters
url |
URL address of the added stream to be removed. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method removes the URL address (added by the addInjectStreamUrl method) from the interactive live streaming.
If this method call is successful, the SDK triggers the didOfflineOfUid callback and returns a stream uid of 666.
Declared In
AgoraRtcChannel.h
– addPublishStreamUrl:transcodingEnabled:
Publishes the local stream to the CDN.
- (int)addPublishStreamUrl:(NSString *_Nonnull)url transcodingEnabled:(BOOL)transcodingEnabled
Parameters
url |
The CDN streaming URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The CDN streaming URL must not contain special characters, such as Chinese language characters. |
---|---|
transcodingEnabled |
Sets whether transcoding is enabled/disabled:
|
Return Value
- 0: Success.
< 0: Failure.
AgoraErrorCodeInvalidArgument
(-2): Invalid parameter. The URL is nil or the string length is 0.AgoraErrorCodeNotInitialized
(-7): You have not initialized the RTC Engine when publishing the stream.
Discussion
After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers the rtmpStreamingChangedToState callback on the local client to report the state of adding a local stream to the CDN.
Note:
- This method applies to the interactive live streaming profile only.
- Ensure that the user joins the channel before calling this method.
- Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
- This method adds only one stream URL each time it is called.
- Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Declared In
AgoraRtcChannel.h
– removePublishStreamUrl:
Removes an RTMP or RTMPS stream from the CDN.
- (int)removePublishStreamUrl:(NSString *_Nonnull)url
Parameters
url |
The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
This method removes the CDN streaming URL added by the addPublishStreamUrl method from a CDN live stream.
This method call triggers the rtmpStreamingChangedToState callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN.
Note:
- This method applies to the interactive live streaming profile only.
- This method removes only one URL each time it is called.
- The URL must not contain special characters, such as Chinese language characters.
Declared In
AgoraRtcChannel.h
– setLiveTranscoding:
Sets the video layout and audio settings for CDN live. (CDN live only.)
- (int)setLiveTranscoding:(AgoraLiveTranscoding *_Nullable)transcoding
Parameters
transcoding |
Sets the CDN live audio/video transcoding settings. See AgoraLiveTranscoding. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The SDK triggers the rtcEngineTranscodingUpdated callback when you call the setLiveTranscoding
method to update the transcoding setting.
Note
- Ensure that you call this method after joining a channel.
- This method applies to the interactive live streaming profile only.
- Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
- If you call the
setLiveTranscoding
method to update the transcoding setting for the first time, the SDK does not trigger thertcEngineTranscodingUpdated
callback. - Agora supports pushing media streams in RTMPS protocol to the CDN only when you enable transcoding.
Declared In
AgoraRtcChannel.h
– createDataStream:reliable:ordered:
Creates a data stream.
- (int)createDataStream:(NSInteger *_Nonnull)streamId reliable:(BOOL)reliable ordered:(BOOL)ordered
Parameters
streamId |
(Output parameter) The ID of the created data stream. |
---|---|
reliable |
Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
|
ordered |
Sets whether or not the recipients receive the data stream in the sent order:
|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Each user can create up to five data streams during the lifecycle of the AgoraRtcChannel.
Note:
- Ensure that you call this method after joining a channel.
- Set both the
reliable
andordered
parameters toYES
orNO
. Do not set one asYES
and the other asNO
.
Declared In
AgoraRtcChannel.h
– sendStreamMessage:data:
Sends data stream messages to all users in a channel.
- (int)sendStreamMessage:(NSInteger)streamId data:(NSData *_Nonnull)data
Parameters
streamId |
ID of the sent data stream returned in the createDataStream method. |
---|---|
data |
Sent data. |
Return Value
- 0: Success.
- < 0: Failure.
Discussion
The SDK has the following restrictions on this method:
- Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
- Each client can send up to 6 kB of data per second.
- Each user can have up to five data streams simultaneously.
A successful sendStreamMessage
method call triggers the receiveStreamMessageFromUid callback on the remote client, from which the remote user gets the stream message.
A failed sendStreamMessage
method call triggers the didOccurStreamMessageErrorFromUid callback on the remote client.
Note
- This method applies only to the Communication profile or to the hosts in the interactive live streaming profile. If an audience in the interactive live streaming profile calls this method, the audience role may be changed to a host.
- Ensure that you have created the data stream using createDataStream before calling this method.
Declared In
AgoraRtcChannel.h
– startChannelMediaRelay:
Starts to relay media streams across channels.
- (int)startChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config
Parameters
config |
The configuration of the media stream relay: AgoraChannelMediaRelayConfiguration. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
After a successful method call, the SDK triggers the channelMediaRelayStateDidChange and didReceiveChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.
- If the
channelMediaRelayStateDidChange
callback returns AgoraChannelMediaRelayStateRunning(2) and AgoraChannelMediaRelayStateIdle(0), and thedidReceiveChannelMediaRelayEvent
callback returns AgoraChannelMediaRelayEventSentToDestinationChannel(4), the SDK starts relaying media streams between the original and the destination channel. - If the
channelMediaRelayStateDidChange
callback returns AgoraChannelMediaRelayStateFailure(3), an exception occurs during the media stream relay.
Note
- Call this method after the joinChannelByToken method.
- This method takes effect only when you are a host in the interactive live streaming channel.
- After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
- Contact support@agora.io before implementing this function.
- We do not support string user accounts in this API.
Declared In
AgoraRtcChannel.h
– updateChannelMediaRelay:
Updates the channels for media stream relay.
- (int)updateChannelMediaRelay:(AgoraChannelMediaRelayConfiguration *_Nonnull)config
Parameters
config |
The media stream relay configuration: AgoraChannelMediaRelayConfiguration. |
---|
Return Value
- 0: Success.
- < 0: Failure.
Discussion
After the channel media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay
method.
After a successful method call, the SDK triggers the didReceiveChannelMediaRelayEvent callback with the AgoraChannelMediaRelayEventUpdateDestinationChannel(7) state code.
Note
- Call this method after the startChannelMediaRelay method to update the destination channel.
- This method supports adding at most four destination channels in the relay. If there are already four destination channels in the relay, remove the unnecessary ones with the
removeDestinationInfoForChannelName
method in channelMediaRelayConfiguration before calling this method.
Declared In
AgoraRtcChannel.h
– stopChannelMediaRelay
Stops the media stream relay.
- (int)stopChannelMediaRelay
Return Value
- 0: Success.
- < 0: Failure.
Discussion
Once the relay stops, the host quits all the destination channels.
After a successful method call, the SDK triggers the channelMediaRelayStateDidChange callback. If the callback returns AgoraChannelMediaRelayStateIdle(0) and AgoraChannelMediaRelayErrorNone(0), the host successfully stops the relay.
Note: If the method call fails, the SDK triggers the channelMediaRelayStateDidChange
callback with the AgoraChannelMediaRelayErrorServerNoResponse(2) or AgoraChannelMediaRelayEventUpdateDestinationChannelRefused(8) state code. You can leave the channel by calling the leaveChannel method, and the media stream relay automatically stops.
Declared In
AgoraRtcChannel.h
– setRemoteVideoRenderer:forUserId:
Customizes the remote video renderer for the AgoraRtcChannel object.
- (void)setRemoteVideoRenderer:(id<AgoraVideoSinkProtocol> _Nullable)videoRenderer forUserId:(NSUInteger)userId
Parameters
videoRenderer |
The customized remote video renderer: AgoraVideoSinkProtocol. |
---|---|
userId |
The ID of the remote user. |
Discussion
During real-time engagements, the Agora SDK enables the default video sink to render the video. In the multi-channel scenario, if you want to customize the video renderer, you can create a customized video sink using AgoraVideoSinkProtocol, and call setRemoteVideoRenderer
to add the customized sink into the AgoraRtcChannel object.
You can call this method either before or after joining a channel. If you call it before joining a channel, you need to maintain the uid
of the remote user on your app level.
Declared In
AgoraRtcChannel.h
– remoteVideoRendererOfUserId:
Gets the customized remote video renderer for the AgoraRtcChannel object.
- (id<AgoraVideoSinkProtocol> _Nullable)remoteVideoRendererOfUserId:(NSUInteger)userId
Parameters
userId |
The ID of the remote user. |
---|
Return Value
The customized remote video renderer: AgoraVideoSourceProtocol.
Declared In
AgoraRtcChannel.h
– setMediaMetadataDataSource:withType:
Sets the data source of the metadata.
- (BOOL)setMediaMetadataDataSource:(id<AgoraMediaMetadataDataSource> _Nullable)metadataDataSource withType:(AgoraMetadataType)type
Parameters
metadataDataSource |
The AgoraMediaMetadataDataSource protocol. |
---|---|
type |
The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only. |
Return Value
- YES: Success.
- NO: Failure.
Discussion
You need to implement the AgoraMediaMetadataDataSource protocol and specify the type of metadata in this method.
Use this method with the setMediaMetadataDelegate method to add synchronized metadata in the video stream. You can create more diversified interactive live streaming interactions, such as sending shopping links, digital coupons, and online quizzes.
Note
- Call this method before the joinChannelByToken method.
- This method applies to the interactive live streaming channel profile only.
Declared In
AgoraRtcChannel.h
– setMediaMetadataDelegate:withType:
Sets the delegate of the metadata.
- (BOOL)setMediaMetadataDelegate:(id<AgoraMediaMetadataDelegate> _Nullable)metadataDelegate withType:(AgoraMetadataType)type
Parameters
metadataDelegate |
The AgoraMediaMetadataDelegate protocol. |
---|---|
type |
The metadata type. See AgoraMetadataType. Currently, the SDK supports video metadata only. |
Return Value
- YES: Success.
- NO: Failure.
Discussion
You need to implement the AgoraMediaMetadataDelegate protocol and specify the type of metadata in this method.
Note
- Call this method before the joinChannelByToken method.
- This method applies to the interactive live streaming channel profile only.
Declared In
AgoraRtcChannel.h