Merge "Various fixes and improvements in audio effects implementation" into gingerbread

6 files changed, 411 insertions, 250 deletions

diff --git a/include/media/AudioCommon.h b/include/media/AudioCommon.h
deleted file mode 100644
index 245d760..0000000
--- a/include/media/AudioCommon.h
+++ /dev/null
@@ -1,80 +0,0 @@
-/*
- * Copyright (C) 2010 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-#ifndef ANDROID_AUDIOCOMMON_H_
-#define ANDROID_AUDIOCOMMON_H_
-
-#if __cplusplus
-extern "C" {
-#endif
-
-/////////////////////////////////////////////////
-//      Common definitions for PCM audio
-/////////////////////////////////////////////////
-
-
-// PCM Sample format
-enum audio_format_e {
-    PCM_FORMAT_S15 = 1,     // PCM signed 16 bits, must be 1 for backward compatibility
-    PCM_FORMAT_U8 = 2,      // PCM unsigned 8 bits, must be 2 for backward compatibility
-    PCM_FORMAT_S7_24        // signed 7.24 fixed point representation
-};
-
-// Channel mask definitions
-enum audio_channels_e {
-    CHANNEL_FRONT_LEFT = 0x4,                   // front left channel
-    CHANNEL_FRONT_RIGHT = 0x8,                  // front right channel
-    CHANNEL_FRONT_CENTER = 0x10,                // front center channel
-    CHANNEL_LOW_FREQUENCY = 0x20,               // low frequency channel
-    CHANNEL_BACK_LEFT = 0x40,                   // back left channel
-    CHANNEL_BACK_RIGHT = 0x80,                  // back right channel
-    CHANNEL_FRONT_LEFT_OF_CENTER = 0x100,       // front left of center channel
-    CHANNEL_FRONT_RIGHT_OF_CENTER = 0x200,      // front right of center channel
-    CHANNEL_BACK_CENTER = 0x400,                // back center channel
-    CHANNEL_MONO = CHANNEL_FRONT_LEFT,
-    CHANNEL_STEREO = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT),
-    CHANNEL_QUAD = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
-            CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT),
-    CHANNEL_SURROUND = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
-            CHANNEL_FRONT_CENTER | CHANNEL_BACK_CENTER),
-    CHANNEL_5POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
-            CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT),
-    CHANNEL_7POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
-            CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT |
-            CHANNEL_FRONT_LEFT_OF_CENTER | CHANNEL_FRONT_RIGHT_OF_CENTER),
-};
-
-// Render device definitions
-enum audio_device_e {
-    DEVICE_EARPIECE = 0x1,                      // earpiece
-    DEVICE_SPEAKER = 0x2,                       // speaker
-    DEVICE_WIRED_HEADSET = 0x4,                 // wired headset, with microphone
-    DEVICE_WIRED_HEADPHONE = 0x8,               // wired headphone, without microphone
-    DEVICE_BLUETOOTH_SCO = 0x10,                // generic bluetooth SCO
-    DEVICE_BLUETOOTH_SCO_HEADSET = 0x20,        // bluetooth SCO headset
-    DEVICE_BLUETOOTH_SCO_CARKIT = 0x40,         // bluetooth SCO car kit
-    DEVICE_BLUETOOTH_A2DP = 0x80,               // generic bluetooth A2DP
-    DEVICE_BLUETOOTH_A2DP_HEADPHONES = 0x100,   // bluetooth A2DP headphones
-    DEVICE_BLUETOOTH_A2DP_SPEAKER = 0x200,      // bluetooth A2DP speakers
-    DEVICE_AUX_DIGITAL = 0x400                  // digital output
-};
-
-#if __cplusplus
-}  // extern "C"
-#endif
-
-
-#endif /*ANDROID_AUDIOCOMMON_H_*/
diff --git a/include/media/AudioEffect.h b/include/media/AudioEffect.h
index 2bdba2d..66670f3 100644
--- a/include/media/AudioEffect.h
+++ b/include/media/AudioEffect.h
@@ -93,14 +93,14 @@ public:
 
     /*
      * Returns the number of effects available. This method together
-     * with EffectQueryNext() is used to enumerate all effects:
+     * with queryEffect() is used to enumerate all effects:
      * The enumeration sequence is:
-     *      QueryNumberEffects(&num_effects);
-     *      while (num_effects--)
-     *          QueryNextEffect();
+     *      queryNumberEffects(&num_effects);
+     *      for (i = 0; i < num_effects; i++)
+     *          queryEffect(i,...);
      *
      * Parameters:
-     *      pNumEffects:    address where the number of effects should be returned.
+     *      numEffects:    address where the number of effects should be returned.
      *
      * Returned status (from utils/Errors.h) can be:
      *      NO_ERROR   successful operation.
@@ -114,24 +114,24 @@ public:
     static status_t queryNumberEffects(uint32_t *numEffects);
 
     /*
-     * Returns number effect descriptor during effect
+     * Returns an effect descriptor during effect
      * enumeration.
      *
      * Parameters:
-     *      pDescriptor:    address where the effect descriptor should be returned.
+     *      index:      index of the queried effect.
+     *      descriptor: address where the effect descriptor should be returned.
      *
      * Returned status (from utils/Errors.h) can be:
      *      NO_ERROR        successful operation.
-     *      NAME_NOT_FOUND  no more effect available
      *      PERMISSION_DENIED could not get AudioFlinger interface
      *      NO_INIT         effect library failed to initialize
-     *      BAD_VALUE       invalid descriptor pointer
+     *      BAD_VALUE       invalid descriptor pointer or index
      *      INVALID_OPERATION  effect list has changed since last execution of queryNumberEffects()
      *
      * Returned value
      *   *descriptor:     updated with effect descriptor
      */
-    static status_t queryNextEffect(effect_descriptor_t *descriptor);
+    static status_t queryEffect(uint32_t index, effect_descriptor_t *descriptor);
 
 
     /*
diff --git a/include/media/AudioSystem.h b/include/media/AudioSystem.h
index f21e83d..194f23a 100644
--- a/include/media/AudioSystem.h
+++ b/include/media/AudioSystem.h
@@ -20,7 +20,6 @@
 #include <utils/RefBase.h>
 #include <utils/threads.h>
 #include <media/IAudioFlinger.h>
-#include <media/AudioCommon.h>
 
 namespace android {
 
@@ -51,8 +50,8 @@ public:
 
     // Audio sub formats (see AudioSystem::audio_format).
     enum pcm_sub_format {
-        PCM_SUB_16_BIT          = PCM_FORMAT_S15, // must be 1 for backward compatibility
-        PCM_SUB_8_BIT           = PCM_FORMAT_U8, // must be 2 for backward compatibility
+        PCM_SUB_16_BIT          = 0x1, // must be 1 for backward compatibility
+        PCM_SUB_8_BIT           = 0x2, // must be 2 for backward compatibility
     };
 
     // MP3 sub format field definition : can use 11 LSBs in the same way as MP3 frame header to specify
@@ -104,21 +103,26 @@ public:
     // Channel mask definitions must be kept in sync with JAVA values in /media/java/android/media/AudioFormat.java
     enum audio_channels {
         // output channels
-        CHANNEL_OUT_FRONT_LEFT = CHANNEL_FRONT_LEFT,
-        CHANNEL_OUT_FRONT_RIGHT = CHANNEL_FRONT_RIGHT,
-        CHANNEL_OUT_FRONT_CENTER = CHANNEL_FRONT_CENTER,
-        CHANNEL_OUT_LOW_FREQUENCY = CHANNEL_LOW_FREQUENCY,
-        CHANNEL_OUT_BACK_LEFT = CHANNEL_BACK_LEFT,
-        CHANNEL_OUT_BACK_RIGHT = CHANNEL_BACK_RIGHT,
-        CHANNEL_OUT_FRONT_LEFT_OF_CENTER = CHANNEL_FRONT_LEFT_OF_CENTER,
-        CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = CHANNEL_FRONT_RIGHT_OF_CENTER,
-        CHANNEL_OUT_BACK_CENTER = CHANNEL_BACK_CENTER,
-        CHANNEL_OUT_MONO = CHANNEL_MONO,
-        CHANNEL_OUT_STEREO = CHANNEL_STEREO,
-        CHANNEL_OUT_QUAD = CHANNEL_QUAD,
-        CHANNEL_OUT_SURROUND = CHANNEL_SURROUND,
-        CHANNEL_OUT_5POINT1 = CHANNEL_5POINT1,
-        CHANNEL_OUT_7POINT1 = CHANNEL_7POINT1,
+        CHANNEL_OUT_FRONT_LEFT = 0x4,
+        CHANNEL_OUT_FRONT_RIGHT = 0x8,
+        CHANNEL_OUT_FRONT_CENTER = 0x10,
+        CHANNEL_OUT_LOW_FREQUENCY = 0x20,
+        CHANNEL_OUT_BACK_LEFT = 0x40,
+        CHANNEL_OUT_BACK_RIGHT = 0x80,
+        CHANNEL_OUT_FRONT_LEFT_OF_CENTER = 0x100,
+        CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = 0x200,
+        CHANNEL_OUT_BACK_CENTER = 0x400,
+        CHANNEL_OUT_MONO = CHANNEL_OUT_FRONT_LEFT,
+        CHANNEL_OUT_STEREO = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT),
+        CHANNEL_OUT_QUAD = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
+                CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT),
+        CHANNEL_OUT_SURROUND = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
+                CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_BACK_CENTER),
+        CHANNEL_OUT_5POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
+                CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT),
+        CHANNEL_OUT_7POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
+                CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT |
+                CHANNEL_OUT_FRONT_LEFT_OF_CENTER | CHANNEL_OUT_FRONT_RIGHT_OF_CENTER),
         CHANNEL_OUT_ALL = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
                 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT |
                 CHANNEL_OUT_FRONT_LEFT_OF_CENTER | CHANNEL_OUT_FRONT_RIGHT_OF_CENTER | CHANNEL_OUT_BACK_CENTER),
@@ -238,17 +242,17 @@ public:
 
     enum audio_devices {
         // output devices
-        DEVICE_OUT_EARPIECE = DEVICE_EARPIECE,
-        DEVICE_OUT_SPEAKER = DEVICE_SPEAKER,
-        DEVICE_OUT_WIRED_HEADSET = DEVICE_WIRED_HEADSET,
-        DEVICE_OUT_WIRED_HEADPHONE = DEVICE_WIRED_HEADPHONE,
-        DEVICE_OUT_BLUETOOTH_SCO = DEVICE_BLUETOOTH_SCO,
-        DEVICE_OUT_BLUETOOTH_SCO_HEADSET = DEVICE_BLUETOOTH_SCO_HEADSET,
-        DEVICE_OUT_BLUETOOTH_SCO_CARKIT = DEVICE_BLUETOOTH_SCO_CARKIT,
-        DEVICE_OUT_BLUETOOTH_A2DP = DEVICE_BLUETOOTH_A2DP,
-        DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES = DEVICE_BLUETOOTH_A2DP_HEADPHONES,
-        DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER = DEVICE_BLUETOOTH_A2DP_SPEAKER,
-        DEVICE_OUT_AUX_DIGITAL = DEVICE_AUX_DIGITAL,
+        DEVICE_OUT_EARPIECE = 0x1,
+        DEVICE_OUT_SPEAKER = 0x2,
+        DEVICE_OUT_WIRED_HEADSET = 0x4,
+        DEVICE_OUT_WIRED_HEADPHONE = 0x8,
+        DEVICE_OUT_BLUETOOTH_SCO = 0x10,
+        DEVICE_OUT_BLUETOOTH_SCO_HEADSET = 0x20,
+        DEVICE_OUT_BLUETOOTH_SCO_CARKIT = 0x40,
+        DEVICE_OUT_BLUETOOTH_A2DP = 0x80,
+        DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES = 0x100,
+        DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER = 0x200,
+        DEVICE_OUT_AUX_DIGITAL = 0x400,
         DEVICE_OUT_DEFAULT = 0x8000,
         DEVICE_OUT_ALL = (DEVICE_OUT_EARPIECE | DEVICE_OUT_SPEAKER | DEVICE_OUT_WIRED_HEADSET |
                 DEVICE_OUT_WIRED_HEADPHONE | DEVICE_OUT_BLUETOOTH_SCO | DEVICE_OUT_BLUETOOTH_SCO_HEADSET |
diff --git a/include/media/EffectApi.h b/include/media/EffectApi.h
index 97874f7..b4d738c 100644
--- a/include/media/EffectApi.h
+++ b/include/media/EffectApi.h
@@ -20,7 +20,6 @@
 #include <errno.h>
 #include <stdint.h>
 #include <sys/types.h>
-#include <media/AudioCommon.h>
 
 #if __cplusplus
 extern "C" {
@@ -65,10 +64,11 @@ typedef struct effect_interface_s **effect_interface_t;
 //--- Effect descriptor structure effect_descriptor_t
 //
 
-// Unique effect ID (can be generated from the following site: http://www.itu.int/ITU-T/asn1/uuid.html)
+// Unique effect ID (can be generated from the following site:
+//  http://www.itu.int/ITU-T/asn1/uuid.html)
 // This format is used for both "type" and "uuid" fields of the effect descriptor structure.
-// - When used for effect type and the engine is implementing and effect corresponding to a standard OpenSL ES
-// interface, this ID must be the one defined in OpenSLES_IID.h for that interface.
+// - When used for effect type and the engine is implementing and effect corresponding to a standard
+// OpenSL ES interface, this ID must be the one defined in OpenSLES_IID.h for that interface.
 // - When used as uuid, it should be a unique UUID for this particular implementation.
 typedef struct effect_uuid_s {
     uint32_t timeLow;
@@ -79,23 +79,32 @@ typedef struct effect_uuid_s {
 } effect_uuid_t;
 
 // NULL UUID definition (matches SL_IID_NULL_)
-#define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } }
+#define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \
+                                  { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } }
 static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER;
 const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_;
 const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210";
 
-// the effect descriptor contains necessary information to facilitate the enumeration of the effect
+// The effect descriptor contains necessary information to facilitate the enumeration of the effect
 // engines present in a library.
 typedef struct effect_descriptor_s {
-    effect_uuid_t type;     // UUID corresponding to the OpenSL ES interface implemented by this effect
+    effect_uuid_t type;     // UUID of to the OpenSL ES interface implemented by this effect
     effect_uuid_t uuid;     // UUID for this particular implementation
-    uint16_t apiVersion;    // Version of the effect API implemented: must match current EFFECT_API_VERSION
+    uint16_t apiVersion;    // Version of the effect API implemented: matches EFFECT_API_VERSION
     uint32_t flags;         // effect engine capabilities/requirements flags (see below)
-    char    name[EFFECT_STRING_LEN_MAX] ;   // human readable effect name
-    char    implementor[EFFECT_STRING_LEN_MAX] ;    // human readable effect implementor name
+    uint16_t cpuLoad;       // CPU load indication (see below)
+    uint16_t memoryUsage;   // Data Memory usage (see below)
+    char    name[EFFECT_STRING_LEN_MAX];   // human readable effect name
+    char    implementor[EFFECT_STRING_LEN_MAX];    // human readable effect implementor name
 } effect_descriptor_t;
 
-// definitions for flags field of effect descriptor.
+// CPU load and memory usage indication: each effect implementation must provide an indication of
+// its CPU and memory usage for the audio effect framework to limit the number of effects
+// instantiated at a given time on a given platform.
+// The CPU load is expressed in 0.1 MIPS units as estimated on an ARM9E core (ARMv5TE) with 0 WS.
+// The memory usage is expressed in KB and includes only dynamically allocated memory
+
+// Definitions for flags field of effect descriptor.
 //  +---------------------------+-----------+-----------------------------------
 //  | description               | bits      | values
 //  +---------------------------+-----------+-----------------------------------
@@ -117,7 +126,7 @@ typedef struct effect_descriptor_s {
 //  |                           |           | 2 requires volume indication
 //  |                           |           | 3 reserved
 //  +---------------------------+-----------+-----------------------------------
-//  | Device management         | 7..8      | 0 none
+//  | Device indication         | 7..8      | 0 none
 //  |                           |           | 1 requires device updates
 //  |                           |           | 2..3 reserved
 //  +---------------------------+-----------+-----------------------------------
@@ -125,7 +134,8 @@ typedef struct effect_descriptor_s {
 //  |                           |           |   command must specify a buffer descriptor
 //  |                           |           | 1 provider: process() function uses the
 //  |                           |           |   bufferProvider indicated by the
-//  |                           |           |   EFFECT_CMD_CONFIGURE command to request input buffers.
+//  |                           |           |   EFFECT_CMD_CONFIGURE command to request input.
+//  |                           |           |   buffers.
 //  |                           |           | 2 both: both input modes are supported
 //  |                           |           | 3 reserved
 //  +---------------------------+-----------+-----------------------------------
@@ -133,18 +143,34 @@ typedef struct effect_descriptor_s {
 //  |                           |           |   command must specify a buffer descriptor
 //  |                           |           | 1 provider: process() function uses the
 //  |                           |           |   bufferProvider indicated by the
-//  |                           |           |   EFFECT_CMD_CONFIGURE command to request output buffers.
+//  |                           |           |   EFFECT_CMD_CONFIGURE command to request output
+//  |                           |           |   buffers.
 //  |                           |           | 2 both: both output modes are supported
 //  |                           |           | 3 reserved
 //  +---------------------------+-----------+-----------------------------------
+//  | Hardware acceleration     | 13..15    | 0 No hardware acceleration
+//  |                           |           | 1 non tunneled hw acceleration: the process() function
+//  |                           |           |   reads the samples, send them to HW accelerated
+//  |                           |           |   effect processor, reads back the processed samples
+//  |                           |           |   and returns them to the output buffer.
+//  |                           |           | 2 tunneled hw acceleration: the process() function is
+//  |                           |           |   transparent. The effect interface is only used to
+//  |                           |           |   control the effect engine. This mode is relevant for
+//  |                           |           |   global effects actually applied by the audio
+//  |                           |           |   hardware on the output stream.
+//  +---------------------------+-----------+-----------------------------------
+//  | Audio Mode indication     | 16..17    | 0 none
+//  |                           |           | 1 requires audio mode updates
+//  |                           |           | 2..3 reserved
+//  +---------------------------+-----------+-----------------------------------
 
-// insert mode
+// Insert mode
 #define EFFECT_FLAG_TYPE_MASK           0x00000003
 #define EFFECT_FLAG_TYPE_INSERT         0x00000000
 #define EFFECT_FLAG_TYPE_AUXILIARY      0x00000001
 #define EFFECT_FLAG_TYPE_REPLACE        0x00000002
 
-// insert preference
+// Insert preference
 #define EFFECT_FLAG_INSERT_MASK         0x0000001C
 #define EFFECT_FLAG_INSERT_ANY          0x00000000
 #define EFFECT_FLAG_INSERT_FIRST        0x00000004
@@ -152,30 +178,40 @@ typedef struct effect_descriptor_s {
 #define EFFECT_FLAG_INSERT_EXCLUSIVE    0x0000000C
 
 
-// volume control
+// Volume control
 #define EFFECT_FLAG_VOLUME_MASK         0x00000060
 #define EFFECT_FLAG_VOLUME_CTRL         0x00000020
 #define EFFECT_FLAG_VOLUME_IND          0x00000040
 #define EFFECT_FLAG_VOLUME_NONE         0x00000000
 
-// device control
+// Device indication
 #define EFFECT_FLAG_DEVICE_MASK         0x00000180
 #define EFFECT_FLAG_DEVICE_IND          0x00000080
 #define EFFECT_FLAG_DEVICE_NONE         0x00000000
 
-// sample input modes
+// Sample input modes
 #define EFFECT_FLAG_INPUT_MASK          0x00000600
 #define EFFECT_FLAG_INPUT_DIRECT        0x00000000
 #define EFFECT_FLAG_INPUT_PROVIDER      0x00000200
 #define EFFECT_FLAG_INPUT_BOTH          0x00000400
 
-// sample output modes
+// Sample output modes
 #define EFFECT_FLAG_OUTPUT_MASK          0x00001800
 #define EFFECT_FLAG_OUTPUT_DIRECT        0x00000000
 #define EFFECT_FLAG_OUTPUT_PROVIDER      0x00000800
 #define EFFECT_FLAG_OUTPUT_BOTH          0x00001000
 
-// forward definition of type audio_buffer_t
+// Hardware acceleration mode
+#define EFFECT_FLAG_HW_ACC_MASK          0x00006000
+#define EFFECT_FLAG_HW_ACC_SIMPLE        0x00002000
+#define EFFECT_FLAG_HW_ACC_TUNNEL        0x00004000
+
+// Audio mode indication
+#define EFFECT_FLAG_AUDIO_MODE_MASK      0x00018000
+#define EFFECT_FLAG_AUDIO_MODE_IND       0x00008000
+#define EFFECT_FLAG_AUDIO_MODE_NONE      0x00000000
+
+// Forward definition of type audio_buffer_t
 typedef struct audio_buffer_s audio_buffer_t;
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -206,7 +242,9 @@ typedef struct audio_buffer_s audio_buffer_t;
 //                          -EINVAL invalid interface handle or
 //                                  invalid input/output buffer description
 ////////////////////////////////////////////////////////////////////////////////
-typedef int32_t (*effect_process_t)(effect_interface_t self, audio_buffer_t *inBuffer, audio_buffer_t *outBuffer);
+typedef int32_t (*effect_process_t)(effect_interface_t self,
+                                    audio_buffer_t *inBuffer,
+                                    audio_buffer_t *outBuffer);
 
 ////////////////////////////////////////////////////////////////////////////////
 //
@@ -238,7 +276,12 @@ typedef int32_t (*effect_process_t)(effect_interface_t self, audio_buffer_t *inB
 //          *pReplyData updated with command response
 //
 ////////////////////////////////////////////////////////////////////////////////
-typedef int32_t (*effect_command_t)(effect_interface_t self, int32_t cmdCode, int32_t cmdSize, void *pCmdData, int32_t *replySize, void *pReplyData);
+typedef int32_t (*effect_command_t)(effect_interface_t self,
+                                    int32_t cmdCode,
+                                    int32_t cmdSize,
+                                    void *pCmdData,
+                                    int32_t *replySize,
+                                    void *pReplyData);
 
 
 // Effect control interface definition
@@ -248,75 +291,9 @@ struct effect_interface_s {
 };
 
 
-//--- Standardized command codes for command function
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | description                    | command code                  | command format                | reply format
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Initialize effect engine:      | EFFECT_CMD_INIT               | size: 0                       | size: sizeof(int)
-//  |  All configurations return to  |                               | data: N/A                     | data: status
-//  |  default                       |                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Apply new audio parameters     | EFFECT_CMD_CONFIGURE          | size: sizeof(effect_config_t) | size: sizeof(int)
-//  | configurations for input and   |                               | data: effect_config_t         | data: status
-//  | output buffers                 |                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Reset effect engine: keep      | EFFECT_CMD_RESET              | size: 0                       | size: 0
-//  | configuration but reset state  |                               | data: N/A                     | data: N/A
-//  | and buffer content.            |                               |                               |
-//  | Called by the framework before |                               |                               |
-//  | enabling the effect            |                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Enable the process             | EFFECT_CMD_ENABLE             | size: 0                       | size: sizeof(int)
-//  | Called by the framework before |                               | data: N/A                     | data: status
-//  | the first call to process()    |                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Disable the process            | EFFECT_CMD_DISABLE            | size: 0                       | size: sizeof(int)
-//  | Called by the framework after  |                               | data: N/A                     | data: status
-//  | the last call to process()     |                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Set a parameter and apply it   | EFFECT_CMD_SET_PARAM          | size: sizeof(effect_param_t)  | size: sizeof(int)
-//  | immediately                    |                               |       + size of param + value | data: status
-//  |                                |                               | data: effect_param_t          |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Set a parameter but apply it   | EFFECT_CMD_SET_PARAM_DEFERRED | size: sizeof(effect_param_t)  | size: 0
-//  | only when receiving command    |                               |       + size of param + value | data: N/A
-//  | EFFECT_CMD_SET_PARAM_COMMIT    |                               | data: effect_param_t          |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Apply all previously received  | EFFECT_CMD_SET_PARAM_COMMIT   | size: 0                       | size: sizeof(int)
-//  | EFFECT_CMD_SET_PARAM_DEFERRED  |                               | data: N/A                     | data: status
-//  | commands                       |                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Get a parameter value          | EFFECT_CMD_GET_PARAM          | size: sizeof(effect_param_t)  | size: sizeof(effect_param_t)
-//  |                                |                               |       + size of param         |       + size of param + value
-//  |                                |                               | data: effect_param_t          | data: effect_param_t
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Set the rendering device the   | EFFECT_CMD_SET_DEVICE         | size: sizeof(uint32_t)        | size: 0
-//  | audio output path is connected |                               | data: audio_device_e          | data: N/A
-//  | to. See audio_device_e in      |                               |                               |
-//  | AudioCommon.h for device values|                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | Set and get volume. Used by    | EFFECT_CMD_SET_VOLUME         | size: n * sizeof(uint32_t)    | size: n * sizeof(uint32_t)
-//  | audio framework to delegate    |                               | data: volume for each channel | data: volume for each channel
-//  | volume control to effect engine|                               | defined in effect_config_t in | defined in effect_config_t in
-//  | If volume control flag is set  |                               | 8.24 fixed point format       | 8.24 fixed point format
-//  | in the effect descriptor, the  |                               |                               | It is legal to receive a null
-//  | effect engine must return the  |                               |                               | pointer as pReplyData in which
-//  | volume that should be applied  |                               |                               | case the effect framework has
-//  | before the effect is processed |                               |                               | delegated volume control to
-//  | The overall volume (the volume |                               |                               | another effect.
-//  | actually applied by the effect |                               |                               |
-//  | multiplied by the returned     |                               |                               |
-//  | value) should match the        |                               |                               |
-//  | requested value                |                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-//  | All proprietary effect commands| EFFECT_CMD_FIRST_PROPRIETARY  |                               |
-//  | must use command codes above   |                               |                               |
-//  | this value. The size and format|                               |                               |
-//  | of command and response fields |                               |                               |
-//  | is free in this case.          |                               |                               |
-//  +--------------------------------+-------------------------------+-------------------------------+--------------------------
-
-
+//
+//--- Standardized command codes for command() function
+//
 enum effect_command_e {
    EFFECT_CMD_INIT,                 // initialize effect engine
    EFFECT_CMD_CONFIGURE,            // configure effect engine (see effect_config_t)
@@ -327,18 +304,202 @@ enum effect_command_e {
    EFFECT_CMD_SET_PARAM_DEFERRED,   // set parameter deferred
    EFFECT_CMD_SET_PARAM_COMMIT,     // commit previous set parameter deferred
    EFFECT_CMD_GET_PARAM,            // get parameter
-   EFFECT_CMD_SET_DEVICE,           // set audio device (see audio_device_e in AudioCommon.h)
+   EFFECT_CMD_SET_DEVICE,           // set audio device (see audio_device_e)
    EFFECT_CMD_SET_VOLUME,           // set volume
+   EFFECT_CMD_SET_AUDIO_MODE,       // set the audio mode (normal, ring, ...)
    EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code
 };
 
-// Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t structure
-// Multi-channel audio is always interleaved. The channel order is from LSB to MSB with regard to the
-// channel mask definition in audio_channels_e (AudioCommon.h) e.g :
+//==================================================================================================
+// command: EFFECT_CMD_INIT
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Initialize effect engine: All configurations return to default
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: 0
+//  data: N/A
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: sizeof(int)
+//  data: status
+//==================================================================================================
+// command: EFFECT_CMD_CONFIGURE
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Apply new audio parameters configurations for input and output buffers
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: sizeof(effect_config_t)
+//  data: effect_config_t
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: sizeof(int)
+//  data: status
+//==================================================================================================
+// command: EFFECT_CMD_RESET
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Reset the effect engine. Keep configuration but resets state and buffer content
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: 0
+//  data: N/A
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: 0
+//  data: N/A
+//==================================================================================================
+// command: EFFECT_CMD_ENABLE
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Enable the process. Called by the framework before the first call to process()
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: 0
+//  data: N/A
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: sizeof(int)
+//  data: status
+//==================================================================================================
+// command: EFFECT_CMD_DISABLE
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Disable the process. Called by the framework after the last call to process()
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: 0
+//  data: N/A
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: sizeof(int)
+//  data: status
+//==================================================================================================
+// command: EFFECT_CMD_SET_PARAM
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Set a parameter and apply it immediately
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: sizeof(effect_param_t) + size of param and value
+//  data: effect_param_t + param + value. See effect_param_t definition below for value offset
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: sizeof(int)
+//  data: status
+//==================================================================================================
+// command: EFFECT_CMD_SET_PARAM_DEFERRED
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: sizeof(effect_param_t) + size of param and value
+//  data: effect_param_t + param + value. See effect_param_t definition below for value offset
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: 0
+//  data: N/A
+//==================================================================================================
+// command: EFFECT_CMD_SET_PARAM_COMMIT
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: 0
+//  data: N/A
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: sizeof(int)
+//  data: status
+//==================================================================================================
+// command: EFFECT_CMD_GET_PARAM
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Get a parameter value
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: sizeof(effect_param_t) + size of param
+//  data: effect_param_t + param
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: sizeof(effect_param_t) + size of param and value
+//  data: effect_param_t + param + value. See effect_param_t definition below for value offset
+//==================================================================================================
+// command: EFFECT_CMD_SET_DEVICE
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Set the rendering device the audio output path is connected to. See audio_device_e for device
+//  values.
+//  The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this
+//  command when the device changes
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: sizeof(uint32_t)
+//  data: audio_device_e
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: 0
+//  data: N/A
+//==================================================================================================
+// command: EFFECT_CMD_SET_VOLUME
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Set and get volume. Used by audio framework to delegate volume control to effect engine.
+//  The effect implementation must set EFFECT_FLAG_VOLUME_IND and/or EFFECT_FLAG_VOLUME_CTRL flag in
+//  its descriptor to receive this command before every call to process() function
+//  If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return
+//  the volume that should be applied before the effect is processed. The overall volume (the volume
+//  actually applied by the effect engine multiplied by the returned value) should match the value
+//  indicated in the command.
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: n * sizeof(uint32_t)
+//  data: volume for each channel defined in effect_config_t for output buffer expressed in
+//      8.24 fixed point format
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: n * sizeof(uint32_t) / 0
+//  data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor:
+//              volume for each channel defined in effect_config_t for output buffer expressed in
+//              8.24 fixed point format
+//        - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor:
+//              N/A
+//  It is legal to receive a null pointer as pReplyData in which case the effect framework has
+//  delegated volume control to another effect
+//==================================================================================================
+// command: EFFECT_CMD_SET_AUDIO_MODE
+//--------------------------------------------------------------------------------------------------
+// description:
+//  Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its
+//  descriptor to receive this command when the audio mode changes.
+//--------------------------------------------------------------------------------------------------
+// command format:
+//  size: sizeof(uint32_t)
+//  data: audio_mode_e
+//--------------------------------------------------------------------------------------------------
+// reply format:
+//  size: 0
+//  data: N/A
+//==================================================================================================
+// command: EFFECT_CMD_FIRST_PROPRIETARY
+//--------------------------------------------------------------------------------------------------
+// description:
+//  All proprietary effect commands must use command codes above this value. The size and format of
+//  command and response fields is free in this case
+//==================================================================================================
+
+
+// Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t
+// structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with
+// regard to the channel mask definition in audio_channels_e e.g :
 // Stereo: left, right
 // 5 point 1: front left, front right, front center, low frequency, back left, back right
 // The buffer size is expressed in frame count, a frame being composed of samples for all
-// channels at a given time
+// channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by
+// definition
 struct audio_buffer_s {
     size_t   frameCount;        // number of frames in buffer
     union {
@@ -349,7 +510,7 @@ struct audio_buffer_s {
     };
 };
 
-// the buffer_provider_s structure contains functions that can be used
+// The buffer_provider_s structure contains functions that can be used
 // by the effect engine process() function to query and release input
 // or output audio buffer.
 // The getBuffer() function is called to retrieve a buffer where data
@@ -369,6 +530,7 @@ typedef struct buffer_provider_s {
     void       *cookie;                // for use by client of buffer provider functions
 } buffer_provider_t;
 
+
 // The buffer_config_s structure specifies the input or output audio format
 // to be used by the effect engine. It is part of the effect_config_t
 // structure that defines both input and output buffer configurations and is
@@ -376,14 +538,69 @@ typedef struct buffer_provider_s {
 typedef struct buffer_config_s {
     audio_buffer_t  buffer;     // buffer for use by process() function if not passed explicitly
     uint32_t   samplingRate;    // sampling rate
-    uint32_t   channels;        // channel mask (see audio_channels_e in AudioCommon.h)
+    uint32_t   channels;        // channel mask (see audio_channels_e)
     buffer_provider_t bufferProvider;   // buffer provider
-    uint8_t    format;          // PCM format  (see audio_format_e in AudioCommon.h)
+    uint8_t    format;          // Audio format  (see audio_format_e)
     uint8_t    accessMode;      // read/write or accumulate in buffer (effect_buffer_access_e)
     uint16_t   mask;            // indicates which of the above fields is valid
 } buffer_config_t;
 
-// values for "accessMode" field of buffer_config_t:
+// Sample format
+enum audio_format_e {
+    SAMPLE_FORMAT_PCM_S15,   // PCM signed 16 bits
+    SAMPLE_FORMAT_PCM_U8,    // PCM unsigned 8 bits
+    SAMPLE_FORMAT_PCM_S7_24, // PCM signed 7.24 fixed point representation
+    SAMPLE_FORMAT_OTHER      // other format (e.g. compressed)
+};
+
+// Channel mask
+enum audio_channels_e {
+    CHANNEL_FRONT_LEFT = 0x1,                   // front left channel
+    CHANNEL_FRONT_RIGHT = 0x2,                  // front right channel
+    CHANNEL_FRONT_CENTER = 0x4,                // front center channel
+    CHANNEL_LOW_FREQUENCY = 0x8,               // low frequency channel
+    CHANNEL_BACK_LEFT = 0x10,                   // back left channel
+    CHANNEL_BACK_RIGHT = 0x20,                  // back right channel
+    CHANNEL_FRONT_LEFT_OF_CENTER = 0x40,       // front left of center channel
+    CHANNEL_FRONT_RIGHT_OF_CENTER = 0x80,      // front right of center channel
+    CHANNEL_BACK_CENTER = 0x100,                // back center channel
+    CHANNEL_MONO = CHANNEL_FRONT_LEFT,
+    CHANNEL_STEREO = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT),
+    CHANNEL_QUAD = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
+            CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT),
+    CHANNEL_SURROUND = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
+            CHANNEL_FRONT_CENTER | CHANNEL_BACK_CENTER),
+    CHANNEL_5POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
+            CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT),
+    CHANNEL_7POINT1 = (CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
+            CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT |
+            CHANNEL_FRONT_LEFT_OF_CENTER | CHANNEL_FRONT_RIGHT_OF_CENTER),
+};
+
+// Render device
+enum audio_device_e {
+    DEVICE_EARPIECE = 0x1,                      // earpiece
+    DEVICE_SPEAKER = 0x2,                       // speaker
+    DEVICE_WIRED_HEADSET = 0x4,                 // wired headset, with microphone
+    DEVICE_WIRED_HEADPHONE = 0x8,               // wired headphone, without microphone
+    DEVICE_BLUETOOTH_SCO = 0x10,                // generic bluetooth SCO
+    DEVICE_BLUETOOTH_SCO_HEADSET = 0x20,        // bluetooth SCO headset
+    DEVICE_BLUETOOTH_SCO_CARKIT = 0x40,         // bluetooth SCO car kit
+    DEVICE_BLUETOOTH_A2DP = 0x80,               // generic bluetooth A2DP
+    DEVICE_BLUETOOTH_A2DP_HEADPHONES = 0x100,   // bluetooth A2DP headphones
+    DEVICE_BLUETOOTH_A2DP_SPEAKER = 0x200,      // bluetooth A2DP speakers
+    DEVICE_AUX_DIGITAL = 0x400,                 // digital output
+    DEVICE_EXTERNAL_SPEAKER = 0x800             // external speaker (stereo and High quality)
+};
+
+// Audio mode
+enum audio_mode_e {
+    AUDIO_MODE_NORMAL,      // phone idle
+    AUDIO_MODE_RINGTONE,    // phone ringing
+    AUDIO_MODE_IN_CALL      // phone call connected
+};
+
+// Values for "accessMode" field of buffer_config_t:
 //   overwrite, read only, accumulate (read/modify/write)
 enum effect_buffer_access_e {
     EFFECT_BUFFER_ACCESS_WRITE,
@@ -392,7 +609,7 @@ enum effect_buffer_access_e {
 
 };
 
-// values for bit field "mask" in buffer_config_t. If a bit is set, the corresponding field
+// Values for bit field "mask" in buffer_config_t. If a bit is set, the corresponding field
 // in buffer_config_t must be taken into account when executing the EFFECT_CMD_CONFIGURE command
 #define EFFECT_CONFIG_BUFFER    0x0001  // buffer field must be taken into account
 #define EFFECT_CONFIG_SMP_RATE  0x0002  // samplingRate field must be taken into account
@@ -404,13 +621,15 @@ enum effect_buffer_access_e {
                            EFFECT_CONFIG_CHANNELS | EFFECT_CONFIG_FORMAT | \
                            EFFECT_CONFIG_ACC_MODE | EFFECT_CONFIG_PROVIDER)
 
-// effect_config_s structure describes the format of the pCmdData argument of EFFECT_CMD_CONFIGURE command
-// to configure audio parameters and buffers for effect engine input and output.
+
+// effect_config_s structure describes the format of the pCmdData argument of EFFECT_CMD_CONFIGURE
+// command to configure audio parameters and buffers for effect engine input and output.
 typedef struct effect_config_s {
     buffer_config_t   inputCfg;
     buffer_config_t   outputCfg;;
 } effect_config_t;
 
+
 // effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM
 // command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command.
 // psize and vsize represent the actual size of parameter and value.
@@ -452,7 +671,7 @@ typedef struct effect_param_s {
 // specified here as the effect framework will get the function address with dlsym():
 //
 // - effect_QueryNumberEffects_t EffectQueryNumberEffects;
-// - effect_QueryNextEffect_t EffectQueryNext;
+// - effect_QueryEffect_t EffectQueryEffect;
 // - effect_CreateEffect_t EffectCreate;
 // - effect_ReleaseEffect_t EffectRelease;
 
@@ -463,11 +682,8 @@ typedef struct effect_param_s {
 //
 //    Description:    Returns the number of different effects exposed by the
 //          library. Each effect must have a unique effect uuid (see
-//          effect_descriptor_t). This function together with EffectQueryNext()
+//          effect_descriptor_t). This function together with EffectQueryEffect()
 //          is used to enumerate all effects present in the library.
-//          Each time EffectQueryNumberEffects() is called, the library must
-//          reset the index of the effect descriptor returned by next call to
-//          EffectQueryNext() to restart enumeration from the beginning.
 //
 //    Input/Output:
 //          pNumEffects:    address where the number of effects should be returned.
@@ -483,28 +699,33 @@ typedef int32_t (*effect_QueryNumberEffects_t)(uint32_t *pNumEffects);
 
 ////////////////////////////////////////////////////////////////////////////////
 //
-//    Function:       EffectQueryNext
+//    Function:       EffectQueryEffect
 //
-//    Description:    Returns a descriptor of the next available effect.
+//    Description:    Returns the descriptor of the effect engine which index is
+//          given as first argument.
 //          See effect_descriptor_t for details on effect descriptors.
-//          This function together with EffectQueryNext() is used to enumerate all
+//          This function together with EffectQueryNumberEffects() is used to enumerate all
 //          effects present in the library. The enumeration sequence is:
 //              EffectQueryNumberEffects(&num_effects);
-//              while (num_effects--)
-//                  EffectQueryNext();
+//              for (i = 0; i < num_effects; i++)
+//                  EffectQueryEffect(i,...);
 //
 //    Input/Output:
+//          index:          index of the effect
 //          pDescriptor:    address where to return the effect descriptor.
 //
 //    Output:
 //        returned value:    0          successful operation.
 //                          -ENODEV     library failed to initialize
-//                          -EINVAL     invalid pDescriptor
+//                          -EINVAL     invalid pDescriptor or index
+//                          -ENOSYS     effect list has changed since last execution of
+//                                      EffectQueryNumberEffects()
 //                          -ENOENT     no more effect available
 //        *pDescriptor:     updated with the effect descriptor.
 //
 ////////////////////////////////////////////////////////////////////////////////
-typedef int32_t (*effect_QueryNextEffect_t)(effect_descriptor_t *pDescriptor);
+typedef int32_t (*effect_QueryEffect_t)(uint32_t index,
+                                        effect_descriptor_t *pDescriptor);
 
 ////////////////////////////////////////////////////////////////////////////////
 //
@@ -516,7 +737,13 @@ typedef int32_t (*effect_QueryNextEffect_t)(effect_descriptor_t *pDescriptor);
 //          a handle on the effect control interface.
 //
 //    Input:
-//          pEffectUuid:    pointer to the effect uuid.
+//          uuid:    pointer to the effect uuid.
+//          sessionId:  audio session to which this effect instance will be attached. All effects
+//              created with the same session ID are connected in series and process the same signal
+//              stream. Knowing that two effects are part of the same effect chain can help the
+//              library implement some kind of optimizations.
+//          ioId:   identifies the output or input stream this effect is directed to at audio HAL.
+//              For future use especially with tunneled HW accelerated effects
 //
 //    Input/Output:
 //          pInterface:    address where to return the effect interface.
@@ -529,7 +756,10 @@ typedef int32_t (*effect_QueryNextEffect_t)(effect_descriptor_t *pDescriptor);
 //        *pInterface:     updated with the effect interface handle.
 //
 ////////////////////////////////////////////////////////////////////////////////
-typedef int32_t (*effect_CreateEffect_t)(effect_uuid_t *uuid, effect_interface_t *pInterface);
+typedef int32_t (*effect_CreateEffect_t)(effect_uuid_t *uuid,
+                                         int32_t sessionId,
+                                         int32_t ioId,
+                                         effect_interface_t *pInterface);
 
 ////////////////////////////////////////////////////////////////////////////////
 //
diff --git a/include/media/EffectFactoryApi.h b/include/media/EffectsFactoryApi.h
index 6cc9932..0ed1a14 100644
--- a/include/media/EffectFactoryApi.h
+++ b/include/media/EffectsFactoryApi.h
@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-#ifndef ANDROID_EFFECTFACTORYAPI_H_
-#define ANDROID_EFFECTFACTORYAPI_H_
+#ifndef ANDROID_EFFECTSFACTORYAPI_H_
+#define ANDROID_EFFECTSFACTORYAPI_H_
 
 #include <errno.h>
 #include <stdint.h>
@@ -36,11 +36,11 @@ extern "C" {
 //
 //    Description:    Returns the number of different effects in all loaded libraries.
 //          Each effect must have a different effect uuid (see
-//          effect_descriptor_t). This function together with EffectQueryNext()
+//          effect_descriptor_t). This function together with EffectQueryEffect()
 //          is used to enumerate all effects present in all loaded libraries.
 //          Each time EffectQueryNumberEffects() is called, the factory must
 //          reset the index of the effect descriptor returned by next call to
-//          EffectQueryNext() to restart enumeration from the beginning.
+//          EffectQueryEffect() to restart enumeration from the beginning.
 //
 //    Input/Output:
 //          pNumEffects:    address where the number of effects should be returned.
@@ -56,28 +56,29 @@ int EffectQueryNumberEffects(uint32_t *pNumEffects);
 
 ////////////////////////////////////////////////////////////////////////////////
 //
-//    Function:       EffectQueryNext
+//    Function:       EffectQueryEffect
 //
 //    Description:    Returns a descriptor of the next available effect.
 //          See effect_descriptor_t for a details on effect descriptor.
-//          This function together with EffectQueryNext() is used to enumerate all
+//          This function together with EffectQueryNumberEffects() is used to enumerate all
 //          effects present in all loaded libraries. The enumeration sequence is:
 //              EffectQueryNumberEffects(&num_effects);
-//              while (num_effects--)
-//                  EffectQueryNext();
+//              for (i = 0; i < num_effects; i++)
+//                  EffectQueryEffect(i,...);
 //
 //    Input/Output:
 //          pDescriptor:    address where to return the effect descriptor.
 //
 //    Output:
 //        returned value:    0          successful operation.
+//                          -ENOENT     no more effect available
 //                          -ENODEV     factory failed to initialize
 //                          -EINVAL     invalid pDescriptor
-//                          -ENOENT     no more effect available
+//                          -ENOSYS     effect list has changed since last execution of EffectQueryNumberEffects()
 //        *pDescriptor:     updated with the effect descriptor.
 //
 ////////////////////////////////////////////////////////////////////////////////
-int EffectQueryNext(effect_descriptor_t *pDescriptor);
+int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor);
 
 ////////////////////////////////////////////////////////////////////////////////
 //
@@ -90,6 +91,12 @@ int EffectQueryNext(effect_descriptor_t *pDescriptor);
 //
 //    Input:
 //          pEffectUuid:    pointer to the effect uuid.
+//          sessionId:  audio session to which this effect instance will be attached. All effects created
+//              with the same session ID are connected in series and process the same signal stream.
+//              Knowing that two effects are part of the same effect chain can help the library implement
+//              some kind of optimizations.
+//          ioId:   identifies the output or input stream this effect is directed to at audio HAL. For future
+//              use especially with tunneled HW accelerated effects
 //
 //    Input/Output:
 //          pInterface:    address where to return the effect interface.
@@ -102,7 +109,7 @@ int EffectQueryNext(effect_descriptor_t *pDescriptor);
 //        *pInterface:     updated with the effect interface.
 //
 ////////////////////////////////////////////////////////////////////////////////
-int EffectCreate(effect_uuid_t *pEffectUuid, effect_interface_t *pInterface);
+int EffectCreate(effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, effect_interface_t *pInterface);
 
 ////////////////////////////////////////////////////////////////////////////////
 //
@@ -211,4 +218,4 @@ int EffectIsNullUuid(effect_uuid_t *pEffectUuid);
 #endif
 
 
-#endif /*ANDROID_EFFECTFACTORYAPI_H_*/
+#endif /*ANDROID_EFFECTSFACTORYAPI_H_*/
diff --git a/include/media/IAudioFlinger.h b/include/media/IAudioFlinger.h
index ccfa530..5814fd6 100644
--- a/include/media/IAudioFlinger.h
+++ b/include/media/IAudioFlinger.h
@@ -148,7 +148,7 @@ public:
 
     virtual status_t queryNumberEffects(uint32_t *numEffects) = 0;
 
-    virtual status_t queryNextEffect(effect_descriptor_t *pDescriptor) = 0;
+    virtual status_t queryEffect(uint32_t index, effect_descriptor_t *pDescriptor) = 0;
 
     virtual status_t getEffectDescriptor(effect_uuid_t *pEffectUUID, effect_descriptor_t *pDescriptor) = 0;