2 * Copyright (C) 2016 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef ANDROID_AUDIO_EFFECT_CORE_H
19 #define ANDROID_AUDIO_EFFECT_CORE_H
22 #include "audio_effect-base.h"
26 /////////////////////////////////////////////////
28 /////////////////////////////////////////////////
31 //--- Effect descriptor structure effect_descriptor_t
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.
38 typedef audio_uuid_t effect_uuid_t;
40 // Maximum length of character strings in structures defines by this API.
41 #define EFFECT_STRING_LEN_MAX 64
43 // NULL UUID definition (matches SL_IID_NULL_)
44 #define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \
45 { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } }
46 static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER;
47 static const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_;
48 static const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210";
50 // The effect descriptor contains necessary information to facilitate the enumeration of the effect
51 // engines present in a library.
52 typedef 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;
63 /////////////////////////////////////////////////
64 // Effect control interface
65 /////////////////////////////////////////////////
68 //--- Standardized command codes for command() function
70 enum effect_command_e {
71 EFFECT_CMD_INIT, // initialize effect engine
72 EFFECT_CMD_SET_CONFIG, // configure effect engine (see effect_config_t)
73 EFFECT_CMD_RESET, // reset effect engine
74 EFFECT_CMD_ENABLE, // enable effect process
75 EFFECT_CMD_DISABLE, // disable effect process
76 EFFECT_CMD_SET_PARAM, // set parameter immediately (see effect_param_t)
77 EFFECT_CMD_SET_PARAM_DEFERRED, // set parameter deferred
78 EFFECT_CMD_SET_PARAM_COMMIT, // commit previous set parameter deferred
79 EFFECT_CMD_GET_PARAM, // get parameter
80 EFFECT_CMD_SET_DEVICE, // set audio device (see audio.h, audio_devices_t)
81 EFFECT_CMD_SET_VOLUME, // set volume
82 EFFECT_CMD_SET_AUDIO_MODE, // set the audio mode (normal, ring, ...)
83 EFFECT_CMD_SET_CONFIG_REVERSE, // configure effect engine reverse stream(see effect_config_t)
84 EFFECT_CMD_SET_INPUT_DEVICE, // set capture device (see audio.h, audio_devices_t)
85 EFFECT_CMD_GET_CONFIG, // read effect engine configuration
86 EFFECT_CMD_GET_CONFIG_REVERSE, // read configure effect engine reverse stream configuration
87 EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS,// get all supported configurations for a feature.
88 EFFECT_CMD_GET_FEATURE_CONFIG, // get current feature configuration
89 EFFECT_CMD_SET_FEATURE_CONFIG, // set current feature configuration
90 EFFECT_CMD_SET_AUDIO_SOURCE, // set the audio source (see audio.h, audio_source_t)
91 EFFECT_CMD_OFFLOAD, // set if effect thread is an offload one,
92 // send the ioHandle of the effect thread
93 EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code
96 //==================================================================================================
97 // command: EFFECT_CMD_INIT
98 //--------------------------------------------------------------------------------------------------
100 // Initialize effect engine: All configurations return to default
101 //--------------------------------------------------------------------------------------------------
105 //--------------------------------------------------------------------------------------------------
109 //==================================================================================================
110 // command: EFFECT_CMD_SET_CONFIG
111 //--------------------------------------------------------------------------------------------------
113 // Apply new audio parameters configurations for input and output buffers
114 //--------------------------------------------------------------------------------------------------
116 // size: sizeof(effect_config_t)
117 // data: effect_config_t
118 //--------------------------------------------------------------------------------------------------
122 //==================================================================================================
123 // command: EFFECT_CMD_RESET
124 //--------------------------------------------------------------------------------------------------
126 // Reset the effect engine. Keep configuration but resets state and buffer content
127 //--------------------------------------------------------------------------------------------------
131 //--------------------------------------------------------------------------------------------------
135 //==================================================================================================
136 // command: EFFECT_CMD_ENABLE
137 //--------------------------------------------------------------------------------------------------
139 // Enable the process. Called by the framework before the first call to process()
140 //--------------------------------------------------------------------------------------------------
144 //--------------------------------------------------------------------------------------------------
148 //==================================================================================================
149 // command: EFFECT_CMD_DISABLE
150 //--------------------------------------------------------------------------------------------------
152 // Disable the process. Called by the framework after the last call to process()
153 //--------------------------------------------------------------------------------------------------
157 //--------------------------------------------------------------------------------------------------
161 //==================================================================================================
162 // command: EFFECT_CMD_SET_PARAM
163 //--------------------------------------------------------------------------------------------------
165 // Set a parameter and apply it immediately
166 //--------------------------------------------------------------------------------------------------
168 // size: sizeof(effect_param_t) + size of param and value
169 // data: effect_param_t + param + value. See effect_param_t definition below for value offset
170 //--------------------------------------------------------------------------------------------------
174 //==================================================================================================
175 // command: EFFECT_CMD_SET_PARAM_DEFERRED
176 //--------------------------------------------------------------------------------------------------
178 // Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command
179 //--------------------------------------------------------------------------------------------------
181 // size: sizeof(effect_param_t) + size of param and value
182 // data: effect_param_t + param + value. See effect_param_t definition below for value offset
183 //--------------------------------------------------------------------------------------------------
187 //==================================================================================================
188 // command: EFFECT_CMD_SET_PARAM_COMMIT
189 //--------------------------------------------------------------------------------------------------
191 // Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands
192 //--------------------------------------------------------------------------------------------------
196 //--------------------------------------------------------------------------------------------------
200 //==================================================================================================
201 // command: EFFECT_CMD_GET_PARAM
202 //--------------------------------------------------------------------------------------------------
204 // Get a parameter value
205 //--------------------------------------------------------------------------------------------------
207 // size: sizeof(effect_param_t) + size of param
208 // data: effect_param_t + param
209 //--------------------------------------------------------------------------------------------------
211 // size: sizeof(effect_param_t) + size of param and value
212 // data: effect_param_t + param + value. See effect_param_t definition below for value offset
213 //==================================================================================================
214 // command: EFFECT_CMD_SET_DEVICE
215 //--------------------------------------------------------------------------------------------------
217 // Set the rendering device the audio output path is connected to. See audio.h, audio_devices_t
218 // for device values.
219 // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this
220 // command when the device changes
221 //--------------------------------------------------------------------------------------------------
223 // size: sizeof(uint32_t)
225 //--------------------------------------------------------------------------------------------------
229 //==================================================================================================
230 // command: EFFECT_CMD_SET_VOLUME
231 //--------------------------------------------------------------------------------------------------
233 // Set and get volume. Used by audio framework to delegate volume control to effect engine.
234 // The effect implementation must set EFFECT_FLAG_VOLUME_IND or EFFECT_FLAG_VOLUME_CTRL flag in
235 // its descriptor to receive this command before every call to process() function
236 // If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return
237 // the volume that should be applied before the effect is processed. The overall volume (the volume
238 // actually applied by the effect engine multiplied by the returned value) should match the value
239 // indicated in the command.
240 //--------------------------------------------------------------------------------------------------
242 // size: n * sizeof(uint32_t)
243 // data: volume for each channel defined in effect_config_t for output buffer expressed in
244 // 8.24 fixed point format
245 //--------------------------------------------------------------------------------------------------
247 // size: n * sizeof(uint32_t) / 0
248 // data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor:
249 // volume for each channel defined in effect_config_t for output buffer expressed in
250 // 8.24 fixed point format
251 // - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor:
253 // It is legal to receive a null pointer as pReplyData in which case the effect framework has
254 // delegated volume control to another effect
255 //==================================================================================================
256 // command: EFFECT_CMD_SET_AUDIO_MODE
257 //--------------------------------------------------------------------------------------------------
259 // Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its
260 // descriptor to receive this command when the audio mode changes.
261 //--------------------------------------------------------------------------------------------------
263 // size: sizeof(uint32_t)
264 // data: audio_mode_t
265 //--------------------------------------------------------------------------------------------------
269 //==================================================================================================
270 // command: EFFECT_CMD_SET_CONFIG_REVERSE
271 //--------------------------------------------------------------------------------------------------
273 // Apply new audio parameters configurations for input and output buffers of reverse stream.
274 // An example of reverse stream is the echo reference supplied to an Acoustic Echo Canceler.
275 //--------------------------------------------------------------------------------------------------
277 // size: sizeof(effect_config_t)
278 // data: effect_config_t
279 //--------------------------------------------------------------------------------------------------
283 //==================================================================================================
284 // command: EFFECT_CMD_SET_INPUT_DEVICE
285 //--------------------------------------------------------------------------------------------------
287 // Set the capture device the audio input path is connected to. See audio.h, audio_devices_t
288 // for device values.
289 // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this
290 // command when the device changes
291 //--------------------------------------------------------------------------------------------------
293 // size: sizeof(uint32_t)
295 //--------------------------------------------------------------------------------------------------
299 //==================================================================================================
300 // command: EFFECT_CMD_GET_CONFIG
301 //--------------------------------------------------------------------------------------------------
303 // Read audio parameters configurations for input and output buffers
304 //--------------------------------------------------------------------------------------------------
308 //--------------------------------------------------------------------------------------------------
310 // size: sizeof(effect_config_t)
311 // data: effect_config_t
312 //==================================================================================================
313 // command: EFFECT_CMD_GET_CONFIG_REVERSE
314 //--------------------------------------------------------------------------------------------------
316 // Read audio parameters configurations for input and output buffers of reverse stream
317 //--------------------------------------------------------------------------------------------------
321 //--------------------------------------------------------------------------------------------------
323 // size: sizeof(effect_config_t)
324 // data: effect_config_t
325 //==================================================================================================
326 // command: EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS
327 //--------------------------------------------------------------------------------------------------
329 // Queries for supported configurations for a particular feature (e.g. get the supported
330 // combinations of main and auxiliary channels for a noise suppressor).
331 // The command parameter is the feature identifier (See effect_feature_e for a list of defined
332 // features) followed by the maximum number of configuration descriptor to return.
333 // The reply is composed of:
334 // - status (uint32_t):
335 // - 0 if feature is supported
336 // - -ENOSYS if the feature is not supported,
337 // - -ENOMEM if the feature is supported but the total number of supported configurations
338 // exceeds the maximum number indicated by the caller.
339 // - total number of supported configurations (uint32_t)
340 // - an array of configuration descriptors.
341 // The actual number of descriptors returned must not exceed the maximum number indicated by
343 //--------------------------------------------------------------------------------------------------
345 // size: 2 x sizeof(uint32_t)
346 // data: effect_feature_e + maximum number of configurations to return
347 //--------------------------------------------------------------------------------------------------
349 // size: 2 x sizeof(uint32_t) + n x sizeof (<config descriptor>)
350 // data: status + total number of configurations supported + array of n config descriptors
351 //==================================================================================================
352 // command: EFFECT_CMD_GET_FEATURE_CONFIG
353 //--------------------------------------------------------------------------------------------------
355 // Retrieves current configuration for a given feature.
356 // The reply status is:
357 // - 0 if feature is supported
358 // - -ENOSYS if the feature is not supported,
359 //--------------------------------------------------------------------------------------------------
361 // size: sizeof(uint32_t)
362 // data: effect_feature_e
363 //--------------------------------------------------------------------------------------------------
365 // size: sizeof(uint32_t) + sizeof (<config descriptor>)
366 // data: status + config descriptor
367 //==================================================================================================
368 // command: EFFECT_CMD_SET_FEATURE_CONFIG
369 //--------------------------------------------------------------------------------------------------
371 // Sets current configuration for a given feature.
372 // The reply status is:
373 // - 0 if feature is supported
374 // - -ENOSYS if the feature is not supported,
375 // - -EINVAL if the configuration is invalid
376 //--------------------------------------------------------------------------------------------------
378 // size: sizeof(uint32_t) + sizeof (<config descriptor>)
379 // data: effect_feature_e + config descriptor
380 //--------------------------------------------------------------------------------------------------
382 // size: sizeof(uint32_t)
384 //==================================================================================================
385 // command: EFFECT_CMD_SET_AUDIO_SOURCE
386 //--------------------------------------------------------------------------------------------------
388 // Set the audio source the capture path is configured for (Camcorder, voice recognition...).
389 // See audio.h, audio_source_t for values.
390 //--------------------------------------------------------------------------------------------------
392 // size: sizeof(uint32_t)
394 //--------------------------------------------------------------------------------------------------
398 //==================================================================================================
399 // command: EFFECT_CMD_OFFLOAD
400 //--------------------------------------------------------------------------------------------------
402 // 1.indicate if the playback thread the effect is attached to is offloaded or not
403 // 2.update the io handle of the playback thread the effect is attached to
404 //--------------------------------------------------------------------------------------------------
406 // size: sizeof(effect_offload_param_t)
407 // data: effect_offload_param_t
408 //--------------------------------------------------------------------------------------------------
410 // size: sizeof(uint32_t)
412 //--------------------------------------------------------------------------------------------------
413 // command: EFFECT_CMD_FIRST_PROPRIETARY
414 //--------------------------------------------------------------------------------------------------
416 // All proprietary effect commands must use command codes above this value. The size and format of
417 // command and response fields is free in this case
418 //==================================================================================================
420 // Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t
421 // structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with
422 // regard to the channel mask definition in audio.h, audio_channel_mask_t e.g :
423 // Stereo: left, right
424 // 5 point 1: front left, front right, front center, low frequency, back left, back right
425 // The buffer size is expressed in frame count, a frame being composed of samples for all
426 // channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by
428 typedef struct audio_buffer_s {
429 size_t frameCount; // number of frames in buffer
431 void* raw; // raw pointer to start of buffer
432 int32_t* s32; // pointer to signed 32 bit data at start of buffer
433 int16_t* s16; // pointer to signed 16 bit data at start of buffer
434 uint8_t* u8; // pointer to unsigned 8 bit data at start of buffer
438 // The buffer_provider_s structure contains functions that can be used
439 // by the effect engine process() function to query and release input
440 // or output audio buffer.
441 // The getBuffer() function is called to retrieve a buffer where data
442 // should read from or written to by process() function.
443 // The releaseBuffer() function MUST be called when the buffer retrieved
444 // with getBuffer() is not needed anymore.
445 // The process function should use the buffer provider mechanism to retrieve
446 // input or output buffer if the inBuffer or outBuffer passed as argument is NULL
447 // and the buffer configuration (buffer_config_t) given by the EFFECT_CMD_SET_CONFIG
448 // command did not specify an audio buffer.
450 typedef int32_t (* buffer_function_t)(void *cookie, audio_buffer_t *buffer);
452 typedef struct buffer_provider_s {
453 buffer_function_t getBuffer; // retrieve next buffer
454 buffer_function_t releaseBuffer; // release used buffer
455 void *cookie; // for use by client of buffer provider functions
458 // The buffer_config_s structure specifies the input or output audio format
459 // to be used by the effect engine.
460 typedef struct buffer_config_s {
461 audio_buffer_t buffer; // buffer for use by process() function if not passed explicitly
462 uint32_t samplingRate; // sampling rate
463 uint32_t channels; // channel mask (see audio_channel_mask_t in audio.h)
464 buffer_provider_t bufferProvider; // buffer provider
465 uint8_t format; // Audio format (see audio_format_t in audio.h)
466 uint8_t accessMode; // read/write or accumulate in buffer (effect_buffer_access_e)
467 uint16_t mask; // indicates which of the above fields is valid
470 // EFFECT_FEATURE_AUX_CHANNELS feature configuration descriptor. Describe a combination
471 // of main and auxiliary channels supported
472 typedef struct channel_config_s {
473 audio_channel_mask_t main_channels; // channel mask for main channels
474 audio_channel_mask_t aux_channels; // channel mask for auxiliary channels
478 // effect_config_s structure is used to configure audio parameters and buffers for effect engine
480 typedef struct effect_config_s {
481 buffer_config_t inputCfg;
482 buffer_config_t outputCfg;
486 // effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM
487 // command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command.
488 // psize and vsize represent the actual size of parameter and value.
490 // NOTE: the start of value field inside the data field is always on a 32 bit boundary:
493 // | status | sizeof(int)
495 // | psize | sizeof(int)
497 // | vsize | sizeof(int)
500 // ~ parameter ~ > psize |
501 // | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int)
510 typedef struct effect_param_s {
511 int32_t status; // Transaction status (unused for command, used for reply)
512 uint32_t psize; // Parameter size
513 uint32_t vsize; // Value size
514 char data[]; // Start of Parameter + Value data
517 // Maximum effect_param_t size
518 #define EFFECT_PARAM_SIZE_MAX 65536
520 // structure used by EFFECT_CMD_OFFLOAD command
521 typedef struct effect_offload_param_s {
522 bool isOffload; // true if the playback thread the effect is attached to is offloaded
523 int ioHandle; // io handle of the playback thread the effect is attached to
524 } effect_offload_param_t;
529 #endif // ANDROID_AUDIO_EFFECT_CORE_H