1/* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware.audio.effect@7.0; 18 19import android.hardware.audio.common@7.0; 20import IEffectBufferProviderCallback; 21 22interface IEffect { 23 /** 24 * Initialize effect engine--all configurations return to default. 25 * 26 * @return retval operation completion status. 27 */ 28 @entry 29 init() generates (Result retval); 30 31 /** 32 * Apply new audio parameters configurations for input and output buffers. 33 * The provider callbacks may be empty, but in this case the buffer 34 * must be provided in the EffectConfig structure. 35 * 36 * @param config configuration descriptor. 37 * @param inputBufferProvider optional buffer provider reference. 38 * @param outputBufferProvider optional buffer provider reference. 39 * @return retval operation completion status. 40 */ 41 setConfig(EffectConfig config, 42 IEffectBufferProviderCallback inputBufferProvider, 43 IEffectBufferProviderCallback outputBufferProvider) 44 generates (Result retval); 45 46 /** 47 * Reset the effect engine. Keep configuration but resets state and buffer 48 * content. 49 * 50 * @return retval operation completion status. 51 */ 52 reset() generates (Result retval); 53 54 /** 55 * Enable processing. 56 * 57 * @return retval operation completion status. 58 */ 59 enable() generates (Result retval); 60 61 /** 62 * Disable processing. 63 * 64 * @return retval operation completion status. 65 */ 66 disable() generates (Result retval); 67 68 /** 69 * Set the rendering device the audio output path is connected to. The 70 * effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its 71 * descriptor to receive this command when the device changes. 72 * 73 * Note: this method is only supported for effects inserted into 74 * the output chain. 75 * 76 * @param device output device specification. 77 * @return retval operation completion status. 78 */ 79 setDevice(DeviceAddress device) generates (Result retval); 80 81 /** 82 * Set and get volume. Used by audio framework to delegate volume control to 83 * effect engine. The effect implementation must set EFFECT_FLAG_VOLUME_CTRL 84 * flag in its descriptor to receive this command. The effect engine must 85 * return the volume that should be applied before the effect is 86 * processed. The overall volume (the volume actually applied by the effect 87 * engine multiplied by the returned value) should match the value indicated 88 * in the command. 89 * 90 * @param volumes vector containing volume for each channel defined in 91 * EffectConfig for output buffer expressed in 8.24 fixed 92 * point format. 93 * @return result updated volume values. 94 * @return retval operation completion status. 95 */ 96 setAndGetVolume(vec<uint32_t> volumes) 97 generates (Result retval, vec<uint32_t> result); 98 99 /** 100 * Notify the effect of the volume change. The effect implementation must 101 * set EFFECT_FLAG_VOLUME_IND flag in its descriptor to receive this 102 * command. 103 * 104 * @param volumes vector containing volume for each channel defined in 105 * EffectConfig for output buffer expressed in 8.24 fixed 106 * point format. 107 * @return retval operation completion status. 108 */ 109 volumeChangeNotification(vec<uint32_t> volumes) 110 generates (Result retval); 111 112 /** 113 * Set the audio mode. The effect implementation must set 114 * EFFECT_FLAG_AUDIO_MODE_IND flag in its descriptor to receive this command 115 * when the audio mode changes. 116 * 117 * @param mode desired audio mode. 118 * @return retval operation completion status. 119 */ 120 setAudioMode(AudioMode mode) generates (Result retval); 121 122 /** 123 * Apply new audio parameters configurations for input and output buffers of 124 * reverse stream. An example of reverse stream is the echo reference 125 * supplied to an Acoustic Echo Canceler. 126 * 127 * @param config configuration descriptor. 128 * @param inputBufferProvider optional buffer provider reference. 129 * @param outputBufferProvider optional buffer provider reference. 130 * @return retval operation completion status. 131 */ 132 setConfigReverse(EffectConfig config, 133 IEffectBufferProviderCallback inputBufferProvider, 134 IEffectBufferProviderCallback outputBufferProvider) 135 generates (Result retval); 136 137 /** 138 * Set the capture device the audio input path is connected to. The effect 139 * implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to 140 * receive this command when the device changes. 141 * 142 * Note: this method is only supported for effects inserted into 143 * the input chain. 144 * 145 * @param device input device specification. 146 * @return retval operation completion status. 147 */ 148 setInputDevice(DeviceAddress device) generates (Result retval); 149 150 /** 151 * Read audio parameters configurations for input and output buffers. 152 * 153 * @return retval operation completion status. 154 * @return config configuration descriptor. 155 */ 156 getConfig() generates (Result retval, EffectConfig config); 157 158 /** 159 * Read audio parameters configurations for input and output buffers of 160 * reverse stream. 161 * 162 * @return retval operation completion status. 163 * @return config configuration descriptor. 164 */ 165 getConfigReverse() generates (Result retval, EffectConfig config); 166 167 /** 168 * Queries for supported combinations of main and auxiliary channels 169 * (e.g. for a multi-microphone noise suppressor). 170 * 171 * @param maxConfigs maximum number of the combinations to return. 172 * @return retval absence of the feature support is indicated using 173 * NOT_SUPPORTED code. RESULT_TOO_BIG is returned if 174 * the number of supported combinations exceeds 'maxConfigs'. 175 * @return result list of configuration descriptors. 176 */ 177 getSupportedAuxChannelsConfigs(uint32_t maxConfigs) 178 generates (Result retval, vec<EffectAuxChannelsConfig> result); 179 180 /** 181 * Retrieves the current configuration of main and auxiliary channels. 182 * 183 * @return retval absence of the feature support is indicated using 184 * NOT_SUPPORTED code. 185 * @return result configuration descriptor. 186 */ 187 getAuxChannelsConfig() 188 generates (Result retval, EffectAuxChannelsConfig result); 189 190 /** 191 * Sets the current configuration of main and auxiliary channels. 192 * 193 * @return retval operation completion status; absence of the feature 194 * support is indicated using NOT_SUPPORTED code. 195 */ 196 setAuxChannelsConfig(EffectAuxChannelsConfig config) 197 generates (Result retval); 198 199 /** 200 * Set the audio source the capture path is configured for (Camcorder, voice 201 * recognition...). 202 * 203 * Note: this method is only supported for effects inserted into 204 * the input chain. 205 * 206 * @param source source descriptor. 207 * @return retval operation completion status. 208 */ 209 setAudioSource(AudioSource source) generates (Result retval); 210 211 /** 212 * This command indicates if the playback thread the effect is attached to 213 * is offloaded or not, and updates the I/O handle of the playback thread 214 * the effect is attached to. 215 * 216 * @param param effect offload descriptor. 217 * @return retval operation completion status. 218 */ 219 offload(EffectOffloadParameter param) generates (Result retval); 220 221 /** 222 * Returns the effect descriptor. 223 * 224 * @return retval operation completion status. 225 * @return descriptor effect descriptor. 226 */ 227 getDescriptor() generates (Result retval, EffectDescriptor descriptor); 228 229 /** 230 * Set up required transports for passing audio buffers to the effect. 231 * 232 * The transport consists of shared memory and a message queue for reporting 233 * effect processing operation status. The shared memory is set up 234 * separately using 'setProcessBuffers' method. 235 * 236 * Processing is requested by setting 'REQUEST_PROCESS' or 237 * 'REQUEST_PROCESS_REVERSE' EventFlags associated with the status message 238 * queue. The result of processing may be one of the following: 239 * OK if there were no errors during processing; 240 * INVALID_ARGUMENTS if audio buffers are invalid; 241 * INVALID_STATE if the engine has finished the disable phase; 242 * NOT_INITIALIZED if the audio buffers were not set; 243 * NOT_SUPPORTED if the requested processing type is not supported by 244 * the effect. 245 * 246 * @return retval OK if both message queues were created successfully. 247 * INVALID_STATE if the method was already called. 248 * INVALID_ARGUMENTS if there was a problem setting up 249 * the queue. 250 * @return statusMQ a message queue used for passing status from the effect. 251 */ 252 prepareForProcessing() generates (Result retval, fmq_sync<Result> statusMQ); 253 254 /** 255 * Set up input and output buffers for processing audio data. The effect 256 * may modify both the input and the output buffer during the operation. 257 * Buffers may be set multiple times during effect lifetime. 258 * 259 * The input and the output buffer may be reused between different effects, 260 * and the input buffer may be used as an output buffer. Buffers are 261 * distinguished using 'AudioBuffer.id' field. 262 * 263 * @param inBuffer input audio buffer. 264 * @param outBuffer output audio buffer. 265 * @return retval OK if both buffers were mapped successfully. 266 * INVALID_ARGUMENTS if there was a problem with mapping 267 * any of the buffers. 268 */ 269 setProcessBuffers(AudioBuffer inBuffer, AudioBuffer outBuffer) 270 generates (Result retval); 271 272 /** 273 * Execute a vendor specific command on the effect. The command code 274 * and data, as well as result data are not interpreted by Android 275 * Framework and are passed as-is between the application and the effect. 276 * 277 * The effect must use standard POSIX.1-2001 error codes for the operation 278 * completion status. 279 * 280 * Use this method only if the effect is provided by a third party, and 281 * there is no interface defined for it. This method only works for effects 282 * implemented in software. 283 * 284 * @param commandId the ID of the command. 285 * @param data command data. 286 * @param resultMaxSize maximum size in bytes of the result; can be 0. 287 * @return status command completion status. 288 * @return result result data. 289 */ 290 command(uint32_t commandId, vec<uint8_t> data, uint32_t resultMaxSize) 291 generates (int32_t status, vec<uint8_t> result); 292 293 /** 294 * Set a vendor-specific parameter and apply it immediately. The parameter 295 * code and data are not interpreted by Android Framework and are passed 296 * as-is between the application and the effect. 297 * 298 * The effect must use INVALID_ARGUMENTS return code if the parameter ID is 299 * unknown or if provided parameter data is invalid. If the effect does not 300 * support setting vendor-specific parameters, it must return NOT_SUPPORTED. 301 * 302 * Use this method only if the effect is provided by a third party, and 303 * there is no interface defined for it. This method only works for effects 304 * implemented in software. 305 * 306 * @param parameter identifying data of the parameter. 307 * @param value the value of the parameter. 308 * @return retval operation completion status. 309 */ 310 setParameter(vec<uint8_t> parameter, vec<uint8_t> value) 311 generates (Result retval); 312 313 /** 314 * Get a vendor-specific parameter value. The parameter code and returned 315 * data are not interpreted by Android Framework and are passed as-is 316 * between the application and the effect. 317 * 318 * The effect must use INVALID_ARGUMENTS return code if the parameter ID is 319 * unknown. If the effect does not support setting vendor-specific 320 * parameters, it must return NOT_SUPPORTED. 321 * 322 * Use this method only if the effect is provided by a third party, and 323 * there is no interface defined for it. This method only works for effects 324 * implemented in software. 325 * 326 * @param parameter identifying data of the parameter. 327 * @param valueMaxSize maximum size in bytes of the value. 328 * @return retval operation completion status. 329 * @return result the value of the parameter. 330 */ 331 getParameter(vec<uint8_t> parameter, uint32_t valueMaxSize) 332 generates (Result retval, vec<uint8_t> value); 333 334 /** 335 * Get supported configs for a vendor-specific feature. The configs returned 336 * are not interpreted by Android Framework and are passed as-is between the 337 * application and the effect. 338 * 339 * The effect must use INVALID_ARGUMENTS return code if the feature ID is 340 * unknown. If the effect does not support getting vendor-specific feature 341 * configs, it must return NOT_SUPPORTED. If the feature is supported but 342 * the total number of supported configurations exceeds the maximum number 343 * indicated by the caller, the method must return RESULT_TOO_BIG. 344 * 345 * Use this method only if the effect is provided by a third party, and 346 * there is no interface defined for it. This method only works for effects 347 * implemented in software. 348 * 349 * @param featureId feature identifier. 350 * @param maxConfigs maximum number of configs to return. 351 * @param configSize size of each config in bytes. 352 * @return retval operation completion status. 353 * @return configsCount number of configs returned. 354 * @return configsData data for all the configs returned. 355 */ 356 getSupportedConfigsForFeature( 357 uint32_t featureId, 358 uint32_t maxConfigs, 359 uint32_t configSize) generates ( 360 Result retval, 361 uint32_t configsCount, 362 vec<uint8_t> configsData); 363 364 /** 365 * Get the current config for a vendor-specific feature. The config returned 366 * is not interpreted by Android Framework and is passed as-is between the 367 * application and the effect. 368 * 369 * The effect must use INVALID_ARGUMENTS return code if the feature ID is 370 * unknown. If the effect does not support getting vendor-specific 371 * feature configs, it must return NOT_SUPPORTED. 372 * 373 * Use this method only if the effect is provided by a third party, and 374 * there is no interface defined for it. This method only works for effects 375 * implemented in software. 376 * 377 * @param featureId feature identifier. 378 * @param configSize size of the config in bytes. 379 * @return retval operation completion status. 380 * @return configData config data. 381 */ 382 getCurrentConfigForFeature(uint32_t featureId, uint32_t configSize) 383 generates (Result retval, vec<uint8_t> configData); 384 385 /** 386 * Set the current config for a vendor-specific feature. The config data 387 * is not interpreted by Android Framework and is passed as-is between the 388 * application and the effect. 389 * 390 * The effect must use INVALID_ARGUMENTS return code if the feature ID is 391 * unknown. If the effect does not support getting vendor-specific 392 * feature configs, it must return NOT_SUPPORTED. 393 * 394 * Use this method only if the effect is provided by a third party, and 395 * there is no interface defined for it. This method only works for effects 396 * implemented in software. 397 * 398 * @param featureId feature identifier. 399 * @param configData config data. 400 * @return retval operation completion status. 401 */ 402 setCurrentConfigForFeature(uint32_t featureId, vec<uint8_t> configData) 403 generates (Result retval); 404 405 /** 406 * Called by the framework to deinitialize the effect and free up 407 * all currently allocated resources. It is recommended to close 408 * the effect on the client side as soon as it is becomes unused. 409 * 410 * The client must ensure that this function is not called while 411 * audio data is being transferred through the effect's message queues. 412 * 413 * @return retval OK in case the success. 414 * INVALID_STATE if the effect was already closed. 415 */ 416 close() generates (Result retval); 417}; 418