AudioFocusRequestClass Classe

Définition

[Android.Runtime.Register("android/media/AudioFocusRequest", ApiSince=26, DoNotGenerateAcw=true)]
public sealed class AudioFocusRequestClass : Java.Lang.Object

[<Android.Runtime.Register("android/media/AudioFocusRequest", ApiSince=26, DoNotGenerateAcw=true)>]
type AudioFocusRequestClass = class
    inherit Object

Héritage

Object

JavaObject

Object

AudioFocusRequestClass

Attributs

RegisterAttribute

Remarques

Classe pour encapsuler des informations sur une demande de focus audio. Une AudioFocusRequest instance est générée par Builder, et est utilisée pour demander et abandonner le focus audio, respectivement avec AudioManager#requestAudioFocus(AudioFocusRequest) et AudioManager#abandonAudioFocusRequest(AudioFocusRequest).

<h3>Qu’est-ce que le focus audio ?</h3>

Le focus audio est un concept introduit dans l’API 8. Il est utilisé pour transmettre le fait qu’un utilisateur ne peut se concentrer que sur un seul flux audio à la fois, par exemple écouter de la musique ou un podcast, mais pas les deux en même temps. Dans certains cas, plusieurs flux audio peuvent être lues en même temps, mais il n’y a qu’un seul utilisateur à écouter (se concentrer), tandis que l’autre joue en arrière-plan. Par exemple, les directions sont parlées pendant que la musique joue à un volume réduit (c’est-à-dire canard).

Lorsqu’une application demande le focus audio, elle exprime son intention de « posséder » le focus audio pour lire l’audio. Examinons les différents types de demandes de focus, la valeur de retour après une demande et les réponses à une perte.

Remarque : les applications ne doivent rien lire tant que le focus n’a pas été accordé.

<h3>Les différents types de demandes< de focus/h3>

Il existe quatre types de demandes de focus. Une demande de focus réussie avec chacune d’elles génère des comportements différents par le système et l’autre application qui détenait précédemment le focus audio. <ul><li>AudioManager#AUDIOFOCUS_GAIN exprime le fait que votre application est désormais la seule source de l’audio que l’utilisateur écoute. La durée de la lecture audio est inconnue et peut-être très longue : une fois que l’utilisateur a fini d’interagir avec votre application, il ne s’attend pas à ce qu’un autre flux audio reprend. Les exemples d’utilisations de ce gain de focus sont destinés à la lecture de musique, à un jeu ou à un lecteur vidéo.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT est pour une situation lorsque vous savez que votre application récupère temporairement le focus du propriétaire actuel, mais l’utilisateur s’attend à ce que la lecture revient à l’endroit où elle était une fois que votre application n’a plus besoin du focus audio. Par exemple, il s’agit de lire une alarme ou pendant un appel VoIP. La lecture est connue pour être finie : l’alarme expire ou est ignorée, l’appel VoIP a un début et une fin. Lorsque l’un de ces événements se termine et si l’utilisateur écoute de la musique au démarrage, l’utilisateur s’attend à ce que la musique reprend, mais ne souhaite pas écouter les deux en même temps.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK : ce type de demande de focus est similaire à AUDIOFOCUS_GAIN_TRANSIENT l’aspect temporaire de la demande de focus, mais il exprime également le fait pendant le temps que vous possédez le focus, vous autorisez une autre application à continuer à jouer à un volume réduit, « canardé ». Par exemple, lorsque vous jouez des directions ou des notifications, il est bon que la musique continue de jouer, mais pas assez fort pour empêcher les directions d’être difficiles à comprendre. Une atténuation classique par l’application « canarded » est un facteur de 0,2f (ou -14dB), qui peut par exemple être appliqué lors MediaPlayer.setVolume(0.2f) de l’utilisation de cette classe pour la lecture.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE est également pour une demande temporaire, mais exprime également que votre application s’attend à ce que l’appareil ne joue rien d’autre. Cela est généralement utilisé si vous effectuez un enregistrement audio ou une reconnaissance vocale et ne souhaitez pas que des exemples de notifications soient lues par le système pendant cette période.</li></ul>

Une AudioFocusRequest instance contient toujours l’un des quatre types de requêtes expliqués ci-dessus. Elle est passée lors de la génération d’une AudioFocusRequest instance avec son générateur dans le Builder constructeur AudioFocusRequest.Builder#Builder(int), ou après AudioFocusRequest.Builder#setFocusGain(int) avoir copié une instance existante avec AudioFocusRequest.Builder#Builder(AudioFocusRequest).

« remarque »><b>Remarque :</b> Si une application cible Android 15 (niveau d’API 35) ou une version ultérieure, elle ne peut pas demander le focus audio, sauf si elle est l’application supérieure ou exécute un service de premier plan. Cette exigence est similaire à la configuration requise pour la lecture audio. Si une application demande le focus audio lorsqu’elle ne répond pas à ces exigences, la méthode retourne <c AudioManager#AUDIOFOCUS_REQUEST_FAILED</c>>. </aside>

<h3>Qualification de votre demande< de focus/h3><h4>Cas d’usage nécessitant une demande< de focus/h4>

Toute demande de focus est qualifiée par le AudioAttributes (voir Builder#setAudioAttributes(AudioAttributes)) qui décrivent le cas d’usage audio qui suivra la demande (une fois qu’elle a réussi ou accordé). Il est recommandé d’utiliser la même AudioAttributes chose pour la requête que les attributs que vous utilisez pour la lecture audio/multimédia. <br>Si aucun attribut n’est défini, les attributs par défaut sont AudioAttributes#USAGE_MEDIA utilisés.

<Focus> différé h4</h4>

Le focus audio peut être « verrouillé » par le système pour plusieurs raisons : pendant un appel téléphonique, lorsque la voiture à laquelle l’appareil est connecté lit un message d’urgence... Pour prendre en charge ces situations, l’application peut demander à être avertie lorsque sa demande est remplie, en signalant sa demande comme acceptant le focus différé, avec Builder#setAcceptsDelayedFocusGain(boolean). <br>Si le focus est demandé pendant le verrouillage par le système, AudioManager#requestAudioFocus(AudioFocusRequest) retourne AudioManager#AUDIOFOCUS_REQUEST_DELAYED. Lorsque le focus n’est plus verrouillé, l’écouteur de focus défini avec Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener) ou avec Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener, Handler) sera appelé pour avertir l’application qu’elle possède désormais le focus audio.

<h4>Pausing vs canarding</h4>

Lorsqu’une application a demandé le focus audio avec AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, le système canarde le propriétaire actuel du focus.

Remarque : ce comportement est <b>nouveau pour Android O</b>, tandis que les applications ciblant le niveau sdk jusqu’à l’API 25 ont dû implémenter les canards eux-mêmes lorsqu’elles ont reçu une perte AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCKde focus .

Mais le canard n’est pas toujours le comportement attendu par l’utilisateur. Un exemple typique est le moment où l’appareil lit des directions de conduite pendant que l’utilisateur écoute un livre audio ou un podcast, et attend que la lecture audio s’interrompe, au lieu de canard, car il est difficile de comprendre une invite de navigation et du contenu parlé en même temps. Par conséquent, le système n’est pas automatiquement canard lorsqu’il détecte qu’il s’agit d’un contenu parlé : ce contenu est détecté lorsque le AudioAttributes lecteur est qualifié par AudioAttributes#CONTENT_TYPE_SPEECH. Reportez-vous par exemple à AudioAttributes.Builder#setContentType(int) et MediaPlayer#setAudioAttributes(AudioAttributes) si vous écrivez une application de lecture multimédia pour le livre audio, les podcasts... Étant donné que le système ne canardera pas automatiquement les applications qui jouent la parole, il appelle plutôt leur écouteur de focus pour les AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCKavertir, afin qu’ils puissent s’interrompre à la place. Notez que ce comportement est indépendant de l’utilisation de AudioFocusRequest, mais lié à l’utilisation de AudioAttributes.

Si votre application nécessite la suspension au lieu de canarder pour une autre raison que la lecture de la parole, vous pouvez également le déclarer avec Builder#setWillPauseWhenDucked(boolean), ce qui entraîne l’appel du système à votre écouteur de focus au lieu de canarder automatiquement.

<exemple> h4</h4>

L’exemple ci-dessous décrit les étapes suivantes à trouver dans n’importe quelle application qui lireait du contenu audio et utiliserait le focus audio. Ici, nous jouons un livre audio, et notre application est destinée à suspendre plutôt qu’à canard lorsqu’elle perd le focus. Ces étapes se composent de : <ul><li>Creating AudioAttributes to be used for the playback and the focus request.</li><li>Configurez et créez l’instance AudioFocusRequest qui définit les comportements de focus prévus.</li li><>Demande de focus audio et vérification du code de retour pour voir si la lecture peut se produire immédiatement, ou est retardée.</li li><>Implémentation d’un écouteur de changement de focus pour répondre aux gains et pertes de focus.</li></ul>

// initialization of the audio attributes and focus request
            mAudioManager = (AudioManager) Context.getSystemService(Context.AUDIO_SERVICE);
            mPlaybackAttributes = new AudioAttributes.Builder()
                    .setUsage(AudioAttributes.USAGE_MEDIA)
                    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
                    .build();
            mFocusRequest = new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
                    .setAudioAttributes(mPlaybackAttributes)
                    .setAcceptsDelayedFocusGain(true)
                    .setWillPauseWhenDucked(true)
                    .setOnAudioFocusChangeListener(this, mMyHandler)
                    .build();
            mMediaPlayer = new MediaPlayer();
            mMediaPlayer.setAudioAttributes(mPlaybackAttributes);
            final Object mFocusLock = new Object();

            boolean mPlaybackDelayed = false;

            // requesting audio focus
            int res = mAudioManager.requestAudioFocus(mFocusRequest);
            synchronized (mFocusLock) {
                if (res == AudioManager.AUDIOFOCUS_REQUEST_FAILED) {
                    mPlaybackDelayed = false;
                } else if (res == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
                    mPlaybackDelayed = false;
                    playbackNow();
                } else if (res == AudioManager.AUDIOFOCUS_REQUEST_DELAYED) {
                   mPlaybackDelayed = true;
                }
            }

            // implementation of the OnAudioFocusChangeListener
            @Override
            public void onAudioFocusChange(int focusChange) {
                switch (focusChange) {
                    case AudioManager.AUDIOFOCUS_GAIN:
                        if (mPlaybackDelayed || mResumeOnFocusGain) {
                            synchronized (mFocusLock) {
                                mPlaybackDelayed = false;
                                mResumeOnFocusGain = false;
                            }
                            playbackNow();
                        }
                        break;
                    case AudioManager.AUDIOFOCUS_LOSS:
                        synchronized (mFocusLock) {
                            // this is not a transient loss, we shouldn't automatically resume for now
                            mResumeOnFocusGain = false;
                            mPlaybackDelayed = false;
                        }
                        pausePlayback();
                        break;
                    case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT:
                    case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK:
                        // we handle all transient losses the same way because we never duck audio books
                        synchronized (mFocusLock) {
                            // we should only resume if playback was interrupted
                            mResumeOnFocusGain = mMediaPlayer.isPlaying();
                            mPlaybackDelayed = false;
                        }
                        pausePlayback();
                        break;
                }
            }

            // Important:
            // Also set "mResumeOnFocusGain" to false when the user pauses or stops playback: this way your
            // application doesn't automatically restart when it gains focus, even though the user had
            // stopped it.

Java documentation pour android.media.AudioFocusRequest.

Les parties de cette page sont des modifications basées sur le travail créé et partagé par Android Open Source et utilisées en fonction des termes décrits dans la Creative Commons 2.5 Attribution License.