Voicemod for Agora
====================================================
**Voicemod's audio filter extension for Agora Marketplace apps**

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Getting Started
====================================================

Please have a look at answers to `Frequently Asked Questions <FAQ.html>`_, and read the `End User License Agreement <EULA.html>`_ 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:                                                                | set      | Set API key, API secret                |
|                        | { apiKey: "<project api key>", apiSecret: "<project 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          |
+------------------------+------------------------------------------------------------------------+----------+----------------------------------------+