Agora RTC Objective-C API Reference Refactor

Instance Methods | Class Methods
AgoraLocalSpatialAudioKit Class Reference

Inherits AgoraSpatialAudioKitBase.

## Instance Methods
(int) | - updateRemotePosition:positionInfo:
(int) | - removeRemotePosition:
(int) | - clearRemotePositionsEx:
(int) | - setRemoteAudioAttenuation:uid:forceSet:
(int) | - setMaxAudioRecvCount:
(int) | - setAudioRecvRange:
(int) | - setDistanceUnit:
(int) | - updatePlayerPositionInfo:positionInfo:
(int) | - updateSelfPosition:axisForward:axisRight:axisUp:
(int) | - updateSelfTransform:
(int) | - setZones:
(int) | - setPlayerAttenuation:playerId:forceSet:

## Class Methods
(instancetype _Nonnull) | + sharedLocalSpatialAudioWithConfig:
(void) | + destroy

## Method Documentation

## ◆ sharedLocalSpatialAudioWithConfig:

+ (instancetype _Nonnull) sharedLocalSpatialAudioWithConfig: |  | (AgoraLocalSpatialAudioConfig *) | config |

Initializes `AgoraLocalSpatialAudioKit`.

Note
  - Before calling other methods of the `AgoraLocalSpatialAudioKit` class, you need to call this method to initialize `AgoraLocalSpatialAudioKit`.
  - The SDK supports creating only one `AgoraLocalSpatialAudioKit` instance for an app.

Parameters

  config | The configuration of `AgoraLocalSpatialAudioKit`. See `AgoraLocalSpatialAudioConfig`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ destroy

+ (void) destroy |  |  |

Destroys `AgoraLocalSpatialAudioKit`.

This method releases all resources under `AgoraLocalSpatialAudioKit`. When the user does not need to use the spatial audio effect, you can call this method to release resources for other operations. After calling this method, you can no longer use any of the APIs under `AgoraLocalSpatialAudioKit`. To use the spatial audio effect again, you need to wait until the `destroy` method execution to complete before calling `sharedLocalSpatialAudioWithConfig:` to create a new `AgoraLocalSpatialAudioKit`.

Note
  Call this method before the `destroy` method under `AgoraRtcEngineKit`.

## ◆ updateRemotePosition:positionInfo:

- (int) updateRemotePosition: |  | (NSUInteger) | uid
positionInfo: |  | (AgoraRemoteVoicePositionInfo *) | posInfo

Updates the spatial position of the specified remote user.

After successfully calling this method, the SDK calculates the spatial audio parameters based on the relative position of the local and remote user.

Note
  Call this method after the `joinChannelByToken:channelId:info:uid:joinSuccess:` or `joinChannelByToken:channelId:uid:mediaOptions:joinSuccess:` method.

Parameters

  uid | The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
  posInfo | The spatial position of the remote user. See `AgoraRemoteVoicePositionInfo`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateRemotePositionEx:positionInfo:connection:

- (int) updateRemotePositionEx: |  | (NSUInteger) | uid
positionInfo: |  | (AgoraRemoteVoicePositionInfo *) | posInfo
connection: |  | (AgoraRtcConnection *) | connection

## ◆ removeRemotePosition:

- (int) removeRemotePosition: |  | (NSUInteger) | uid |

Removes the spatial position of the specified remote user.

After successfully calling this method, the local user no longer hears the specified remote user. After leaving the channel, to avoid wasting computing resources, call this method to delete the spatial position information of the specified remote user. Otherwise, the user's spatial position information will be saved continuously. When the number of remote users exceeds the number of audio streams that can be received as set in `setMaxAudioRecvCount:`, the system automatically unsubscribes from the audio stream of the user who is furthest away based on relative distance.

Parameters

  uid | The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ removeRemotePositionEx:connection:

- (int) removeRemotePositionEx: |  | (NSUInteger) | uid
connection: |  | (AgoraRtcConnection *) | connection

## ◆ clearRemotePositionsEx:

- (int) clearRemotePositionsEx: |  | (AgoraRtcConnection *) | connection |

Removes the spatial positions of all remote users.

After successfully calling this method, the local user no longer hears any remote users. After leaving the channel, to avoid wasting resources, you can also call this method to delete the spatial positions of all remote users.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setRemoteAudioAttenuation:uid:forceSet:

- (int) setRemoteAudioAttenuation: |  | (double) | attenuation
uid: |  | (NSUInteger) | uid
forceSet: |  | (BOOL) | forceSet

Sets the sound attenuation effect for the specified user.

Parameters

  uid | The user ID. This parameter must be the same as the user ID passed in when the user joined the channel.
  attenuation | For the user's sound attenuation coefficient, the value range is [0,1]. The values are as follows: 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance. (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment. 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the `speaker_attenuation` parameter. (0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process.
  forceSet | Whether to force the user's sound attenuation effect: `YES`: Force `attenuation` to set the sound attenuation of the user. At this time, the `attenuation` coefficient of the sound insulation area set in the `audioAttenuation` of the `AgoraSpatialAudioZone` does not take effect for the user. `NO`: Do not force `attenuation` to set the user's sound attenuation effect, as shown in the following two cases. If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the `audioAttenuation` in `AgoraSpatialAudioZone`. If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by `attenuation` in this method.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateSelfPositionEx:axisForward:axisRight:axisUp:connection:

- (int) updateSelfPositionEx: |  | (simd_float3) | position
axisForward: |  | (simd_float3) | axisForward
axisRight: |  | (simd_float3) | axisRight
axisUp: |  | (simd_float3) | axisUp
connection: |  | (AgoraRtcConnection *) | connection

## ◆ setMaxAudioRecvCount:

- (int) setMaxAudioRecvCount: |  | (NSUInteger) | maxCount |

Sets the maximum number of streams that a user can receive in a specified audio reception range.

If the number of receivable streams exceeds the set value, the local user receives the `maxCount` streams that are closest to the local user.

Parameters

  maxCount | The maximum number of streams that a user can receive within a specified audio reception range. The value of this parameter should be ≤ 16, and the default value is 10.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setAudioRecvRange:

- (int) setAudioRecvRange: |  | (float) | range |

Sets the audio reception range of the local user.

After the setting is successful, the local user can only hear the remote users within the setting range or belonging to the same team. You can call this method at any time to update the audio reception range.

Parameters

  range | The maximum audio reception range. The unit is meters. The value of this parameter must be greater than 0, and the default value is 20.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setDistanceUnit:

- (int) setDistanceUnit: |  | (float) | unit |

Sets the length (in meters) of the game engine distance per unit.

In a game engine, the unit of distance is customized, while in the Agora spatial audio algorithm, distance is measured in meters. By default, the SDK converts the game engine distance per unit to one meter. You can call this method to convert the game engine distance per unit to a specified number of meters.

Parameters

  unit | The number of meters that the game engine distance per unit is equal to. The value of this parameter must be greater than 0.00, and the default value is 1.00. For example, setting unit as 2.00 means the game engine distance per unit equals 2 meters.The larger the value is, the faster the sound heard by the local user attenuates when the remote user moves far away from the local user.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updatePlayerPositionInfo:positionInfo:

- (int) updatePlayerPositionInfo: |  | (NSInteger) | playerId
positionInfo: |  | (AgoraRemoteVoicePositionInfo *_Nonnull) | positionInfo

Updates the spatial position of the media player.

After a successful update, the local user can hear the change in the spatial position of the media player. Call timing: This method can be called either before or after joining the channel.

Parameters

  playerId | The ID of the media player. You can get the Device ID by calling `getMediaPlayerId`.
  positionInfo | The spatial position of the media player. See `AgoraRemoteVoicePositionInfo`.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateSelfPosition:axisForward:axisRight:axisUp:

- (int) updateSelfPosition: |  | (simd_float3) | position
axisForward: |  | (simd_float3) | axisForward
axisRight: |  | (simd_float3) | axisRight
axisUp: |  | (simd_float3) | axisUp

Updates the spatial position of the local user.

- Under the `AgoraLocalSpatialAudioKit` class, this method needs to be used with `updateRemotePosition:positionInfo:`. The SDK calculates the relative position between the local and remote users according to this method and the parameter settings in `updateRemotePosition:positionInfo:`, and then calculates the user's spatial audio effect parameters.

Parameters

  position | The coordinates in the world coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
  axisForward | The unit vector of the x axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
  axisRight | The unit vector of the y axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.
  axisUp | The unit vector of the z axis in the coordinate system. This parameter is an array of length 3, and the three values represent the front, right, and top coordinates in turn.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ updateSelfTransform:

- (int) updateSelfTransform: |  | (simd_float4x4) | transform |

Update coordinate conversion.

Applicable scenarios: When using native iOS frameworks like SceneKit or RealityKit, you can use this method to directly pass the position vector into the mentioned frameworks for rendering.

Parameters

  transform | Convert parameters. It's a 4 × 4 matrix.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setZones:

- (int) setZones: |  | (NSArray< AgoraSpatialAudioZone * > *_Nullable) | zones |

Sets the sound insulation area.

In virtual interactive scenarios, you can use this method to set the sound insulation area and sound attenuation coefficient. When the sound source (which can be the user or the media player) and the listener belong to the inside and outside of the sound insulation area, they can experience the attenuation effect of sound similar to the real environment when it encounters a building partition.

- When the sound source and the listener belong to the inside and outside of the sound insulation area, the sound attenuation effect is determined by the sound attenuation coefficient in `AgoraSpatialAudioZone`.
- If the user or media player is in the same sound insulation area, it is not affected by `AgoraSpatialAudioZone`, and the sound attenuation effect is determined by the `attenuation` parameter in `setPlayerAttenuation:playerId:forceSet:` or `setRemoteAudioAttenuation:userId:forceSet:`. If you do not call `setPlayerAttenuation:playerId:forceSet:` or `setRemoteAudioAttenuation:userId:forceSet:`, the default sound attenuation coefficient of the SDK is 0.5, which simulates the attenuation of the sound in the real environment.
- If the sound source and the receiver belong to two sound insulation areas, the receiver cannot hear the sound source.

Note
  If this method is called multiple times, the last sound insulation area set takes effect.

Parameters

  zones | Sound insulation area settings. See `AgoraSpatialAudioZone`. When you set this parameter to `nil`, it means clearing all sound insulation zones.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ setPlayerAttenuation:playerId:forceSet:

- (int) setPlayerAttenuation: |  | (double) | attenuation
playerId: |  | (NSUInteger) | playerId
forceSet: |  | (BOOL) | forceSet

Sets the sound attenuation properties of the media player.

Parameters

  playerId | The ID of the media player. You can get the Device ID by calling `getMediaPlayerId`.
  attenuation | The sound attenuation coefficient of the remote user or media player. The value range is [0,1]. The values are as follows: 0: Broadcast mode, where the volume and timbre are not attenuated with distance, and the volume and timbre heard by local users do not change regardless of distance. (0,0.5): Weak attenuation mode, that is, the volume and timbre are only weakly attenuated during the propagation process, and the sound can travel farther than the real environment. 0.5: (Default) simulates the attenuation of the volume in the real environment; the effect is equivalent to not setting the `speaker_attenuation` parameter. (0.5,1]: Strong attenuation mode, that is, the volume and timbre attenuate rapidly during the propagation process.
  forceSet | Whether to force the sound attenuation effect of the media player: `YES`: Force `attenuation` to set the attenuation of the media player. At this time, the attenuation coefficient of the sound insulation are set in the `audioAttenuation` in the `AgoraSpatialAudioZone` does not take effect for the media player. `NO`: Do not force `attenuation` to set the sound attenuation effect of the media player, as shown in the following two cases. If the sound source and listener are inside and outside the sound isolation area, the sound attenuation effect is determined by the `audioAttenuation` in `AgoraSpatialAudioZone`. If the sound source and the listener are in the same sound insulation area or outside the same sound insulation area, the sound attenuation effect is determined by `attenuation` in this method.

Returns
  - 0: Success.
  - < 0: Failure.

## ◆ clearRemotePositions

- (int) clearRemotePositions |  |  |