diff --git a/src/common/Enums.ts b/src/common/Enums.ts index 94fef4806..83bf92ca9 100644 --- a/src/common/Enums.ts +++ b/src/common/Enums.ts @@ -470,35 +470,39 @@ export enum AudioSampleRateType { */ export enum AudioScenario { /** - * 0: Default. + * 0: Default audio scenario. */ Default = 0, /** - * 1: Entertainment scenario, supporting voice during gameplay. + * 1: Entertainment scenario where users need to frequently switch the user role. */ ChatRoomEntertainment = 1, /** - * 2: Education scenario, prioritizing fluency and stability. + * 2: Education scenario where users want smoothness and stability. */ Education = 2, /** - * 3: Live gaming scenario, enabling the gaming audio effects in the speaker mode in a live broadcast scenario. Choose this scenario for high-fidelity music playback. + * 3: High-quality audio chatroom scenario where hosts mainly play music. */ GameStreaming = 3, /** - * 4: Showroom scenario, optimizing the audio quality with external professional equipment. + * 4: Showroom scenario where a single host wants high-quality audio. */ ShowRoom = 4, /** - * 5: Gaming scenario. + * 5: Gaming scenario for group chat that only contains the human voice. */ ChatRoomGaming = 5, /** - * TODO + * IoT (Internet of Things) scenario where users use IoT devices with low power consumption. + * + * @since v3.2.0. */ IOT = 6, /** - * TODO + * Meeting scenario that mainly contains the human voice. + * + * @since v3.2.0. */ MEETING = 8, } @@ -2387,73 +2391,277 @@ export enum AudioSessionOperationRestriction { } /** - * TODO + * The options for SDK preset audio effects. */ export enum AudioEffectPreset { + /** + * Turn off audio effects and use the original voice. + */ AudioEffectOff = 0x00000000, + /** + * An audio effect typical of a KTV venue. + * + * **Note** + * + * To achieve better audio effect quality, Agora recommends calling setAudioProfile and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ RoomAcousticsKTV = 0x02010100, - + /** + * An audio effect typical of a concert hall. + * + * **Note** + * + * To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ RoomAcousticsVocalConcert = 0x02010200, + /** + * An audio effect typical of a recording studio. + * + * **Note** + * + * To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ RoomAcousticsStudio = 0x02010300, + /** + * An audio effect typical of a vintage phonograph. + * + * **Note** + * + * To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ RoomAcousticsPhonograph = 0x02010400, + /** + * A virtual stereo effect that renders monophonic audio as stereo audio. + * + * **Note** + * + * Call `setAudioProfile` and set the profile parameter to `MusicStandardStereo(3)` or `MusicHighQualityStereo(5)` + * before setting this enumerator; otherwise, the enumerator setting does not take effect. + */ RoomAcousticsVirtualStereo = 0x02010500, + /** + * A more spatial audio effect. + * + * **Note** + * + * To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ RoomAcousticsSpacial = 0x02010600, + /** + * A more ethereal audio effect. + * + * **Note** + * + * To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ RoomAcousticsEthereal = 0x02010700, + /** + * A 3D voice effect that makes the voice appear to be moving around the user. + * The default cycle period of the 3D voice effect is 10 seconds. To change the cycle period, call `setAudioEffectParameters` after this method. + * + * **Note** + * + * - Call `setAudioProfile` and set the profile parameter to `MusicStandardStereo(3)` or `MusicHighQualityStereo(5)` before setting this enumerator; + * otherwise, the enumerator setting does not take effect. + * - If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect. + */ RoomAcoustics3DVoice = 0x02010800, + /** + * The voice of an uncle. + * + * **Note** + * + * - Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ VoiceChangerEffectUncle = 0x02020100, + /** + * The voice of an uncle. + * + * **Note** + * + * - Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ VoiceChangerEffectOldMan = 0x02020200, + /** + * The voice of a boy. + * + * **Note** + * + * - Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ VoiceChangerEffectBoy = 0x02020300, + /** + * The voice of a young woman. + * + * **Note** + * + * - Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ VoiceChangerEffectSister = 0x02020400, + /** + * The voice of a girl. + * + * **Note** + * + * - Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ VoiceChangerEffectGirl = 0x02020500, + /** + * The voice of Pig King, a character in Journey to the West who has a voice like a growling bear. + * + * **Note** + * + * - Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ VoiceChangerEffectPigKing = 0x02020600, + /** + * The voice of Hulk. + * + * **Note** + * + * - Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may not hear the anticipated voice effect. + * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ VoiceChangerEffectHulk = 0x02020700, + /** + * An audio effect typical of R&B music. + * + * **Note** + * + * Call `setAudioProfile` and set the profile parameter to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator; + * otherwise, the enumerator setting does not take effect. + */ StyleTransformationRnB = 0x02030100, + /** + * An audio effect typical of popular music. + * + * **Note** + * + * Call `setAudioProfile` and set the profile parameter to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator; + * otherwise, the enumerator setting does not take effect. + */ StyleTransformationPopular = 0x02030200, + /** + * A pitch correction effect that corrects the user's pitch based on the pitch of the natural C major scale. + * To change the basic mode and tonic pitch, call `setAudioEffectParameters` after this method. + * + * **Note** + * + * To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter + * to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. + */ PitchCorrection = 0x02040100, } /** - * TODO + * The options for SDK preset voice beautifier effects. */ export enum VoiceBeautifierPreset { + /** + * Turn off voice beautifier effects and use the original voice. + */ VoiceBeautifierOff = 0x00000000, + /** + * A more magnetic voice. + * + * **Note** + * + * Agora recommends using this enumerator to process a male-sounding voice; otherwise, you may experience vocal distortion. + */ ChatBeautifierMagnetic = 0x01010100, + /** + * A fresher voice. + * + * **Note** + * + * Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. + */ ChatBeautifierFresh = 0x01010200, + /** + * A more vital voice. + * + * **Note** + * + * Agora recommends using this enumerator to process a female-sounding voice; otherwise, you may experience vocal distortion. + */ ChatBeautifierVitality = 0x01010300, + /** + * A more vigorous voice. + */ TimbreTransformationVigorous = 0x01030100, + /** + * A deeper voice. + */ TimbreTransformationDeep = 0x01030200, + /** + * A mellower voice. + */ TimbreTransformationMellow = 0x01030300, + /** + * A falsetto voice. + */ TimbreTransformationFalsetto = 0x01030400, + /** + * A fuller voice. + */ TimbreTransformationFull = 0x01030500, + /** + * A clearer voice. + */ TimbreTransformationClear = 0x01030600, + /** + * A more resounding voice. + */ TimbreTransformationResounding = 0x01030700, + /** + * A more ringing voice. + */ TimbreTransformationRinging = 0x01030800, } diff --git a/src/common/RtcEngine.native.ts b/src/common/RtcEngine.native.ts index 6d6022b8a..f8bfc4c57 100644 --- a/src/common/RtcEngine.native.ts +++ b/src/common/RtcEngine.native.ts @@ -812,11 +812,11 @@ export default class RtcEngine implements RtcEngineInterface { * * - You must call this method before calling [`joinChannel`]{@link joinChannel}. * - In the [`Communication`]{@link ChannelProfile.Communication} and [`LiveBroadcasting`]{@link ChannelProfile.LiveBroadcasting} profiles, the bitrates may be different from your settings due to network self-adaptation. - * - In scenarios requiring high-quality audio, we recommend setting profile as [`MusicHighQuality(4)`]{@link AudioProfile.MusicHighQuality} and scenario as [`GameStreaming(3)`]{@link AudioScenario.GameStreaming}. - * For example, for music education scenarios. + * - In scenarios requiring high-quality audio, we recommend setting profile as `ShowRoom(4)` and scenario as `GameStreaming(3)`. For example, for music education scenarios. * - * @param profile Sets the sample rate, bitrate, encoding mode, and the number of channels. - * @param scenario Sets the audio application scenarios. Under different audio scenarios, the device uses different volume tracks, i.e. either the in-call volume or the media volume. + * @param profile Sets the sample rate, bitrate, encoding mode, and the number of channels. See [`AudioProfile`]{@link AudioProfile}. + * @param scenario Sets the audio application scenarios. See [`AudioScenario`]{@link AudioScenario}. Under different audio scenarios, the device uses different volume tracks, i.e. either the in-call volume or the media volume. + * For details, see [What is the difference between the in-call volume and the media volume?](https://docs.agora.io/en/Voice/faq/system_volume). */ setAudioProfile( profile: AudioProfile, @@ -1431,7 +1431,7 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets the local voice changer option. * - * @deprecated + * @deprecated Deprecated as of v3.2.0. Use `setAudioEffectPreset` or `setVoiceBeautifierPreset` instead. * * **Note** * @@ -1492,7 +1492,7 @@ export default class RtcEngine implements RtcEngineInterface { /** * Sets the preset local voice reverberation effect. * - * @deprecated + * @deprecated Deprecated as of v3.2.0. Use `setAudioEffectPreset` or `setVoiceBeautifierPreset` instead. * * **Note** * @@ -2503,11 +2503,68 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * TODO + * Sets parameters for SDK preset audio effects. + * + * @since v3.2.0. + * + * Call this method to set the following parameters for the local user who send an audio stream: + * - 3D voice effect: Sets the cycle period of the 3D voice effect. + * - Pitch correction effect: Sets the basic mode and tonic pitch of the pitch correction effect. Different songs have different modes and tonic pitches. + * Agora recommends bounding this method with interface elements to enable users to adjust the pitch correction interactively. + * + * After setting parameters, all users in the channel can hear the relevant effect. + * + * You can call this method directly or after `setAudioEffectPreset`. If you call this method after `setAudioEffectPreset`, ensure that you set the preset parameter of `setAudioEffectPreset` to `RoomAcoustics3DVoice` or `PitchCorrection` and + * then call this method to set the same enumerator; otherwise, this method overrides `setAudioEffectPreset`. + * + * **Note** + * - To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the scenario parameter + * to `GameStreaming(3)` before calling this method. + * - Do not set the profile parameter of `setAudioProfile` to `SpeechStandard(1)` or `AUDIO_PROFILE_IOT(6)`; otherwise, this method call fails. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * - After calling this method, Agora recommends not calling the following methods, because they can override `setAudioEffectParameters`: + * - `setAudioEffectPreset` + * - `setVoiceBeautifierPreset` + * - `setLocalVoiceReverbPreset` + * - `setLocalVoiceChanger` + * - `setLocalVoicePitch` + * - `setLocalVoiceEqualization` + * - `setLocalVoiceReverb` + * + * @param preset The options for SDK preset audio effects: + * - 3D voice effect: `RoomAcoustics3DVoice`. + * - Call `setAudioProfile` and set the profile parameter to `MusicStandardStereo(3)` or `MusicHighQualityStereo(5)` before setting this enumerator; + * otherwise, the enumerator setting does not take effect. + * - If the 3D voice effect is enabled, users need to use stereo audio playback devices to hear the anticipated voice effect. + * - Pitch correction effect: `PitchCorrection`. To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the profile parameter to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before setting this enumerator. * - * @param preset * @param param1 + * - If you set preset to `RoomAcoustics3DVoice`, the `param1` sets the cycle period of the 3D voice effect. + * The value range is [1,60] and the unit is a second. The default value is 10 seconds, indicating that the voice moves around you every 10 seconds. + * - If you set preset to `PitchCorrection`, `param1` sets the basic mode of the pitch correction effect: + * - 1: (Default) Natural major scale. + * - 2: Natural minor scale. + * - 3: Japanese pentatonic scale. + * * @param param2 + * - You need to set `param2` to 0. + * - If you set `preset` to `PitchCorrection`, `param2` sets the tonic pitch of the pitch correction effect: + * - 1: A + * - 2: A# + * - 3: B + * - 4: (Default) C + * - 5: C# + * - 6: D + * - 7: D# + * - 8: E + * - 9: F + * - 10: F# + * - 11: G + * - 12: G# + * + * @returns + * - 0: Success. + * - < 0: Failure. */ setAudioEffectParameters( preset: AudioEffectPreset, @@ -2522,18 +2579,69 @@ export default class RtcEngine implements RtcEngineInterface { } /** - * TODO + * Sets an SDK preset audio effect. + * + * @since v3.2.0. + * + * Call this method to set an SDK preset audio effect for the local user who sends an audio stream. + * This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the channel can hear the effect. + * + * You can set different audio effects for different scenarios. * - * @param preset + * To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the scenario parameter to `GameStreaming(3)` before calling this method. + * + * **Note** + * - You can call this method either before or after joining a channel. + * - Do not set the profile parameter of `setAudioProfile` to `SpeechStandard(1)`; otherwise, this method call fails. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * - If you call this method and set the preset parameter to enumerators except `RoomAcoustics3DVoice` or `PitchCorrection`, do not call `setAudioEffectParameters`; otherwise, `setAudioEffectParameters` overrides this method. + * - After calling this method, Agora recommends not calling the following methods, because they can override `setAudioEffectPreset`: + * - `setVoiceBeautifierPreset` + * - `setLocalVoiceReverbPreset` + * - `setLocalVoiceChanger` + * - `setLocalVoicePitch` + * - `setLocalVoiceEqualization` + * - `setLocalVoiceReverb` + * + * @param preset The options for SDK preset audio effects. See [`AudioEffectPreset`]{@link AudioEffectPreset}. + * + * @returns + * - 0: Success. + * - < 0: Failure. */ setAudioEffectPreset(preset: AudioEffectPreset): Promise { return RtcEngine._callMethod('setAudioEffectPreset', { preset }); } /** - * TODO + * Sets an SDK preset voice beautifier effect. + * + * @since v3.2.0. + * + * Call this method to set an SDK preset voice beautifier effect for the local user who sends an audio stream. + * After setting a voice beautifier effect, all users in the channel can hear the effect. * - * @param preset + * You can set different voice beautifier effects for different scenarios. + * + * To achieve better audio effect quality, Agora recommends calling `setAudioProfile` and setting the scenario parameter to `GameStreaming(3)` and the profile parameter to `MusicHighQuality(4)` or `MusicHighQualityStereo(5)` before calling this method. + * + * **Note** + * - You can call this method either before or after joining a channel. + * - Do not set the profile parameter of `setAudioProfile` to `SpeechStandard(1)`; otherwise, this method call fails. + * - This method works best with the human voice. Agora does not recommend using this method for audio containing music. + * - After calling this method, Agora recommends not calling the following methods, because they can override `setVoiceBeautifierPreset`: + * - `setAudioEffectPreset` + * - `setLocalVoiceReverbPreset` + * - `setLocalVoiceChanger` + * - `setLocalVoicePitch` + * - `setLocalVoiceEqualization` + * - `setLocalVoiceReverb` + * + * @param preset The options for SDK preset voice beautifier effects. See [`VoiceBeautifierPreset`]{@link VoiceBeautifierPreset}. + * + * @returns + * - 0: Success. + * - < 0: Failure. */ setVoiceBeautifierPreset(preset: VoiceBeautifierPreset): Promise { return RtcEngine._callMethod('setVoiceBeautifierPreset', { preset });