Agora RTC Objective-C API Reference Refactor

Public Types | Public Member Functions
IRemoteAudioTrack Class Referenceabstract

Inherits IAudioTrack.

## Public Types
enum | AudioFilterPosition { RecordingLocalPlayback, PostAudioProcessing, RemoteUserPlayback, PcmSource, PcmSourceSending, PcmSourceLocalPlayback, RemoteMixedPlayback }

## Public Member Functions
virtual bool | getStatistics (RemoteAudioTrackStats &stats)=0
virtual REMOTE_AUDIO_STATE | getState ()=0
virtual int | registerMediaPacketReceiver (IMediaPacketReceiver *packetReceiver, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterMediaPacketReceiver (IMediaPacketReceiver *packetReceiver)=0
virtual int | registerAudioEncodedFrameReceiver (IAudioEncodedFrameReceiver *packetReceiver, const AudioEncFrameRecvParams &recvParams, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | unregisterAudioEncodedFrameReceiver (IAudioEncodedFrameReceiver *packetReceiver)=0
virtual int | setRemoteVoicePosition (float pan, float gain, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | adjustDecodedAudioVolume (int decoded_index, int volume, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | muteRemoteFromTimestamp (uint32_t timestamp)=0
virtual int | unmuteRemoteFromTimestamp (uint32_t timestamp)=0
virtual int | adjustAudioAcceleration (int percentage, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | adjustAudioDeceleration (int percentage, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | enableAudioBurstAccelerate (bool enable, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | enableSpatialAudio (bool enabled, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | adjustPlayoutVolume (int volume, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | getPlayoutVolume (int *volume)=0
virtual bool | addAudioFilter (agora_refptr< IAudioFilter > filter, AudioFilterPosition position, ExtensionContext *extContext=NULL, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | removeAudioFilter (agora_refptr< IAudioFilter > filter, AudioFilterPosition position, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual int | enableAudioFilter (const char *id, bool enable, AudioFilterPosition position, aosl_ref_t ares=AOSL_REF_INVALID)
virtual int | setFilterProperty (const char *id, const char *key, const char *jsonValue, AudioFilterPosition position, aosl_ref_t ares=AOSL_REF_INVALID)
virtual int | getFilterProperty (const char *id, const char *key, char *jsonValue, size_t bufSize, AudioFilterPosition position)
virtual agora_refptr< IAudioFilter > | getAudioFilter (const char *name, AudioFilterPosition position) const =0
virtual bool | addAudioSink (agora_refptr< IAudioSinkBase > sink, const AudioSinkWants &wants, aosl_ref_t ares=AOSL_REF_INVALID)=0
virtual bool | removeAudioSink (agora_refptr< IAudioSinkBase > sink, aosl_ref_t ares=AOSL_REF_INVALID)=0

## Detailed Description

The IRemoteAudioTrack class.

## Member Enumeration Documentation

## ◆ AudioFilterPosition

enum AudioFilterPosition
| inherited

The position of the audio filter in audio frame.

Enumerator
RecordingLocalPlayback | Work on the local playback
PostAudioProcessing | Work on the post audio processing.
RemoteUserPlayback | Work on the remote audio before mixing.
PcmSource | Work on the pcm source.
PcmSourceSending | Work on the sending branch of the pcm source.
PcmSourceLocalPlayback | Work on the local playback branch of the pcm source.
RemoteMixedPlayback | Work on the playback after remote-audio mix.

## Member Function Documentation

## ◆ getStatistics()

virtual bool getStatistics | ( | RemoteAudioTrackStats & | stats | ) |
| pure virtual

Gets the statistics of the remote audio track.

Parameters

  stats | A reference to the statistics of the remote audio track: RemoteAudioTrackStats.

Returns
  - `true`: Success.
  - `false`: Failure.

## ◆ getState()

virtual REMOTE_AUDIO_STATE getState | ( |  | ) |
| pure virtual

Gets the state of the remote audio.

Returns
  The state of the remote audio: REMOTE_AUDIO_STATE.

## ◆ registerMediaPacketReceiver()

virtual int registerMediaPacketReceiver | ( | IMediaPacketReceiver * | packetReceiver,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an `IMediaPacketReceiver` object.

You need to implement the `IMediaPacketReceiver` class in this method. Once you successfully register the media packet receiver, the SDK triggers the `onMediaPacketReceived` callback when it receives an audio packet.

Parameters

  packetReceiver | The pointer to the `IMediaPacketReceiver` object.

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

## ◆ unregisterMediaPacketReceiver()

virtual int unregisterMediaPacketReceiver | ( | IMediaPacketReceiver * | packetReceiver | ) |
| pure virtual

Releases the `IMediaPacketReceiver` object.

Parameters

  packetReceiver | The pointer to the `IMediaPacketReceiver` object.

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

## ◆ registerAudioEncodedFrameReceiver()

virtual int registerAudioEncodedFrameReceiver | ( | IAudioEncodedFrameReceiver * | packetReceiver,
|  | const AudioEncFrameRecvParams & | recvParams,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Registers an `IAudioEncodedFrameReceiver` object.

You need to implement the `IAudioEncodedFrameReceiver` class in this method. Once you successfully register the media packet receiver, the SDK triggers the `onEncodedAudioFrameReceived` callback when it receives an audio packet.

Parameters

  packetReceiver | The pointer to the `IAudioEncodedFrameReceiver` object.
  recvParams | The parameter

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

## ◆ unregisterAudioEncodedFrameReceiver()

virtual int unregisterAudioEncodedFrameReceiver | ( | IAudioEncodedFrameReceiver * | packetReceiver | ) |
| pure virtual

Releases the `IAudioEncodedFrameReceiver` object.

Parameters

  packetReceiver | The pointer to the `IAudioEncodedFrameReceiver` object.

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

## ◆ setRemoteVoicePosition()

virtual int setRemoteVoicePosition | ( | float | pan,
|  | float | gain,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the sound position and gain

Parameters

  pan | The sound position of the remote user. The value ranges from -1.0 to 1.0: 0.0: the remote sound comes from the front. -1.0: the remote sound comes from the left. 1.0: the remote sound comes from the right.
  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.

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

## ◆ adjustDecodedAudioVolume()

virtual int adjustDecodedAudioVolume | ( | int | decoded_index,
|  | int | volume,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

Sets the volume of each audio decoded channel

Parameters

  decoded_index | The channel index of the remote user. The value ranges from 0 to 100:
  volume | The channel index of the remote user. The value ranges from 0 to 100. 0: mute the channel. 100: keep the origin volume of the channel.

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

## ◆ muteRemoteFromTimestamp()

virtual int muteRemoteFromTimestamp | ( | uint32_t | timestamp | ) |
| pure virtual

mute remote stream from timestamp

Note
  - unmuteRemoteFromTimestamp should be called after muteRemoteFromTimestamp, othewise this stream will be muted all time

Parameters

  timestamp | The rtp timestamp of start mute

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

## ◆ unmuteRemoteFromTimestamp()

virtual int unmuteRemoteFromTimestamp | ( | uint32_t | timestamp | ) |
| pure virtual

unmute remote stream from timestamp

Note
  - unmuteRemoteFromTimestamp should be called after muteRemoteFromTimestamp, othewise this stream will be muted all time

Parameters

  timestamp | The rtp timestamp of start unmute

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

## ◆ adjustAudioAcceleration()

virtual int adjustAudioAcceleration | ( | int | percentage,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

set percentage of audio acceleration during poor network

Note
  - The relationship between this percentage and the degree of audio acceleration is non-linear and varies with different audio material.

Parameters

  percentage | The percentage of audio acceleration. The value ranges from 0 to 100. The higher the percentage, the faster the acceleration. The default value is 100 (no change to the acceleration): 0: disable audio acceleration. > 0: enable audio acceleration.

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

## ◆ adjustAudioDeceleration()

virtual int adjustAudioDeceleration | ( | int | percentage,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

set percentage of audio deceleration during poor network

Note
  - The relationship between this percentage and the degree of audio deceleration is non-linear and varies with different audio material.

Parameters

  percentage | The percentage of audio deceleration. The value ranges from 0 to 100. The higher the percentage, the faster the deceleration. The default value is 100 (no change to the deceleration): 0: disable audio deceleration. > 0: enable audio deceleration.

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

## ◆ enableAudioBurstAccelerate()

virtual int enableAudioBurstAccelerate | ( | bool | enable,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

enable audio fast acceleration during audio packets burst arrival.

Parameters

  enable | Whether to enable audio burst acceleration.

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

## ◆ enableSpatialAudio()

virtual int enableSpatialAudio | ( | bool | enabled,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual

enable spatial audio

Parameters

  enabled | enable/disable spatial audio: true: enable spatial audio. false: disable spatial audio.

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

## ◆ adjustPlayoutVolume()

virtual int adjustPlayoutVolume | ( | int | volume,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual inherited

Adjusts the playback volume.

Parameters

  volume | The playback volume. The value ranges between 0 and 100 (default).

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

## ◆ getPlayoutVolume()

virtual int getPlayoutVolume | ( | int * | volume | ) |
| pure virtual inherited

Gets the current playback volume.

Parameters

  volume | A pointer to the playback volume.

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

## ◆ addAudioFilter()

virtual bool addAudioFilter | ( | agora_refptr< IAudioFilter > | filter,
|  | AudioFilterPosition | position,
|  | ExtensionContext * | extContext = `NULL`,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual inherited

Adds an audio filter.

By adding an audio filter, you can apply various audio effects to the audio, for example, voice change.

Parameters

  filter | A pointer to the audio filter. See IAudioFilter.
  position | The position of the audio filter. See AudioFilterPosition.
  extContext | The context of current filter. See ExtensionContext.

Returns
  - `true`: Success.
  - `false`: Failure.

## ◆ removeAudioFilter()

virtual bool removeAudioFilter | ( | agora_refptr< IAudioFilter > | filter,
|  | AudioFilterPosition | position,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual inherited

Removes the audio filter added by callling `addAudioFilter`.

Parameters

  filter | The pointer to the audio filter that you want to remove. See IAudioFilter.
  position | The position of the audio filter. See AudioFilterPosition.

Returns
  - `true`: Success.
  - `false`: Failure.

## ◆ enableAudioFilter()

virtual int enableAudioFilter | ( | const char * | id,
|  | bool | enable,
|  | AudioFilterPosition | position,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| inline virtual inherited

Enable / Disable specified audio filter

Parameters

  id | id of the filter
  enable | enable / disable the filter with given id
  position | The position of the audio filter. See AudioFilterPosition.

Returns
  - 0: success
  - <0: failure

## ◆ setFilterProperty()

virtual int setFilterProperty | ( | const char * | id,
|  | const char * | key,
|  | const char * | jsonValue,
|  | AudioFilterPosition | position,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| inline virtual inherited

set the properties of the specified audio filter

Parameters

  id | id of the filter
  key | key of the property
  jsonValue | json str value of the property
  position | The position of the audio filter. See AudioFilterPosition.

Returns
  - 0: success
  - <0: failure

## ◆ getFilterProperty()

virtual int getFilterProperty | ( | const char * | id,
|  | const char * | key,
|  | char * | jsonValue,
|  | size_t | bufSize,
|  | AudioFilterPosition | position
| ) |  |
| inline virtual inherited

get the properties of the specified video filter

Parameters

  id | id of the filter
  key | key of the property
  jsonValue | json str value of the property
  bufSize | max length of the json value buffer
  position | The position of the audio filter. See AudioFilterPosition.

Returns
  - 0: success
  - <0: failure

## ◆ getAudioFilter()

virtual agora_refptr<IAudioFilter> getAudioFilter | ( | const char * | name,
|  | AudioFilterPosition | position
| ) |  | const
| pure virtual inherited

Gets the audio filter by its name.

Parameters

  name | The name of the audio filter.
  position | The position of the audio filter. See AudioFilterPosition.

Returns
  - The pointer to the audio filter: Success.
  - A null pointer: Failure.

## ◆ addAudioSink()

virtual bool addAudioSink | ( | agora_refptr< IAudioSinkBase > | sink,
|  | const AudioSinkWants & | wants,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual inherited

Adds an audio sink to get PCM data from the audio track.

Parameters

  sink | The pointer to the audio sink. See IAudioSinkBase.
  wants | The properties an audio frame should have when it is delivered to the sink. See AudioSinkWants.

Returns
  - `true`: Success.
  - `false`: Failure.

## ◆ removeAudioSink()

virtual bool removeAudioSink | ( | agora_refptr< IAudioSinkBase > | sink,
|  | aosl_ref_t | ares = `AOSL_REF_INVALID`
| ) |  |
| pure virtual inherited

Removes an audio sink.

Parameters

  sink | The pointer to the audio sink to be removed. See IAudioSinkBase.

Returns
  - `true`: Success.
  - `false`: Failure.

## ◆ AddRef()

virtual void AddRef | ( |  | ) | const
| pure virtual inherited

## ◆ Release()

virtual RefCountReleaseStatus Release | ( |  | ) | const
| pure virtual inherited

## ◆ HasOneRef()

virtual bool HasOneRef | ( |  | ) | const
| pure virtual inherited