1/* 2 * Copyright (C) 2016 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 17 18#ifndef ANDROID_AUDIO_EFFECT_CORE_H 19#define ANDROID_AUDIO_EFFECT_CORE_H 20 21#include "audio.h" 22#include "audio_effect-base.h" 23 24__BEGIN_DECLS 25 26///////////////////////////////////////////////// 27// Common Definitions 28///////////////////////////////////////////////// 29 30// 31//--- Effect descriptor structure effect_descriptor_t 32// 33 34// This format is used for both "type" and "uuid" fields of the effect descriptor structure. 35// - When used for effect type and the engine is implementing and effect corresponding to a standard 36// OpenSL ES interface, this ID must be the one defined in OpenSLES_IID.h for that interface. 37// - When used as uuid, it should be a unique UUID for this particular implementation. 38typedef audio_uuid_t effect_uuid_t; 39 40// Maximum length of character strings in structures defines by this API. 41#define EFFECT_STRING_LEN_MAX 64 42 43// NULL UUID definition (matches SL_IID_NULL_) 44#define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \ 45 { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } } 46static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER; 47static const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_; 48static const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210"; 49 50// The effect descriptor contains necessary information to facilitate the enumeration of the effect 51// engines present in a library. 52typedef struct effect_descriptor_s { 53 effect_uuid_t type; // UUID of to the OpenSL ES interface implemented by this effect 54 effect_uuid_t uuid; // UUID for this particular implementation 55 uint32_t apiVersion; // Version of the effect control API implemented 56 uint32_t flags; // effect engine capabilities/requirements flags (see below) 57 uint16_t cpuLoad; // CPU load indication (see below) 58 uint16_t memoryUsage; // Data Memory usage (see below) 59 char name[EFFECT_STRING_LEN_MAX]; // human readable effect name 60 char implementor[EFFECT_STRING_LEN_MAX]; // human readable effect implementor name 61} effect_descriptor_t; 62 63#define EFFECT_CONFIG_ALL (EFFECT_CONFIG_BUFFER | \ 64 EFFECT_CONFIG_SMP_RATE | \ 65 EFFECT_CONFIG_CHANNELS | \ 66 EFFECT_CONFIG_FORMAT | \ 67 EFFECT_CONFIG_ACC_MODE) 68 69///////////////////////////////////////////////// 70// Effect control interface 71///////////////////////////////////////////////// 72 73// 74//--- Standardized command codes for command() function 75// 76enum effect_command_e { 77 EFFECT_CMD_INIT, // initialize effect engine 78 EFFECT_CMD_SET_CONFIG, // configure effect engine (see effect_config_t) 79 EFFECT_CMD_RESET, // reset effect engine 80 EFFECT_CMD_ENABLE, // enable effect process 81 EFFECT_CMD_DISABLE, // disable effect process 82 EFFECT_CMD_SET_PARAM, // set parameter immediately (see effect_param_t) 83 EFFECT_CMD_SET_PARAM_DEFERRED, // set parameter deferred 84 EFFECT_CMD_SET_PARAM_COMMIT, // commit previous set parameter deferred 85 EFFECT_CMD_GET_PARAM, // get parameter 86 EFFECT_CMD_SET_DEVICE, // set audio device (see audio.h, audio_devices_t) 87 EFFECT_CMD_SET_VOLUME, // set volume 88 EFFECT_CMD_SET_AUDIO_MODE, // set the audio mode (normal, ring, ...) 89 EFFECT_CMD_SET_CONFIG_REVERSE, // configure effect engine reverse stream(see effect_config_t) 90 EFFECT_CMD_SET_INPUT_DEVICE, // set capture device (see audio.h, audio_devices_t) 91 EFFECT_CMD_GET_CONFIG, // read effect engine configuration 92 EFFECT_CMD_GET_CONFIG_REVERSE, // read configure effect engine reverse stream configuration 93 EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS,// get all supported configurations for a feature. 94 EFFECT_CMD_GET_FEATURE_CONFIG, // get current feature configuration 95 EFFECT_CMD_SET_FEATURE_CONFIG, // set current feature configuration 96 EFFECT_CMD_SET_AUDIO_SOURCE, // set the audio source (see audio.h, audio_source_t) 97 EFFECT_CMD_OFFLOAD, // set if effect thread is an offload one, 98 // send the ioHandle of the effect thread 99 EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code 100}; 101 102//================================================================================================== 103// command: EFFECT_CMD_INIT 104//-------------------------------------------------------------------------------------------------- 105// description: 106// Initialize effect engine: All configurations return to default 107//-------------------------------------------------------------------------------------------------- 108// command format: 109// size: 0 110// data: N/A 111//-------------------------------------------------------------------------------------------------- 112// reply format: 113// size: sizeof(int) 114// data: status 115//================================================================================================== 116// command: EFFECT_CMD_SET_CONFIG 117//-------------------------------------------------------------------------------------------------- 118// description: 119// Apply new audio parameters configurations for input and output buffers 120//-------------------------------------------------------------------------------------------------- 121// command format: 122// size: sizeof(effect_config_t) 123// data: effect_config_t 124//-------------------------------------------------------------------------------------------------- 125// reply format: 126// size: sizeof(int) 127// data: status 128//================================================================================================== 129// command: EFFECT_CMD_RESET 130//-------------------------------------------------------------------------------------------------- 131// description: 132// Reset the effect engine. Keep configuration but resets state and buffer content 133//-------------------------------------------------------------------------------------------------- 134// command format: 135// size: 0 136// data: N/A 137//-------------------------------------------------------------------------------------------------- 138// reply format: 139// size: 0 140// data: N/A 141//================================================================================================== 142// command: EFFECT_CMD_ENABLE 143//-------------------------------------------------------------------------------------------------- 144// description: 145// Enable the process. Called by the framework before the first call to process() 146//-------------------------------------------------------------------------------------------------- 147// command format: 148// size: 0 149// data: N/A 150//-------------------------------------------------------------------------------------------------- 151// reply format: 152// size: sizeof(int) 153// data: status 154//================================================================================================== 155// command: EFFECT_CMD_DISABLE 156//-------------------------------------------------------------------------------------------------- 157// description: 158// Disable the process. Called by the framework after the last call to process() 159//-------------------------------------------------------------------------------------------------- 160// command format: 161// size: 0 162// data: N/A 163//-------------------------------------------------------------------------------------------------- 164// reply format: 165// size: sizeof(int) 166// data: status 167//================================================================================================== 168// command: EFFECT_CMD_SET_PARAM 169//-------------------------------------------------------------------------------------------------- 170// description: 171// Set a parameter and apply it immediately 172//-------------------------------------------------------------------------------------------------- 173// command format: 174// size: sizeof(effect_param_t) + size of param and value 175// data: effect_param_t + param + value. See effect_param_t definition below for value offset 176//-------------------------------------------------------------------------------------------------- 177// reply format: 178// size: sizeof(int) 179// data: status 180//================================================================================================== 181// command: EFFECT_CMD_SET_PARAM_DEFERRED 182//-------------------------------------------------------------------------------------------------- 183// description: 184// Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command 185//-------------------------------------------------------------------------------------------------- 186// command format: 187// size: sizeof(effect_param_t) + size of param and value 188// data: effect_param_t + param + value. See effect_param_t definition below for value offset 189//-------------------------------------------------------------------------------------------------- 190// reply format: 191// size: 0 192// data: N/A 193//================================================================================================== 194// command: EFFECT_CMD_SET_PARAM_COMMIT 195//-------------------------------------------------------------------------------------------------- 196// description: 197// Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands 198//-------------------------------------------------------------------------------------------------- 199// command format: 200// size: 0 201// data: N/A 202//-------------------------------------------------------------------------------------------------- 203// reply format: 204// size: sizeof(int) 205// data: status 206//================================================================================================== 207// command: EFFECT_CMD_GET_PARAM 208//-------------------------------------------------------------------------------------------------- 209// description: 210// Get a parameter value 211//-------------------------------------------------------------------------------------------------- 212// command format: 213// size: sizeof(effect_param_t) + size of param 214// data: effect_param_t + param 215//-------------------------------------------------------------------------------------------------- 216// reply format: 217// size: sizeof(effect_param_t) + size of param and value 218// data: effect_param_t + param + value. See effect_param_t definition below for value offset 219//================================================================================================== 220// command: EFFECT_CMD_SET_DEVICE 221//-------------------------------------------------------------------------------------------------- 222// description: 223// Set the rendering device the audio output path is connected to. See audio.h, audio_devices_t 224// for device values. 225// The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this 226// command when the device changes 227//-------------------------------------------------------------------------------------------------- 228// command format: 229// size: sizeof(uint32_t) 230// data: uint32_t 231//-------------------------------------------------------------------------------------------------- 232// reply format: 233// size: 0 234// data: N/A 235//================================================================================================== 236// command: EFFECT_CMD_SET_VOLUME 237//-------------------------------------------------------------------------------------------------- 238// description: 239// Set and get volume. Used by audio framework to delegate volume control to effect engine. 240// The effect implementation must set EFFECT_FLAG_VOLUME_IND or EFFECT_FLAG_VOLUME_CTRL flag in 241// its descriptor to receive this command before every call to process() function 242// If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return 243// the volume that should be applied before the effect is processed. The overall volume (the volume 244// actually applied by the effect engine multiplied by the returned value) should match the value 245// indicated in the command. 246//-------------------------------------------------------------------------------------------------- 247// command format: 248// size: n * sizeof(uint32_t) 249// data: volume for each channel defined in effect_config_t for output buffer expressed in 250// 8.24 fixed point format 251//-------------------------------------------------------------------------------------------------- 252// reply format: 253// size: n * sizeof(uint32_t) / 0 254// data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor: 255// volume for each channel defined in effect_config_t for output buffer expressed in 256// 8.24 fixed point format 257// - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor: 258// N/A 259// It is legal to receive a null pointer as pReplyData in which case the effect framework has 260// delegated volume control to another effect 261//================================================================================================== 262// command: EFFECT_CMD_SET_AUDIO_MODE 263//-------------------------------------------------------------------------------------------------- 264// description: 265// Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its 266// descriptor to receive this command when the audio mode changes. 267//-------------------------------------------------------------------------------------------------- 268// command format: 269// size: sizeof(uint32_t) 270// data: audio_mode_t 271//-------------------------------------------------------------------------------------------------- 272// reply format: 273// size: 0 274// data: N/A 275//================================================================================================== 276// command: EFFECT_CMD_SET_CONFIG_REVERSE 277//-------------------------------------------------------------------------------------------------- 278// description: 279// Apply new audio parameters configurations for input and output buffers of reverse stream. 280// An example of reverse stream is the echo reference supplied to an Acoustic Echo Canceler. 281//-------------------------------------------------------------------------------------------------- 282// command format: 283// size: sizeof(effect_config_t) 284// data: effect_config_t 285//-------------------------------------------------------------------------------------------------- 286// reply format: 287// size: sizeof(int) 288// data: status 289//================================================================================================== 290// command: EFFECT_CMD_SET_INPUT_DEVICE 291//-------------------------------------------------------------------------------------------------- 292// description: 293// Set the capture device the audio input path is connected to. See audio.h, audio_devices_t 294// for device values. 295// The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this 296// command when the device changes 297//-------------------------------------------------------------------------------------------------- 298// command format: 299// size: sizeof(uint32_t) 300// data: uint32_t 301//-------------------------------------------------------------------------------------------------- 302// reply format: 303// size: 0 304// data: N/A 305//================================================================================================== 306// command: EFFECT_CMD_GET_CONFIG 307//-------------------------------------------------------------------------------------------------- 308// description: 309// Read audio parameters configurations for input and output buffers 310//-------------------------------------------------------------------------------------------------- 311// command format: 312// size: 0 313// data: N/A 314//-------------------------------------------------------------------------------------------------- 315// reply format: 316// size: sizeof(effect_config_t) 317// data: effect_config_t 318//================================================================================================== 319// command: EFFECT_CMD_GET_CONFIG_REVERSE 320//-------------------------------------------------------------------------------------------------- 321// description: 322// Read audio parameters configurations for input and output buffers of reverse stream 323//-------------------------------------------------------------------------------------------------- 324// command format: 325// size: 0 326// data: N/A 327//-------------------------------------------------------------------------------------------------- 328// reply format: 329// size: sizeof(effect_config_t) 330// data: effect_config_t 331//================================================================================================== 332// command: EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS 333//-------------------------------------------------------------------------------------------------- 334// description: 335// Queries for supported configurations for a particular feature (e.g. get the supported 336// combinations of main and auxiliary channels for a noise suppressor). 337// The command parameter is the feature identifier (See effect_feature_e for a list of defined 338// features) followed by the maximum number of configuration descriptor to return. 339// The reply is composed of: 340// - status (uint32_t): 341// - 0 if feature is supported 342// - -ENOSYS if the feature is not supported, 343// - -ENOMEM if the feature is supported but the total number of supported configurations 344// exceeds the maximum number indicated by the caller. 345// - total number of supported configurations (uint32_t) 346// - an array of configuration descriptors. 347// The actual number of descriptors returned must not exceed the maximum number indicated by 348// the caller. 349//-------------------------------------------------------------------------------------------------- 350// command format: 351// size: 2 x sizeof(uint32_t) 352// data: effect_feature_e + maximum number of configurations to return 353//-------------------------------------------------------------------------------------------------- 354// reply format: 355// size: 2 x sizeof(uint32_t) + n x sizeof (<config descriptor>) 356// data: status + total number of configurations supported + array of n config descriptors 357//================================================================================================== 358// command: EFFECT_CMD_GET_FEATURE_CONFIG 359//-------------------------------------------------------------------------------------------------- 360// description: 361// Retrieves current configuration for a given feature. 362// The reply status is: 363// - 0 if feature is supported 364// - -ENOSYS if the feature is not supported, 365//-------------------------------------------------------------------------------------------------- 366// command format: 367// size: sizeof(uint32_t) 368// data: effect_feature_e 369//-------------------------------------------------------------------------------------------------- 370// reply format: 371// size: sizeof(uint32_t) + sizeof (<config descriptor>) 372// data: status + config descriptor 373//================================================================================================== 374// command: EFFECT_CMD_SET_FEATURE_CONFIG 375//-------------------------------------------------------------------------------------------------- 376// description: 377// Sets current configuration for a given feature. 378// The reply status is: 379// - 0 if feature is supported 380// - -ENOSYS if the feature is not supported, 381// - -EINVAL if the configuration is invalid 382//-------------------------------------------------------------------------------------------------- 383// command format: 384// size: sizeof(uint32_t) + sizeof (<config descriptor>) 385// data: effect_feature_e + config descriptor 386//-------------------------------------------------------------------------------------------------- 387// reply format: 388// size: sizeof(uint32_t) 389// data: status 390//================================================================================================== 391// command: EFFECT_CMD_SET_AUDIO_SOURCE 392//-------------------------------------------------------------------------------------------------- 393// description: 394// Set the audio source the capture path is configured for (Camcorder, voice recognition...). 395// See audio.h, audio_source_t for values. 396//-------------------------------------------------------------------------------------------------- 397// command format: 398// size: sizeof(uint32_t) 399// data: uint32_t 400//-------------------------------------------------------------------------------------------------- 401// reply format: 402// size: 0 403// data: N/A 404//================================================================================================== 405// command: EFFECT_CMD_OFFLOAD 406//-------------------------------------------------------------------------------------------------- 407// description: 408// 1.indicate if the playback thread the effect is attached to is offloaded or not 409// 2.update the io handle of the playback thread the effect is attached to 410//-------------------------------------------------------------------------------------------------- 411// command format: 412// size: sizeof(effect_offload_param_t) 413// data: effect_offload_param_t 414//-------------------------------------------------------------------------------------------------- 415// reply format: 416// size: sizeof(uint32_t) 417// data: uint32_t 418//-------------------------------------------------------------------------------------------------- 419// command: EFFECT_CMD_FIRST_PROPRIETARY 420//-------------------------------------------------------------------------------------------------- 421// description: 422// All proprietary effect commands must use command codes above this value. The size and format of 423// command and response fields is free in this case 424//================================================================================================== 425 426// Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t 427// structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with 428// regard to the channel mask definition in audio.h, audio_channel_mask_t e.g : 429// Stereo: left, right 430// 5 point 1: front left, front right, front center, low frequency, back left, back right 431// The buffer size is expressed in frame count, a frame being composed of samples for all 432// channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by 433// definition 434typedef struct audio_buffer_s { 435 size_t frameCount; // number of frames in buffer 436 union { 437 void* raw; // raw pointer to start of buffer 438 float* f32; // pointer to float 32 bit data at start of buffer 439 int32_t* s32; // pointer to signed 32 bit data at start of buffer 440 int16_t* s16; // pointer to signed 16 bit data at start of buffer 441 uint8_t* u8; // pointer to unsigned 8 bit data at start of buffer 442 }; 443} audio_buffer_t; 444 445// The buffer_provider_s structure contains functions that can be used 446// by the effect engine process() function to query and release input 447// or output audio buffer. 448// The getBuffer() function is called to retrieve a buffer where data 449// should read from or written to by process() function. 450// The releaseBuffer() function MUST be called when the buffer retrieved 451// with getBuffer() is not needed anymore. 452// The process function should use the buffer provider mechanism to retrieve 453// input or output buffer if the inBuffer or outBuffer passed as argument is NULL 454// and the buffer configuration (buffer_config_t) given by the EFFECT_CMD_SET_CONFIG 455// command did not specify an audio buffer. 456 457typedef int32_t (* buffer_function_t)(void *cookie, audio_buffer_t *buffer); 458 459typedef struct buffer_provider_s { 460 buffer_function_t getBuffer; // retrieve next buffer 461 buffer_function_t releaseBuffer; // release used buffer 462 void *cookie; // for use by client of buffer provider functions 463} buffer_provider_t; 464 465// The buffer_config_s structure specifies the input or output audio format 466// to be used by the effect engine. 467typedef struct buffer_config_s { 468 audio_buffer_t buffer; // buffer for use by process() function if not passed explicitly 469 uint32_t samplingRate; // sampling rate 470 uint32_t channels; // channel mask (see audio_channel_mask_t in audio.h) 471 buffer_provider_t bufferProvider; // buffer provider 472 uint8_t format; // Audio format (see audio_format_t in audio.h) 473 uint8_t accessMode; // read/write or accumulate in buffer (effect_buffer_access_e) 474 uint16_t mask; // indicates which of the above fields is valid 475} buffer_config_t; 476 477// EFFECT_FEATURE_AUX_CHANNELS feature configuration descriptor. Describe a combination 478// of main and auxiliary channels supported 479typedef struct channel_config_s { 480 audio_channel_mask_t main_channels; // channel mask for main channels 481 audio_channel_mask_t aux_channels; // channel mask for auxiliary channels 482} channel_config_t; 483 484 485// effect_config_s structure is used to configure audio parameters and buffers for effect engine 486// input and output. 487typedef struct effect_config_s { 488 buffer_config_t inputCfg; 489 buffer_config_t outputCfg; 490} effect_config_t; 491 492 493// effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM 494// command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command. 495// psize and vsize represent the actual size of parameter and value. 496// 497// NOTE: the start of value field inside the data field is always on a 32 bit boundary: 498// 499// +-----------+ 500// | status | sizeof(int) 501// +-----------+ 502// | psize | sizeof(int) 503// +-----------+ 504// | vsize | sizeof(int) 505// +-----------+ 506// | | | | 507// ~ parameter ~ > psize | 508// | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int) 509// +-----------+ | 510// | padding | | 511// +-----------+ 512// | | | 513// ~ value ~ > vsize 514// | | | 515// +-----------+ 516 517typedef struct effect_param_s { 518 int32_t status; // Transaction status (unused for command, used for reply) 519 uint32_t psize; // Parameter size 520 uint32_t vsize; // Value size 521 char data[]; // Start of Parameter + Value data 522} effect_param_t; 523 524// Maximum effect_param_t size 525#define EFFECT_PARAM_SIZE_MAX 65536 526 527// structure used by EFFECT_CMD_OFFLOAD command 528typedef struct effect_offload_param_s { 529 bool isOffload; // true if the playback thread the effect is attached to is offloaded 530 int ioHandle; // io handle of the playback thread the effect is attached to 531} effect_offload_param_t; 532 533 534__END_DECLS 535 536#endif // ANDROID_AUDIO_EFFECT_CORE_H 537