1 /* 2 * Copyright (C) 2024 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.media.audio.eraser; 18 19 import android.media.audio.eraser.Classification; 20 21 /** 22 * Configuration for the eraser to apply specific gain adjustments to certain sound classifications. 23 * 24 * Gain is applied to the audio signal by scaling the amplitude of the output audio based on the 25 * classification of the input sound. 26 * If a classification exists in the configuration list, the remixer applies the specified gain to 27 * the output audio when the confidence score is higher than `confidenceThreshold`. If a 28 * classification is not present in the configuration, it is considered to have a gain of 1.0 29 * (no gain adjustment). 30 * If a ClassificationConfig contains an empty classification list, the same threshold and gain 31 * specified in the ClassificationConfig will be applied to all classifications not explicitly 32 * configured. 33 * 34 * Examples: 35 * 36 * 1. {classifications = [{classification = SoundClassification.NATURE}, 37 * {classification = SoundClassification.ENVIRONMENT}], 38 * confidenceThreshold = 0.8, 39 * gainFactor = 0.0} 40 * 41 * - If the input audio is classified as NATURE or ENVIRONMENT, with a confidence score higher 42 * than 0.8, the output audio will be muted. 43 * - If the classification confidence score is 0.8 or lower, or if the audio is classified 44 * differently, the output audio remains unchanged. 45 * 46 * 2. {classifications = [{classification = SoundClassification.MUSIC}], 47 * confidenceThreshold = 0.6, 48 * gainFactor = 0.5} 49 * 50 * - If the input audio is classified as MUSIC with a confidence score higher than 0.6, the 51 * output audio should have a gain factor of 0.5 (reduced by half). 52 * - If the classification confidence score is 0.6 or lower, or if the audio is classified 53 * differently, the output audio remains unchanged. 54 * 55 * 3. When combined as a list, the eraser can be configured to apply different gainFactor to 56 * a classifications when confideence score is higher than the corresponding threshold. 57 * [{classifications = [{classification = SoundClassification.NATURE}], 58 * confidenceThreshold = 0.8, 59 * gainFactor = 0.0}, 60 * {classifications = [{classification = SoundClassification.MUSIC}], 61 * confidenceThreshold = 0.8, 62 * gainFactor = 0.6}, 63 * {classifications = [{classification = SoundClassification.MUSIC}], 64 * confidenceThreshold = 0.5, 65 * gainFactor = 0.5}] 66 * 67 * - If the input audio is classified as NATURE, and the confidence score is higher than 0.8, 68 * the output audio classification will be muted (gainFactor = 0.0). 69 * 70 * - If the input audio is classified as MUSIC with a confidence score higher than 0.8, the 71 * output audio classification will have a gain factor of 0.6. If the input audio is 72 * classified as MUSIC with a confidence score higher than 0.5, the output audio 73 * classification will have a gain factor of 0.5. 74 * 75 * - For all other sound classifications, the audio signal remains unchanged (gainFactor = 1.0). 76 * 77 * 4. [{classifications = [{classification = SoundClassification.HUMAN}], 78 * confidenceThreshold = 0.8, 79 * gainFactor = 1.0}, 80 * {classifications = [], 81 * confidenceThreshold = 0.0, 82 * gainFactor = 0.5}] 83 * 84 * - If the input audio is classified as HUMAN, and the confidence score is higher than 0.8, the 85 * output audio classification will remains unchanged. 86 * 87 * - For all other sound classifications, the audio signal will have a gain factor of 0.5. 88 * 89 */ 90 @JavaDerive(equals=true, toString=true) 91 @VintfStability 92 parcelable ClassificationConfig { 93 /** 94 * List of sound classifications to which this configuration applies. 95 * 96 * Each entry specifies a sound classification (e.g., MUSIC, NATURE) targeted by this 97 * configuration. 98 */ 99 Classification[] classifications; 100 101 /** 102 * Confidence threshold in the range of [0.0, 1.0], only apply the gainFactor when the 103 * classifier's confidence score for the specified classifications exceeds this threshold. 104 * 105 * Default Value is 0.0 which means apply gain regardless of confidence score. 106 */ 107 float confidenceThreshold = 0f; 108 109 /** 110 * Gain factor to apply to the output audio when the specified classifications are detected. 111 * Gain factor is applied by multiplying the amplitude of the audio signal by the `gainFactor`. 112 * 113 * - A `gainFactor` of `1.0` means no gain adjustment (the original volume is preserved). 114 * - A `gainFactor` of `0.5` reduces the amplitude of the audio by half. 115 * - A `gainFactor` of `0.0` mutes the audio. 116 * - A `gainFactor` > `1.0` amplifies the audio signal, increasing its volume (useful for 117 * compressor and amplification cases). 118 * - A `gainFactor` < `0.0` inverts the phase of the audio signal (useful for phase 119 * cancellation or specific spatial audio manipulation). 120 * 121 * The `gainFactor` must be within the `gainFactorRange` defined in `RemixerCapability`, the 122 * default value is `1.0`. 123 */ 124 float gainFactor = 1f; 125 } 126