1 /*
2  * Copyright (C) 2017 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 com.android.server.audio;
18 
19 import android.annotation.NonNull;
20 import android.media.AudioAttributes;
21 
22 public interface PlayerFocusEnforcer {
23 
24     /**
25      * Ducks the players associated with the "loser" focus owner (i.e. same UID). Returns true if
26      * at least one active player was found and ducked, false otherwise.
27      * @param winner
28      * @param loser
29      * @return
30      */
duckPlayers(@onNull FocusRequester winner, @NonNull FocusRequester loser, boolean forceDuck)31     boolean duckPlayers(@NonNull FocusRequester winner, @NonNull FocusRequester loser,
32                                boolean forceDuck);
33 
34     /**
35      * Restore the initial state of any players that had had a volume ramp applied as the result
36      * of a duck or fade out through {@link #duckPlayers(FocusRequester, FocusRequester, boolean)}
37      * or {@link #fadeOutPlayers(FocusRequester, FocusRequester)}
38      * @param winner
39      */
restoreVShapedPlayers(@onNull FocusRequester winner)40     void restoreVShapedPlayers(@NonNull FocusRequester winner);
41 
42     /**
43      * Mute players at the beginning of a call
44      * @param usagesToMute array of {@link android.media.AudioAttributes} usages to mute
45      */
mutePlayersForCall(int[] usagesToMute)46     void mutePlayersForCall(int[] usagesToMute);
47 
48     /**
49      * Unmute players at the end of a call
50      */
unmutePlayersForCall()51     void unmutePlayersForCall();
52 
53     /**
54      * Fade out whatever is still playing after the non-transient focus change
55      * @param winner the new non-transient focus owner
56      * @param loser the previous focus owner
57      * @return true if there were any active players for the loser that qualified for being
58      *         faded out (because of audio attributes, or player types), and as such were faded
59      *         out.
60      */
fadeOutPlayers(@onNull FocusRequester winner, @NonNull FocusRequester loser)61     boolean fadeOutPlayers(@NonNull FocusRequester winner, @NonNull FocusRequester loser);
62 
63     /**
64      * Mark this UID as no longer playing a role in focus enforcement
65      * @param uid
66      */
forgetUid(int uid)67     void forgetUid(int uid);
68 
69     /**
70      * Get the fade out duration currently active for the given usage
71      * @param aa The {@link android.media.AudioAttributes}
72      * @return fade out duration in milliseconds
73      */
getFadeOutDurationMillis(@onNull AudioAttributes aa)74     long getFadeOutDurationMillis(@NonNull AudioAttributes aa);
75 
76     /**
77      * Returns the delay to fade-in the offending players
78      * @param aa The {@link android.media.AudioAttributes}
79      * @return delay in milliseconds
80      */
getFadeInDelayForOffendersMillis(@onNull AudioAttributes aa)81     long getFadeInDelayForOffendersMillis(@NonNull AudioAttributes aa);
82 
83     /**
84      * Check if the fade should be enforced
85      *
86      * @return {@code true} if fade should be enforced, {@code false} otherwise
87      */
shouldEnforceFade()88     boolean shouldEnforceFade();
89 }