From fbd459a6666b2c5469f0485ebb706641bef5ea5b Mon Sep 17 00:00:00 2001 From: Saud <65331551+saudsami@users.noreply.github.com> Date: Sat, 6 Jul 2024 18:34:39 +0500 Subject: [PATCH] Updates (#1575) --- .../video-sdk/develop/voice-effects/index.mdx | 23 ++- .../project-implementation/android.mdx | 133 ++++++++++------- .../project-implementation/swift.mdx | 139 ++++++++++------- .../project-implementation/windows.mdx | 141 ++++++++++-------- .../voice-effects/reference/android.mdx | 10 +- .../develop/voice-effects/reference/ios.mdx | 7 + .../develop/voice-effects/reference/macos.mdx | 7 + .../voice-effects/reference/windows.mdx | 12 +- 8 files changed, 286 insertions(+), 186 deletions(-) diff --git a/shared/video-sdk/develop/voice-effects/index.mdx b/shared/video-sdk/develop/voice-effects/index.mdx index d1b907ede..730a3c703 100644 --- a/shared/video-sdk/develop/voice-effects/index.mdx +++ b/shared/video-sdk/develop/voice-effects/index.mdx @@ -9,19 +9,26 @@ import NotAvailable from '@docs/shared/common/not-available.mdx' ## Understand the tech -With you can implement voice modifying effects such as chat beautifier, singing beautifier, and voice changer. These are gaining popularity in social interaction and entertainment scenarios. To help you quickly integrate voice effects into your project, provides pre-configured effects. You can choose from the following types: +Voice effects are gaining popularity in social interaction and entertainment scenarios. To help you quickly integrate voice effects into your project, provides pre-configured effects. Choose from the following effects: - * **Preset voice beautifiers**: Chat beautifier, singing beautifier, and timbre transformation. +* **Voice beautifiers** + * Voice beautifier for Chat: Beautify the voice in chat scenarios according to the characteristics of male and female voices without changing the original voice recognition. + * Singing beautifier: Beautify the singing voice according to male and female voice characteristics while retaining the original character of the singing voice. + * Timbre shift: Fine-tune the timbre of a vocal in a specific direction. - * **Preset audio effects**: Voice changer, style transformation, room acoustics, and pitch correction. +* **Sound effects** + * Style sound effects: For songs of a specific style, make the singing and accompaniment more compatible. + * Spatial shaping: Create a spatial atmosphere through spatial reverberation effects. Make the vocals seem to come from a specific source. + * Electronic sound effects: Adjust the pitch of the vocals to perfectly match the key and pitch of the accompaniment for an electronic sound effect. - * **Preset voice conversion**: Changing the original voice to make it unrecognizable. +* **Voice changer** + * Basic voice changing: Make the voice more neutral, sweet, or stable while retain a certain degree of voice recognition. + * Advanced voice changing: Dramatically change the human voice to realize voices of uncle, girl, Hulk, etc. - * **Voice formant modification**: Changing the voice timbre by adjusting the formant ratio. +* **Custom vocal effects** + If the preset effects don't meet your needs, manually adjust the vocal pitch, equalization, and reverb effects to achieve a customized effect. - * **Customized audio effects**: Controlling the voice pitch, equalization, and reverberation. - -Try the [Online Demo](https://www.agora.io/en/audio-demo?_gl=1*skmawq*_ga*MjA2MzYxMjY4Mi4xNzAzMDczMjA1*_ga_BFVGG7E02W*MTcwNzgwOTIyNS4xOC4xLjE3MDc4MTA2OTAuMC4wLjA) to experience different voice effects. +Try the [Online Demo](https://web-cdn.agora.io/marketing/audio_en_v3.html) to experience different voice effects. ## Prerequisites diff --git a/shared/video-sdk/develop/voice-effects/project-implementation/android.mdx b/shared/video-sdk/develop/voice-effects/project-implementation/android.mdx index 034ba3c1e..4634e7f3a 100644 --- a/shared/video-sdk/develop/voice-effects/project-implementation/android.mdx +++ b/shared/video-sdk/develop/voice-effects/project-implementation/android.mdx @@ -2,108 +2,133 @@ ### Set audio scenario and audio profile -For optimal audio quality, configure `RtcEngineConfig` to set an audio scenario and call `setAudioProfile` to specify an audio profile: +For optimal audio quality, take the following steps: + +- Call setAudioScenario to set the audio scenario to high-quality `AUDIO_SCENARIO_GAME_STREAMING`. +- Call setAudioProfile to set the audio encoding properties to high-quality encoding: + + - For mono transmission, set the profile to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`. + - For stereo transmission, set the profile to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO` ```java -// Set mAudioScenario in RtcEngineConfig to AUDIO_SCENARIO_GAME_STREAMING -config.mAudioScenario = Constants.AudioScenario.getValue(Constants.AudioScenario.GAME_STREAMING); +// Create the RtcEngine object mRtcEngine = RtcEngine.create(config); - -// Call setAudioProfile to set the scene to AUDIO_PROFILE_MUSIC_HIGH_QUALITY or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO +// Set the audio scenario +mRtcEngine.setAudioScenario(Constants.AudioScenario.getValue(Constants.AudioScenario.GAME_STREAMING)); +// Set the audio encoding properties mRtcEngine.setAudioProfile(Constants.AudioProfile.getValue(Constants.AudioProfile.MUSIC_HIGH_QUALITY_STEREO)); ``` -### Enhance voice with voice effects +### Voice beautifiers -Enhance the characteristics of male and female voices while preserving the inherent identity of the original voice. The following code snippets demonstrate how to enable different voice beautifiers: +Call `setAudioEffectPreset` to set music style, space shaping, electronic music, and other effects. -* Enhance the character and charm of male voices with the 'Magnetic' vocal effect. Be cautious when applying this setting to female voices, as it may lead to distortion: +- Chat voice beautifier ```java - // Set the vocal effect to magnetic. This enumeration only applies to beautifying male voices - // When used to beautify female voices, it will cause distortion + // Set the vocal effect to magnetic (for male voices) mRtcEngine.setVoiceBeautifierPreset(Constants.CHAT_BEAUTIFIER_MAGNETIC); - // Turn off the vocal effect + + // Turn off the effect mRtcEngine.setVoiceBeautifierPreset(Constants.VOICE_BEAUTIFIER_OFF); ``` -* Optimize the singing voice for musical scenarios: +- Singing voice beautifier ```java - // Beautify a male singing voice. Do not use for female voice + // Example 1: Set male voice effect + // Set the singing voice preset to beautify the male voice and add a small room reverberation effect mRtcEngine.setVoiceBeautifierPreset(Constants.SINGING_BEAUTIFIER); - // Turn off the vocal effect + // Turn off the effect mRtcEngine.setVoiceBeautifierPreset(Constants.VOICE_BEAUTIFIER_OFF); - // Beautify a female singing voice + // Example 2: Set female voice effect + // Call the setVoiceBeautifierParameters method to beautify the female voice and add hall reverberation effect mRtcEngine.setVoiceBeautifierParameters(Constants.SINGING_BEAUTIFIER, 2, 3); - // Turn off the vocal effect + // Turn off the effect mRtcEngine.setVoiceBeautifierPreset(Constants.VOICE_BEAUTIFIER_OFF); ``` -* Transform the vocal richness with the 'Vibrant' timbre transformation effect: +* Tone change ```java - // Set the timbre transformation effect. Default vocal effect is 'thick' + // Set the timbre to thick mRtcEngine.setVoiceBeautifierPreset(Constants.TIMBRE_TRANSFORMATION_VIGOROUS); - // Turn off the vocal effect + // Turn off the effect mRtcEngine.setVoiceBeautifierPreset(Constants.VOICE_BEAUTIFIER_OFF); ``` -* Enrich audio with the 'Hulk' effect: - - ```java - // Default vocal effect is 'Hulk' - mRtcEngine.setAudioEffectPreset(Constants.VOICE_CHANGER_EFFECT_HULK); - // Turn off the vocal effect - mRtcEngine.setAudioEffectPreset(Constants.AUDIO_EFFECT_OFF); - ``` +### Sound effects -* Enhance vocal characteristics with 'Pop' style: +Call `setAudioEffectPreset` to set music style, space shaping, electronic music and other effects. + +* Music Style ```java - // Default vocal effect is 'Pop' + // Set the style to pop mRtcEngine.setAudioEffectPreset(Constants.STYLE_TRANSFORMATION_POPULAR); - // Turn off vocal effects + // Turn off the effect mRtcEngine.setAudioEffectPreset(Constants.AUDIO_EFFECT_OFF); ``` -* Simulate karaoke room acoustics with the 'KTV' effect: +* Space shaping ```java - // Default vocal effect is 'KTV' + // Set the space shaping effect to KTV mRtcEngine.setAudioEffectPreset(Constants.ROOM_ACOUSTICS_KTV); - // Turn off vocal effects + // Turn off the effect mRtcEngine.setAudioEffectPreset(Constants.AUDIO_EFFECT_OFF); ``` -* Apply electronic sound correction to a natural minor key with a pitch of C: +* Electronic sound effects ```java - // Set electronic sound to a natural minor key with a pitch of C + // Example 1: Use the preset pitch adjustment method to achieve the electronic music sound effect + // The preset is based on the natural major key with the tonic pitch of C, and corrects the actual pitch of the audio mRtcEngine.setAudioEffectPreset(Constants.PITCH_CORRECTION); - // Turn off vocal effects + // Turn off the effect + mRtcEngine.setAudioEffectPreset(Constants.AUDIO_EFFECT_OFF); + + // Example 2: Adjust the basic mode and tonic pitch to achieve the electronic music sound effect + // Call setAudioEffectParameters to adjust the basic mode of the tone to the natural minor key and the tonic pitch to D + mRtcEngine.setAudioEffectParameters(Constants.PITCH_CORRECTION, 2, 6); + // Turn off the effect mRtcEngine.setAudioEffectPreset(Constants.AUDIO_EFFECT_OFF); ``` -* Default voice change effect for a more neutral voice: +### Voice change effects + +To implement basic voice-changing effects, call the `setAudioEffectPreset` method. For advanced voice-changing effects, use the `setVoiceConversionPreset` method. + +* Basic voice changer ```java - // Default voice change effect to a more neutral voice + // Set the voice change effect to a more neutral voice mRtcEngine.setVoiceConversionPreset(Constants.VOICE_CHANGER_NEUTRAL); - // Turn off vocal effects + // Turn off the effect mRtcEngine.setVoiceConversionPreset(Constants.VOICE_CONVERSION_OFF); ``` -* Fine-tune vocal output parameters, including pitch, equalization, and reverberation effects. Transform a human voice into the distinctive sound of your choice by adjusting parameter values manually: +* Advanced voice changer + + ```java + // Set the vocal effect to 'Hulk' + mRtcEngine.setAudioEffectPreset(Constants.VOICE_CHANGER_EFFECT_HULK); + // Turn off the effect + mRtcEngine.setAudioEffectPreset(Constants.AUDIO_EFFECT_OFF); + ``` + +### Custom audio effects + +Call `setLocalVoicePitch`, `setLocalVoiceEqualization`, and `setLocalVoiceReverb` to fine-tune vocal output parameters, including pitch, equalization, and reverberation effects. The following example shows you how to transform a human voice into the voice of the Hulk by manually setting parameter values: ```java double pitch = 0.5; mRtcEngine.setLocalVoicePitch(pitch); - - // Set the center frequency of the local vocal equalization band - // The first parameter is the spectrum sub-band index, with values in [0, 9], representing 10 frequency bands (31, 62, 125, 250, 500, 1000, 2000, 4000, 8000, 16000 Hz) - // The second parameter is the gain value of each frequency interval, with values in [-15, 15] dB (default is 0) + + // Set the center frequency of the local voice equalization band + // The first parameter is the spectrum sub-band index, the value range is [0,9], representing 10 frequency bands, and the corresponding center frequencies are [31,62,125,250,500,1000,2000,4000,8000,16000] Hz + // The second parameter is the gain value of each frequency interval, the value range is [-15,15], the unit is dB, the default value is 0 mRtcEngine.setLocalVoiceEqualization(Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY.fromInt(0), -15); mRtcEngine.setLocalVoiceEqualization(Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY.fromInt(1), 3); mRtcEngine.setLocalVoiceEqualization(Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY.fromInt(2), -9); @@ -114,20 +139,20 @@ Enhance the characteristics of male and female voices while preserving the inher mRtcEngine.setLocalVoiceEqualization(Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY.fromInt(7), -2); mRtcEngine.setLocalVoiceEqualization(Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY.fromInt(8), -1); mRtcEngine.setLocalVoiceEqualization(Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY.fromInt(9), 1); - - // Original vocal intensity (dry signal), values in [-20, 10] dB + + // Original voice intensity or dry signal, value range [-20,10], unit is dB mRtcEngine.setLocalVoiceReverb(Constants.AUDIO_REVERB_TYPE.fromInt(0), 10); - - // Early reflection signal strength (wet signal), values in [-20, 10] dB + + // Early reflection signal intensity or wet signal, value range [-20,10], unit is dB mRtcEngine.setLocalVoiceReverb(Constants.AUDIO_REVERB_TYPE.fromInt(1), 7); - - // Room size required for the reverberation effect, values in [0, 100] + + // The room size for the required reverberation effect. Generally, the larger the room, the stronger the reverberation effect. Value range: [0,100] mRtcEngine.setLocalVoiceReverb(Constants.AUDIO_REVERB_TYPE.fromInt(2), 6); - - // Initial delay length of the wet signal, values in [0, 200] ms + + // Initial delay length of wet signal, value range: [0,200], unit: ms mRtcEngine.setLocalVoiceReverb(Constants.AUDIO_REVERB_TYPE.fromInt(3), 124); - - // Continuous intensity of the reverberation effect, values in [0, 100] + + // The continuous strength of reverberation effect, value range: [0,100], the larger the value, the stronger the reverberation effect mRtcEngine.setLocalVoiceReverb(Constants.AUDIO_REVERB_TYPE.fromInt(4), 78); ``` diff --git a/shared/video-sdk/develop/voice-effects/project-implementation/swift.mdx b/shared/video-sdk/develop/voice-effects/project-implementation/swift.mdx index 6f3aa780a..e1a8a98c5 100644 --- a/shared/video-sdk/develop/voice-effects/project-implementation/swift.mdx +++ b/shared/video-sdk/develop/voice-effects/project-implementation/swift.mdx @@ -1,108 +1,133 @@ ### Set audio scenario and audio profile -For optimal audio quality, configure `AgoraRtcEngineConfig` to set an audio scenario and call `setAudioProfile` to specify an audio profile: +For optimal audio quality, take the following steps: -```swift -// Set audioScenario in AgoraRtcEngineConfig to AgoraAudioScenarioGameStreaming -config.audioScenario = .gameStreaming -agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) +- Call `setAudioScenario` to set the audio scenario to the high-quality scenario `AgoraAudioScenarioGameStreaming`. + +- Call `setAudioProfile` to set the audio encoding properties to high-quality encoding: + + - For mono transmission, set the profile to `AgoraAudioProfileMusicHighQuality`. + - For stereo transmission, set the profile to `AgoraAudioProfileMusicHighQualityStereo`. -// Call setAudioProfile to set the audio profile to AgoraAudioProfileMusicHighQuality or AgoraAudioProfileMusicHighQualityStereo -agoraKit.setAudioProfile(.musicHighQualityStereo) +```swift +// Create RtcEngine object +let agoraKit = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self) +// Set audio scene +agoraKit.setAudioScenario(.gameStreaming) +// Set audio encoding properties +agoraKit.setAudioProfile(.musicHighQaulityStereo) ``` -### Enhance voice with voice effects +### Voice beautifiers -Enhance the characteristics of male and female voices while preserving the inherent identity of the original voice. The following code snippets demonstrate how to enable different voice beautifiers: +Call `setAudioEffectPreset` to set music style, space shaping, electronic music and other effects. -* Enhance the character and charm of male voices with the 'Magnetic' vocal effect. Be cautious when applying this setting to female voices, as it may lead to distortion: +- Chat voice beautifier ```swift - // Set the vocal effect to magnetic. This enumeration only applies to beautifying male voices - // When used to beautify female voices, it will cause distortion + // Set the voice effect to magnetic (for male voices) agoraKit.setVoiceBeautifierPreset(.chatBeautifierMagnetic) - // Turn off the vocal effect + + // Turn off the effect agoraKit.setVoiceBeautifierPreset(.voiceBeautifierOff) ``` -* Optimize the singing voice for musical scenarios: +- Singing voice beautifier ```swift - // Beautify a male singing voice. Do not use to beautify a female voice + // Example 1: Set male voice effect + // Set to singing beauty voice preset, which can beautify male voices and add small room reverberation effect agoraKit.setVoiceBeautifierPreset(.singingBeautifier) - // Turn off the vocal effect + // Turn off the effect agoraKit.setVoiceBeautifierPreset(.voiceBeautifierOff) - - // Beautify a female singing voice + + // Example 2: Set female voice effects + // Call the setVoiceBeautifierParameters method to beautify female voices and add hall reverberation effect agoraKit.setVoiceBeautifierParameters(.singingBeautifier, 2, 3) - // Turn off the vocal effect + // Turn off the effect agoraKit.setVoiceBeautifierPreset(.voiceBeautifierOff) ``` -* Transform the vocal richness with the 'Vibrant' timbre transformation effect: +* Tone change + ```swift - - // Set the timbre transformation effect - // The default vocal effect is thick + // Set the timbre to thick agoraKit.setVoiceBeautifierPreset(.timbreTransformationVigorous) - // Turn off the vocal effect + // Turn off the effect agoraKit.setVoiceBeautifierPreset(.voiceBeautifierOff) ``` -* Enrich audio with the 'Hulk' effect: +### Sound effects - ```swift - // The default vocal effect is Hulk - agoraKit.setAudioEffectPreset(.voiceChangerEffectHulk) - // Turn off the vocal effect - agoraKit.setAudioEffectPreset(.audioEffectOff) - ``` +Call the `setAudioEffectPreset` method to set music style, space shaping, electronic music, and other effects. -* Enhance vocal characteristics with 'Pop' style: +* Music Style ```swift - // The default vocal effect is pop + // Set the style to pop agoraKit.setAudioEffectPreset(.styleTransformationPopular) - // Turn off the vocal effect + // Turn off the effect agoraKit.setAudioEffectPreset(.audioEffectOff) ``` -* Simulate karaoke room acoustics with the 'KTV' effect: +* Space shaping ```swift - // The default vocal effect is the effect in KTV + // Set the space shaping effect to KTV agoraKit.setAudioEffectPreset(.roomAcousticKTV) - // Turn off the vocal effect + // Turn off the effect agoraKit.setAudioEffectPreset(.audioEffectOff) ``` -* Apply electronic sound correction to a natural minor key with a pitch of C: +* Electronic sound effects ```swift - // Set the electronic sound effect to the natural minor key with a pitch of C + // Example 1: Use the preset pitch adjustment method to achieve the electronic music sound effect + // The preset is based on the natural major key with the tonic pitch of C, and corrects the actual pitch of the audio agoraKit.setAudioEffectPreset(.pitchCorrection) - // Turn off the vocal effect + // Turn off the effect + agoraKit.setAudioEffectPreset(.audioEffectOff) + + // Example 2: Adjust the basic mode and tonic pitch to achieve the electronic sound effect + // Call setAudioEffectParameters to adjust the basic mode of the tone to the natural minor key and the tonic pitch to D + agoraKit.setAudioEffectParameters(.pitchCorrection, 2, 6); + // Turn off the effect agoraKit.setAudioEffectPreset(.audioEffectOff) ``` -* Default voice change effect for a more neutral voice: +### Voice changer effects + +To implement basic voice-changing effects, call the `setAudioEffectPreset` method. For advanced voice-changing effects, use the `setVoiceConversionPreset` method. + +* Basic voice changer ```swift // The default voice change effect is a more neutral voice agoraKit.setVoiceConversionPreset(.voiceChangerNeutral) - // Turn off the vocal effect + // Turn off the effect agoraKit.setVoiceConversionPreset(.voiceConversionOff) ``` + +* Advanced voice changer + + ```swift + // Set the voice changer effect to Hulk + agoraKit.setAudioEffectPreset(.voiceChangerEffectHulk) + // Turn off the effect + agoraKit.setAudioEffectPreset(.audioEffectOff) + ``` + +### Custom audio effects -* Fine-tune vocal output parameters, including pitch, equalization, and reverberation effects. Transform a human voice into the distinctive sound of your choice by adjusting parameter values manually: +Call `setLocalVoicePitch`, `setLocalVoiceEqualizationOf`, and `setLocalVoiceReverbOf` to fine-tune vocal output parameters, including pitch, equalization, and reverberation effects. The following example shows you how to transform a human voice into the voice of the Hulk by manually setting parameter values: ```swift agoraKit.setLocalVoicePitch(1) - - // Set the center frequency of the local vocal equalization band - // The first parameter is the spectrum sub-band index, with values in [0, 9], representing 10 frequency bands (31, 62, 125, 250, 500, 1000, 2000, 4000, 8000, 16000 Hz) - // The second parameter is the gain value of each frequency interval, with values in [-15, 15] dB (default is 0) + + // Set the center frequency of the local voice equalization band + // The first parameter is the spectrum sub-band index, the value range is [0,9], representing 10 frequency bands, and the corresponding center frequencies are [31,62,125,250,500,1000,2000,4000,8000,16000] Hz + // The second parameter is the gain value of each frequency interval, the value range is [-15,15], the unit is dB, the default value is 0 agoraKit.setLocalVoiceEqualizationOf(.band31, withGain: 0) agoraKit.setLocalVoiceEqualizationOf(.band62, withGain: 0) agoraKit.setLocalVoiceEqualizationOf(.band125, withGain: 0) @@ -113,19 +138,19 @@ Enhance the characteristics of male and female voices while preserving the inher agoraKit.setLocalVoiceEqualizationOf(.band4K, withGain: 0) agoraKit.setLocalVoiceEqualizationOf(.band8K, withGain: 0) agoraKit.setLocalVoiceEqualizationOf(.band16K, withGain: 0) - - // Original vocal intensity (dry signal), values in [-20, 10] dB + + // Original voice intensity, or dry signal, value range [-20,10], unit is dB agoraKit.setLocalVoiceReverbOf(.dryLevel, withValue: -1) - - // Early reflection signal strength (wet signal), values in [-20, 10] dB + + // Early reflection signal strength, or wet signal, value range [-20,10], unit is dB agoraKit.setLocalVoiceReverbOf(.wetLevel, withValue: -7) - - // Room size required for the reverberation effect, values in [0, 100]. Generally, the larger the room, the stronger the reverberation effect. + + // The size of the room for the required reverberation effect. Generally, the larger the room, the stronger the reverberation effect. Value range: [0,100] agoraKit.setLocalVoiceReverbOf(.roomSize, withValue: 57) - - // The initial delay length of wet signal, values in [0, 200] ms + + // Initial delay length of wet signal, value range: [0,200], unit: ms agoraKit.setLocalVoiceReverbOf(.wetDelay, withValue: 135) - - // Continuous intensity of the reverberation effect, values in [0, 100]. The larger the value, the stronger the reverberation effect + + // The strength of the reverberation effect, value range: [0,100], the larger the value, the stronger the reverberation effect agoraKit.setLocalVoiceReverbOf(.strength, withValue: 45) ``` \ No newline at end of file diff --git a/shared/video-sdk/develop/voice-effects/project-implementation/windows.mdx b/shared/video-sdk/develop/voice-effects/project-implementation/windows.mdx index 78c51f5ad..87fc61aa0 100644 --- a/shared/video-sdk/develop/voice-effects/project-implementation/windows.mdx +++ b/shared/video-sdk/develop/voice-effects/project-implementation/windows.mdx @@ -2,113 +2,132 @@ ### Set audio scenario and audio profile - For optimal audio quality, configure `RtcEngineConfig` to set an audio scenario and call `setAudioProfile` to specify an audio profile: +For optimal audio quality, take the following steps: + +- Call `setAudioScenario` to set the audio scenario to high-quality `AUDIO_SCENARIO_GAME_STREAMING`. +- Call `setAudioProfile` to set the audio encoding properties to high-quality encoding: + + - For mono transmission, set the profile to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY`. + - For stereo transmission, set the profile to `AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO`. ```cpp - // Set audioScenario in RtcEngineContext to AUDIO_SCENARIO_GAME_STREAMING - context.audioScenario = AUDIO_SCENARIO_GAME_STREAMING; - m_rtcEngine->initialize(context); - - // Call setAudioProfile to set the scene to AUDIO_PROFILE_MUSIC_HIGH_QUALITY or AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO + // Create RtcEngine object + m_rtcEngine = createAgoraRtcEngine(); + // Set the audio scenario + m_rtcEngine->setAudioScenario(AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO); + // Set audio encoding properties m_rtcEngine->setAudioProfile(AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO); ``` -### Enhance voice with voice effects +### Voice beautifiers -Enhance the characteristics of male and female voices while preserving the inherent identity of the original voice. The following code snippets demonstrate how to enable different voice beautifiers: +Call `setVoiceBeautifierPreset` to set music style, space shaping, electronic music and other effects. -* Enhance the character and charm of male voices with the 'Magnetic' vocal effect. Be cautious when applying this setting to female voices, as it may lead to distortion: +- Chat voice beautifier ```cpp - // Set the vocal effect to magnetic. This enumeration only applies to beautifying male voices - // When used to beautify female voices, it will cause distortion + // Set the vocal effect to magnetic (for male voices) m_rtcEngine->setVoiceBeautifierPreset(CHAT_BEAUTIFIER_MAGNETIC); - // Turn off the vocal effect + + // Turn off the effect m_rtcEngine->setVoiceBeautifierPreset(VOICE_BEAUTIFIER_OFF); ``` -* Optimize the singing voice for musical scenarios: +- Singing voice beautifier ```cpp - // Beautify a male singing voice. Do not use to beautify a female voice + // Example 1: Set male voice effect + // Set the singing voice preset to beautify the male voice and add a small room reverberation effect m_rtcEngine->setVoiceBeautifierPreset(SINGING_BEAUTIFIER); - // Turn off the vocal effect + // Turn off the effect m_rtcEngine->setVoiceBeautifierPreset(VOICE_BEAUTIFIER_OFF); - // Beautify a female singing voice + // Example 2: Set female voice effect + // Call the setVoiceBeautifierParameters method to beautify female voice and add hall reverberation effect m_rtcEngine->setVoiceBeautifierParameters(SINGING_BEAUTIFIER, 2, 3); - // Turn off the vocal effect + // Turn off the effect m_rtcEngine->setVoiceBeautifierPreset(VOICE_BEAUTIFIER_OFF); ``` -* Transform the vocal richness with the 'Vibrant' timbre transformation effect: +* Tone change ```cpp - // Set the timbre transformation effect - // The default vocal effect is thick + // Set the timbre to thick m_rtcEngine->setVoiceBeautifierPreset(TIMBRE_TRANSFORMATION_VIGOROUS); - - // Turn off the vocal effect + // Turn off the effect m_rtcEngine->setVoiceBeautifierPreset(VOICE_BEAUTIFIER_OFF); ``` -* Enrich audio with the 'Hulk' effect: - ```cpp - // The default vocal effect is Hulk - m_rtcEngine->setAudioEffectPreset(VOICE_CHANGER_EFFECT_HULK); - - // Turn off the vocal effect - m_rtcEngine->setAudioEffectPreset(AUDIO_EFFECT_OFF); - ``` -* Enhance vocal characteristics with a 'Pop' style: +### Sound effects + +Call `setAudioEffectPreset` to set music style, space shaping, electronic music and other effects. + +* Music Style ```cpp - // The default vocal effect is pop + // Set the music style to pop m_rtcEngine->setAudioEffectPreset(STYLE_TRANSFORMATION_POPULAR); - - // Turn off the vocal effect + // Turn off the effect m_rtcEngine->setAudioEffectPreset(AUDIO_EFFECT_OFF); ``` -* Simulate karaoke room acoustics with the 'KTV' effect: +* Space shaping ```cpp - // The default vocal effect is the effect in KTV + // Set the space shaping effect to the effect in KTV m_rtcEngine->setAudioEffectPreset(ROOM_ACOUSTICS_KTV); - - // Turn off the vocal effect + // Turn off the effect m_rtcEngine->setAudioEffectPreset(AUDIO_EFFECT_OFF); ``` -* Apply electronic sound correction to a natural minor key with a pitch of C: +* Electronic sound effects ```cpp - // Set the electronic sound effect to the natural minor key with a pitch of C + // Example 1: Use the preset pitch adjustment method to achieve the electronic music sound effect + // The preset is based on the natural major key with the tonic pitch of C, and corrects the actual pitch of the audio m_rtcEngine->setAudioEffectPreset(PITCH_CORRECTION); - - // Turn off the vocal effect + // Turn off the effect m_rtcEngine->setAudioEffectPreset(AUDIO_EFFECT_OFF); + // Example 2: Adjust the basic mode and tonic pitch to achieve the electronic music sound effect + // Call setAudioEffectParameters to adjust the basic mode of the tone to the natural minor key and the tonic pitch to D + m_rtcEngine->setAudioEffectParameters(PITCH_CORRECTION, 2, 6); + // Turn off the effect + m_rtcEngine->setAudioEffectPreset(AUDIO_EFFECT_OFF); ``` -* Default voice change effect for a more neutral voice: +### Voice change effects + +To implement basic voice-changing effects, call the `setAudioEffectPreset` method. For advanced voice-changing effects, use the `setVoiceConversionPreset` method. + +* Basic voice changer ```cpp - // The default voice change effect is a more neutral voice + // Set the voice changer to a more neutral sound m_rtcEngine->setVoiceConversionPreset(VOICE_CHANGER_NEUTRAL); - - // Turn off the vocal effect + // Turn off the effect m_rtcEngine->setVoiceConversionPreset(VOICE_CONVERSION_OFF); ``` -* Fine-tune vocal output parameters, including pitch, equalization, and reverberation effects. Transform a human voice into the distinctive sound of your choice by adjusting parameter values manually: +* Advanced voice changer + ```cpp + // Set the vocal effect to 'Hulk' + m_rtcEngine->setAudioEffectPreset(VOICE_CHANGER_EFFECT_HULK); + // Turn off the effect + m_rtcEngine->setAudioEffectPreset(AUDIO_EFFECT_OFF); + ``` + +### Custom audio effects + +Call `setLocalVoicePitch`, `setLocalVoiceEqualization`, and `setLocalVoiceReverb` to fine-tune vocal output parameters, including pitch, equalization, and reverberation effects. The following example shows you how to transform a human voice into the voice of the Hulk by manually setting parameter values: + ```cpp m_rtcEngine->setLocalVoicePitch(0.5); - // Set the center frequency of the local vocal equalization band - // The first parameter is the spectrum sub-band index, with values in [0, 9], representing 10 frequency bands (31, 62, 125, 250, 500, 1000, 2000, 4000, 8000, 16000 Hz) - // The second parameter is the gain value of each frequency interval, with values in [-15, 15] dB (default is 0) + // Set the center frequency of the local voice equalization band + // The first parameter is the spectrum sub-band index, the value range is [0,9], representing 10 frequency bands, and the corresponding center frequencies are [31,62,125,250,500,1000,2000,4000,8000,16000] Hz + // The second parameter is the gain value of each frequency interval, the value range is [-15,15], the unit is dB, the default value is 0 m_rtcEngine->setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_31, -15); m_rtcEngine->setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_62, 3); m_rtcEngine->setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_125, -9); @@ -119,20 +138,20 @@ Enhance the characteristics of male and female voices while preserving the inher m_rtcEngine->setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_4K, -2); m_rtcEngine->setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_8K, -1); m_rtcEngine->setLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_16K, 1); - - // Original vocal intensity (dry signal), values in [-20, 10] dB - m_rtcEngine->setLocalVoiceReverb(AUDIO_REVERB_DRY_LEVEL, 10); - - // Early reflection signal strength (wet signal), values in [-20, 10] dB + + // Original voice intensity, or dry signal, value range [-20,10], unit is dB m_rtcEngine->setLocalVoiceReverb(AUDIO_REVERB_DRY_LEVEL, 10); - - // Room size required for the reverberation effect, values in [0, 100] + + // Early reflection signal intensity, or wet signal, value range [-20,10], unit is dB + m_rtcEngine->setLocalVoiceReverb(AUDIO_REVERB_WET_LEVEL, 7); + + // The room size for the required reverberation effect. Generally, the larger the room, the stronger the reverberation effect. Value range: [0,100] m_rtcEngine->setLocalVoiceReverb(AUDIO_REVERB_ROOM_SIZE, 6); - - // Initial delay length of the wet signal, values in [0, 200] ms + + // Initial delay length of wet signal, value range: [0,200], unit: ms m_rtcEngine->setLocalVoiceReverb(AUDIO_REVERB_WET_DELAY, 124); - - // Continuous intensity of the reverberation effect, values in [0, 100] + + // The strength of the reverberation effect, value range: [0,100], the larger the value, the stronger the reverberation effect m_rtcEngine->setLocalVoiceReverb(AUDIO_REVERB_STRENGTH, 78); ``` diff --git a/shared/video-sdk/develop/voice-effects/reference/android.mdx b/shared/video-sdk/develop/voice-effects/reference/android.mdx index 8c22c0064..9d10263a5 100644 --- a/shared/video-sdk/develop/voice-effects/reference/android.mdx +++ b/shared/video-sdk/develop/voice-effects/reference/android.mdx @@ -1,21 +1,25 @@ +### Development considerations + +- Only one vocal effect can be set at a time. If multiple effects are set, the last one will overwrite the previous ones. +- The enumerations in `setVoiceBeautifierPreset`, `setAudioEffectPreset`, `setVoiceConversionPreset`, and other preset methods are optimized for different genders and should be used appropriately. Using these presets on vocals of the opposite gender may cause distortion. For more details, see [API reference](#api-reference). + ### Sample project provides an open source [Voice effects project](https://github.com/AgoraIO/API-Examples/blob/main/Android/APIExample-Audio/app/src/main/java/io/agora/api/example/examples/advanced/VoiceEffects.java) on GitHub for your reference. Download or view the source code for a more detailed example. - ### API reference +#### Audio scenario and audio profile + * setAudioProfile * setAudioScenario #### Preset voice effects -The enumerations in `setVoiceBeautifierPreset`, `setAudioEffectPreset`, `setVoiceConversionPreset`, and other preset methods are optimized for different genders and should be used appropriately. Using these presets on vocals of the opposite gender may cause distortion. Refer to the API reference for details. - * setAudioEffectPreset * setAudioEffectParameters diff --git a/shared/video-sdk/develop/voice-effects/reference/ios.mdx b/shared/video-sdk/develop/voice-effects/reference/ios.mdx index 7f12a40db..05467b7ea 100644 --- a/shared/video-sdk/develop/voice-effects/reference/ios.mdx +++ b/shared/video-sdk/develop/voice-effects/reference/ios.mdx @@ -1,12 +1,19 @@ +### Development considerations + +- Only one vocal effect can be set at a time. If multiple effects are set, the last one will overwrite the previous ones. +- The enumerations in `setVoiceBeautifierPreset`, `setAudioEffectPreset`, `setVoiceConversionPreset`, and other preset methods are optimized for different genders and should be used appropriately. Using these presets on vocals of the opposite gender may cause distortion. For more details, see [API reference](#api-reference). + ### Sample project provides an open source [VoiceChanger](https://github.com/AgoraIO/API-Examples/tree/main/iOS/APIExample/APIExample/Examples/Advanced/VoiceChanger) project on GitHub for your reference. Download or view the source code for a more detailed example. ### API reference +#### Audio scenario and audio profile + - setAudioProfile - setAudioScenario diff --git a/shared/video-sdk/develop/voice-effects/reference/macos.mdx b/shared/video-sdk/develop/voice-effects/reference/macos.mdx index 26ba03d8f..4e6e936e4 100644 --- a/shared/video-sdk/develop/voice-effects/reference/macos.mdx +++ b/shared/video-sdk/develop/voice-effects/reference/macos.mdx @@ -1,11 +1,18 @@ +### Development considerations + +- Only one vocal effect can be set at a time. If multiple effects are set, the last one will overwrite the previous ones. +- The enumerations in `setVoiceBeautifierPreset`, `setAudioEffectPreset`, `setVoiceConversionPreset`, and other preset methods are optimized for different genders and should be used appropriately. Using these presets on vocals of the opposite gender may cause distortion. For more details, see [API reference](#api-reference). + ### Sample project provides an open source [VoiceChanger](https://github.com/AgoraIO/API-Examples/tree/main/macOS/APIExample/Examples/Advanced/VoiceChanger) project on GitHub for your reference. Download or view the source code for a more detailed example. ### API reference +#### Audio scenario and audio profile + - setAudioProfile - setAudioScenario diff --git a/shared/video-sdk/develop/voice-effects/reference/windows.mdx b/shared/video-sdk/develop/voice-effects/reference/windows.mdx index 76864b174..d3a42553d 100644 --- a/shared/video-sdk/develop/voice-effects/reference/windows.mdx +++ b/shared/video-sdk/develop/voice-effects/reference/windows.mdx @@ -1,18 +1,24 @@ +### Development considerations + +- Only one vocal effect can be set at a time. If multiple effects are set, the last one will overwrite the previous ones. +- The enumerations in `setVoiceBeautifierPreset`, `setAudioEffectPreset`, `setVoiceConversionPreset`, and other voice methods are optimized for different genders and should be used appropriately. Using these presets on vocals of the opposite gender may cause distortion. Refer to the API reference for details. + ### Sample project provides an open source [BeautyAudio project](https://github.com/AgoraIO/API-Examples/tree/main/windows/APIExample/APIExample/Advanced/BeautyAudio) on GitHub for your reference. Download or view the source code for a more detailed example. ### API reference -* setAudioProfile +#### Audio scenario and audio profile -#### Preset voice effects +* setAudioProfile -The enumerations in `setVoiceBeautifierPreset`, `setAudioEffectPreset`, `setVoiceConversionPreset`, and other voice methods are optimized for different genders and should be used appropriately. Using these presets on vocals of the opposite gender may cause distortion. Refer to the API reference for details. +* setAudioScenario +#### Preset voice effects * setAudioEffectPreset