1 /* 2 * Copyright (C) 2022 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 package android.hardware.audio.effect; 18 19 import android.hardware.audio.common.SinkMetadata; 20 import android.hardware.audio.common.SourceMetadata; 21 import android.hardware.audio.effect.AcousticEchoCanceler; 22 import android.hardware.audio.effect.AutomaticGainControlV1; 23 import android.hardware.audio.effect.AutomaticGainControlV2; 24 import android.hardware.audio.effect.BassBoost; 25 import android.hardware.audio.effect.Downmix; 26 import android.hardware.audio.effect.DynamicsProcessing; 27 import android.hardware.audio.effect.EnvironmentalReverb; 28 import android.hardware.audio.effect.Equalizer; 29 import android.hardware.audio.effect.HapticGenerator; 30 import android.hardware.audio.effect.LoudnessEnhancer; 31 import android.hardware.audio.effect.NoiseSuppression; 32 import android.hardware.audio.effect.PresetReverb; 33 import android.hardware.audio.effect.Spatializer; 34 import android.hardware.audio.effect.VendorExtension; 35 import android.hardware.audio.effect.Virtualizer; 36 import android.hardware.audio.effect.Visualizer; 37 import android.hardware.audio.effect.Volume; 38 import android.media.audio.common.AudioConfig; 39 import android.media.audio.common.AudioDeviceDescription; 40 import android.media.audio.common.AudioMode; 41 import android.media.audio.common.AudioSource; 42 43 /** 44 * Defines all parameters supported by the effect instance. 45 * 46 * There are three groups of parameters: 47 * 1. Common parameters are essential parameters, MUST pass to effects at open() interface. 48 * 2. Parameters defined for a specific effect type. 49 * 3. Extension parameters ParcelableHolder can be used for vendor effect definition. 50 * 51 * All parameter settings must be inside the range of Capability.Range.$EffectType$ definition. If 52 * an effect implementation doesn't have limitation for a parameter, then don't define any effect 53 * range. 54 * 55 * All parameters are get-able, if any parameter doesn't support set, effect implementation should 56 * report the supported range for this parameter as range.min > range.max. If no support range is 57 * defined for a parameter, it means this parameter doesn't have any limitation. 58 * 59 */ 60 @VintfStability 61 union Parameter { 62 /** 63 * Client can pass in Parameter.Id with the corresponding tag value in IEffect.getParameter() 64 * call to get android.hardware.audio.effect.Parameter. 65 * 66 * As an example, if a client want to get audio.hardware.audio.effect.Specific.Equalizer, the 67 * value of Id should be audio.hardware.audio.effect.Parameter.Specific.equalizer. 68 */ 69 @VintfStability 70 union Id { 71 /** 72 * Parameter tag defined for vendor effects. Use VendorExtension here so it's possible to 73 * pass customized information. 74 */ 75 VendorExtension vendorEffectTag; 76 /** 77 * Parameter tag defined for nested parameters. Can be used to get any parameter defined in 78 * nested Union structure. 79 * 80 * Example: 81 * To get BassBoost strength in param from effectInstance: 82 * IEffect effectInstance; 83 * Parameter param; 84 * BassBoost::Id bassId = BassBoost::Id::make<BassBoost::Id::tag>(BassBoost::strengthPm); 85 * Parameter::Id id = Parameter::Id::make<Parameter::Id::bassBoostTag>(bassId); 86 * effectInstance.getParameter(id, ¶m); 87 * 88 */ 89 AcousticEchoCanceler.Id acousticEchoCancelerTag; 90 AutomaticGainControlV1.Id automaticGainControlV1Tag; 91 AutomaticGainControlV2.Id automaticGainControlV2Tag; 92 BassBoost.Id bassBoostTag; 93 Downmix.Id downmixTag; 94 DynamicsProcessing.Id dynamicsProcessingTag; 95 EnvironmentalReverb.Id environmentalReverbTag; 96 Equalizer.Id equalizerTag; 97 HapticGenerator.Id hapticGeneratorTag; 98 LoudnessEnhancer.Id loudnessEnhancerTag; 99 NoiseSuppression.Id noiseSuppressionTag; 100 PresetReverb.Id presetReverbTag; 101 Virtualizer.Id virtualizerTag; 102 Visualizer.Id visualizerTag; 103 Volume.Id volumeTag; 104 /** 105 * Non-nested parameter tag. Can be used to get any parameter defined in Union Parameter 106 * directly. 107 */ 108 Parameter.Tag commonTag; 109 110 /** 111 * Parameter tag defined for Spatializer parameters. 112 */ 113 Spatializer.Id spatializerTag; 114 } 115 116 /** 117 * Common parameters MUST be supported by all effect implementations. 118 */ 119 @VintfStability 120 parcelable Common { 121 /** 122 * Type of Audio device. 123 */ 124 int session; 125 /** 126 * I/O Handle. 127 */ 128 int ioHandle; 129 /** 130 * Input config. 131 */ 132 AudioConfig input; 133 /** 134 * Output config. 135 */ 136 AudioConfig output; 137 } 138 Common common; 139 140 /** 141 * Used by audio framework to set the device type(s) to effect engine. 142 * Effect engine must apply all AudioDeviceDescription in the list. 143 * Effect must implement setParameter(deviceDescription) if Flags.deviceIndication set to true. 144 */ 145 AudioDeviceDescription[] deviceDescription; 146 147 /** 148 * Used by audio framework to set the audio mode to effect engine. 149 * Effect must implement setParameter(mode) if Flags.audioModeIndication set to true. 150 */ 151 AudioMode mode; 152 153 /** 154 * Used by audio framework to set the audio source to effect engine. 155 * Effect must implement setParameter(source) if Flags.audioSourceIndication set to true. 156 */ 157 AudioSource source; 158 159 /** 160 * Used by audio framework to indicate whether the playback thread the effect is attached to is 161 * offloaded or not. 162 */ 163 boolean offload; 164 165 /** 166 * The volume gain for left and right channel, left and right equals to same value if it's mono. 167 */ 168 @VintfStability 169 parcelable VolumeStereo { 170 float left; 171 float right; 172 } 173 /** 174 * Used by audio framework to delegate volume control to effect engine. 175 * Effect must implement setParameter(volume) if Flags.volume set to Volume.IND. 176 */ 177 VolumeStereo volumeStereo; 178 179 /** 180 * Parameters MUST be supported by a Specific type of effect. 181 */ 182 @VintfStability 183 union Specific { 184 VendorExtension vendorEffect; 185 AcousticEchoCanceler acousticEchoCanceler; 186 AutomaticGainControlV1 automaticGainControlV1; 187 AutomaticGainControlV2 automaticGainControlV2; 188 BassBoost bassBoost; 189 Downmix downmix; 190 DynamicsProcessing dynamicsProcessing; 191 EnvironmentalReverb environmentalReverb; 192 Equalizer equalizer; 193 HapticGenerator hapticGenerator; 194 LoudnessEnhancer loudnessEnhancer; 195 NoiseSuppression noiseSuppression; 196 PresetReverb presetReverb; 197 Virtualizer virtualizer; 198 Visualizer visualizer; 199 Volume volume; 200 Spatializer spatializer; 201 } 202 Specific specific; 203 204 /** 205 * SinkMetadata defines the metadata of record AudioTracks which the effect instance associate 206 * with. 207 * The effect engine is required to set Flags.sinkMetadataIndication to true if it wants to 208 * receive sinkMetadata update from the audio framework. 209 */ 210 SinkMetadata sinkMetadata; 211 212 /** 213 * SourceMetadata defines the metadata of playback AudioTracks which the effect instance 214 * associate with. 215 * The effect engine is required to set Flags.sourceMetadataIndication to true if it wants to 216 * receive sourceMetadata update from the audio framework. 217 */ 218 SourceMetadata sourceMetadata; 219 } 220