Voicemod for Agora

Voicemod’s audio filter extension for Agora Marketplace apps

Getting Started

Please have a look at answers to Frequently Asked Questions, and read the End User License Agreement before starting development.

Download and link to the extension

You can download the libraries and example code from the Agora dashboard.

For Android, place the aar file into the libs folder of your project and link to the file, e.g., in build.gradle file:

dependencies {
   implementation (name : 'voicemod-agora-extension', ext:'aar' )
   ...
}

For iOS (Swift and Objective-C), place the framework package into your Frameworks folder and add the package to your project.

Enable the extension

Please note: There is currently no callback that notifies the app when the extension has been enabled, and enabling the extension can take up to a few seconds.

Android:

public void initializeAgoraEngine() {
   RtcEngineConfig config = new RtcEngineConfig();
   ...
   config.addExtension("VoicemodExtension");
   ...
   ...
   mRtcEngine = RtcEngine.create(config);
   ...
   mRtcEngine.enableExtension("Voicemod", "VoicemodExtension", true);
}

iOS (Swift)

func initializeAgoraEngine() {
   ...
   ...
   self.agoraKit.enableExtension(withVendor: "Voicemod", extension: "VoicemodExtension", enabled: true)
}

iOS (Objective-C):

- (void)initializeAgoraEngine {
   ...
   ...
   [self.agoraKit enableExtensionWithVendor:@"Voicemod" extension:@"VoicemodExtension" enabled:YES];
}

Disable the extension

Don’t forget to disable the extension when your app closes! You will eventually be charged for usage, so it’s important that your app disables the extension when exiting the app.

Android:

mRtcEngine.enableExtension("Voicemod", "VoicemodExtension", false);

iOS (Swift):

self.agoraKit.enableExtension(withVendor: "Voicemod", extension: "VoicemodExtension", enabled: false)

iOS (Objective-C):

[self.agoraKit enableExtensionWithVendor:@"Voicemod" extension:@"VoicemodExtension" enabled:NO];

Initialize Voicemod

To start the extension, set your project’s API key and API secret

Please note: A request to initialise the Voicemod extension will fail unless the extension has been successfully enabled.

Android:

public void initVoicemodSession(String userId) {
   String userData = "{" +
                     "\"apiKey\": \"<your API key>\"," +
                     "\"apiSecret\": \"<your API secret>\"" +
                     "}";
   mRtcEngine.setExtensionProperty("Voicemod", "VoicemodExtension", "vcmd_user_data", userData);
}

iOS (Swift):

func initVoicemodSession() {
   let userData = [
      "apiKey": <your API key>,
      "apiSecret": <your API secret>
   ]
   do {
      let jsonData = try JSONSerialization.data(withJSONObject: userData, options: [.prettyPrinted])
      let jsonString = String(data: jsonData, encoding: .utf8)!
      self.agoraKit.setExtensionPropertyWithVendor("Voicemod", extension: "VoicemodExtension", key: "vcmd_user_data", value: jsonString)
   } catch {
      print("JSON serialization failed")
   }
}

iOS (Objective-C):

- (void)initVoicemodSession:(NSString *)userId {
   NSDictionary * userData = @{
      @"apiKey" : @"<your API key>",
      @"apiSecret" : @"<your API secret>"
   };
   NSError *error;
   NSData *jsonData = [NSJSONSerialization dataWithJSONObject:userData options:NSJSONWritingPrettyPrinted error:&error];
   NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
   [self.agoraKit setExtensionPropertyWithVendor:@"Voicemod" extension:@"VoicemodExtension" key:@"vcmd_user_data" value:jsonString];
}

Using the extension

Enable a voice

Please note: A request to set the voice will fail unless the Voicemod extension has been successfully initialized.

Android:

String voice = "\"titan\"";
mRtcEngine.setExtensionProperty("Voicemod", "VoicemodExtension", "vcmd_voice", voice);

iOS (Swift):

let voiceJson = String(format: "\"%@\"", vcmdVoices[row])
self.agoraKit.setExtensionPropertyWithVendor("Voicemod", extension: "VoicemodExtension", key: "vcmd_voice", value: voiceJson)

iOS (Objective-C):

NSString* voice = [NSString stringWithFormat:@"\"%@\"" , @"titan"];
[self.agoraKit setExtensionPropertyWithVendor:@"Voicemod" extension:@"VoicemodExtension" key:@"vcmd_voice" value:voice];

Disable voices

Android:

String voice = "null";
mRtcEngine.setExtensionProperty("Voicemod", "VoicemodExtension", "vcmd_voice", voice);

iOS (Swift):

let voiceJson = "null"
self.agoraKit.setExtensionPropertyWithVendor("Voicemod", extension: "VoicemodExtension", key: "vcmd_voice", value: voiceJson)

iOS (Objective-C):

NSString* voice = @"null";
[self.agoraKit setExtensionPropertyWithVendor:@"Voicemod" extension:@"VoicemodExtension" key:@"vcmd_voice" value:voice];

Voicemod Properties

You can configure and control the Voicemod extension using the following properties.

Before you can use the extension, you must provide your API key and API secret by setting the vcmd_user_data property.

With the exception of vcmd_user_data and vcmd_version, the extension must be initialised for Voicemod property accessors to work.

Property Key	Property Value	Access	Description
vcmd_user_data	object: { apiKey: “<project api key>”, apiSecret: “<project api secret>” }	set	Set API key, API secret
vcmd_version	string: “MAJOR.MINOR.PATCH”	get	Get Voicemod plugin version
vcmd_voice	string	get, set	Set or get the current voice (“null” for no voice)
vcmd_presets	JSON array of strings containing the list of voices	get	Get list of existing voices
vcmd_background_sounds	boolean	get, set	get/toggle background sounds
vcmd_mute	boolean	get, set	get/toggle mute audio samples