1 /* 2 * Copyright (C) 2009 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 #ifndef ANDROID_AUDIOEFFECT_H 18 #define ANDROID_AUDIOEFFECT_H 19 20 #include <stdint.h> 21 #include <sys/types.h> 22 23 #include <media/IAudioFlinger.h> 24 #include <media/IAudioPolicyService.h> 25 #include <media/IEffect.h> 26 #include <media/IEffectClient.h> 27 #include <media/AudioSystem.h> 28 #include <system/audio_effect.h> 29 30 #include <utils/RefBase.h> 31 #include <utils/Errors.h> 32 #include <binder/IInterface.h> 33 34 35 namespace android { 36 37 // ---------------------------------------------------------------------------- 38 39 struct effect_param_cblk_t; 40 41 // ---------------------------------------------------------------------------- 42 43 class AudioEffect : public RefBase 44 { 45 public: 46 47 /* 48 * Static methods for effects enumeration. 49 */ 50 51 /* 52 * Returns the number of effects available. This method together 53 * with queryEffect() is used to enumerate all effects: 54 * The enumeration sequence is: 55 * queryNumberEffects(&num_effects); 56 * for (i = 0; i < num_effects; i++) 57 * queryEffect(i,...); 58 * 59 * Parameters: 60 * numEffects: address where the number of effects should be returned. 61 * 62 * Returned status (from utils/Errors.h) can be: 63 * NO_ERROR successful operation. 64 * PERMISSION_DENIED could not get AudioFlinger interface 65 * NO_INIT effect library failed to initialize 66 * BAD_VALUE invalid numEffects pointer 67 * 68 * Returned value 69 * *numEffects: updated with number of effects available 70 */ 71 static status_t queryNumberEffects(uint32_t *numEffects); 72 73 /* 74 * Returns an effect descriptor during effect 75 * enumeration. 76 * 77 * Parameters: 78 * index: index of the queried effect. 79 * descriptor: address where the effect descriptor should be returned. 80 * 81 * Returned status (from utils/Errors.h) can be: 82 * NO_ERROR successful operation. 83 * PERMISSION_DENIED could not get AudioFlinger interface 84 * NO_INIT effect library failed to initialize 85 * BAD_VALUE invalid descriptor pointer or index 86 * INVALID_OPERATION effect list has changed since last execution of queryNumberEffects() 87 * 88 * Returned value 89 * *descriptor: updated with effect descriptor 90 */ 91 static status_t queryEffect(uint32_t index, effect_descriptor_t *descriptor); 92 93 /* 94 * Returns a descriptor for the specified effect uuid or type. 95 * 96 * Lookup an effect by uuid, or if that's unspecified (EFFECT_UUID_NULL), 97 * do so by type and preferred flags instead. 98 * 99 * Parameters: 100 * uuid: pointer to effect uuid. 101 * type: pointer to effect type uuid. 102 * preferredTypeFlags: if multiple effects of the given type exist, 103 * one with a matching type flag will be chosen over one without. 104 * Use EFFECT_FLAG_TYPE_MASK to indicate no preference. 105 * descriptor: address where the effect descriptor should be returned. 106 * 107 * Returned status (from utils/Errors.h) can be: 108 * NO_ERROR successful operation. 109 * PERMISSION_DENIED could not get AudioFlinger interface 110 * NO_INIT effect library failed to initialize 111 * BAD_VALUE invalid type or descriptor pointers 112 * NAME_NOT_FOUND no effect with this uuid found 113 * 114 * Returned value 115 * *descriptor updated with effect descriptor 116 */ 117 static status_t getEffectDescriptor(const effect_uuid_t *uuid, 118 const effect_uuid_t *type, 119 uint32_t preferredTypeFlag, 120 effect_descriptor_t *descriptor); 121 122 /* 123 * Returns a list of descriptors corresponding to the pre processings enabled by default 124 * on an AudioRecord with the supplied audio session ID. 125 * 126 * Parameters: 127 * audioSession: audio session ID. 128 * descriptors: address where the effect descriptors should be returned. 129 * count: as input, the maximum number of descriptor than should be returned 130 * as output, the number of descriptor returned if status is NO_ERROR or the actual 131 * number of enabled pre processings if status is NO_MEMORY 132 * 133 * Returned status (from utils/Errors.h) can be: 134 * NO_ERROR successful operation. 135 * NO_MEMORY the number of descriptor to return is more than the maximum number 136 * indicated by count. 137 * PERMISSION_DENIED could not get AudioFlinger interface 138 * NO_INIT effect library failed to initialize 139 * BAD_VALUE invalid audio session or descriptor pointers 140 * 141 * Returned value 142 * *descriptor updated with descriptors of pre processings enabled by default 143 * *count number of descriptors returned if returned status is NO_ERROR. 144 * total number of pre processing enabled by default if returned status is 145 * NO_MEMORY. This happens if the count passed as input is less than the number 146 * of descriptors to return. 147 * *count is limited to kMaxPreProcessing on return. 148 */ 149 static status_t queryDefaultPreProcessing(audio_session_t audioSession, 150 effect_descriptor_t *descriptors, 151 uint32_t *count); 152 153 /* 154 * Gets a new system-wide unique effect id. 155 * 156 * Parameters: 157 * id: The address to return the generated id. 158 * 159 * Returned status (from utils/Errors.h) can be: 160 * NO_ERROR successful operation. 161 * PERMISSION_DENIED could not get AudioFlinger interface 162 * or caller lacks required permissions. 163 * Returned value 164 * *id: The new unique system-wide effect id. 165 */ 166 static status_t newEffectUniqueId(audio_unique_id_t* id); 167 168 /* 169 * Static methods for adding/removing system-wide effects. 170 */ 171 172 /* 173 * Adds an effect to the list of default output effects for a given source type. 174 * 175 * If the effect is no longer available when a source of the given type 176 * is created, the system will continue without adding it. 177 * 178 * Parameters: 179 * typeStr: Type uuid of effect to be a default: can be null if uuidStr is specified. 180 * This may correspond to the OpenSL ES interface implemented by this effect, 181 * or could be some vendor-defined type. 182 * opPackageName: The package name used for app op checks. 183 * uuidStr: Uuid of effect to be a default: can be null if type is specified. 184 * This uuid corresponds to a particular implementation of an effect type. 185 * Note if both uuidStr and typeStr are specified, typeStr is ignored. 186 * priority: Requested priority for effect control: the priority level corresponds to the 187 * value of priority parameter: negative values indicate lower priorities, positive 188 * values higher priorities, 0 being the normal priority. 189 * source: The source this effect should be a default for. 190 * id: Address where the system-wide unique id of the default effect should be returned. 191 * 192 * Returned status (from utils/Errors.h) can be: 193 * NO_ERROR successful operation. 194 * PERMISSION_DENIED could not get AudioFlinger interface 195 * or caller lacks required permissions. 196 * NO_INIT effect library failed to initialize. 197 * BAD_VALUE invalid source, type uuid or implementation uuid. 198 * NAME_NOT_FOUND no effect with this uuid or type found. 199 * 200 * Returned value 201 * *id: The system-wide unique id of the added default effect. 202 */ 203 static status_t addSourceDefaultEffect(const char* typeStr, 204 const String16& opPackageName, 205 const char* uuidStr, 206 int32_t priority, 207 audio_source_t source, 208 audio_unique_id_t* id); 209 210 /* 211 * Adds an effect to the list of default output effects for a given stream type. 212 * 213 * If the effect is no longer available when a stream of the given type 214 * is created, the system will continue without adding it. 215 * 216 * Parameters: 217 * typeStr: Type uuid of effect to be a default: can be null if uuidStr is specified. 218 * This may correspond to the OpenSL ES interface implemented by this effect, 219 * or could be some vendor-defined type. 220 * opPackageName: The package name used for app op checks. 221 * uuidStr: Uuid of effect to be a default: can be null if type is specified. 222 * This uuid corresponds to a particular implementation of an effect type. 223 * Note if both uuidStr and typeStr are specified, typeStr is ignored. 224 * priority: Requested priority for effect control: the priority level corresponds to the 225 * value of priority parameter: negative values indicate lower priorities, positive 226 * values higher priorities, 0 being the normal priority. 227 * usage: The usage this effect should be a default for. Unrecognized values will be 228 * treated as AUDIO_USAGE_UNKNOWN. 229 * id: Address where the system-wide unique id of the default effect should be returned. 230 * 231 * Returned status (from utils/Errors.h) can be: 232 * NO_ERROR successful operation. 233 * PERMISSION_DENIED could not get AudioFlinger interface 234 * or caller lacks required permissions. 235 * NO_INIT effect library failed to initialize. 236 * BAD_VALUE invalid type uuid or implementation uuid. 237 * NAME_NOT_FOUND no effect with this uuid or type found. 238 * 239 * Returned value 240 * *id: The system-wide unique id of the added default effect. 241 */ 242 static status_t addStreamDefaultEffect(const char* typeStr, 243 const String16& opPackageName, 244 const char* uuidStr, 245 int32_t priority, 246 audio_usage_t usage, 247 audio_unique_id_t* id); 248 249 /* 250 * Removes an effect from the list of default output effects for a given source type. 251 * 252 * Parameters: 253 * id: The system-wide unique id of the effect that should no longer be a default. 254 * 255 * Returned status (from utils/Errors.h) can be: 256 * NO_ERROR successful operation. 257 * PERMISSION_DENIED could not get AudioFlinger interface 258 * or caller lacks required permissions. 259 * NO_INIT effect library failed to initialize. 260 * BAD_VALUE invalid id. 261 */ 262 static status_t removeSourceDefaultEffect(audio_unique_id_t id); 263 264 /* 265 * Removes an effect from the list of default output effects for a given stream type. 266 * 267 * Parameters: 268 * id: The system-wide unique id of the effect that should no longer be a default. 269 * 270 * Returned status (from utils/Errors.h) can be: 271 * NO_ERROR successful operation. 272 * PERMISSION_DENIED could not get AudioFlinger interface 273 * or caller lacks required permissions. 274 * NO_INIT effect library failed to initialize. 275 * BAD_VALUE invalid id. 276 */ 277 static status_t removeStreamDefaultEffect(audio_unique_id_t id); 278 279 /* 280 * Events used by callback function (effect_callback_t). 281 */ 282 enum event_type { 283 EVENT_CONTROL_STATUS_CHANGED = 0, 284 EVENT_ENABLE_STATUS_CHANGED = 1, 285 EVENT_PARAMETER_CHANGED = 2, 286 EVENT_ERROR = 3 287 }; 288 289 /* Callback function notifying client application of a change in effect engine state or 290 * configuration. 291 * An effect engine can be shared by several applications but only one has the control 292 * of the engine activity and configuration at a time. 293 * The EVENT_CONTROL_STATUS_CHANGED event is received when an application loses or 294 * retrieves the control of the effect engine. Loss of control happens 295 * if another application requests the use of the engine by creating an AudioEffect for 296 * the same effect type but with a higher priority. Control is returned when the 297 * application having the control deletes its AudioEffect object. 298 * The EVENT_ENABLE_STATUS_CHANGED event is received by all applications not having the 299 * control of the effect engine when the effect is enabled or disabled. 300 * The EVENT_PARAMETER_CHANGED event is received by all applications not having the 301 * control of the effect engine when an effect parameter is changed. 302 * The EVENT_ERROR event is received when the media server process dies. 303 * 304 * Parameters: 305 * 306 * event: type of event notified (see enum AudioEffect::event_type). 307 * user: Pointer to context for use by the callback receiver. 308 * info: Pointer to optional parameter according to event type: 309 * - EVENT_CONTROL_STATUS_CHANGED: boolean indicating if control is granted (true) 310 * or stolen (false). 311 * - EVENT_ENABLE_STATUS_CHANGED: boolean indicating if effect is now enabled (true) 312 * or disabled (false). 313 * - EVENT_PARAMETER_CHANGED: pointer to a effect_param_t structure. 314 * - EVENT_ERROR: status_t indicating the error (DEAD_OBJECT when media server dies). 315 */ 316 317 typedef void (*effect_callback_t)(int32_t event, void* user, void *info); 318 319 320 /* Constructor. 321 * AudioEffect is the base class for creating and controlling an effect engine from 322 * the application process. Creating an AudioEffect object will create the effect engine 323 * in the AudioFlinger if no engine of the specified type exists. If one exists, this engine 324 * will be used. The application creating the AudioEffect object (or a derived class like 325 * Reverb for instance) will either receive control of the effect engine or not, depending 326 * on the priority parameter. If priority is higher than the priority used by the current 327 * effect engine owner, the control will be transfered to the new application. Otherwise 328 * control will remain to the previous application. In this case, the new application will be 329 * notified of changes in effect engine state or control ownership by the effect callback. 330 * After creating the AudioEffect, the application must call the initCheck() method and 331 * check the creation status before trying to control the effect engine (see initCheck()). 332 * If the effect is to be applied to an AudioTrack or MediaPlayer only the application 333 * must specify the audio session ID corresponding to this player. 334 */ 335 336 /* Simple Constructor. 337 * 338 * Parameters: 339 * 340 * opPackageName: The package name used for app op checks. 341 */ 342 AudioEffect(const String16& opPackageName); 343 344 345 /* Constructor. 346 * 347 * Parameters: 348 * 349 * type: type of effect created: can be null if uuid is specified. This corresponds to 350 * the OpenSL ES interface implemented by this effect. 351 * opPackageName: The package name used for app op checks. 352 * uuid: Uuid of effect created: can be null if type is specified. This uuid corresponds to 353 * a particular implementation of an effect type. 354 * priority: requested priority for effect control: the priority level corresponds to the 355 * value of priority parameter: negative values indicate lower priorities, positive values 356 * higher priorities, 0 being the normal priority. 357 * cbf: optional callback function (see effect_callback_t) 358 * user: pointer to context for use by the callback receiver. 359 * sessionID: audio session this effect is associated to. 360 * If equal to AUDIO_SESSION_OUTPUT_MIX, the effect will be global to 361 * the output mix. Otherwise, the effect will be applied to all players 362 * (AudioTrack or MediaPLayer) within the same audio session. 363 * io: HAL audio output or input stream to which this effect must be attached. Leave at 0 for 364 * automatic output selection by AudioFlinger. 365 */ 366 367 AudioEffect(const effect_uuid_t *type, 368 const String16& opPackageName, 369 const effect_uuid_t *uuid = NULL, 370 int32_t priority = 0, 371 effect_callback_t cbf = NULL, 372 void* user = NULL, 373 audio_session_t sessionId = AUDIO_SESSION_OUTPUT_MIX, 374 audio_io_handle_t io = AUDIO_IO_HANDLE_NONE 375 ); 376 377 /* Constructor. 378 * Same as above but with type and uuid specified by character strings 379 */ 380 AudioEffect(const char *typeStr, 381 const String16& opPackageName, 382 const char *uuidStr = NULL, 383 int32_t priority = 0, 384 effect_callback_t cbf = NULL, 385 void* user = NULL, 386 audio_session_t sessionId = AUDIO_SESSION_OUTPUT_MIX, 387 audio_io_handle_t io = AUDIO_IO_HANDLE_NONE 388 ); 389 390 /* Terminates the AudioEffect and unregisters it from AudioFlinger. 391 * The effect engine is also destroyed if this AudioEffect was the last controlling 392 * the engine. 393 */ 394 ~AudioEffect(); 395 396 /* Initialize an uninitialized AudioEffect. 397 * Returned status (from utils/Errors.h) can be: 398 * - NO_ERROR or ALREADY_EXISTS: successful initialization 399 * - INVALID_OPERATION: AudioEffect is already initialized 400 * - BAD_VALUE: invalid parameter 401 * - NO_INIT: audio flinger or audio hardware not initialized 402 * */ 403 status_t set(const effect_uuid_t *type, 404 const effect_uuid_t *uuid = NULL, 405 int32_t priority = 0, 406 effect_callback_t cbf = NULL, 407 void* user = NULL, 408 audio_session_t sessionId = AUDIO_SESSION_OUTPUT_MIX, 409 audio_io_handle_t io = AUDIO_IO_HANDLE_NONE 410 ); 411 412 /* Result of constructing the AudioEffect. This must be checked 413 * before using any AudioEffect API. 414 * initCheck() can return: 415 * - NO_ERROR: the effect engine is successfully created and the application has control. 416 * - ALREADY_EXISTS: the effect engine is successfully created but the application does not 417 * have control. 418 * - NO_INIT: the effect creation failed. 419 * 420 */ 421 status_t initCheck() const; 422 423 424 /* Returns the unique effect Id for the controlled effect engine. This ID is unique 425 * system wide and is used for instance in the case of auxiliary effects to attach 426 * the effect to an AudioTrack or MediaPlayer. 427 * 428 */ 429 int32_t id() const { return mId; } 430 431 /* Returns a descriptor for the effect (see effect_descriptor_t in audio_effect.h). 432 */ 433 effect_descriptor_t descriptor() const; 434 435 /* Returns effect control priority of this AudioEffect object. 436 */ 437 int32_t priority() const { return mPriority; } 438 439 440 /* Enables or disables the effect engine. 441 * 442 * Parameters: 443 * enabled: requested enable state. 444 * 445 * Returned status (from utils/Errors.h) can be: 446 * - NO_ERROR: successful operation 447 * - INVALID_OPERATION: the application does not have control of the effect engine or the 448 * effect is already in the requested state. 449 */ 450 virtual status_t setEnabled(bool enabled); 451 bool getEnabled() const; 452 453 /* Sets a parameter value. 454 * 455 * Parameters: 456 * param: pointer to effect_param_t structure containing the parameter 457 * and its value (See audio_effect.h). 458 * Returned status (from utils/Errors.h) can be: 459 * - NO_ERROR: successful operation. 460 * - INVALID_OPERATION: the application does not have control of the effect engine. 461 * - BAD_VALUE: invalid parameter identifier or value. 462 * - DEAD_OBJECT: the effect engine has been deleted. 463 */ 464 virtual status_t setParameter(effect_param_t *param); 465 466 /* Prepare a new parameter value that will be set by next call to 467 * setParameterCommit(). This method can be used to set multiple parameters 468 * in a synchronous manner or to avoid multiple binder calls for each 469 * parameter. 470 * 471 * Parameters: 472 * param: pointer to effect_param_t structure containing the parameter 473 * and its value (See audio_effect.h). 474 * 475 * Returned status (from utils/Errors.h) can be: 476 * - NO_ERROR: successful operation. 477 * - INVALID_OPERATION: the application does not have control of the effect engine. 478 * - NO_MEMORY: no more space available in shared memory used for deferred parameter 479 * setting. 480 */ 481 virtual status_t setParameterDeferred(effect_param_t *param); 482 483 /* Commit all parameter values previously prepared by setParameterDeferred(). 484 * 485 * Parameters: 486 * none 487 * 488 * Returned status (from utils/Errors.h) can be: 489 * - NO_ERROR: successful operation. 490 * - INVALID_OPERATION: No new parameter values ready for commit. 491 * - BAD_VALUE: invalid parameter identifier or value: there is no indication 492 * as to which of the parameters caused this error. 493 * - DEAD_OBJECT: the effect engine has been deleted. 494 */ 495 virtual status_t setParameterCommit(); 496 497 /* Gets a parameter value. 498 * 499 * Parameters: 500 * param: pointer to effect_param_t structure containing the parameter 501 * and the returned value (See audio_effect.h). 502 * 503 * Returned status (from utils/Errors.h) can be: 504 * - NO_ERROR: successful operation. 505 * - INVALID_OPERATION: the AudioEffect was not successfully initialized. 506 * - BAD_VALUE: invalid parameter identifier. 507 * - DEAD_OBJECT: the effect engine has been deleted. 508 */ 509 virtual status_t getParameter(effect_param_t *param); 510 511 /* Sends a command and receives a response to/from effect engine. 512 * See audio_effect.h for details on effect command() function, valid command codes 513 * and formats. 514 */ 515 virtual status_t command(uint32_t cmdCode, 516 uint32_t cmdSize, 517 void *cmdData, 518 uint32_t *replySize, 519 void *replyData); 520 521 522 /* 523 * Utility functions. 524 */ 525 526 /* Converts the string passed as first argument to the effect_uuid_t 527 * pointed to by second argument 528 */ 529 static status_t stringToGuid(const char *str, effect_uuid_t *guid); 530 /* Converts the effect_uuid_t pointed to by first argument to the 531 * string passed as second argument 532 */ 533 static status_t guidToString(const effect_uuid_t *guid, char *str, size_t maxLen); 534 535 // kMaxPreProcessing is a reasonable value for the maximum number of preprocessing effects 536 // that can be applied simultaneously. 537 static const uint32_t kMaxPreProcessing = 10; 538 539 protected: 540 bool mEnabled; // enable state 541 audio_session_t mSessionId; // audio session ID 542 int32_t mPriority; // priority for effect control 543 status_t mStatus; // effect status 544 effect_callback_t mCbf; // callback function for status, control and 545 // parameter changes notifications 546 void* mUserData; // client context for callback function 547 effect_descriptor_t mDescriptor; // effect descriptor 548 int32_t mId; // system wide unique effect engine instance ID 549 Mutex mLock; // Mutex for mEnabled access 550 Mutex mConstructLock; // Mutex for integrality construction 551 552 String16 mOpPackageName; // The package name used for app op checks. 553 554 // IEffectClient 555 virtual void controlStatusChanged(bool controlGranted); 556 virtual void enableStatusChanged(bool enabled); 557 virtual void commandExecuted(uint32_t cmdCode, 558 uint32_t cmdSize, 559 void *pCmdData, 560 uint32_t replySize, 561 void *pReplyData); 562 563 private: 564 565 // Implements the IEffectClient interface 566 class EffectClient : 567 public android::BnEffectClient, public android::IBinder::DeathRecipient 568 { 569 public: 570 571 EffectClient(AudioEffect *effect) : mEffect(effect){} 572 573 // IEffectClient 574 virtual void controlStatusChanged(bool controlGranted) { 575 sp<AudioEffect> effect = mEffect.promote(); 576 if (effect != 0) { 577 { 578 // Got the mConstructLock means the construction of AudioEffect 579 // has finished, we should release the mConstructLock immediately. 580 AutoMutex lock(effect->mConstructLock); 581 } 582 effect->controlStatusChanged(controlGranted); 583 } 584 } 585 virtual void enableStatusChanged(bool enabled) { 586 sp<AudioEffect> effect = mEffect.promote(); 587 if (effect != 0) { 588 { 589 // Got the mConstructLock means the construction of AudioEffect 590 // has finished, we should release the mConstructLock immediately. 591 AutoMutex lock(effect->mConstructLock); 592 } 593 effect->enableStatusChanged(enabled); 594 } 595 } 596 virtual void commandExecuted(uint32_t cmdCode, 597 uint32_t cmdSize, 598 void *pCmdData, 599 uint32_t replySize, 600 void *pReplyData) { 601 sp<AudioEffect> effect = mEffect.promote(); 602 if (effect != 0) { 603 { 604 // Got the mConstructLock means the construction of AudioEffect 605 // has finished, we should release the mConstructLock immediately. 606 AutoMutex lock(effect->mConstructLock); 607 } 608 effect->commandExecuted( 609 cmdCode, cmdSize, pCmdData, replySize, pReplyData); 610 } 611 } 612 613 // IBinder::DeathRecipient 614 virtual void binderDied(const wp<IBinder>& /*who*/) { 615 sp<AudioEffect> effect = mEffect.promote(); 616 if (effect != 0) { 617 { 618 // Got the mConstructLock means the construction of AudioEffect 619 // has finished, we should release the mConstructLock immediately. 620 AutoMutex lock(effect->mConstructLock); 621 } 622 effect->binderDied(); 623 } 624 } 625 626 private: 627 wp<AudioEffect> mEffect; 628 }; 629 630 void binderDied(); 631 632 sp<IEffect> mIEffect; // IEffect binder interface 633 sp<EffectClient> mIEffectClient; // IEffectClient implementation 634 sp<IMemory> mCblkMemory; // shared memory for deferred parameter setting 635 effect_param_cblk_t* mCblk; // control block for deferred parameter setting 636 pid_t mClientPid; 637 }; 638 639 640 }; // namespace android 641 642 #endif // ANDROID_AUDIOEFFECT_H 643
